2. Domain ID Rules

All master data in PlantPulse is subject to server-side regular expression validation. Domain validators (SiteValidator, OPCValidator, AssetValidator, TagValidator, …) enforce regex matching; on violation, create() / update() calls return null and the response envelope includes _code=E1002 (VALIDATION_FAILED). Precise ID design is the starting point for building a scalable IoT system.

📖 For a summary of platform-wide conventions, see the Domain ID Naming Conventions page.

2.1 ID Rules at a Glance (Based on Server Regex)

Domain	Regex	Recommended Pattern	Example
Site	^V?SITE_[A-Z0-9_]+$	SITE_<token> (or VSITE_… Virtual)	SITE_DJ, VSITE_AGG_01
OPC	^(OPC|EDGE|TEST)_[A-Z0-9_]+$	OPC_<type>_<number> / EDGE_<location>_<number>	OPC_00303, EDGE_GW01, TEST_VIRTUAL
Edge	^(EDGE|OPC)_[A-Z0-9_]+$	EDGE_<location>_<number>	EDGE_LINE1_01
Asset (Area/Line/Equipment)	^ASSET_[A-Z0-9_]+$	ASSET_<site>_<type>_<number>	ASSET_DJ_L_0001
Tag	^V*TAG_[A-Z0-9_]+$	TAG_<OPC>_<number> (or VTAG_ for virtual tags)	TAG_EDGE_00303_90007, VTAG_OEE_LINE1
AlarmConfig	^ALARM_CONFIG_[A-Z0-9_]+$	ALARM_CONFIG_<metric>_<number>	ALARM_CONFIG_TEMP_HIGH_01
Employee	^EMP_[A-Z0-9_]+$	EMP_<employee-no>	EMP_E12345
Customer	^CUSTOMER_[A-Z0-9_]+$	CUSTOMER_<number>	CUSTOMER_001
Product	^PRODUCT_[A-Z0-9_]+$	PRODUCT_<SKU>	PRODUCT_A001
Flow	^FLOW_[A-Z0-9_]+$	FLOW_<purpose>_<interval>	FLOW_OEE_DAILY
User (login)	^[A-Z][A-Z0-9_]*$	Starts with an uppercase letter, [A-Z0-9_]	ADMIN, OPERATOR_01
Calendar	(free-form)	CAL_<YYYYMMDD>_<seq>	CAL_20260514_0001
Order	(free-form)	ORD_<YYYYMMDD>_<seq>	ORD_20260514_001

⚠️ Validation is enforced: Every domain with a regex listed above is checked on the server. On violation, V5 returns null and the response includes _code=E1002, _message="site_id must match ^V?SITE_[A-Z0-9_]+$", and so on.

⚠️ Customer/Product use full words: CUSTOMER_ and PRODUCT_ are the correct prefixes. The shortened CUST_ and PROD_ are rejected.

⚠️ The API_ prefix cannot be used for OPC: Even for external API channels, opc_id must start with one of OPC_ / EDGE_ / TEST_.

2.2 Site ID

정규식: ^V?SITE_[A-Z0-9_]+$
허용: SITE_… 또는 VSITE_… (Virtual Site — 물리 사이트 없이 만드는 가상/집계용 사이트)

Examples

import plantpulse.api.v5.dto.request.SiteRequestV5;
import plantpulse.api.v5.dto.response.SiteResponseV5;

SiteRequestV5 req = new SiteRequestV5();
req.setSite_id("SITE_DJ");                 // 대전공장
req.setSite_name("대전 1공장");
req.setLat("36.3504");
req.setLng("127.3845");

SiteResponseV5 created = client.site().create(req);
if (created == null) {
    System.err.println("등록 실패 — site_id 정규식 확인 필요");
}

// Virtual Site (테스트·집계용)
SiteRequestV5 vsite = new SiteRequestV5();
vsite.setSite_id("VSITE_AGG_01");
vsite.setSite_name("집계 가상 사이트");
client.site().create(vsite);

❌ Invalid Examples (all return null in V5)

req.setSite_id("DJ_FACTORY");    // ❌ SITE_ 누락 → E1002
req.setSite_id("site_00001");    // ❌ 소문자 → E1002
req.setSite_id("00001");         // ❌ 접두사 없음 → E1002
req.setSite_id("VVSITE_01");     // ❌ V는 0 또는 1개만 (V?)

2.3 OPC ID

정규식: ^(OPC|EDGE|TEST)_[A-Z0-9_]+$
허용: OPC_…  / EDGE_…  / TEST_…

