8. Tag Service

Access via client.tag(). A tag is a definition (metadata) of a data point (sensor value, counter, state). In V5, 10 types of tab-specific PATCH operations allow for the safe partial modification of detailed settings such as alarms, aggregation, and calculations.

ID Rule: TAG_ prefix is mandatory. For more details, refer to Domain ID Rules.

8.1 Method List

CRUD

Method	Return Type	HTTP	Endpoint
`create(TagRequestV5)`	`TagResponseV5` or `null`	POST	`/api/v5/tag`
`update(tag_id, TagRequestV5)`	`TagResponseV5` or `null`	PUT	`/api/v5/tag/{id}`
`delete(tag_id)`	`boolean`	DELETE	`/api/v5/tag/{id}`
`get(tag_id)`	`TagResponseV5` or `null`	GET	`/api/v5/tag/{id}`
`exists(tag_id)`	`boolean`	GET	`/api/v5/tag/{id}/exists`

List / Count

Method	Return Type	HTTP	Endpoint
`list()`	`List<TagResponseV5>`	GET	`/api/v5/tag`
`listBySite(site_id)`	`List<TagResponseV5>`	GET	`/api/v5/tag?site_id=...`
`listByOpc(opc_id)`	`List<TagResponseV5>`	GET	`/api/v5/tag?opc_id=...`
`listByAsset(asset_id)`	`List<TagResponseV5>`	GET	`/api/v5/tag?asset_id=...`
`count()`	`long`	GET	`/api/v5/tag/count`
`countBySite(site_id)`	`long`	GET	`/api/v5/tag/count?site_id=...`
`countByOpc(opc_id)`	`long`	GET	`/api/v5/tag/count?opc_id=...`
`countByAsset(asset_id)`	`long`	GET	`/api/v5/tag/count?asset_id=...`

PATCH — Tab-specific Partial Modification (V5 Core Feature)

The 10 types of PATCH follow the rule: null field = no change (handled by COALESCE in the server DAO). Some PATCH operations automatically trigger CEP/EQL redeployment on the server.

Method	HTTP	Endpoint	Side Effect
`patchBasic(id, TagBasicPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/basic`	—
`patchAlarm(id, TagAlarmPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/alarm`	CEP/EQL Redeployment
`patchMetadata(id, TagMetadataPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/metadata`	—
`patchCalculation(id, TagCalculationPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/calculation`	Recalls `deployCalculation`
`patchSampling(id, TagSamplingPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/sampling`	—
`patchAggregation(id, TagAggregationPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/aggregation`	Recalls `deployAggregation`
`patchAi(id, TagAiPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/ai`	—
`patchPublish(id, TagPublishPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/publish`	—
`patchAttribute(id, TagAttributePatchRequestV5)`	PATCH	`/api/v5/tag/{id}/attribute`	—
`patchLink(id, TagLinkPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/link`	—

8.2 TagRequestV5 / TagResponseV5 (For Full Registration/Modification)

Field	Type	Description
`tag_id`	String	Tag ID (PK, `TAG_` mandatory)
`tag_name`	String	Display Name
`opc_id`	String	Associated OPC (FK)
`site_id`	String	Associated Site
`linked_asset_id`	String	Connected Equipment
`java_type`	String	Value Data Type — `Double`, `Float`, `Int`, `Long`, `Short`, `Boolean`, `String`, `Date`
`unit`	String	Unit (e.g., `℃`, `RPM`, `kPa`)
`source_type`	String	(Response Only) Source Type — Derived from the tag's connection protocol (`OPC`/`PLC`/`MODBUS`/`DATABASE`/`MESSAGING`/`API`/`SYSTEM`)
`description`	String	Description

8.3 PATCH DTO Fields (By Tab)

TagBasicPatchRequestV5 (Basic)

Field	Description
`tag_name`	Display Name
`java_type`	Data Type
`description`	Description

TagMetadataPatchRequestV5 (Metadata)

Field	Description
`tag_type`	Tag Type
`importance`	Importance (1~10)
`use_metric`	Metric Usage Enable
`rate`	Reception Cycle (ms) — For recording. Actual polling interval is determined in the connection settings
`rw`	Read/Write (`R`/`W`/`RW`)
`alias_name`	Alias
`min_value` / `max_value`	Scale reference for gauge charts — Does not validate values
`display_format`	UI Display Format
`unit`	Unit
`number_round` / `number_scale`	Rounding / Decimal Place
`io_address` / `source_tag_name`	I/O Address · Original Tag Name
`lat` / `lng`	Latitude/Longitude

TagAlarmPatchRequestV5 (Alarm)

Field	Description
`trip_hi`, `hi_hi`, `hi`, `lo`, `lo_lo`, `trip_lo`	Thresholds (6 levels)
`bool_true`, `bool_true_priority`, `bool_true_message`	Boolean TRUE alarm
`bool_false`, `bool_false_priority`, `bool_false_message`	Boolean FALSE alarm
`band_message`	Normal band message
`duplicate_check_minutes`	Duplicate alarm block minutes
`user_defined_alarm_class`	User-defined class
`use_alarm`	Alarm Enable (`Y`/`N`)
`recieve_me`, `recieve_others`	Self/Others reception
`send_email`, `send_sms`	Email/SMS transmission

