Batch Set Device Tags

Tool Name: Not defined in the current tool contract

Risk Level: Write (medium-risk)

Execution Mode: Synchronous

Category: Device Management (Tags)

Quick Start (Copy & Use)

Summary: Append, replace, or clear the tag set for 1-1,000 devices in one atomic request.

Prerequisites: DeviceIds, TagIds, and Mode. The account requires Device Tag feature read/write permission.

Success Criteria: StatusCode == 200 and ErrorMessage is empty. All selected devices change, or none do; there is no per-device result payload.

What to Do Next: Use List Devices to verify current assignments after an uncertain write.

Minimal Request Example:

{
  "DeviceIds": ["a8f3d91c72b44e5fa103c892d0b74561", "4c7e2a90f15d438bb617e9206ab34fd8"],
  "TagIds": [4102, 4103],
  "Mode": "append"
}

Minimal Response Example:

{
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Append Tags

When to use: Keep existing assignments and add tags.

{
  "DeviceIds": ["a8f3d91c72b44e5fa103c892d0b74561"],
  "TagIds": [4102],
  "Mode": "append"
}

Recipe 2: Replace the Complete Tag Set

When to use: The supplied tags are the complete desired assignment.

{
  "DeviceIds": ["a8f3d91c72b44e5fa103c892d0b74561"],
  "TagIds": [4102, 4103],
  "Mode": "replace"
}

Recipe 3: Clear All Tags

When to use: Every selected device should have no tag assignments.

{
  "DeviceIds": ["a8f3d91c72b44e5fa103c892d0b74561"],
  "TagIds": [],
  "Mode": "replace"
}

1. Overview

1.1 Description

Changes device tag assignments synchronously. The full selection succeeds or fails as one unit.

1.2 When to Use

• Add classifications while retaining existing tags.
• Replace or clear assignments on multiple devices.

1.3 Execution Mode and Response

This operation is synchronous and returns only standard status fields. An empty ErrorMessage means the selected devices changed as a unit; it does not return the final tag sets.

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Similar Tools

Use Create Tags for tag definitions; use this tool only to change assignments.

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceIds`

Obtain IDs from device lookup. Blank and duplicate IDs are rejected.

`TagIds`

Obtain existing IDs with Batch Resolve Tag IDs by Name, or create missing tags first. append requires at least one ID. replace permits an empty list to clear tags. The final tag count on every selected device must not exceed five.

`Mode`

append retains current tags and adds TagIds. replace removes all current tags not in TagIds and makes the supplied list the complete set.

2.3 Parameter Combination Logic

• append plus [] is invalid.
• replace plus [] clears all tags.
• The request is atomic across the selected devices.

3. Outputs

3.1 Response Examples

The Quick Start response is the full successful output.

Invalid append request:

{
  "Hint": "Provide at least one Tag ID or use replace with an empty list to clear tags.",
  "Retryable": false,
  "OriginalStatusCode": 0,
  "StatusCode": -1,
  "ErrorMessage": "TagIds cannot be empty in append mode."
}

3.2 Field Descriptions

3.3 Result Semantics

There is no Results array. A successful response means all selected devices changed; a failed response means none did.

4. Examples

4.1 Too Many Tags

More than five tag IDs returns StatusCode -1 with TagIds must contain 0-5 IDs.

4.2 Duplicate Device ID

Duplicate device entries are rejected with DeviceIds contains duplicates.; they are not de-duplicated automatically.

4.3 Final Tag Limit

In append mode, an upstream failure can direct the caller to reduce the final tag count to five or fewer on every selected device.

5. Error Handling

5.1 StatusCode Semantics

5.2 Common Errors

5.3 Retry Decision

append does not duplicate assignments. Before repeating an uncertain replace, verify current tags because it removes every tag omitted from TagIds.

6. Best Practices

6.1 Security

For replace, validate the entire desired set before submitting because omitted tags are removed.

6.2 Idempotency

Conditional. append does not duplicate assignments. A repeat replace is safe only after verifying the current complete tag set.

7. Related Tools

8. Tool Chains

8.1 Resolve, Assign, and Verify

Batch Resolve Tag IDs by Name -> Batch Set Device Tags -> List Devices

Use the final read to verify state after an uncertain write.