The OPC ID identifies the physical and logical source of data collection. When you need to separate meanings within the same OPC type, express the hierarchy with _.

Recommended Patterns by OPC Type

OPC Type	Purpose	Recommended ID Prefix
OPC	OPC UA / OPC DA server	OPC_<ua-server-name>_<number>
PLC	Siemens, Mitsubishi, Allen-Bradley, etc.	OPC_PLC_<line>_<number>
MODBUS	Modbus TCP/RTU devices	OPC_MB_<equipment>_<number>
DATABASE	External RDBMS polling	OPC_DB_<system>
FILE	REST API / file import	OPC_FILE_<system>_<number>
VIRTUAL	Testing and simulation	TEST_VIRTUAL_<number>
Edge Gateway	Edge gateway (uses a separate edge_id)	EDGE_<location>_<number>

⚠️ Earlier documents mentioned the API_ prefix, but current server validation allows only OPC_/EDGE_/TEST_. Even for external API/file channels, use the OPC_FILE_… form in the OPC domain.

Examples

import plantpulse.api.v5.dto.request.OPCRequestV5;

OPCRequestV5 req = new OPCRequestV5();
req.setOpc_id("OPC_EDGE_00303");
req.setOpc_name("Line1 Edge Gateway");
req.setOpc_type("PLC");                    // OPC/PLC/MODBUS/DATABASE/FILE/VIRTUAL
req.setOpc_sub_type("SIEMENS_S7");
req.setSite_id("SITE_DJ");
req.setOpc_server_ip("192.168.10.50");
req.setOpc_agent_ip("192.168.10.5");
req.setOpc_agent_port(60000);
client.opc().create(req);

// ERP 연동 — OPC_FILE_ 접두사 (API_ 아님!)
OPCRequestV5 fileChannel = new OPCRequestV5();
fileChannel.setOpc_id("OPC_FILE_ERP_001");
fileChannel.setOpc_type("FILE");
fileChannel.setSite_id("SITE_DJ");
client.opc().create(fileChannel);

// 테스트·시뮬레이션
OPCRequestV5 testOpc = new OPCRequestV5();
testOpc.setOpc_id("TEST_VIRTUAL_001");
testOpc.setOpc_type("VIRTUAL");
testOpc.setSite_id("SITE_DJ");
client.opc().create(testOpc);

2.4 Edge ID

정규식: ^(EDGE|OPC)_[A-Z0-9_]+$

edge_id is the identifier for an edge gateway device. The regex is nearly identical to OPC, but the TEST_ prefix is not allowed.

req.setEdge_id("EDGE_LINE1_01");
req.setEdge_id("OPC_EDGE_00303");   // OPC도 가능
// req.setEdge_id("TEST_EDGE_01");  // ❌ edge_id는 TEST_ 불가

2.5 Asset ID — The Core of the Hierarchy

Assets form a three-level tree: Area → Line → Equipment. We recommend designing IDs that include the type code so the hierarchy is visually apparent.

정규식: ^ASSET_[A-Z0-9_]+$
권장 형식: ASSET_<site-token>_<type-code>_<number>

Asset Type Codes

asset_type value	Meaning	Recommended ID Pattern
A	Area	ASSET_<site>_A_<number>
L	Line	ASSET_<site>_L_<number>
M	Equipment (Machine)	ASSET_<site>_M_<number>

💡 Why the EQUIPMENT code is M: Equipment = Machine. A short, unambiguous single-character code is used for search and filtering.

Standard ID Pattern Example

Area 1 at the Daejeon plant (SITE_DJ), Line 2 within it, and Equipment 3 on that line:

ASSET_DJ_A_0001     ← Area (1구역)
  └ ASSET_DJ_L_0002 ← Line (2번 라인)
      └ ASSET_DJ_M_0003 ← Equipment (3번 설비)

Example — Creating an Asset Tree

import plantpulse.api.v5.dto.request.AssetRequestV5;
import plantpulse.api.v5.dto.response.AssetResponseV5;

// 1) 사이트 직속 Area
AssetRequestV5 area = new AssetRequestV5();
area.setSite_id("SITE_DJ");
area.setParent_asset_id("SITE_DJ");        // 부모는 사이트 ID
area.setAsset_id("ASSET_DJ_A_0001");
area.setAsset_name("조립구역");
area.setAsset_type("A");
client.asset().create(area);

