8. Tag Service

Access via client.tag(). A Tag is the definition (metadata) of a data point (sensor value, counter, status). In V5, the 10 tab-specific PATCH operations let you safely apply partial updates to detailed settings such as alarms, aggregation, and calculations.

ID rule: The TAG_ prefix is required. See Domain ID Rules for details.

8.1 Method Overview

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 Updates (Core V5 Feature)

All 10 PATCH operations follow the null field = no change rule (handled by COALESCE in the server-side DAO). Some PATCH operations also trigger automatic 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`	`deployCalculation` re-invoked
`patchSampling(id, TagSamplingPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/sampling`	—
`patchAggregation(id, TagAggregationPatchRequestV5)`	PATCH	`/api/v5/tag/{id}/aggregation`	`deployAggregation` re-invoked
`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/Update)

Field	Type	Description
`tag_id`	String	Tag ID (PK, `TAG_` required)
`tag_name`	String	Display name
`opc_id`	String	Parent OPC (FK)
`site_id`	String	Parent site
`linked_asset_id`	String	Linked asset (Equipment)
`java_type`	String	Value data type — `Double`, `Float`, `Int`, `Long`, `Short`, `Boolean`, `String`, `Date`
`unit`	String	Unit (e.g. `℃`, `RPM`, `kPa`)
`tag_source`	String	Data source (e.g. `OPC`, `API`, `FILE`)
`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`	Priority (1–10)
`tag_source`	Source
`use_metric`	Whether used as a metric
`rate`	Collection interval (ms)
`rw`	Read/write (`R`/`W`/`RW`)
`alias_name`	Alias
`min_value` / `max_value`	Measurement range
`display_format`	UI display format
`unit`	Unit
`number_round` / `number_scale`	Rounding / decimal places
`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 suppression window (minutes)
`user_defined_alarm_class`	User-defined class
`use_alarm`	Alarm enabled (`Y`/`N`)
`recieve_me`, `recieve_others`	Notify self / others
`send_email`, `send_sms`	Email/SMS delivery

TagCalculationPatchRequestV5 (Calculation)

Field	Description
`calculation_eql`	EQL expression
`use_calculation`	Enabled (`Y`/`N`)

TagSamplingPatchRequestV5 (Sampling)

Field	Description
`use_sampling`	Enabled (`Y`/`N`)

TagAggregationPatchRequestV5 (Aggregation)

Field	Description
`use_aggregation`	Enabled
`aggregation_1_minutes` – `aggregation_1_hours`	Enable flags for the 5 intervals

TagAiPatchRequestV5 (AI Anomaly Diagnosis)

Field	Description
`use_target`	Training target
`use_category`	Use category classification

TagPublishPatchRequestV5 (Publishing)

Field	Description
`publish_mqtt`	MQTT publishing (`Y`/`N`)
`publish_kafka`	Kafka publishing (`Y`/`N`)

TagAttributePatchRequestV5 (Notes)

Field	Description
`note`	Free-form memo

TagLinkPatchRequestV5 (Equipment Mapping)

Field	Description
`linked_asset_id`	Linked asset ID. Empty string = unmap

8.4 Usage Examples

Creating a Tag (OPC-Linked 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("ASSET_DJ_M_0001");
req.setJava_type("Double");
req.setUnit("RPM");
req.setTag_source("OPC");
req.setDescription("Spindle 회전수");

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

Single Lookup / 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");

Listing 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("ASSET_DJ_M_0001");

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("ASSET_DJ_M_0001");

Full Update (PUT)

When resending all fields:

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 Update — 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 Update — patchAlarm

Setting alarm thresholds (triggers CEP/EQL redeployment on the server):

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 Update — patchMetadata

Changing the 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 Update — patchCalculation

Attaching an EQL formula (re-invokes deployCalculation on the server):

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 Update — patchAggregation

Enabling aggregation for the 5 intervals (re-invokes 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 Update — 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 Update — patchLink (Asset Mapping)

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

// 자산에 연결
TagLinkPatchRequestV5 link = new TagLinkPatchRequestV5();
link.setLinked_asset_id("ASSET_DJ_M_0001");
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 Usage Scenarios

Scenario — Auto-Classifying New Line Tags and Applying Bulk Settings

// 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("ASSET_DJ_M_CNC1");
    } else if (name.contains("CNC2")) {
        link.setLinked_asset_id("ASSET_DJ_M_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 — Enabling Aggregation and Publishing Together

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 — Querying alarm events
Path Service — Asset paths for tags

8.1 Method Overview​

CRUD​

List / Count​

PATCH — Tab-Specific Partial Updates (Core V5 Feature)​

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

8.3 PATCH DTO Fields (By Tab)​

TagBasicPatchRequestV5 (Basic)​

TagMetadataPatchRequestV5 (Metadata)​

TagAlarmPatchRequestV5 (Alarm)​

TagCalculationPatchRequestV5 (Calculation)​

TagSamplingPatchRequestV5 (Sampling)​

TagAggregationPatchRequestV5 (Aggregation)​

TagAiPatchRequestV5 (AI Anomaly Diagnosis)​

TagPublishPatchRequestV5 (Publishing)​

TagAttributePatchRequestV5 (Notes)​

TagLinkPatchRequestV5 (Equipment Mapping)​

8.4 Usage Examples​

Creating a Tag (OPC-Linked Tag)​

Single Lookup / Existence Check​

Listing by Site / OPC / Asset​

Count​

Full Update (PUT)​

Partial Update — patchBasic​

Partial Update — patchAlarm​

Partial Update — patchMetadata​

Partial Update — patchCalculation​

Partial Update — patchAggregation​

Partial Update — patchPublish​

Partial Update — patchLink (Asset Mapping)​

Deletion​

8.5 Usage Scenarios​

Scenario — Auto-Classifying New Line Tags and Applying Bulk Settings​

Scenario — Enabling Aggregation and Publishing Together​

Next Steps​