alterTag

The "alterTag" action modifies an existing tag. You can identify the tag using either the "id" or "tagName" properties.

When you set the "sourceFieldName" to the name of a field in the tag's integration, it links the tag to the field. Once linked, a field is managed by the tag instead of the "alterIntegrationTable" action. The tag becomes the source of truth for the field definition and the server ensures the tag's data is synchronized between the tag's property in the source_payload field and the tag's user-defined field.

Tips: The optional "newTagName" property renames a tag.
Set the "status" property to "inactive" to deprecate a tag and set it to "active" to activate a tag.

Note: The action returns the following error message if you specify both the "id" and "tagName" properties: 
The "id" and "tagName" properties are mutually exclusive.

 

How to use the "alterTag" action to manage the tag's field

  • To create a field and link it to a tag, assign a tag's "sourceFieldName" to a non-existent field and specify the "sourceFieldType", "sourceFieldLength", and "sourceFieldScale" properties. If necessary, it unlinks the tag from a previously linked field. 
  • To rename a field linked to a tag, take a tag that is already linked to a field and change its "sourceFieldName" to a non-existent field. In contrast, if you assign an existing field name to "sourceFieldName", the action will link the tag to that field instead of renaming it.
  • To modify a field linked to a tag, change the values of the tag's "sourceFieldType", "sourceFieldLength", and/or "sourceFieldScale" properties. The action archives the existing field by renaming it to <previousName>_ARCHIVED<N> and creates a new field with the original name, new type, new length, and/or new scale. This approach preserves previously collected data in the archived field. You can use the "alterIntegrationTable" action to permanently delete the archived field.
  • To delete a field linked to a tag, set the tag's "sourceFieldName" property to null or use the "deleteTag" action to delete the tag. This unlinks the tag from the field. You can then use the "alterIntegrationTable" action to permanently delete an unlinked field and its data.
  • To unlink a field from a tag, set the tag's "sourceFieldName" property to null or use the "deleteTag" action to delete the tag.
  • To link an existing field to a tag, assign a tag's "sourceFieldName" to an target field, which must already exist in the integration table. 
    • If another tag is already linked to the target field, the action returns the error "Cannot link tag TTT to field FFF because tag XXX is already linked to it". 
      • To overcome this error, first unlink the other tag from the field by setting its "sourceFieldName" property to null.
    • If the target field's type, length, and scale are not identical to those specified in the tag, the action returns the error "Cannot link tag TTT to field FFF because the field has a different type, length, or scale".
      • To overcome this error, unlink the tag from the target field by setting the tag's "sourceFieldName" property to null. Then, change the tag's "sourceFieldType", "sourceFieldLength", and "sourceFieldScale" properties to match the field. Alternatively, use the "alterIntegrationTable" action to modify the target field's type, length, and scale to match the tag. Lastly, assign the tag's  "sourceFieldName" to the target field.  

 

Request examples

Rename a tag using "id" to select the tag