// 2) Area 산하 Line
AssetRequestV5 line = new AssetRequestV5();
line.setSite_id("SITE_DJ");
line.setParent_asset_id("ASSET_DJ_A_0001");  // 부모는 Area
line.setAsset_id("ASSET_DJ_L_0001");
line.setAsset_name("1라인");
line.setAsset_type("L");
client.asset().create(line);

// 3) Line 산하 Equipment
AssetRequestV5 equip = new AssetRequestV5();
equip.setSite_id("SITE_DJ");
equip.setParent_asset_id("ASSET_DJ_L_0001"); // 부모는 Line
equip.setAsset_id("ASSET_DJ_M_0001");
equip.setAsset_name("CNC #1");
equip.setAsset_type("M");
equip.setTable_type("CNC");
client.asset().create(equip);

parent_asset_id Rules

Child Type	parent_asset_id Value
Area (A)	Site ID (e.g., SITE_DJ)
Line (L)	asset_id of the Area (e.g., ASSET_DJ_A_0001)
Equipment (M)	asset_id of the Line (e.g., ASSET_DJ_L_0001)

You can also nest sub-Equipment beneath Equipment (subassemblies). In that case, parent_asset_id is the asset_id of the parent Equipment.

2.6 Tag ID

정규식: ^V*TAG_[A-Z0-9_]+$
허용: TAG_…, VTAG_…, VVTAG_… (V 누적 가능 — Virtual Tag 파생 단계)

A tag is the definition of a data point (sensor value, counter, status, etc.). It has a 1:1 relationship with OPC and a 0:N (optional) relationship with Asset.

Recommended Patterns

Scenario	Pattern	Example
OPC-linked tag	TAG_<part-of-opc-id>_<channel-no>	TAG_EDGE_00303_90007
Self-defined tag	TAG_<domain>_<number>	TAG_PROD_COUNT_001
Virtual Tag (level 1)	VTAG_<purpose>_<number>	VTAG_OEE_LINE1
Virtual Tag (level 2 derivation)	VVTAG_<purpose>_<number>	VVTAG_AGGREGATED_01

💡 Accumulating V in Virtual Tags: Add another V as the derivation depth of formula and aggregation tags increases. A single VTAG_ level is usually sufficient.

Examples

import plantpulse.api.v5.dto.request.TagRequestV5;

TagRequestV5 req = new TagRequestV5();
req.setTag_id("TAG_EDGE_00303_90007");
req.setTag_name("Spindle RPM");
req.setOpc_id("OPC_EDGE_00303");
req.setSite_id("SITE_DJ");
req.setLinked_asset_id("ASSET_DJ_M_0001");
req.setJava_type("Double");
req.setUnit("RPM");
req.setTag_source("OPC");
req.setDescription("Spindle 회전수 (RPM)");
client.tag().create(req);

// Virtual Tag — 라인별 OEE 집계
TagRequestV5 vtag = new TagRequestV5();
vtag.setTag_id("VTAG_OEE_LINE1");
vtag.setTag_name("Line1 OEE");
vtag.setSite_id("SITE_DJ");
vtag.setTag_source("VIRTUAL");
client.tag().create(vtag);

tag_id vs tag_name vs alias_name

Field	Changeable in V5?	Purpose
tag_id	Not changeable (re-create instead)	Unique internal system key. Immutable
tag_name	update() or patchBasic()	Name shown to users
alias_name	patchMetadata()	Alias for mapping to external systems (e.g., HMI tag name)

Where possible, keep tag_id immutable and use tag_name / alias_name for display names. Changing tag_id can cause consistency issues with external time series data.

2.7 AlarmConfig / Employee / Customer / Product / Flow

Server validation is enforced for all of these domains as well. Use the exact, full prefix.

// Alarm Config
AlarmConfigRequestV5 alarm = new AlarmConfigRequestV5();
alarm.setAlarm_config_id("ALARM_CONFIG_TEMP_HIGH_01");
alarm.setSite_id("SITE_DJ");

// Employee
EmployeeRequestV5 emp = new EmployeeRequestV5();
emp.setEmployee_id("EMP_E12345");
emp.setRole_code("OPERATOR");                // OPERATOR, SUPERVISOR 등

// Customer — CUSTOMER_ (전체 단어, CUST_ 아님!)
CustomerRequestV5 cust = new CustomerRequestV5();
cust.setCustomer_id("CUSTOMER_001");
cust.setExternal_customer_id("ERP_C001");

// Product — PRODUCT_ (전체 단어, PROD_ 아님!)
ProductRequestV5 prod = new ProductRequestV5();
prod.setProduct_id("PRODUCT_A001");
prod.setProduct_code("SKU-A001");

