Tag types
A tag type (the API calls it a UDT) is a template of members and parameters; an instance is a tag tree built from it. All routes live under /api/v1/udt. Reading needs viewer, changing needs engineer. Background in Tag types.
Routes
| Method and path | Role | Purpose |
|---|---|---|
GET /api/v1/udt/types | viewer | Every type |
GET /api/v1/udt/types/{id} | viewer | One type with its members and parameters |
POST /api/v1/udt/types | engineer | Create a type |
PATCH /api/v1/udt/types/{id} | engineer | Update a type |
POST /api/v1/udt/types/{id}/move | engineer | Move a type to another folder |
DELETE /api/v1/udt/types/{id} | engineer | Delete a type |
GET /api/v1/udt/types/export?path= | viewer | Export the types at or under a path |
POST /api/v1/udt/types/import | engineer | Import types under a target path |
POST /api/v1/udt/folders | engineer | Create a type folder |
PATCH /api/v1/udt/folders/{path} | engineer | Rename a type folder |
POST /api/v1/udt/folders/move | engineer | Move a type folder |
DELETE /api/v1/udt/folders/{path} | engineer | Delete a type folder |
GET /api/v1/udt/instances | viewer | Every instance |
GET /api/v1/udt/instances/{id} | viewer | One instance with its member tags and extra tags |
POST /api/v1/udt/instances | engineer | Create an instance |
PATCH /api/v1/udt/instances/{id} | engineer | Rename or change parameters |
POST /api/v1/udt/instances/{id}/sync | engineer | Rebuild the instance's tags from its type |
DELETE /api/v1/udt/instances/{id} | engineer | Delete the instance and its tags |
Types live in the tag tree under @types (the legacy _types_ root is still accepted). Folder routes take the folder's path in the type tree; {path} may contain dots and slashes.
Types
POST /api/v1/udt/types takes CreateUdtTypeDto:
| Field | Type | Required | Meaning |
|---|---|---|---|
path | string | yes | The type's path under @types, for example @types.Motors.Pump |
name | string | yes | Display name |
parentPath | string | no | Folder path; derived from path when absent |
typeColor | string | no | Color shown in the tag browser |
documentation | string | no | |
rootMemberKey | string | no | The member whose value stands for the instance as a whole |
parameters | UdtParameterDto[] | no | See below |
members | UdtMemberDto[] | no | See below |
parentTypePath | string | no | The type this one extends, by path |
PATCH /api/v1/udt/types/{id} takes the same fields except path and parentPath, all optional. members and parameters, when present, replace the whole list. parentTypePath: null leaves it as it is, an empty string makes the type stand alone.
POST /api/v1/udt/types/{id}/move body {"newParentPath": "@types.Motors"}.
Parameters
UdtParameterDto: { "name": "Prefix", "dataType": "string", "defaultValue": "M1" }. name is required; two parameters cannot share a name (400). Instances substitute {Prefix} in member bindings and expressions.
Members
UdtMemberDto has the same value fields as a tag (see Tags) plus the member-specific ones:
| Field | Type | Meaning |
|---|---|---|
memberPath | string | Path inside the type, dotted for nesting. Two members cannot share a path (400) |
kind | string | folder, memory, derived, expression, a driver kind, or udt for a nested type |
typeRef | string | For kind: "udt": the nested type's path |
producerModuleId, producerInstanceRef, binding | string, string, object of strings | Driver binding; producerInstanceRef and binding values may contain {Param} placeholders |
dataType, sourceTag, property, sourceBit, expression, memoryStartValue | As on a tag | |
tooltip, documentation, engUnit, formatString | string | As on a tag |
scaleMode, rawLow, rawHigh, engLowLim, engHighLim, engLimitMode, scaleFactor, bitCount, scaleMap, deadbandMode, deadband | As on a tag | |
memberParams | object of strings | Parameter values passed into a nested type |
alarms | array | Alarm templates; each instance gets a live alarm per template, resolved at each alarm reload |
enabled | boolean | Default for every instance's member tag; absent means enabled |
overrides | object | In a type that extends another: a sparse patch of the parent's member at this memberPath. When present, every other field on the row is ignored |
Inheritance and effectiveMembers
A type with parentTypePath inherits the parent's members and parameters. Its own members list holds only additions and patches (overrides). The response of GET /api/v1/udt/types/{id} includes the type's own members and an effectiveMembers list: the flattened result after applying the whole chain, which is what instances are built from.
Built-in types
Types under the folder @types.built-in are owned by Scadex and synced at start. Creating, updating, moving or deleting them, or creating anything inside that folder, answers 400. Instances of them are allowed. See Built-in tag types.
Export and import
GET /api/v1/udt/types/export?path=@types.Motors returns:
{ "version": 1, "type": "…", "exportedPath": "@types.Motors", "types": [ { "relativePath": "Pump", "name": "Pump", "typeColor": null, "documentation": null, "rootMemberKey": null, "parameters": [], "members": [], "parentTypePath": null } ] }
POST /api/v1/udt/types/import body {"targetPath": "@types.Imported", "data": <the export>}; answers 204. parentTypePath in an entry is an absolute path, as a nested member's typeRef is.
Type folders
POST /api/v1/udt/foldersbody{"path": "@types.Motors"};204.PATCH /api/v1/udt/folders/{path}body{"newName": "Drives"}; returns the renamed folder.POST /api/v1/udt/folders/movebody{"path": "@types.Motors", "newParentPath": "@types.Plant"}(nullmoves to the root of the type tree).DELETE /api/v1/udt/folders/{path};204.
Instances
POST /api/v1/udt/instances takes CreateUdtInstanceDto:
| Field | Type | Required | Meaning |
|---|---|---|---|
typeId | string | yes | The type's id |
tagPath | string | one of | Full path of the instance root tag |
path | string | one of | Alias of tagPath |
name + parentPath | string | one of | Alternative: the name and the folder |
parameters | object of strings | no | Parameter values; missing ones take the type's defaults |
One of tagPath, path, or name with parentPath is required. The instance root is a tag of kind udt; the members are created as tags under it. An instance cannot be created inside another instance (400).
GET /api/v1/udt/instances/{id} returns the instance with memberTags (the tags the type defines, with their per-instance overrides) and extraTags (tags added to this instance that the type has no member for; see Tags).
PATCH /api/v1/udt/instances/{id} body {"name": "...", "parameters": {...}}: both optional. Changing parameters re-resolves the member bindings. Per-member overrides are changed on the member tag itself with PATCH /api/v1/tags/{id} and its overrides field.
POST /api/v1/udt/instances/{id}/sync creates members the type gained, removes members it lost and re-applies parameters; answers {"ok": true}. DELETE /api/v1/udt/instances/{id} removes the instance and every member tag; 204.
Notable status codes
400: a built-in type, a duplicate member path or parameter name, an instance inside an instance, a nested type that would recurse.404: unknown type, folder or instance.409: a tag path already taken when creating an instance.