{
  "api": "hub",
  "action": "alterTag",
  "params": {
    "id": 1,
    "newTagName": "My New Tag Name"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"  
}
 
 

Rename a tag using "tagName" to select the tag

{
  "api": "hub",
  "action": "alterTag",
  "params": {
    "tagName": "Temperature Celsius",
    "newTagName": "My New Tag Name"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"  
}
 
 

Change tag values

  • You can use the "id" property or "tagName" property to select the tag – but not both.
  • To change a property value, include the property and assign it to a new value. 
  • To leave a property value unchanged, omit it.
  • The optional "include…" properties return extra information in the response. 
{
  "api": "hub",
  "action": "alterTag",
  "params": {
    "tagName": "Temperature Celsius",

    "tableName": "temperature",
    "ownerName": "admin",
    "databaseName": "faircom",

    "tagDataType": "number",

    "sourceFieldName": "temperature_celsius",

    "sourcePayloadPath": "temperature.celsius",
    "sourcePayloadBinaryFormat": "hex",
    "sourcePayloadDateFormat": "iso8601",
    "sourcePayloadTimeFormat": "iso8601",
    "sourcePayloadNumberRounding": "roundup",
    "sourcePayloadVariantFormat": "json",
    
    "onSyncConflict": "overwriteFieldWithoutError",

    "status": "active",
    "purpose": "Track Celsius Temperatures from devices",
    "description": "My tag's description",
    "labels": ["temperature", "celsius"],
    "metadata": { "myProperty": "myValue" },

    "includeInputConnectorProperties": ["id", "connectorName", "connectorId" ], 
    "includeOutputConnectorProperties": ["id", "connectorName", "connectorId" ], 
    "includeThingProperties": [], 
    "includeTopicProperties": ["id", "topic", "tableName"]

  },
  "responseOptions": {},
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "1",
  "debug": "none"  
}
 
 

Change list and object values

  • When modifying a property with a list or object value, replace the entire value with a new one. 
  • To clear a list, set it to []. 
  • To clear an object, set it to {}. 
  • The following example replaces the values assigned to the "labels" and "metadata" properties.
{
  "api": "hub",
  "action": "alterTag",
  "params": {
    "tagName": "Temperature Celsius",

    "labels": ["temperature", "celsius", "fahrenheit"],
    "metadata": {},

  },
  "responseOptions": {},
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "requestId": "1",
  "debug": "none"  
}
 
 

 

Response examples

Minimal

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {

    "id": 1,
    "tagName": "temperatureCelsius",

    "tableName": "temperature",
    "ownerName": "admin",
    "databaseName": "faircom",

    "tagDataType": "number",

    "sourceFieldName": "temperature_celsius",
    "sourceFieldType": "integer",
    "sourceFieldLength": 4,
    "sourceFieldScale": null,

    "sourcePayloadPath": "temperature.celsius",
    "sourcePayloadBinaryFormat": "hex",
    "sourcePayloadDateFormat": "iso8601",
    "sourcePayloadTimeFormat": "iso8601",
    "sourcePayloadNumberRounding": "roundup",
    "sourcePayloadVariantFormat": "json",
    
    "onSyncConflict": "retainValues",

    "status": "active",
    "purpose": "Store temperature in Celsius",
    "description": "My tag's description",
    "labels": ["temperature", "celsius"],
    "metadata": { "myProperty": "myValue" }, 

    "createdTimestamp": "2026-01-03T12:13:04Z",
    "updatedTimestamp": "2026-01-03T12:13:04Z"null,
    "inactiveTimestamp": null

  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Maximal

{
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "result": {

    "id": 1,
    "tagName": "temperatureCelsius",

    "tableName": "temperature",
    "ownerName": "admin",
    "databaseName": "faircom",

    "tagDataType": "number",

    "sourceFieldName": "temperature_celsius",
    "sourceFieldType": "integer",
    "sourceFieldLength": 4,
    "sourceFieldScale": null,

    "sourcePayloadPath": "temperature.celsius",
    "sourcePayloadBinaryFormat": "hex",
    "sourcePayloadDateFormat": "iso8601",
    "sourcePayloadTimeFormat": "iso8601",
    "sourcePayloadNumberRounding": "roundup",
    "sourcePayloadVariantFormat": "json",
    
    "onSyncConflict": "retainValues",

    "status": "inactive",
    "purpose": "Store temperature in Celsius",
    "description": "My tag's description",
    "labels": ["temperature", "celsius"],
    "metadata": { "myProperty": "myValue" }, 

    "createdTimestamp": "2026-01-03T12:13:04Z",
    "updatedTimestamp": "2026-02-03T17:36:57Z",
    "inactiveTimestamp": "2026-03-03T09:01:13Z",

    "inputConnectors": [
      { "connectorId": 51, "connectorName": "INPUT: PLC 74 & Modbus", "lastCollectedTimestamp": "2025-08-28T10:47:13.041" }
    ],
    "outputConnectors": [
      { "connectorId": 52, "connectorName": "OUTPUT: PLC 74 & Modbus","lastDeliveredTimestamp": "2025-08-28T10:47:13.041" },
      { "connectorId": 53, "connectorName": "OUTPUT: MES & REST",     "lastDeliveredTimestamp": "2025-08-28T10:47:13.041" }
    ],
    "things": [ 
      { "thingId": 1 }
    ],
    "topics": [ 
      { "topicId": 1, "topic": "Temperature",          "tableName": "temperature" },
      { "topicId": 1, "topic": "Temperature//Celsius", "tableName": "celsius" }
    ]
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

databaseName

The "databaseName" property specifies the database that contains an object, such as a table or code package. If it is set to null or is omitted, it defaults to the default database of the JSON Action session, see "createSession" and the "defaultDatabaseName" property. 

You specify this property when you want to use a different database instead of the default. 

This property is useful because objects, such as tables and code packages, can have the same name in multiple databases. This feature allows you to create multiple environments in the same server and reuse the same JSON actions in each environment. For example, you can create "dev", "test", "stage", and "prod" databases on the same server and use the "defaultDatabaseName" or "databaseName" properties to specify the desired environment.

It is an error to set "databaseName" to the empty string "".

If no default database is specified during "createSession", the server sets the "defaultDatabaseName" to the "defaultDatabaseName" value specified in the services.json file.

 Defaults to the session's "defaultDatabaseName" property string 1 to 64 bytes

description

 The "description" property describes objects such as code packages, labels, or things. The server indexes this field with a full-text index so that you can search for any word or phrase. You cannot use this property for filtering in the Thing API.

Optional with default of "".

"unknown" for Thing API 

 string

0 to 65,500 bytes

1 to 512 bytes for the Thing API 

id

The "id" property is a unique identifier automatically generated by the server. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create an object such as a label or thing and stores it in the table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property. You can use the "id" or "thingName" properties to identify and look up a thing.

 

 Automatically generated by the server integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API

includeInputConnectorProperties

The "includeInputConnectorProperties" property specifies names of connector properties. When it is included in the request, the response includes an "inputConnectors" list that contains all the connectors related to the request. Each item in the list is an object that contains the specified properties.

 

For more details, see "includeInputConnectorProperties".

 Optional with default of [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includeOutputConnectorProperties

The "includeOutputConnectorProperties" property causes the response to include an "outputConnectors" list that contains all the connectors related to the request. Each item in the list is an object that contains the specified properties.

 

For more details, see "includeOutputConnectorProperties".

 Optional with default of [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includeThingProperties

 The "includeThingProperties" property causes the response to include a "things" list that contains all the devices and software related to the request. Each string is the name of a device property. For more details, see "includeThingProperties". Optional with default of [] array of strings

"id"

"thingName"

"status"

"manufacturer"

"model"

"serialNumber"

"type"

"purpose"

"description"

"location"

"labels"

"hostnames"

"metadata"

"photo"

includeTopicProperties

 The "includeTopicProperties" property causes the response to include a "topics" list that contains all the MQTT topics related to the request. Each string is the name of a topic property. For more info, see “includeTopicProperties”.  Optional with default of [] array of strings zero or more of the properties in the results example of the describeTopics action

labels

The "labels" property specifies 1 or more label objects to be assigned to records. It can assign many labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

The "labels" property must contain at least one label object. Each label object specifies the label's group name and label name. 

  • The "name" property is required and must be set to a string value. If it is omitted or set to null, the action returns an error. 
  • The "group" property is optional. If it is omitted or set to null, the action sets it to the empty string "". 

When using tag actions, the optional "labels" property assigns zero or more labels to a tag. It defaults to []. Each label is a string from 1 to 64 bytes. You can use it to do lookups and filtering. You can display a list of existing stages, add new ones, rename them, and deprecate them.

 

When you use the "alterThing" action, omit the "labels" property to leave existing labels unchanged or specify the complete set of labels. The action does not allow you to change one label at a time.

 

You can use the "labelsFilter" property to lookup and filter things.

 

The Tag API implements the "labels" property using the Label API. 

  • The API stores and manages labels in the label group, "faircom/labels".
  • An API client can retrieve a list of all labels by using the "listLabels" action with "partialGroupFilter": "faircom/labels".
  • An API client should use the Thing API's "labels" property to manage the labels assigned to a thing. It should not use the Label API to rename, link, or unlink host names to things.

Required - No default value

 

Defaults to

[] when using tag actions

 array of objects

1 or more label objects

 

Values are managed in the Label API with the group of "faircom/edge/label".

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

newTagName

 The "newTagName" property specifies the unique name of a tag that is created by a transform step. For more details, see "newTagName". Varies string 1 to 256 bytes

onSyncConflict

 The "onSyncConflict" property specifies what happens when the automatic synchronization between a tag's property and field cannot be synchronized because both have different values. "retainValues" string enum "overwriteField"
"overwriteFieldWithoutError"
"overwriteProperty"
"overwritePropertyWithoutError"
"retainValues"
"retainValuesWithoutError"
 

ownerName

The "ownerName" property specifies the account that owns an object, such as a table or code package. See "createSession" and the "defaultOwnerName" property for more details. 

You specify this property when you want to use a different account instead of the default. Your session's account must have the appropriate privileges to access the code package. 

This property is useful because objects, such as tables and code packages, can have the same name in the same database as long as different accounts own each object. This feature allows you to create duplicate objects for different users on the same server and reuse the same JSON actions on those objects. For example, an administrator can copy objects from a production environment to her account so she can troubleshoot an issue using the same JSON actions, JavaScript, and SQL code.

It is an error to set "ownerName" to the empty string "".

If no default owner is specified during "createSession", the server sets the "defaultOwnerName" to the "defaultOwnerName" value specified in the services.json file.

 Optional with default of the session's "defaultOwnerName" property string 1 to 64 bytes

purpose

The "purpose" property provides a short description of the specified server's purpose.

 

In the Thing API, the "purpose" property specifies the thing's purpose, which is a short description of why a thing is in use. A thing may have one purpose. 

 

The Thing API uses the Label API to manage purposes.

  • It uses the label group, "faircom/edge/purpose". 
  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listThings" action with the "purposeFilter" property to ensure the label is unused.

Optional with default of "". Defaults to

"unknown" in the Thing API 

 string 1 to 64 bytes

sourceFieldName

The "sourceFieldName" property links a tag to a field in the tag's integration table. It is the tag's primary field. Transformations can associate a tag with additional fields.

  • It must be the name of an existing field in an integration table. 
  • It is a case-sensitive string from 1 to 64 bytes in length. 
  • It is an optional request property in the "createTag" and "alterTag" actions.
  • When a primary field is assigned to a tag, the field's information is returned in the responses to the "createTag", "alterTag", "deleteTag" and "describeTag" actions.

Note: Before using the "sourceFieldName" property with the "createTag" and "alterTag" actions to link a tag to a field, that field must already be defined in the integration table. The integration table defines each field's type, length, and scale. For convenience, tag action responses include this information when a tag is linked to a field.

 Optional with default of "" string 1 to 64 bytes

sourcePayloadBinaryFormat

The "sourcePayloadBinaryFormat" property specifies the "binaryFormat" of data embedded in a string property in the source_payload field.

 

"hex"

 

 string

"hex"
"base64"
"byteArray"

 

sourcePayloadDateFormat

 The "sourcePayloadDateFormat" property specifies the "dateFormat" of data embedded in a string property in the source_payload field. "iso8601" string

"ccyy.mm.dd"
"mm.dd.ccyy"
"mm.dd.yy"
"dd.mm.ccyy"
"dd.mm.yy"
"ccyymmdd"
"iso8601"
"yymmdd"
"utc"

 

sourcePayloadNumberRounding

 The "sourcePayloadNumberRounding" property specifies the rounding option to use when reducing the scale of a number property in the source_payload field. "iso8601" string

"truncate"
"roundup"
"rounddown"

 

sourcePayloadPath

The "sourcePayloadPath" property is the propertyPath of the tag's value in the source_payload field, such as "sourcePayloadPath": "temperature".

  • It must not be an empty string and it may contain up to 2048 bytes.
  • It is the primary location of a tag's value.
    • Transforms may make additional copies of the value and store them in other locations in the source_payload field, other JSON fields, user-defined fields, and fields in other tables.
    • It does not have to be the first location of the value as identified in a tag's provenance.


For example, setting "sourcePayloadPath" to "temperature" causes the server to take a value it collects, such as 20.1, and assign it to the "temperature" property in the source_payload field, such as { "temperature": 20.1 }. 

 Required by the "createTag" action. Otherwise, it is optional with default of "". string 1 to 2048 bytes

sourcePayloadTimeFormat

 The "sourcePayloadTimeFormat" property specifies how the server encodes and decodes a time value assigned to a tag. For more details, see "sourcePayloadTimeFormat". Optional with default of "iso8601" string enum "hh.mm.ss.ttt"
"hh.mm.am/pm"
"hh.mm.ss.am/pm"
"hh.mm.ss"
"hh.mm"
"hhmm"
"iso8601"
"utc"

sourcePayloadVariantFormat

The "sourcePayloadVariantFormat" property indicates how a variant value is encoded in the "sourcePayloadPath". 

  • It applies to the tag's value only when the "tagDataType" property is "variant".
  • The default value is "json".
  • It can be set to one of the following:
    • "json"
    • "variantObject"
    • "binary"
    • "string"


Examples

  • "sourcePayloadVariantFormat":"json" encodes the tag's value in the source_payload field as JSON. If the variant field value is binary, it is encoded in a string and the "sourcePayloadBinaryFormat" property specifies the binary encoding.
  • "sourcePayloadVariantFormat":"variantObject" encodes the tag's value in the source_payload field as a variant object.
  • "sourcePayloadVariantFormat":"binary" encodes the tag's value in the source_payload field as binary. The "sourcePayloadBinaryFormat" property specifies the binary encoding.
  • "sourcePayloadVariantFormat":"string" encodes the tag's value in the source_payload field as a string. If the variant field value is binary, it is encoded in a string and the "sourcePayloadBinaryFormat" property specifies the binary encoding.


For more details, see "variantFormat".

 Optional with default of "json" string enum "json"
"variantObject"
"binary"
"string"

status

The "status" property indicates an items status. When set to "inactive", an item is no longer in active use. Setting an item to "status": "inactive", functions similarly to deleting an item without making the deletion permanent.

 

When the "status" property is omitted or set to null, API actions set the "status" property to "active". Thus, when you create an item, it defaults to being active. When you list items, the action defaults to returning active items.

 

To create, alter, and list inactive items, set the "status" property to "inactive".
Use a delete action to permanently delete an item.

 Optional with default of "active" string enum

"active"

"inactive"

tableName

The "tableName" property contains the unique, user-defined name of a table.

See table name in System limits for the table naming requirements and limitations.

 

"params": {
  "tableName": "ctreeTable"
}
 Required - No default value string 1 to 64 bytes

tagDataType

The "tagDataType" property specifies the data type of the tag.

  • It defines the data type of the tag's value. 
  • It must be one of the following values:
    • "string"
    • "number" 
    • "boolean" 
    • "date" 
    • "time" 
    • "timestamp" 
    • "json" 
    • "variant" 
    • "binary" 
  • It defines how the server interprets the tag's value, which is located in the source_payload field and its primary table field.
 Optional with default of "json" string enum "string"
"number" 
"boolean" 
"date" 
"time" 
"timestamp" 
"json" 
"variant" 
"binary" 

tagName

 The "tagName" property specifies the unique name of a tag. For more details, see "tagName".  Required - No default value string 1 to 256 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

createdTimestamp

 The "createdTimestamp" property is the date and time when something, such as a thing or key, was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

databaseName

The "databaseName" property specifies the database that contains the tables. 

Note In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
  • This property's value is case insensitive. 
 string 1 to 64 bytes

description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

Markdown is a good language for formatting description text. You must ensure the text is compatible with a JSON string. For example, you must escape a double quote character using the backslash character:  \".

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 

 string 1 to 65,500 bytes

id

The "id" property is the unique identifier of an object such as a label or thing. In JSON, you may use an integer number or a string containing an integer number. The server automatically generates the "id" when you create a label and stores it in the label table as an integer. You cannot alter the "id" value. If your application needs to specify a specific numeric identifier for a label, use the "enum" property.

 integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API 

inactiveTimestamp

 The "inactiveTimestamp" property is the date and time when the thing was last made inactive. It is null when the thing is active. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

inputConnectors

The "inputConnectors" property occurs in the response to Tag API actions when the "includeInputConnectorProperties" property is in the request. It contains all input connectors related to a tag. Each object contains the requested connector properties. See "includeInputConnectorProperties" for examples and additional information.

 

Note Input and output connectors are included separately because they have different properties.

 array of objects

zero or more objects containing zero or more of the following properties: 

"connectorName"

"connectorId"

"lastCollectedTimestamp"

labels

The "labels" property can assign 1 or more labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

The "labels" property must contain at least one label object. Each label object specifies the label's group name and label name. 

  • The "name" property must be set to a string value. If it is omitted or set to null, the action returns an error. 
  • The "group" property is optional. If it is omitted or set to null, the action sets it to the empty string "". 

When using tag actions, the optional "labels" property assigns zero or more labels to a tag. You can use it to do lookups and filtering. You can display a list of existing stages, add new ones, rename them, and deprecate them.

 

When you use the "alterThing" action, omit the "labels" property to leave existing labels unchanged or specify the complete set of labels. The action does not allow you to change one label at a time.

 

You can use the "labelsFilter" property to lookup and filter things.

 

The Tag API implements the "labels" property using the Label API. 

  • The API stores and manages labels in the label group, "faircom/labels".
  • An API client can retrieve a list of all labels by using the "listLabels" action with "partialGroupFilter": "faircom/labels".
  • An API client should use the Thing API's "labels" property to manage the labels  assigned to a thing. It should not use the Label API to rename, link, or unlink host names to things.
 array of objects

1 or more label objects

 

Values are managed in the Label API with the group of "faircom/edge/label".

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. object 0 or more key/value pairs

onSyncConflict

 The "onSyncConflict" property specifies what happens when the automatic synchronization between a tag's property and field cannot be synchronized because both have different values. string enum "overwriteField"
"overwriteFieldWithoutError"
"overwriteProperty"
"overwritePropertyWithoutError"
"retainValues"
"retainValuesWithoutError"
 

outputConnectors

The "outputConnectors" property occurs in the response to Tag API actions when the "includeOutputConnectorProperties" property is in the request. It is an array of objects that contains all output connectors related to a tag. Each object contains the requested connector properties. See "includeOutputConnectorProperties" for examples and additional information.

 

Note Input and output connectors are included separately because they have different properties.

 array of objects

Zero or more objects containing zero or more of the following properties:

"connectorId"

"connectorName"

"lastDeliveredTimestamp"

ownerName

 The "ownerName" property identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

purpose

The "purpose" property provides a short description of the specified server's purpose.

 

In the Thing API, the "purpose" property specifies the thing's purpose, which is a short description of why a thing is in use. A thing may have one purpose. 

 

This API uses the Label API to manage purposes.

  • It uses the label group, "faircom/edge/purpose". 
  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listThings" action with the "purposeFilter" property to ensure the label is unused.
 string 1 to 64 bytes

sourceFieldLength

 The "sourceFieldLength" property links a tag to a field in the tag's integration table. string 1 to 64 bytes

sourceFieldName

The "sourceFieldName" property links a tag to a field in the tag's integration table. It is the tag's primary field. Transformations can associate a tag with additional fields.

  • It must be the name of an existing field in an integration table. 
  • It is a case-sensitive string from 1 to 64 bytes in length. 
  • It is an optional request property in the "createTag" and "alterTag" actions.
  • When a primary field is assigned to a tag, the field's information is returned in the responses to the "createTag", "alterTag", "deleteTag" and "describeTag" actions.

Note: Before using the "sourceFieldName" property with the "createTag" and "alterTag" actions to link a tag to a field, that field must already be defined in the integration table. The integration table defines each field's type, length, and scale. For convenience, tag action responses include this information when a tag is linked to a field.

 string 1 to 64 bytes

sourceFieldScale

 The "sourceFieldScale" property contains the scale of the tag's field in the integration table. integer "money": 2 digits to the right of the decimal point allows 30 digits to the left.
"money": 4 digits to the right of the decimal point allows 28 digits to the left.
"number": 0 to 32 digits. It must be less than or equal to "sourceFieldLength" which defaults to 32.

sourceFieldType

 The "sourceFieldType" property specifies the number of bytes of the tag's field in the integration table. integer "json", "varchar", and "varbinary": 1 to 65500 (Specifies the variable-length field's maximum number of bytes.)
"char" and "binary": 1 to 65500 (Specifies the fixed-length field's length in bytes.)
"number" and "money": 1 to 32 (Optionally specifies the field's maximum total number of numeric digits.)

sourcePayloadBinaryFormat

The "sourcePayloadBinaryFormat" property specifies the "binaryFormat" of data embedded in a string property in the source_payload field.

 

 string

"hex"
"base64"
"byteArray"

 

sourcePayloadDateFormat

 The "sourcePayloadDateFormat" property specifies the "dateFormat" of data embedded in a string property in the source_payload field. string

"ccyy.mm.dd"
"mm.dd.ccyy"
"mm.dd.yy"
"dd.mm.ccyy"
"dd.mm.yy"
"ccyymmdd"
"iso8601"
"yymmdd"
"utc"

 

sourcePayloadNumberRounding

 The "sourcePayloadNumberRounding" property specifies the rounding option to use when reducing the scale of a number property in the source_payload field. string

"truncate"
"roundup"
"rounddown"

 

sourcePayloadPath

The "sourcePayloadPath" property is the propertyPath of the tag's value in the source_payload field, such as "sourcePayloadPath": "temperature".

  • It must not be an empty string and it may contain up to 2048 bytes.
  • It is the primary location of a tag's value.
    • Transforms may make additional copies of the value and store them in other locations in the source_payload field, other JSON fields, user-defined fields, and fields in other tables.
    • It does not have to be the first location of the value as identified in a tag's provenance.


For example, setting "sourcePayloadPath" to "temperature" causes the server to take a value it collects, such as 20.1, and assign it to the "temperature" property in the source_payload field, such as { "temperature": 20.1 }. 

 string 1 to 2048 bytes

sourcePayloadTimeFormat

 The "sourcePayloadTimeFormat" property specifies how the server encodes and decodes a time value assigned to a tag. For more details, see "sourcePayloadTimeFormat". string enum "hh.mm.ss.ttt"
"hh.mm.am/pm"
"hh.mm.ss.am/pm"
"hh.mm.ss"
"hh.mm"
"hhmm"
"iso8601"
"utc"

sourcePayloadVariantFormat

The "sourcePayloadVariantFormat" property indicates how a variant value is encoded in the "sourcePayloadPath". 

  • It applies to the tag's value only when the "tagDataType" property is "variant".
  • The default value is "json".
  • It can be set to one of the following:
    • "json"
    • "variantObject"
    • "binary"
    • "string"


Examples

  • "sourcePayloadVariantFormat":"json" encodes the tag's value in the source_payload field as JSON. If the variant field value is binary, it is encoded in a string and the "sourcePayloadBinaryFormat" property specifies the binary encoding.
  • "sourcePayloadVariantFormat":"variantObject" encodes the tag's value in the source_payload field as a variant object.
  • "sourcePayloadVariantFormat":"binary" encodes the tag's value in the source_payload field as binary. The "sourcePayloadBinaryFormat" property specifies the binary encoding.
  • "sourcePayloadVariantFormat":"string" encodes the tag's value in the source_payload field as a string. If the variant field value is binary, it is encoded in a string and the "sourcePayloadBinaryFormat" property specifies the binary encoding.


For more details, see "variantFormat".

 string enum "json"
"variantObject"
"binary"
"string"

status

The "status" property defaults to "active". The alternative is "inactive", which indicates an item is no longer in active use. Setting an item to "status": "inactive", functions similarly to deleting an item without making the deletion permanent.

 

When the "status" property is omitted or set to null, API actions set the "status" property to "active". Thus, when you create an item, it defaults to being active. When you list items, the action defaults to returning active items.

 

To create, alter, and list inactive items, set the "status" property to "inactive".
Use a delete action to permanently delete an item.

 string enum

"active"

"inactive"

tableName

The "tableName" property is a string containing the name of a table.

See table name in System limits for the table naming requirements and limitations.

 string 1 to 64 bytes

tagDataType

The "tagDataType" property specifies the data type of the tag.  

  • It defines the data type of the tag's value. 
  • It defines how the server interprets the tag's value, which is located in the source_payload field and its primary table field.
 string enum "string"
"number" 
"boolean" 
"date" 
"time" 
"timestamp" 
"json" 
"variant" 
"binary" 

tagName

The "tagName" property is a string that specifies the unique name of a tag. See also "tagId".

  • In "createInput" and "createOutput", you can use the "tagId" or "tagName" properties to associate the connector with a tag. 
  • In "alterInput" and "alterOutput", you can use the "tagId" or "tagName" properties to change the connector's association with a tag.
  • When assigning a tag to a connector, you can use either the "tagId" or "tagName" property but not both.
  • If a tag is associated with a connector, the response to the input and output actions include both the "tagId" or "tagName" properties; otherwise, these properties are omitted in the response. 

Important The "propertyPath" property is deprecated for the "createInput", "createOutput", "alterInput", and "alterOutput" actions. Instead, use the "tagName" or "tagId" properties.

 string 1 to 256 bytes

things

 The "things" property occurs in the response to Tag API actions when the "includeThingProperties" property is in the request. It is an array of objects that contains all devices and software related to a tag. Each object contains the requested device properties. See "includeThingProperties" for examples and additional information. array of objects All devices and software related to a tag.

topics

 The "topics" property occurs in the response to Tag API actions when the "includeTopicProperties" property is in the request. It is an array of objects that contains all topics related to a tag. Each object contains the requested topic properties. See "includeTopicProperties" for examples and additional information. array of objects All topics related to a tag.

updatedTimestamp

 The "updatedTimestamp" property is the date and time when the thing was last updated. It is the same as the "createdTimestamp" property when the thing has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

 

Was this article helpful?

Give feedback about this article

Related Articles