TagCalculationPatchRequestV5 (Calculation)

Field	Description
`calculation_eql`	EQL Expression
`use_calculation`	Usage Enable (`Y`/`N`)

TagSamplingPatchRequestV5 (Sampling)

Field	Description
`use_sampling`	Usage Enable (`Y`/`N`)

TagAggregationPatchRequestV5 (Aggregation)

Field	Description
`use_aggregation`	Usage Enable
`aggregation_1_minutes` ~ `aggregation_1_hours`	5 types of cycle activation flags

TagAiPatchRequestV5 (AI Anomaly Diagnosis)

Field	Description
`use_target`	Multivariate correlation analysis target (`Y`/`N`) — Analysis is activated when there are 2 or more targets per equipment
`use_category`	Branch column for splitting multivariate data (`Y`/`N`) — Recipe, equipment mode, operation, etc.

TagPublishPatchRequestV5 (Publish)

Field	Description
`publish_mqtt`	MQTT Publish (`Y`/`N`)
`publish_kafka`	Kafka Publish (`Y`/`N`) — Must be `Y` for OPC-UA server plugins to receive data

TagAttributePatchRequestV5 (Note)

Field	Description
`note`	Free-form memo

TagLinkPatchRequestV5 (Equipment Mapping)

Field	Description
`linked_asset_id`	Connected Asset ID. Empty string = Unmap

8.4 Usage Examples

Tag Creation (OPC Connection Tag)

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

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("EQUIPMENT_000001");
req.setJava_type("Double");
req.setUnit("RPM");
req.setDescription("Spindle 회전수");

TagResponseV5 created = client.tag().create(req);

Single Retrieval / Existence Check

TagResponseV5 tag = client.tag().get("TAG_EDGE_00303_90007");
if (tag != null) {
    System.out.println(tag.getTag_name() + " (" + tag.getUnit() + ")");
}

boolean exists = client.tag().exists("TAG_EDGE_00303_90007");

Lists by Site / OPC / Asset

List<TagResponseV5> siteTags  = client.tag().listBySite("SITE_DJ");
List<TagResponseV5> opcTags   = client.tag().listByOpc("OPC_PLC_L1_001");
List<TagResponseV5> assetTags = client.tag().listByAsset("EQUIPMENT_000001");

Count

long total       = client.tag().count();
long siteTotal   = client.tag().countBySite("SITE_DJ");
long opcTotal    = client.tag().countByOpc("OPC_PLC_L1_001");
long assetTotal  = client.tag().countByAsset("EQUIPMENT_000001");

Full Modification (PUT)

When sending all fields again:

TagRequestV5 update = new TagRequestV5();
update.setTag_id("TAG_EDGE_00303_90007");
update.setTag_name("Spindle RPM (변경됨)");
update.setOpc_id("OPC_EDGE_00303");
update.setSite_id("SITE_DJ");
update.setJava_type("Double");
update.setUnit("RPM");
// ... 모든 필드 ...
client.tag().update("TAG_EDGE_00303_90007", update);

Partial Modification — patchBasic

Changing only the name and description:

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

TagBasicPatchRequestV5 patch = new TagBasicPatchRequestV5();
patch.setTag_name("Spindle RPM (보정 후)");
patch.setDescription("2026-05-14 보정 적용");
// java_type 은 null 로 두면 변경 안 함
client.tag().patchBasic("TAG_EDGE_00303_90007", patch);

Partial Modification — patchAlarm

Setting alarm thresholds (Server performs CEP/EQL redeployment):

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

TagAlarmPatchRequestV5 alarm = new TagAlarmPatchRequestV5();
alarm.setUse_alarm("Y");
alarm.setLo_lo("0");
alarm.setLo("10");
alarm.setHi("80");
alarm.setHi_hi("95");
alarm.setTrip_hi("100");
alarm.setDuplicate_check_minutes(5);
alarm.setSend_email("Y");
client.tag().patchAlarm("TAG_EDGE_00303_90007", alarm);

Partial Modification — patchMetadata

Changing alias and display format:

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

TagMetadataPatchRequestV5 meta = new TagMetadataPatchRequestV5();
meta.setAlias_name("HMI_TAG_RPM_01");
meta.setDisplay_format("#,##0");
meta.setNumber_scale(0);
meta.setImportance(8);
client.tag().patchMetadata("TAG_EDGE_00303_90007", meta);

Partial Modification — patchCalculation

Attaching EQL formula (Server recalls deployCalculation):

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

TagCalculationPatchRequestV5 calc = new TagCalculationPatchRequestV5();
calc.setUse_calculation("Y");
calc.setCalculation_eql("VAL('TAG_RAW_RPM') * 60 / 1000");   // 가상의 EQL
client.tag().patchCalculation("TAG_EDGE_00303_90007", calc);