// Flow
FlowRequestV5 flow = new FlowRequestV5();
flow.setFlow_id("FLOW_OEE_DAILY");
flow.setSite_id("SITE_DJ");

❌ Common Rejection Cases

cust.setCustomer_id("CUST_001");      // ❌ CUST_ 아님 → E1002
prod.setProduct_id("PROD_A001");      // ❌ PROD_ 아님 → E1002
emp.setEmployee_id("E12345");          // ❌ EMP_ 누락 → E1002
flow.setFlow_id("flow_oee_daily");    // ❌ 소문자 → E1002

2.8 User ID (Login Account)

정규식: ^[A-Z][A-Z0-9_]*$
규칙: 대문자로 시작, 이후 [A-Z0-9_]만 허용

Unlike other domains, there is no fixed prefix, but the first character must be uppercase.

✅ ADMIN
✅ OPERATOR_01
✅ KOPENS_USER
❌ admin              → 소문자 시작
❌ 1USER              → 숫자 시작
❌ _ADMIN             → _ 시작

2.9 Calendar / Order — No Validation

These two domains have no server validation, so the ID format is free-form. Even so, follow the recommended patterns for operational consistency and easier searching.

Calendar

import plantpulse.api.v5.dto.request.CalendarRequestV5;

CalendarRequestV5 cal = new CalendarRequestV5();
cal.setCalendar_id("CAL_20260514_0001");   // CAL_<YYYYMMDD>_<seq>
cal.setSite_id("SITE_DJ");
cal.setAsset_id("ASSET_DJ_M_0001");
cal.setTarget_type("MTN");                  // 점검 일정

target_type	Meaning
MTN	Scheduled maintenance
HOLIDAY	Holiday / non-production
INSPECTION	Inspection
MEETING	Meeting

Order

import plantpulse.api.v5.dto.request.OrderRequestV5;

OrderRequestV5 order = new OrderRequestV5();
order.setOrder_id("ORD_20260514_001");      // ORD_<YYYYMMDD>_<seq>
order.setSite_id("SITE_DJ");
order.setAsset_id("ASSET_DJ_M_0001");
order.setCustomer_id("CUSTOMER_001");        // CUSTOMER_ 주의!
order.setProduct_id("PRODUCT_A001");         // PRODUCT_ 주의!
order.setEmployee_id("EMP_E12345");
order.setTarget_units(500);

Work order status (ISA-88): WAIT → START → END / ABORTED (for details, see Order Service)

2.10 ID Design Best Practices

Recommendations

1. Keep IDs immutable — Never change an ID once it has been assigned. If a change is required, migrate to a new ID.
2. Express the hierarchy in the ID — Including hierarchy information in the ID, as in ASSET_<site>_<type>_<number>, improves operational visibility.
3. Use a fixed number of digits — Pad the numeric portion, as in 0001 and 00001, to preserve sort order.
4. Stick to uppercase and underscores — Avoid mixed case across the system and maintain the [A-Z0-9_] pattern.
5. Keep external system IDs in a separate field — Store the original ERP/MES ID in the external_*_id field and keep the PlantPulse ID on its own scheme.

Patterns to Avoid

• ❌ Korean characters, spaces, or special characters — ASSET_라인1, OPC 001
• ❌ IDs that are too short or meaningless — S1, A, T01
• ❌ Missing prefixes or incorrect abbreviations — CUST_001 (correct: CUSTOMER_001), PROD_A001 (correct: PRODUCT_A001)
• ❌ Meaning hard-coded into the ID so it cannot be changed — ASSET_DJ_L_OLD_BROKEN_LINE

2.11 Checking Validation Failure Responses

On validation failure, V5 methods return null (or false). Detailed error information is available in the envelope.

import plantpulse.api.v5.service.BaseServiceV5;
import plantpulse.json.JSONObject;

// V5 서비스 내부는 envelope를 외부에 노출하지 않으나,
// 디버그 모드를 켜면 로그에 출력됩니다.
client = new APIClient_V5(proto, host, port, user, token, true);  // debug=true

Example response envelope:

{
  "_status": "ERROR",
  "_code": "E1002",
  "_message": "validation failed: site_id must match ^V?SITE_[A-Z0-9_]+$",
  "_http_status": 400
}

For detailed error codes, see Response Format and Error Handling.

Next Steps

• Response Format and Error Handling — Error code mapping
• Site Service — Start by creating a site
• Asset Service — Build the asset tree
• Tag Service — Define data points