Tool Name: airdroid_business_tag_batch_create
Risk Level: 🟡 Write (medium-risk write: creates org-visible tags)
Execution Mode: âš¡ Synchronous
Category: Device Management (Tags)
Quick Start (Copy & Use)
Summary: Create one or more organization device tags and return each new tag’s ID and final name.
Prerequisites: TagNames (1–100 distinct strings, 1–30 characters after trim).
Success Criteria: StatusCode == 200 and ErrorMessage is empty and Tags length matches the number of names you submitted. Do not treat StatusCode == 200 alone as success—always check ErrorMessage.
What to Do Next: Pass returned tag_id values to Set Tags or store them for later device assignment.
Minimal Request Example:
{
"TagNames": [
"Chicago Warehouse",
"Priority Devices"
]
}
Minimal Response Example:
{
"Tags": [
{ "tag_id": 4102, "name": "Chicago Warehouse" },
{ "tag_id": 4103, "name": "Priority Devices" }
],
"Hint": "",
"Retryable": false,
"OriginalStatusCode": 200,
"StatusCode": 200,
"ErrorMessage": ""
}
Recipes (Common Recipes)
Recipe 1: Create a Single Tag
When to use: One new label for later device assignment.
{
"TagNames": ["Chicago Warehouse"]
}
Recipe 2: Create Several Tags in One Call
When to use: Bootstrap a small tag set (stay within 100 names per call).
{
"TagNames": ["Sales", "VIP", "Loaner Pool"]
}
Recipe 3: Name Already Exists (Do Not Recreate)
When to use: You are unsure whether the tag exists.
- Prefer Batch Resolve Tag IDs by Name first to get existing IDs.
- Call Create Tags only for names that are still missing.
- If Create Tags returns StatusCode 200 with a non-empty ErrorMessage and the Hint about existing names, use Batch Resolve Tag IDs by Name—do not retry the same names. The exact ErrorMessage text comes from the upstream service and is not fixed.
1. Overview
1.1 Description
Creates organization-level device tags. On success, returns tag_id and final saved name for every requested name that was created.
1.2 When to Use
- Add new classification tags before assigning them to devices
- Prepare tag IDs for Set Tags workflows
- Bulk-create a predefined tag vocabulary
1.3 Execution Mode and Response
Synchronous. Tags are created immediately; results appear in Tags when ErrorMessage is empty.
1.4 Prerequisites
| Condition | Description | How to Check |
|---|---|---|
| Device Tag write permission | Account role must allow tag management | Admin Console roles |
| Unique names | Each name must not already exist in the organization | Use Batch Resolve Tag IDs by Name first if unsure |
1.5 Prerequisite Tools
| Tool | Purpose | Required? |
|---|---|---|
| Batch Resolve Tag IDs by Name | Look up existing tag IDs by name | When names may already exist |
1.6 Similar Tools
| Tool | Use instead when |
|---|---|
| Batch Resolve Tag IDs by Name | You only need IDs for tags that already exist |
| Set Tags | Tags exist and you want to assign them to a device |
2. Inputs
2.1 Parameter List
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| TagNames | string-array | Yes | — | Tag names to create (1–100 items) |
2.2 Parameter Details
`TagNames`
- Type: string-array (JSON array of strings)
- Rules:
- 1–100 names per call
- Each name: 1–30 characters after leading/trailing spaces are removed
- No control characters (for example newline \n, tab \t, or other ASCII control codes)
- No duplicates after trimming
- Duplicate in organization: If any name already exists, the call fails (ErrorMessage non-empty, Tags empty). Use Batch Resolve Tag IDs by Name for existing tags.
- Fill in a GI workflow node:
- Constants: Enter a JSON string array in the node input, for example ["Chicago Warehouse", "Priority Devices"].
- Reference upstream output: Map a prior node field into the array when your workflow supplies dynamic names, for example ["{{upstream.new_tag_name}}"] or a merged list built in an earlier step—keep each item a string and respect the 1–100 / 1–30 character rules.
- Example:
["Chicago Warehouse", "Priority Devices"]
2.3 Parameter Combination Logic
- Only TagNames is required; one request either creates every name or fails as a whole—there is no partial success.
3. Outputs
3.1 Response Examples
Success:
{
"Tags": [
{ "tag_id": 4102, "name": "Chicago Warehouse" }
],
"Hint": "",
"Retryable": false,
"OriginalStatusCode": 200,
"StatusCode": 200,
"ErrorMessage": ""
}
Business failure (duplicate name):
When the upstream business code indicates a duplicate name, StatusCode stays 200, Tags is [], and Hint (not a fixed ErrorMessage string) tells you to resolve existing IDs. **ErrorMessage is copied from the upstream msg field and may vary by locale or wording—use Hint and empty Tags to detect this case; do not match ErrorMessage text literally.
{
"Tags": [],
"Hint": "One or more tag names already exist; use 'Batch Resolve Tag IDs by Name' to obtain existing tag IDs instead of creating duplicates.",
"Retryable": false,
"OriginalStatusCode": 200,
"StatusCode": 200,
"ErrorMessage": "<upstream message; not a fixed tool string>"
}
Validation failure:
{
"Tags": [],
"Hint": "Provide 1-100 distinct tag names, then retry.",
"Retryable": false,
"OriginalStatusCode": 0,
"StatusCode": -1,
"ErrorMessage": "TagNames must contain 1-100 names."
}
3.2 Field Descriptions
| Field | Type | Description |
|---|---|---|
| Tags | object-array | On success only: { tag_id, name } per created tag. [] whenever ErrorMessage is non-empty (business or validation failure). |
| StatusCode | number | 200 = call finished (check ErrorMessage); -1 = local validation; 500 = upstream HTTP/auth/transport or tool failure (auth/permission failures use 500, not 403—see OriginalStatusCode) |
| ErrorMessage | string | Empty on success; otherwise failure reason |
| Hint | string | Suggested next step when failed; empty on success |
| Retryable | bool | Whether repeating the same request may help |
| OriginalStatusCode | number | HTTP status from the service; 0 if no response |
3.3 Status Values in `Tags`
Each successful item includes the final saved name (after trim) and tag_id as a positive integer (not boolean, not zero).
4. Examples
4.1 Create Two Tags
Request:
{ "TagNames": ["Chicago Warehouse", "Priority Devices"] }
Response: See Quick Start minimal response.
4.2 Duplicate Name After Trim
Request:
{ "TagNames": [" Sales ", "Sales"] }
Response: StatusCode -1, ErrorMessage about duplicate after trimming.
4.3 Existing Organization Name
Request:
{ "TagNames": ["Existing Label"] }
Response: StatusCode 200, non-empty ErrorMessage, empty Tags, Hint points to Batch Resolve Tag IDs by Name.
5. Error Handling
5.1 StatusCode Semantics (This Action)
| StatusCode | Meaning | Agent action |
|---|---|---|
| -1 | Local validation failed | Fix TagNames; do not retry unchanged |
| 200 | Request completed | Empty ErrorMessage = success; non-empty = business failure (e.g. duplicate name) |
| 500 | Upstream HTTP error, auth/permission failure, timeout, network, malformed response, or incomplete success payload | Read OriginalStatusCode, Hint, and Retryable; for this write action, verify whether tags were created before retrying |
HTTP mapping (tool output uses StatusCode 500, not 403/401 on the tool layer):
| Scenario | StatusCode | OriginalStatusCode | Typical Hint direction | Retryable |
|---|---|---|---|---|
| Invalid or expired token | 500 | 401 | Refresh or re-authorize credential | false |
| Missing tag write permission / scope | 500 | 403 | Request required role permission | false |
| Upstream rate limit | 500 | 429 | Wait 10–30 seconds, retry once | true |
| Transient upstream 5xx | 500 | 502/503/504 | Check service health | may be true |
5.2 Common Errors
| StatusCode | ErrorMessage (example) | Cause | Fix |
|---|---|---|---|
| -1 | TagNames must contain 1-100 names. | Count out of range | Send 1–100 names |
| -1 | Every TagNames item must be a string. | Non-string array element | Use string items only |
| -1 | Each tag name must be 1-30 characters... | Invalid name or control character | Shorten or remove control chars |
| -1 | TagNames contains a duplicate after trimming. | Duplicate in array | Deduplicate input |
| 200 | <upstream msg> (wording not fixed) | Name already exists in org | Follow Hint → Batch Resolve Tag IDs by Name |
| 500 | Upstream reported success without complete tag records. | Success payload incomplete | Verify whether tags were created before retry |
| 500 | Request timed out before a usable response was received. | Timeout on POST | Retryable is false for Create Tags—check org tags before resubmitting |
5.3 Agent Self-Healing
| StatusCode | Auto-retry | Notes |
|---|---|---|
| -1 | No | Fix parameters |
| 200 + ErrorMessage | No | Do not recreate; resolve or pick new names |
| 500 | Rarely | For Create Tags, Retryable is usually false (including POST timeout). Only retry when Retryable is true and you confirmed tags were not created |
6. Best Practices
6.1 Performance
- Create up to 100 tags per call; batch new names instead of one call per tag when safe.
6.2 Security
- 🟡 Write operation: new tags are visible org-wide; avoid generic names that collide with existing labels.
6.3 Idempotency
- Not idempotent for duplicate names (call fails rather than returning existing IDs).
- A successful create followed by the same names again hits business failure—it does not return the existing IDs.
- Re-running with the same new names after success may fail if names now exist.
7. Related Tools
| Tool | Role |
|---|---|
| Batch Resolve Tag IDs by Name | Resolve existing names → IDs |
| Set Tags | Assign tag IDs to a device |
| Delete Tag | Remove a tag org-wide |
8. Tool Chains
8.1 Create Then Assign
Create Tags → Set Tags (use tag_id from Tags[])
8.2 Resolve-or-Create Pattern
Batch Resolve Tag IDs by Name → Create Tags (only missing names) → Set Tags
Appendix Reference:
Leave a Reply.