Partial Modification — patchAggregation

Activating 5-cycle aggregation (Recalls deployAggregation):

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

TagAggregationPatchRequestV5 agg = new TagAggregationPatchRequestV5();
agg.setUse_aggregation("Y");
agg.setAggregation_1_minutes("Y");
agg.setAggregation_5_minutes("Y");
agg.setAggregation_10_minutes("Y");
agg.setAggregation_30_minutes("N");
agg.setAggregation_1_hours("Y");
client.tag().patchAggregation("TAG_EDGE_00303_90007", agg);

Partial Modification — patchPublish

Toggling MQTT/Kafka publishing:

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

TagPublishPatchRequestV5 pub = new TagPublishPatchRequestV5();
pub.setPublish_mqtt("Y");
pub.setPublish_kafka("N");
client.tag().patchPublish("TAG_EDGE_00303_90007", pub);

Partial Modification — patchLink (Asset Mapping)

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

// 자산에 연결
TagLinkPatchRequestV5 link = new TagLinkPatchRequestV5();
link.setLinked_asset_id("EQUIPMENT_000001");
client.tag().patchLink("TAG_EDGE_00303_90007", link);

// 매핑 해제 — 빈 문자열
TagLinkPatchRequestV5 unlink = new TagLinkPatchRequestV5();
unlink.setLinked_asset_id("");
client.tag().patchLink("TAG_EDGE_00303_90007", unlink);

Deletion

boolean ok = client.tag().delete("TAG_EDGE_00303_90007");

8.5 Application Scenarios

Scenario — Automatic classification and bulk setting of tags for a new line

// 1) 자동 등록된 태그 목록 (OPC 연결 직후)
List<TagResponseV5> tags = client.tag().listByOpc("OPC_PLC_L2_001");

// 2) 이름 패턴으로 자산 자동 연결 + 알람 일괄 설정
for (TagResponseV5 t : tags) {
    String name = t.getTag_name();

    // 자산 매핑
    TagLinkPatchRequestV5 link = new TagLinkPatchRequestV5();
    if (name.contains("CNC1")) {
        link.setLinked_asset_id("EQUIPMENT_CNC1");
    } else if (name.contains("CNC2")) {
        link.setLinked_asset_id("EQUIPMENT_CNC2");
    } else {
        continue;
    }
    client.tag().patchLink(t.getTag_id(), link);

    // 온도 태그는 알람 임계치 자동 설정
    if (name.endsWith("_TEMP")) {
        TagAlarmPatchRequestV5 alarm = new TagAlarmPatchRequestV5();
        alarm.setUse_alarm("Y");
        alarm.setHi("80");
        alarm.setHi_hi("95");
        client.tag().patchAlarm(t.getTag_id(), alarm);
    }
}

Scenario — Simultaneous activation of aggregation and publishing

String tagId = "TAG_EDGE_00303_90007";

TagAggregationPatchRequestV5 agg = new TagAggregationPatchRequestV5();
agg.setUse_aggregation("Y");
agg.setAggregation_1_minutes("Y");
agg.setAggregation_1_hours("Y");
client.tag().patchAggregation(tagId, agg);

TagPublishPatchRequestV5 pub = new TagPublishPatchRequestV5();
pub.setPublish_mqtt("Y");
client.tag().patchPublish(tagId, pub);

Next Steps

Alarm Service — Alarm event retrieval
Path Service — Asset path of tags

8.1 Method List​

CRUD​

List / Count​

PATCH — Tab-specific Partial Modification (V5 Core Feature)​

8.2 TagRequestV5 / TagResponseV5 (For Full Registration/Modification)​

8.3 PATCH DTO Fields (By Tab)​

TagBasicPatchRequestV5 (Basic)​

TagMetadataPatchRequestV5 (Metadata)​

TagAlarmPatchRequestV5 (Alarm)​

TagCalculationPatchRequestV5 (Calculation)​

TagSamplingPatchRequestV5 (Sampling)​

TagAggregationPatchRequestV5 (Aggregation)​

TagAiPatchRequestV5 (AI Anomaly Diagnosis)​

TagPublishPatchRequestV5 (Publish)​

TagAttributePatchRequestV5 (Note)​

TagLinkPatchRequestV5 (Equipment Mapping)​

8.4 Usage Examples​

Tag Creation (OPC Connection Tag)​

Single Retrieval / Existence Check​

Lists by Site / OPC / Asset​

Count​

Full Modification (PUT)​

Partial Modification — patchBasic​

Partial Modification — patchAlarm​

Partial Modification — patchMetadata​

Partial Modification — patchCalculation​

Partial Modification — patchAggregation​

Partial Modification — patchPublish​

Partial Modification — patchLink (Asset Mapping)​

Deletion​

8.5 Application Scenarios​

Scenario — Automatic classification and bulk setting of tags for a new line​

Scenario — Simultaneous activation of aggregation and publishing​

Next Steps​