deleteDatabase

JSON DB "deleteDatabase" action deletes a database

Request examples

Minimal

{
    "action": "deleteDatabase",
    "params": {
        "databaseName": "test_db_min"
    },
    "requestId": "1",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
    "api": "db",
    "apiVersion": "1.0",
    "requestId": "00000022",
    "action": "deleteDatabase",
    "params": {
        "databaseName": "test_db_max"
    },
    "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string"
    },
    "debug": "max",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Request properties

Request properties

Universal request properties list

Property Description Default Type Limits (inclusive)

accountDescription

The "accountDescription" property is an optional string up to 65,500 bytes long that defines the account.

  • If omitted or set to null, an account description is not set.
  • If present and set to a non-empty string, it is set to the new description.
  • If preset and set to an empty string, it is set to the empty string.
 "" string 0 to 65,500 bytes

add

The optional "add" property is an array of objects that specifies which roles will be added to which accounts. You can specify the roles you want to add with the "rolenames" property and the accounts that will be assigned those roles with the "usernames" property.

 {} array of objects

"rolenames"

"usernames"

addFields

The "addFields" property is optional. It is an array of objects. It allows you to add new fields to a table and specify their properties. Each object in the array defines the properties of a field being added.

"addFields": [
  {
    "autoValue": "none",
    "name": "field1",
    "type": "varchar",
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false,
    "primaryKey":1
  }
]
 [] array of objects

"autoValue"

"defaultValue"

"length"

"name"

"newName"

"newPosition"

"nullable"

"scale"

"type"

allowedCipherSuites

The "allowedCiperSuites" property is an optional string that specifies an array of ciphers that the server will accept for communications with clients. It defaults to an empty string.

  • It specifies the encryption ciphers that are allowed to be used for encrypting a TLS (SSL) connection.
  • A client is allowed to connect to the server only if it uses one of the ciphers in this list.
  • The default setting of an empty string supports industry-standard secure connections.
  • The default value requires clients to use full AES 256-bit encryption when they talk to the server.
  • If a client cannot support AES 256-bit encryption, a lower encryption level should be added to the list.
    • This is undesirable because malicious users will attempt to connect at the lowest possible level so they can harm the system (for more information, see ciphers main page at OPENSSL.org.
  • Example settings:
    • Maximally secure example:
      • This example only allows clients to connect securely.
      • ["AES256-SHA256", "AES256-GCM-SHA384", "DHE-RSA-AES256-SHA256"]
    • Minimally secure example with the broadest client support:
      • ["!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
    • Insecure example allowing clients to connect using any level of security from  none to the maximal:
      • ["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • Add @STRENGTH to the end of the list to force the server to prioritize the strongest algorithms first. 
  • Place an exclamation point before a cipher to disable it. 
 "" string No limits

alterFields

The "alterFields" property is optional. It is an array of objects. It allows you to modify properties of existing fields in a table. Each object in the array defines the modifications to the named field.

In this example, the field named "field1" is being modified.

 

Example

"alterFields": [
  {
    "autoValue": "none",
    "name": "field1",
    "type": "varchar",
    "newName": "address",
    "newPosition": 5,
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false
  }
]
 [{"name":""}] array of objects "autoValue"
"name"
"type"
"newName"
"newPosition"
"length"
"scale"
"defaultValue"
"nullable"

amount

The optional "amount" property specifies the number of consecutive "dataType" values the connector retrieves.

The connector retrieves 3 one-byte values when "amount" is 3 and "dataType" is "byte".  

The connector retrieves 2 four-byte values when "amount" is 2 and "dataType" is "real".

If "dataType" is "bit", "amount" must be 1 because the connector retrieves one 8-bit byte for each bit. See bitPosition below.

 1 integer 1 to 65535

api

 The optional "api" property is an enumerated string which specifies which api the action will run on. "" string enum

"admin"

"db"

"hub"

"mq"

atEnd

The "atEnd" property is an optional string that defines how the action commits or rolls back the statement it runs. It defaults to "rollbackOnError".

  • Possible values:
    • "commit"
      • Setting "atEnd" to "commit" causes the "runSqlStatements" action to always commit the results of all successful SQL statements that you specify.
    • "rollbackOnError"
      • Setting "atEnd" to "rollbackOnError" causes the "runSqlStatements" action to commit the results of all SQL statements as long as all are completed successfully.  If one SQL statement returns an error, the "runSqlStatements" action rolls back all changes.
    • "rollback"
      • Setting "atEnd" to "rollback" causes the "runSqlStatements" action to always roll back the results of all SQL statements. It does not matter if some complete successfully and some fail.
  • There are use cases in which use "onError" and "atEnd" together.
    • When prototyping code.
      • "onError": "continue ", "atEnd": "rollback"
      • Use this sample when you want all statements to run and report errors, but you do not want to commit any changes. This is useful in development when you want to try out a number of SQL statements to check their syntax, performance, and proper execution and you do not yet want to commit changes because you are still developing the code. It is convenient since it eliminates the need to drop newly created objects and delete newly inserted records.
    • When developing code.
      • "onError": "continue", "atEnd": "rollbackOnError"
      • Use this sample when you want all statements to run so you can see and troubleshoot all errors and you want to commit all changes, but only when all SQL statements run successfully. This is the default setting because it is good for development and is still safe when these settings are accidentally deployed to production.
    • When running in production and test environments.
      • "onError": "stop", "atEnd": "rollbackOnError"
      • Use this sample when you want to immediately stop running SQL statements and rollback all changes when there is an error, but you want to commit all changes when all the SQL statements run successfully. This is useful in production because you want to commit a set of successfully executed SQL statements, but when a failure occurs, you want the server to immediately stop running the remaining SQL statements and roll back all changes. Immediately stopping execution and rolling back changes prevents server resources from being consumed unnecessarily.
    • When deploying database changes.
      • "onError": "continue", "atEnd": "commit"
      • Use this sample when you want to unconditionally commit all SQL statements even when an error occurs on one or more statements. This is useful for deploying database changes because it is common to ignore errors during a deployment process — for example, the DROP table command returns an error when dropping a table that does not exist. This error does not prevent a subsequent CREATE table from running successfully.
 "rollbackOnError" string

"commit"

"rollbackOnError"

"rollback"

authTokens

The "authTokens" property is an array that specifies which sessions the server should return in its response. At least one valid "authToken" must be specified in this property.

{
  "api": "admin",
  "requestId": "2",
  "action": "replaceWithCorrectAction",
  "params": {
    "authTokens": [
      "replaceWithAuthTokenFromCreateSession",
      "replaceWithAuthTokenFromCreateSession"
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 [] array At least one "authToken"

autotimestamp

This optional property works only with fields that have a type of "timestamp". The default value is "none", which prevents the server from populating the value of the field automatically.

The value is an official timestamp of the date and time when the server inserted or updated the associated field. The timezone is always UTC time (ZULU time). Once set, the value cannot be changed.

When the value is "onInsert", the server automatically populates the value of the field when the associated field is inserted.

When the value is "onUpdate", the server automatically populates the value of the field each time the associated field is updated.

When the value is "onUpdateOrInsert", the server automatically populates the value of the field each time the associated field is inserted or updated.

"fields": [
  {
    "name": "name",
    "type": "timestamp",
    "autoTimeStamp": "onupdate"
  }
]
 "none" string

"none"

"onInsert"

"onUpdate"

"onUpdateAndInsert"

autoValue

This optional property indicates when and how the server automatically sets the field value.

Only one of these values is allowed per field.

  • "none" indicates that the server does not automatically set the field's value.
  • "incrementOnInsert" indicates that the server automatically increments a field’s value each time the server inserts a new record. It applies to fields that are of the type of decimal or one of the integer types, such as "bigint". Only one field per table can have this attribute. The server returns an error when assigning this attribute to multiple fields. The JSON DB API automatically creates the "id" field as an "incrementOnInsert" field. If you apply this attribute to another field, it becomes the only automatically incremented field in the table. If you want that field to be the primary key, assign "primaryKey": 1 to it.
  • "timestampOnInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert. It applies only to fields with a type of "timestamp".
    • If you attempt to insert a record and specify a timestamp for a field that has "autoValue" set to "timestampOnInsert", the timestamp you specified is ignored, and the current date and time are assigned to the field.
  • "timestampOnUpdate" indicates that the server automatically sets a field’s value to the current date and time of an update. This setting applies only to timestamp fields.
  • "timestampOnUpdateAndInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert and an update. It applies only to fields with a type of "timestamp".
  • "changeId" indicates the server uses the field for optimistic locking. The server automatically sets the field's value to the internal transaction number used during the last update of the record. This value changes each time the server updates the record. A table may only have one change tracking field. The field type must be "bigint".
    • The JSON DB API automatically creates a "changeid" field with change-tracking functionality.
    • Change tracking is optional in the CTDB and ISAM APIs. The application must create a 64-bit integer field and assign change-tracking functionality to it.

 

Request Example

"fields": [
  {
    "name": "signed_int32",
    "type": "integer",
    "autoValue": "incrementOnInsert"
  }
]

 

Response Example

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "changeIdField": "changeId",
        "createRecByteIndex": false,
        "databaseName": "ctreeSQL",
        "fieldDelimiterValue": 0,
        "fields": [
          {
            "autoValue": "incrementOnInsert",
            "defaultValue": null,
            "length": null,
            "name": "signed_int32",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "integer"
          }
        ]
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "none" string

"none"

"incrementOnInsert"

"timestampOnInsert"

"timestampOnUpdate"

"timestampOnUpdate AndInsert"

"changeid"

 

binaryFormat

The "binaryFormat" property designates the format of binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

  • The "binaryFormat" property may occur inside "params",  "responseOptions", "defaultResponseOptions", "result", and "mapOfPropertiesToFields".
    • It occurs in "params" when actions create or change values.
    • It occurs in "responseOptions" when actions return values.
  • When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
    • For example, when  "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
  • When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
    • For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
  • When "binaryFormat" occurs in "result", it signifies how binary values are represented.
    • For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
  • When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
    • For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
    • For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields"  transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
  • The following are the possible values for each format.
    • "base64"
      • When the server reads and writes from a binary field, it represents the binary value as a base64 string.
      • Base64 is harder for people to read and convert to binary.
      • Base64 creates the smallest payload for the most efficient data transmission in JSON.
      • "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
    • "hex"
      • When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
      • Hexadecimal is easier for people to read and convert to binary.
      • Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
      • Hexadecimal strings contain the characters 0 - 9 and A - F.
    • "byteArray"
      • When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
      • An array of bytes is easiest for a program to manipulate.
      • An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
      • An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
        • "aBinaryField": [ 255, 0, 255 ]

 

Example requests

 
Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Response examples

Note Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "hex" string One of the following: "base64", "hex", or "byteArray".

bitBooleanZeroValue

The "bitBooleanZeroValue" property is optional and defaults to false. It applies when the "modbusDataType" property is set to "bitBoolean". When set to true, the connector maps a bit value of 1 to false and 0 to true.

 false Boolean

true

false

bitEndPosition

The "bitEndPosition" property is a zero-based bit position with a value from 0 to 15. When present, it must be greater than or equal to "modbusStartBitPosition". When omitted, it defaults to the value of the "bitStartPosition" property.

When "modbusDataType" is "bitInt", "bitEndPosition" is required. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". The server converts these bits into an integer number before writing the value to the record. You can optionally use the "bitIntSigned", "bitLittleEndian", and "bitReversedOrder" properties to change how the server converts the value into an integer. You can optionally use "bitIntSigned", "bitLittleEndian", and "bitReversedOrder" to control how the server interprets the bits when it converts them into an integer number.

When "modbusDataType" is "bitEnum", "bitEndPosition" is required. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". The server converts these bits into an unsigned integer number before writing the value to the record. You can optionally use the "bitLittleEndian" and "bitReversedOrder" properties to change how the server converts the value into an integer.

When "modbusDataType" is "bitBoolean", "bitEndPosition" is not allowed.

For examples, see Modbus data types.

 Required if "modbusDataType" is "bitInt" or "bitEnum". Defaults to the value of the "bitStartPosition" int16 0 to 15

bitEnumValues

The "bitEnumValues" property is an array of JSON values, each typically a JSON string.

"bitEnumValues" is required when the data type is "bitEnum". It is an array of strings, such as ["one", "two", "three"]. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". The server converts these bits into an unsigned integer number, looks up the string in the "bitEnumValues" array, and writes the enumerated string value on the record. The server sets the value to null if the "bitEnumValues" array does not contain a string value corresponding to the integer value. You can optionally use the "bitLittleEndian" and "bitReversedOrder" properties to change how the server converts the value into an integer.

For examples, see Modbus data types.

 Required if "modbusDataType" is "bitEnum" array of strings 1 or more strings

bitIntSigned

The "bitIntSigned" property is optional and defaults to false.

When "modbusDataType" is "bitInt", "bitIntSigned" is optional. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". If "bitIntSigned" is true, the server interprets these bits as a signed integer number before writing the value to the record; otherwise, it interprets them as an unsigned integer.

When "modbusDataType" is "bitBoolean", "bitIntSigned" is not allowed.

When "modbusDataType" is "bitEnum", "bitIntSigned" is not allowed.

For examples, see Modbus data types.

 false Boolean

true

false

bitLittleEndian

The "bitLittleEndian" property is optional and defaults to false. When set to true, the connector interprets a range of nine or more bits in little-endian order instead of big-endian order. A range of eight bits or less is unaffected by endian status. The Modbus "int16SignedBA" or "int16UnsignedBA" data types are in little-endian order.

When "modbusDataType" is "bitInt", "bitLittleEndian" is optional. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". If "bitLittleEndian" is true, the server interprets these bits as a little-endian number before writing the value to the record; otherwise, it interprets the bits as a big-endian number.

When "modbusDataType" is "bitEnum", "bitLittleEndian" is optional. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". If "bitLittleEndian" is true, the server interprets the bit order in little-endian order before converting each bit to an enumerated value and writing it to the record; otherwise, it interprets the bits in big-endian number.

When "modbusDataType" is "bitBoolean", "bitLittleEndian" is not allowed.

For examples, see Modbus data types.

 false Boolean

true

false

bitPosition

 If "dataType":"bit", "bitPosition" defines which of the eight zero-based bits to read from the byte the connector retrieves. 0 integer 0 to 7

bitReverseOrder

The "bitReverseOrder" property is an optional Boolean value. When true, the connector assigns bit values to the integer value starting from the end bit position to the start bit position; otherwise, it starts with the start bit position. It places bit values into the integer, starting from the rightmost bit to the leftmost.

When "modbusDataType" is "bitInt", "bitReversedOrder" is optional. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". If "bitReversedOrder" is true, the server interprets these bits in reverse order before writing the value to the record; otherwise, it interprets the bits in normal order.

When "modbusDataType" is "bitEnum", "bitReversedOrder" is optional. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". If "bitReversedOrder" is true, the server interprets these bits in reverse order before writing the value to the record; otherwise, it interprets the bits in normal order.

For example, if "bitReverseOrder" is false, "bitStartPosition" is 5, and "bitEndPosition" is 6, the connector works its way from the end position to the starting position, setting bits in the integer from right to left. For example, it takes the bit value at the bit end position and sets it into the rightmost bit in the integer. It then takes the bit value at the next-to-last position and sets it to the left of the previous bit. Thus, if 1 is the bit value in the Modbus register at bit position 5 and 0 is the value of bit position 6, the resulting binary integer value is 0000 0010. Given the same bit values, if "bitReverseOrder" is true, the resulting integer value is 0000 0001.

When "modbusDataType" is "bitBoolean", "bitReversedOrder" is not allowed.

For examples, see Modbus data types.

 false Boolean

true

false

bitStartPosition

The "bitStartPosition" property is a zero-based bit position with a value from 0 to 15.

When "modbusDataType" is "bitBoolean", "bitStartPosition" is required. The server retrieves 16 bits at the address specified by "modbusDataAddress" and converts the bit value at the specified starting offset to a boolean value. The server converts a zero bit to false and a one bit to true before writing the value to the record.

When "modbusDataType" is "bitInt", "bitStartPosition" is required. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". The server converts these bits into an integer number before writing the value to the record. You can optionally use the "bitIntSigned", "bitLittleEndian", and "bitReversedOrder" properties to change how the server converts the value into an integer. You can optionally use "bitIntSigned", "bitLittleEndian", and "bitReversedOrder" to control how the server interprets the bits when it converts them into an integer number.

When "modbusDataType" is "bitEnum", "bitStartPosition" is required. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". The server converts these bits into an unsigned integer number, looks up the string in the "bitEnumValues" array, and writes the enumerated string value on the record. You can optionally use the "bitLittleEndian" and "bitReversedOrder" properties to change how the server converts the value into an integer.

For examples, see Modbus data types.

 Required if modbusDataType is , "bitString", "bitInt", or "bitEnum" int16 0 to 15

bitStringOneValue

The "bitStringOneValue" property is a string that is used to define the JSON key. When the bit value is 1, the connector assigns the value of "bitStringOneValue" to the JSON key defined by "propertyPath". You may set it to any string value, including the empty string "", "null", "true", "false", "2", or "-9". You cannot set it to a non-string value, such as the JSON symbols null, true, false, or a number like 2, or -9.

"bitStringOneValue" is required when the data type is "bitString". The server retrieves an integer from the address specified by "modbusDataAddress". It extracts one bit starting from the offset specified by "bitStartPosition". The server maps a zero bit value to the string specified by "bitStringZeroValue" or maps a one value to the string specified by the "bitStringOneValue" property and writes the string into the record.

The "bitStringOneValue" property is only allowed when the data type is "bitString".

For examples, see Modbus data types.

 Required if "modbusDataType" is "bitString" string No limit

bitStringZeroValue

The "bitStringZeroValue" property is a string that is used to define the JSON key. When the bit value is 0, the connector assigns the value of "bitStringZeroValue" to the JSON key defined by "propertyPath". You may set it to any string value, including the empty string "", "null", "true", "false", "2", or "-9". You cannot set it to a non-string value, such as the JSON symbols null, true, false, or a number like 2, or -9.

"bitStringZeroValue" is required when the data type is "bitString". The server retrieves an integer from the address specified by "modbusDataAddress". It extracts one bit starting from the offset specified by "bitStartPosition". The server maps a zero bit value to the string specified by "bitStringZeroValue" or maps a one value to the string specified by the "bitStringOneValue" property and writes the string into the record.

The "bitStringZeroValue" property is only allowed when the data type is "bitString".

For examples, see Modbus data types.

 Required if "modbusDataType" is "bitString" string No limit

body

 The "body" property specifies information to send to a REST server by defining the "propertyPath" and "propertyValue" properties. [] array of objects

"propertyPath"

"propertyValue"

brokerConnectionName

The "brokerConnectionName" property is an optional string that is a unique user-defined name for the connection. It may be up to 100 characters long.

  • The unique name defined in the "brokerConnectionName" property is used in all subsequent references to the connection, such as when configuring a topic to subscribe or forward messages to an external broker or when altering or deleting a broker connection.
  • If the "brokerConnectionName" already exists, FairCom's server will update the record rather than create it.
  • If you do not wish to share a broker connection between multiple topics/integration tables (so you can control the broker connections independently), you can create multiple broker connections which all connect to the same external MQTT broker - giving each broker connection record a different "brokerConnectionName".
 "" string 1 to 100 bytes

brokerConnectionNames

The "brokerConnectionNames" property is a required array that contains a list of "brokerConnectionName" strings. It defaults to an empty array.

  • Must contain at least one string.
  • Each string is the name of a table.
  • A zero-length string is invalid.
  • A client should force uniqueness of the items in the array because the server ignores duplicate items.
 []

array

"brokerHostname"

"brokerPort"

"brokerUserName"

"isConnected"

"reconnectFrequencySeconds"

"statusCode"

"statusMessage"

brokerHostname

The "brokerHostname" property is required. It must not be a zero-length string or contain only whitespace.  It has a maximum length of 255 characters.

When these rules are violated the following errors will be displayed:
  • When creating a new broker connection, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because brokerHostname is empty."
  • When updating an existing broker connection, FairCom's servers log an error stating, "Cannot update the broker connection named xxx because the new "brokerHostname" is empty. The current brokerHostname xxx and brokerPort xxx remain unchanged."

Required - No default value

 string 1 to 255 bytes

brokerPort

The "brokerPort" property is optional. It defines the TCP/IP port. If it is not present, it defaults to 1883.

  • If present, it must be a number between 1 and 65535 inclusive.
  • If the port is already in use, FairCom's server will not be able to run.
  • When it is set to a non-numeric value, or is out of range, FairCom's servers log an error stating, “Cannot create the broker connection named xxx because the brokerPort property is missing or is set to an invalid value. It must be present and set to a number greater than zero and less than 65536.”
1883 integer

2 to 65534

brokerUserName

The "brokerUsername" property is the login name to the external broker. This property is an optional string from 1 to 64 bytes. If omitted, it defaults to an empty string.

Note Unlike some other properties containing the "name", the "name" in "brokerUsername" is all lowercase.

  • A zero-length username is invalid.
  • It is VARCHAR(500).

""

 string 1 to 64 bytes

brokerUserPassword

The "brokerUserPassword" property is in JSON format and contains the login password to the external broker and information about how that password might be encrypted. This property is optional. It is VARCHAR(500). If omitted, it defaults to the empty string. Additional properties may be added in the future.

 

Example

{ 
  "encryption": "NONE", 
  "password": "myPassword" 
}

""

 string 0 to 256 bytes

caCertificateFilename

The "caCertificateFilename" property is an optional string that specifies the name and optional path of the CA certificate file (such as "ca.pem"). It defaults to an empty string.

  • You must include "caCertificateFilename" to allow clients to use X509 certificates to authenticate with the server.
  • The certificate authorities file contains the list of certificate authorities the server uses to validate X509 certificates that clients present as authentication credentials.
  • In order for an X509 certificate to be accepted by the server, the certificate must be signed by a certificate authority that is present in the certificate authorities certificate file.
 "" string No limits

caseInsensitive

This property is an optional boolean with a default of false, so the server stores index key values in mixed case for comparisons.

When true, case comparisons are case-insensitive, and the server stores index key values in upper case for comparisons.

"fields": [
  {
    "caseInsensitive": true
  }
]
 false Boolean

true

false

certificateAuthoritiesFilename

 The "certificateAuthoritiesFilename" property specifies the name and optional path of the certificate authorities certificate file (such as "ca.pem"). "" string No limits

certificateFilename

 The "certificateFilename" property is an optional string that specifies the name and optional path of a server certificate file. "" string No limits

changeIdField

The value of this property is the name of the field used for the change-tracking functionality.

If the table already has a change-tracking field, this new field is now used instead for change-tracking.

 "" string 1 to 64 bytes

cleanSession

The "cleanSession" property is a synonym for "temporarySession" (see temporarySession). It exists for name compatibility with MQTT. Use "temporarysession" because its name is more intuitive.

This property is an optional Boolean property. It defaults to false when omitted or set to null. When true, the MQ engine resets the current session, and when the client disconnects, the engine removes the session's settings, subscriptions, and message position. Because you normally want the engine to remember your message position between sessions, you rarely set "cleanSession" to true.

 false Boolean

true

false

clientCertificateEnabled

 The "clientCertificateEnabled" property is an optional boolean that enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates. false boolean

true

false

clientCertificateFilename

The "clientCertificateFilename" property is an optional string that specifies the name of the client certificate file. It defaults to an empty string.

 Required - No default value string No limits

clientPrivateKeyFilename

The "clientPrivateKeyFilename" property is an optional string that specifies the name of the client private key file. It defaults to an empty string.

 Required - No default value string No limits

clientName

 The optional "clientName" property specifies the unique name that identifies the client to the FairCom MQ engine. "" string 0 to 65,550 bytes

clientNames

The "clientNames" property is an optional array containing 0 or more "clientName" strings. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.

Connection authorization is done using an account name with a password or a client certificate.

The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.

The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics. 

The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the FairCom server disconnects the other client and vice-versa.

 "" an array of "clientName" strings 0 or more strings

cloneUsername

The "cloneUsername" property is a required string up to 31 bytes long that specifies the new of name of the clone account.

Note See System limits for user name and other system properties requirements.

 

 Required - No default value string 1 to 31 bytes

clonePassword

The "clonePassword" property is a required string up to 63 bytes long that specifies the code used to authenticate the clone account.

  • If it is set to an empty string, the server authenticates the account without a password. This is not recommended because it allows anyone to log into the account without supplying a password.

Note See System limits for user name and other system properties requirements.

 

 Required - No default value string 1 to 63 bytes

cloneRoles

The "cloneRoles" property is an optional Boolean that specifies whether the cloned account will also have the roles assigned to the source account.

  • If omitted, the clone will not have the same assigned roles as the source account.

 

 true Boolean

true

false

cloneDescription

The "cloneDescription" property is an optional string up to 31 bytes long that specifies the "accountDescription" for the clone account.

  • If omitted or set to null, an account description is not set.
  • If present and set to a non-empty string, it is set to the new description.
  • If present and set to an empty string, it is set to the empty string.

 

 "" string 0 to 31 bytes

cloneMetadata

The "cloneMetadata" property contains user-defined properties that add keywords and tags about the clone account. The server indexes this field with a full-text index so you can search for any word or phrase to find the account.

  • In the clone account, the value in this property will become the value for the "metadata" property.
 {} object 0 or more key/value pairs up to 65,500 bytes

code

 The optional "code" property contains the source code. Before embedding it in a JSON string, encode the source code using the format specified in the "codeFormat" property. "" string 1 to 8,388,096 bytes

codeFormat

 The "codeFormat" property is an optional string that specifies the encoding of code in the code property. You must encode your code to embed it in a JSON string. "codeFormat" currently only supports the "utf8" encoding, requiring you to use JSON rules to escape problem characters in your code with the \ backslash character, such as \n. "utf8" string "utf8"

codeLanguage

 The "codeLanguage" property is a required string. It is the programming language's name. Any string value is accepted. Currently, "javascript" and "json" are the only types of code the FairCom server can use. Required - No default value string

"javascript"

"json"

codeName

The "codeName" property is a required, case-sensitive string between 1 and 64 bytes containing the user-defined name for the code package.

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

The package's unique identifier is the combination of "databaseName", "ownerName", and "codeName". See the "databaseName" and "ownerName" properties for more information.

 Required - No default value string 1 to 64 bytes

codeNames

The "codeNames" property is a required array of strings specifying the names of the code packages you want to be described.

  "params": {
    "codeNames": [
      "convertTemperature"
    ]
  },
 Required - No default value array of strings 1 or more strings

codeServices

 The "codeServices" property is an optional array of objects that specifies which programming languages are available in the product. [] array of objects

"serviceName"

"serviceLibrary"

"enabled"

codeStatus

 The "codeStatus" property is optional and specifies a new status for the code. When you create a code package, it defaults to "developing". When you alter a code package, it defaults to the current state. You may set it to one of the following states: "developing", "deleted", "inactive", "deprecated", "testing", or "active". You can use "alterCodePackage" to transition from any state to any other. See "Use "codeStatus" to make a package runnable". "developing" string

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

codeType

The "codeType" property defines how and where a FairCom server can run the JavaScript code. See Code Package Types for how to use each type of Code Package. The following enumerated values are supported:

 Required - No default value string

"integrationTableTransform"

"getRecordsTransform"

codeTypeFilter

 The "codeTypeFilter" property is an optional query filter with an array of code types. If the array is empty, null, or omitted, it matches all code types; otherwise, it returns code packages with a code type that matches one of the array's values. "" array

"integrationTableTransform"

"expression"

"getRecordsTransform"

"globalFunction"

"module"

"event"

"beforeTrigger"

"afterTrigger"

"job"

codeVersion

The 

"codeVersion" property is a required integer value that specifies the code's version stored in the version history.

 Required - No default value integer 0 to 2147483647

collectStats

The "collectStats" property is an optional boolean. Its default is false , so the server does not collect statistics. If set to true, the server will collect statistics that it uses to maximize performance.

"params": {
  "collectStats": true
}
 true Boolean

true

false

command

The "command" property is optional. When omitted, it defaults to the empty string. If set to a valid command string, it executes the command.

The following service commands are available:
  • "disconnect"
    • Tells the server to disconnect this broker connection.
  • "reconnect"
    • Tells the server to reconnect this broker connection..
  • "applySettingsNow"
    • Immediately applies the settings from this command.
  • "applySettingsWhenDisconnected"
    • Postpones the application of the settings within this command until the broker connection has been disconnected.

"applySettingsWhenDisconnected"

 string

"disconnect"

"reconnect"

"applySettingsNow"

"applySettingsWhenDisconnected"

comment

 The "comment" property is an optional string explaining the code change. "" string 1 to 65,535 bytes

commentFilter

 The "commentFilter" property is an optional query filter that is a string value. It defaults to null. If this value is not null or omitted, the results only include code packages with comments that match the full-text search specified in the "commentFilter" property. For example, to constrain results to include the three words FairCom Edge rocks anywhere in a  comment, use  "commentFilter": "FairCom Edge rocks". null string 1 to 65,500 bytes

compression

The "compression" property is an optional, case-insensitive string enum that defines how an index key is compressed. The default value is "auto".

Possible values
  • "on"
    • Turns compression on.
  • "off"
    • Disables or turns compression off.
  • "auto"
    • This is the default and automatically compresses the key when it makes sense.
"params": {
  "compression": "off"
}
 "auto" string

"on"

"off"

"auto"

conditionalExpression

The "conditionalExpression" property is an optional string from 0 to 65535 bytes. It defaults to an empty string. It contains an expression using FairCom's expression language. It applies a filter to the index, which prevents the index from including records that do not match the expression.

  • You can create a conditional index to navigate a predefined set of data quickly and efficiently.
  • Since it prevents the index from including records that do not match the expression entered, it causes the index to contain a predefined subset of records, which is similar to a materialized view except that only the index key is materialized.
"params": {
  "conditionalExpression": "livedpast2000 == 1"
}
 "" string 0 to 65,535 bytes

connectionStatusFilter

The "connectionStatusFilter" property is an optional array that filters the returned sessions by the selected connection statuses. The "listThings" action uses it to return things that match the specified connection states. Omitting the property or setting it to null matches all things.
 

 [] array

"disconnected"

"connected"

"connectedTemporarily"

"unknown"

connectorId

        

connectorIdFilter

 The optional "connectorIdFilter" property contains the unique integer ID of a connector. The "listTags" action includes the tag associated with the specified connector. [] array zero or more connector id integers

containsTransformSteps

The "containsTransformSteps" property is an optional Boolean that filters the response based on the presence of transform steps. When set to true, the response will include any tables with at least one transform step. When set to null, the response includes tables regardless of the presence of transform steps.

 null Boolean

true

false

contentType

The "contentType" property is an optional string typically set to an IANA media type or a custom type you define. It is used by MQTT 5.

 "" string an IANA media or custom type

correlationData

The "correlationData" property is an optional JSON value with a byte length of up to 65500 bytes. Set it to a useful value when using MQTT for request-response messages. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include this "correlationData" value (if any) to connect the response to the published message.

 "" JSON 0 to 65,500 bytes

createRecByteIndex

The "createRecByteIndex" property is an optional Boolean that creates a special index for quickly walking variable-length records backward when set to true. It defaults to false.

Note It is not needed for fixed-length records.

"params": {
  "createRecByteIndex": true
  }
 false Boolean

true

false

cursorId

The "cursorId" property is a required string from 0 to 255 bytes. It is a unique identifier returned by the server.

  • The "getRecordsFromCursor" action uses it to quickly and efficiently retrieve paginated records.
  • Setting a zero-length "cursorId" in the request is invalid.
  • It is not returned when "returnCursor" is false.

Important Do not assume the "cursorId" is a number embedded in a string.

Required - No default value

 string 0 to 225 bytes

databaseName

The "databaseName" property is an optional string from 1 to 64 bytes that 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. 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 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

databaseNameFilter

The "databaseNameFilter" property is an optional string that, when set to a non-empty string, causes the server to include tables that match the entire value of the specified database name, such as "faircom". It defaults to an empty string.

  • When "databaseNameFilter" is set to an empty string, an action will return tables from all databases.
  • When the value of "databaseNameFilter" is a non-empty string, it must be set to a valid database name.
  • "databaseNameFilter" is case-insensitive.
  • When the "partialName" property is present, the "databaseNameFilter" and "partialName" properties must be set to valid database and owner names.
 ""

string

 1 to 64 bytes

dataBlockNumber

The "dataBlockNumber" property specifies the number of the Data Block memory area where the connector retrieves data.

It is ignored unless "memoryArea":"db".

 Required if "memoryArea": "db" integer 1 to 65535

dataChangeStreamStatusFilter

 The "dataChangeStreamStatusFilter" is an optional array of strings that filters the results based on the change stream status. The response to this action will include streams that match one of the included status values or all streams if no values are included. null array

"scheduled"

"jumpstarting"

"running"

"failed"

"initializing"

"pausing"

"paused"

dataCollectionIntervalMilliseconds

The "dataCollectionIntervalMilliseconds" property schedules the connector to collect data periodically using the specified number of milliseconds. It defaults to 10000, which is ten seconds. It must be an integer number >= 1.

 10000 integer 0 and negative values are invalid.

dataCollectionBufferCount

The "dataCollectionBufferCount" property specifies the number of times the collector retrieves and caches data from the device before writing the data to the integration table.

This option combines multiple data collection events and inserts them into the integration table as one MQTT message.

If this value is more than 1, the connector converts each set of collected data into a JSON object and adds the object to an array inside a JSON document. When the count is reached, the connector writes the JSON document to the source_payload field of a record it inserts into the integration table.

 1 integer 1 to 65535

dataFormat

The "dataFormat" property is a case-insensitive string enum that defines the format of the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
    • Possible values include:
      • "arrays"
        • This causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
      • "autoDetect"
        • This is the default, and the server automatically detects the format of the data in the "sourceData" property.
  • "dataFormat" in the response shows the client how the server formatted the "data" property.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
 "arrays" string

"default"

"arrays"

"objects"

dataPersistenceStrategy
  • The "dataPersistenceStrategy" property controls when a connector writes collected data to a record in the input table specified by "tableName". It is an optional string enum property with two values: "onSchedule" and "onChange". The default value when the property is omitted or set to null is "onSchedule".
  • The "onSchedule" setting causes the connector to persist each collected value, which occurs on the schedule set by the "dataCollectionIntervalMilliseconds" property. This setting is useful for continuously collecting device data for trend analysis and machine learning.
  • The "onChange" setting causes the connector to collect data on the schedule set by the "dataCollectionIntervalMilliseconds" property, but it only persists data when it changes. This allows the connector to detect and store data changes as events, such as alerts and status updates. This setting greatly reduces data storage for infrequently changing telemetry, such as changes to a temperature sensor.

Note The connector misses events when its data collection schedule is not frequent enough to see data changes. Thus, the "onChange" setting makes a polling protocol, such as Modbus, behave like a push protocol, but it is not a push protocol like MQTT.

 "onSchedule" string

"onSchedule"

"onChange"

dataReadingTimeoutMilliseconds

 The optional "dataReadingTimeoutMilliseconds" property specifies the timeout in milliseconds while connecting and reading data from the PLC. 1000 int32 0 and negative values are invalid.

dataType

The "dataType" property specifies the data type of memory retrieved by the connector.

If "memoryArea":"ct", "dataType" must be "counter". 

If "memoryArea":"tm", "dataType" must be "timer".

 Required - No default value string
  • "bit" - inside a byte
  • "byte" - 8-bit integer
  • "ubyte" - unsigned 8-bit integer
  • "word" - 16-bit integer
  • "uword" - unsigned 16-bit integer
  • "doubleword" - 32-bit integer
  • "udoubleword" - unsigned 32-bit integer
  • "real" - 32-bit float
  • "counter" - 16-bit integer
  • "timer" - 16-bit integer

dateFormat

The optional "dateFormat" property specifies the format of a date or a datetime embedded in a JSON string. It applies to user-provided JSON and to server-generated JSON. The server uses it when it needs to transform or convert a date or datetime embedded in a JSON string into a FairCom date or timestamp. It also uses it when it needs to convert a date or datetime field value into a date embedded in a JSON string.

It is an enumerated string with one of the following values: "ccyy.mm.dd", "mm.dd.ccyy", "mm.dd.yy", "dd.mm.ccyy", "dd.mm.yy", "ccyymmdd", "yymmdd", "iso8601", and "utc".

The default value for "dateFormat" is the "defaultDateFormat" property defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultDateFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "iso8601" because the ISO8601 date is the defacto standard in JSON.

The enumerated string defines how the server parses a date in a JSON string and how it writes a date into a JSON string. The following key explains the parts of each enumerated value:

  • ccyy is a four-digit year (0000-9999).
  • yy is a two-digit year (00-99).
  • mm is a two-digit month (01-12).
  • dd is a two-digit day of the month (01-31).
  • hh is a two-digit hour (00-23).
  • . represents one character that can be one of the following values: /, ., or -.
  • "utc", "iso8601", and "ccyy.mm.dd" are the same.
UTC datetime format

Coordinated Universal Time (UTC) is an industry-standard for dates and times that uses the ISO8601 datetime format: "ccyy-mm-ddThh:mi:ss.fffz" or "ccyy-mm-ddThh:mi:ss.fff±hh:mi":

  • Variable parts
    • ccyy is a four-digit year.
    • mm is a two-digit month (01-12).
    • dd is a two-digit day of the month (01-31).
    • hh is a two-digit hour (00-23).
    • T is the letter T or the space character. It is required only when the time is present.
    • mi is a two-digit minute (00-59).
    • ss is a two-digit second (00-59).
    • fff is an optional fraction of a second with up to three digits of precision.
    • ± is an optional + or - character representing a positive or negative timezone offset. It is required only when a timezone offset is present.
  • Constant parts
    • - separates the year, month, and day.
    • : separates the hour, minute, and second.
    • . separates the second from a fraction of a second. It is required when the fraction is present.
    • Z is optional and represents the UTC timezone (also called Zulu time), which represents the timezone offset of +00:00.
  • Examples
    • 2025-07-11T16:18:33Z
    • 2025-07-11T16:18:33+00:00
    • 2025-07-11 16:18:33.9-07:00
 "iso8601" string enum

"ccyy.mm.dd"

"mm.dd.ccyy"

"mm.dd.yy"

"dd.mm.ccyy"

"dd.mm.yy"

"ccyymmdd"

"yymmdd"

"iso8601"

"utc"

deadbandLowerLimit

The optional, inclusive "deadbandLowerLimit" property specifies the value of the deadband's lower limit. It can be any numeric value. The default is "disabled". A change is saveable when it is less than the deadband lower limit.


A deadband is a zone where data changes are ignored. For example, a deadband prevents an HVAC system from constantly switching between heating and cooling due to minor temperature fluctuations. A FairCom connector ignores values that are inside the deadband zone. 


The connector uses the following rules to implement a deadband range:

  • When both the "deadbandLowerLimit" and "deadbandUpperLimit" properties are disabled, the connector ignores the deadband zone. 
  • When the "deadbandLowerLimit" is disabled and the "deadbandUpperLimit" is set to a numeric value, the deadband range has an unlimited lower limit and a fixed upper limit. 
  • When the "deadbandUpperLimit" is disabled and the "deadbandLowerLimit" is set to a numeric value, the deadband range has an unlimited upper limit and a fixed lower limit.


The following chart shows a connector saving values when they are outside the deadband range.

 

 

Scenario
A connector may collect temperature from an HVAC system once a second. Most collected values are between 70 and 73 degrees Fahrenheit. To ignore values in this range, set "deadbandLowerLimit" to 70, and "deadbandUpperLimit" to 73. To save the temperature once an hour – even if it has not changed, set "maxUnsavedEvents" to 3600.


Code example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,      
   "dataPersistenceStrategy": "onChange",

   "maxUnsavedEvents": 3600,
  
   "settings": {      
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed",

         "deadbandLowerLimit": 70,
         "deadbandUpperLimit": 73

       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}


NOTES

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • "normalLowerLimit"
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude" 
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "disabled" integer No limit

deadbandUpperLimit

The optional, inclusive "deadbandUpperLimit" property specifies the value of the deadband's upper limit. It can be any numeric value. The default is "disabled".  A change is saveable when it is greater than the deadband upper limit.


A deadband is a zone where data changes are ignored. For example, a deadband prevents an HVAC system from constantly switching between heating and cooling due to minor temperature fluctuations. A FairCom connector ignores values that are inside the deadband zone.


The connector uses the following rules to implement a deadband range:

  • When both the "deadbandLowerLimit" and "deadbandUpperLimit" properties are disabled, the connector ignores the deadband zone. 
  • When the "deadbandLowerLimit" is disabled and the "deadbandUpperLimit" is set to a numeric value, the deadband range has an unlimited lower limit and a fixed upper limit. 
  • When the "deadbandUpperLimit" is disabled and the "deadbandLowerLimit" is set to a numeric value, the deadband range has an unlimited upper limit and a fixed lower limit.

The following chart shows a connector saving values when they are outside the deadband range.

 

 

Scenario
A connector may collect temperature from an HVAC system once a second. Most collected values are between 70 and 73 degrees Fahrenheit. To ignore values in this range, set "deadbandLowerLimit" to 70, and "deadbandUpperLimit" to 73. To save the temperature once an hour – even if it has not changed, set "maxUnsavedEvents" to 3600.


Code example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,      
   "dataPersistenceStrategy": "onChange",

   "maxUnsavedEvents": 3600,
  
   "settings": {      
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed",

         "deadbandLowerLimit": 70,
         "deadbandUpperLimit": 73

       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • "normalLowerLimit"
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude" 
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "disabled" integer No limit

defaultApi

The "defaultApi" property specifies the default value of the "api" property when it is omitted from an action request. The default value for "defaultApi" is "admin", which is the API used by all session actions.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

FairCom DB defaults to "db"

FairCom Edge defaults "hub"

FairCom MQ defaults "mq"

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

The "binaryFormat" property designates the formatof binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

  • The "binaryFormat" property may occur inside "params",  "responseOptions", "defaultResponseOptions", "result", and "mapOfPropertiesToFields".
    • It occurs in "params" when actions create or change values.
    • It occurs in "responseOptions" when actions return values.
  • When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
    • For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
  • When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
    • For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
  • When "binaryFormat" occurs in "result", it signifies how binary values are represented.
    • For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
  • When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a  JSON property.
    • For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
    • For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields"  transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
  • The following are the possible values for each format.
    • "base64"
      • When the server reads and writes from a binary field, it represents the binary value as a base64 string.
      • Base64 is harder for people to read and convert to binary.
      • Base64 creates the smallest payload for the most efficient data transmission in JSON.
      • "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
    • "hex"
      • When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
      • Hexadecimal is easier for people to read and convert to binary.
      • Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
      • Hexadecimal strings contain the characters 0 - 9 and A - F.
    • "byteArray"
      • When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
      • An array of bytes is easiest for a program to manipulate.
      • An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
      • An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
        • "aBinaryField": [ 255, 0, 255 ]

 

Example requests

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Responses

Note Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

"hex"

 string One of the following: "base64", "hex", or "byteArray".

defaultDatabaseName

The "defaultDatabaseName" property is an optional string that specifies which database name to use when the "databaseName" property is omitted.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

FairCom DB defaults to "ctreeSQL"

FairCom Edge defaults to "faircom"

FairCom MQ defaults to "faircom"

 string 1 to 64 bytes

defaultDebug

The "defaultDebug" property is an optional string that defines the default value of the "debug" property for all requests in a session. It defaults to "max".

Important This is different than the "debug" property in that the "debug" property can be universally used in any action while the "defaultDebug" property is only set in the "createSession" action and sets the "debug" property for any action run using the session being created.

  • Possible values include:
    • "none"
    • "max"
  • If "defaultDebug" is omitted or set to null, it defaults to "max".
    • This causes the server to include the "debugInfo" property in the response.
    • This setting is typically used in development environments and for temporarily troubleshooting issues in production environments.
  • For maximum performance set "defaultDebug" to "none".
    • This causes the server to omit the "debugInfo" property in the response.
    • This setting is typically used in production and staging environments where it is desirable to have maximum performance and minimal network traffic.
 "max" string enum

"none"

"max"

defaultOwnerName

The optional "defaultOwnerName" property is is used by "createSession" and "alterSession" to specify the default owner of objects created by the session. Its value must be a valid username of an account. If it is omitted, null, or "", it defaults to the value of the session's "username" property.

  • See Object owner in the JSON DB Concepts section for an explanation of how to use the "defaultOwnerName" and "ownername" properties to specify the owner of objects.
  • When "ownerName" is omitted the server uses the "defaultOwnerName" property value set during login.
  • In "createSession" and "alterSession" when "defaultOwnerName" is omitted or set to null:
    • In the JSON DB API, the server sets "defaultOwnerName" to the "username" of the logged-in user. Thus, by default, the logged-in account owns the objects it creates.
    • In the JSON Hub API and JSON MQ API, the server sets "defaultOwnerName" to "admin" allowing the server to own the objects it creates.
  • Actions that create objects, such as "createTable" and "createIntegrationTable", can omit the "ownerName" property making the server set "ownerName" to the value of "defaultOwnerName".
  • When an action that creates an object sets the "ownerName" property to a valid account name, the specified account owns the created object and an account that owns an object has full management rights over the object. You can use object ownership as a simple way to control access to objects.
  • When "ownerName" is set to the empty string, then no account owns the object. Unowned objects can be managed by administrator accounts and by accounts assigned to roles that grant access rights to the object making it useful when you want to prevent an account from owning an object and inheriting full management rights to that object.

"admin"

 string 1 to 64 bytes

defaultResponseOptions

The "defaultResponseOptions" property is a "responseOptions" object. It defines a default value for "responseOptions" that is used by default in all other action calls. It defaults to an empty object.

JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.

The example omits the error object in all responses which makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

 "defaultResponseOptions": {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number",
      "variantFormat": "json"
    }

{}

 object

"binaryFormat"

"dataFormat"

"numberFormat"

defaultRetentionPeriod

The "defaultRetentionPeriod" property specifies how many retention units will be retained if the "retentionPeriod" property is omitted. It is used in tandem with "defaultRetentionUnit", the retention period describing how many units, and the retention unit describing what kind of unit of measurement. For example, if the "defaultRetentionPeriod" is set to 4, and the "defaultRetentionUnit" is set to "week", the server will purge messages once 4 weeks have passed by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },
 4 integer 1 to 100

defaultRetentionPolicy

The "defaultRetentionPolicy" property specifies the default way in which messages are persisted if the "retentionPolicy" property is omitted. Using this property, you can configure messages to persist indefinitely, be purged according to the retention unit and period, or be immediately purged by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },
 "autoPurge" string enum

"doNotPersist"

"neverPurge"

"autoPurge"

defaultRetentionUnit

The "defaultRetentionUnit" property specifies the type of retention unit if the "retentionUnit" property is omitted. It is used in tandem with "defaultRetentionUnit", the retention period describing how many units, and the retention unit describing what kind of unit of measurement. For example, if the "defaultRetentionPeriod" is set to 4, and the "defaultRetentionUnit" is set to "week", the server will purge messages once 4 weeks have passed by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },
 "week" string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

defaultValue

 The optional "defaultValue" property specifies the default value of a field. It is used when a record is inserted without specifying a value for the field. The server coerces the string value into the proper field type. It is a string because a string can represent any type of data. "" string 0 to 65,500 bytes

defaultVariantFormat

The "defaultVariantFormat" property sets the default value of the "variantFormat" property when a JSON Action request does not include it.

 "json" string

"json"

"binary"

"string"

"variantObject"

deleteAllRecords

deletes all records in a table when set it to true.

 Required - No default value Boolean

true

false

deleteFields

The "deleteFields" property is an optional array of strings. Each string is the name of a field to remove from a table.

  • Each string is 1 to 64 bytes.
  • Removing a field destroys the data in that field.
  • A zero-length "fieldName" is invalid.
 [] array 1 to 64 bytes

deprecated

The "deprecated" property optionally deprecates a label. Set it to true to deprecate a label and false to preserve it. It defaults to false. Deprecating a label is similar to marking a label as deleted.

 

 false Boolean

true

false

null

deprecatedFilter

The "deprecatedFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, to include deprecated and non-deprecated labels; in other words, a value of null provides no filtering. Set it to true to include only deprecated labels and false to include only non-deprecated labels.

 

 false Boolean

true

false

null

description

 The "description" property is an optional string that 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.

""

"unknown" for Thing API 

 string

0 to 65,500 bytes

1 to 512 bytes for the Thing API 

descriptionFilter

The 

"descriptionFilter" property is an optional string value that defaults to null. If the value is not null or omitted, the results only include code packages with descriptions that match the full-text search specified in the "descriptionFilter" property. For example, to constrain results to include the exact phrase 'FairCom Edge rocks' and the phrase 'around the clock' in the description, use "descriptionFilter": "'FairCom Edge rocks' 'around the clock'". Notice that a phrase is enclosed in single quotation marks. To constrain results to include the word FairCom as the first word plus the word rocks anywhere else in the description, use the search string, "descriptionFilter": "^FairCom rocks". The ^ operator followed by a word or phrase can only be included once in a full-text expression.

 

 null string 1 to 65,500 bytes

disableDatetime

The "disableDatetime" property is an optional datetime that specifies the last date and time that the account can log into the server. It is useful when you want to set a future date for automatically deactivating an account.

  • If omitted or set to null, it is not changed.
  • If present and set to a valid date, it is updated.
  • If present and set to an empty string, it disables this feature, which means there is no final date when the account can login.
 "" date Any date after "0336-10-07"

disableTransformSteps

The optional "disableTransformSteps" property has a true or false value. When true, it prevents the server from running an integration table's transform steps on newly inserted records. It is useful to quickly stop a broken transform process. It disables transform steps without removing them from the integration table.

 false Boolelan

true

false

downgradeQoS

The "downgradeQoS" property controls how FairCom's servers manage the Quality of Service (QoS) of subscriptions to this topic. This property is optional. The default value is false.

  • When false, FairCom's servers honor the QoS requested by each subscriber regardless of the QoS of publishers.
  • When true, FairCom's servers downgrade the QoS of subscribers to match the QoS of the publisher.
 false Boolean

true

false

enabled

The "enabled" property is an optional Boolean that specifies whether or not the feature is enabled. The example below enables the TLS feature.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
 true Boolean

true

false

enableDatetime

The "enableDatetime" property is an optional datetime that specifies the first date and time that the account can log into the server. It is useful when you want to set a future date for automatically activating a new account.

  • If omitted or set to null, the earliest date and time a user can log in is not specified, and the account can be used immediately.
  • If present and set to a valid date, it is updated with that date.
  • If present and set to an empty string, it disables this feature, which means there is no earliest date when the account can log in.
 "" date Any date after "0336-10-07"

endTimestamp

The "endTimestamp" property is an optional string that contains an ISO8601 timestamp, which filters the response to return problems that ended before or on its value. If any parts of the timestamp are missing or omitted, the server defaults the remaining parts to 0.

 null string containing an ISO8601 timestamp

"2025-08-19"

"2025-08-19T00:00:00.000"

"2025-08-19T01:13"

"2025-08-19T01:13:59"

"2025-08-19T01:13:59.853"

enum

The "enum" property optionally assigns an integer from -32768 to 32767 to a label. By default, this property is set to 0. You can use this property to assign an application's hardcoded enumerated value to a label.

 

 0 smallint -32768 to 32767

enumFilter

The "enumFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of integers with values from -32768 to 32767. The "enum" property of a label must match one of the integers in the array to be included in the results.

 

 [] array of smallints Each array item is an integer from -32768 to 32767

expiredMessagesFilter

The "expiredMessagesFilter" property is optional. It is an enumerated string that contains one of the following values: "include", "exclude", and "only". It defaults to "include".

  • "include" (default) returns expired messages in the results.
  • "exclude" omits expired messages from the results.
  • "only" returns only expired messages in the results.
 "include" string

"include"

"exclude"

"only"

expirySeconds

The "expirySeconds" property is an optional number of seconds the message remains active before the server stops delivering it to MQTT 5 subscribers. If you set it to null, the message does not expire. MQTT 3 messages do not expire. The server persists all messages, and the "getMessagesFromMqApiSession" action includes expired messages in its results. The caller can filter out expired messages by setting "includeExpiredMessages" to false when using the "subscribeToMq" action.

 null integer No limits

fetchRecords

The "fetchRecords" property is a required integer number from -2,147,483,648 to 2,147,483,647. A positive integer fetches that number of records forward. A negative integer fetches that number of records backward. It defaults to null.

  • A value of zero is an error because it does not fetch any records.
  • Fetching around 10,000 records at a time may be the most efficient way to transfer large numbers of records.
  • Larger numbers may cause network delays and slow processing on the client. Smaller numbers require more client-server round trips.
 null integer -2147483648 to 2147483647

fieldDelimiterValue

The "fieldDelimiterValue" property is a decimal number from 0 to 255. It is optional. If omitted, it defaults to 0. The only reason to change it is for backward compatibility with legacy c-tree files.

Note Do not set this value without first contacting FairCom customer support.

"params": {
  "fieldDelimiterValue": 255
}
 0 integer 0 to 255

fieldName

 The "fieldName" property specifies the name of a field in a table. Required - No default value string 1 to 64 bytes

fieldNames

The "fieldNames" property is an optional, case-sensitive array of strings where each string is the name of a field. It defaults to an empty array.

  • "fieldNames" is required in two possible cases:
    • When "dataFormat" is set to "arrays".
    • When "dataFormat" is set to "autoDetect" and the value in "sourceData" is an array of arrays.
  • It is recommended to create tables with all lowercase "fieldNames".

[]

When "sourceData" is an array of arrays, it is required and has no default value.

 array 1 to 64 bytes

fields

The "fields" property is a required array of index definition field objects. It specifies which fields in a table are included in the index and how each field should be indexed.

  • The "fields" array contains one object for each field in an index.
  • Each field has separate index settings such as:
    • Case sensitivity
    • Sort order
    • Comparison algorithm
  • For example, an index containing two fields can use different settings for each field. It can index the first field as case sensitive, ascending, and forward comparison, and the second field as case insensitive, descending, and reverse comparison.
  • When a string field is indexed as case insensitive, the server ignores the case of the ASCII letters in the field value; otherwise, it does an exact comparison.
  • When a field is indexed for reverse comparison, the server starts comparisons with the last byte in the field value rather than the first. This speeds up the comparison process when the last bytes of a field value are most likely to be dissimilar.
  • When a field is sorted ascending, queries that use the index return results in ascending index order for that field; otherwise, they return results in decreasing order.
  • When you configure multiple fields for sorting in an index, queries return results in the order the fields are listed — for example, if an index has birthday and name fields specified in the fields array in that order, with the birthday sorted descending and the name sorted ascending, then queries return results with the most recent birthdays first and multiple names on the same birthday are returned in ascending alphabetical order.
"fields":
[
  {
    "name": "name",
    "caseInsensitive": true,
    "sortDescending": true,
    "reverseCompare": false
  }
]

Required - No default value

 array of objects

"caseInsensitive"

"name"

"reverseCompare"

"sortDescending"

"autotimestamp"

"autoValue"

"defaultValue"

"length"

"name"

"nullable"

"primaryKey"

"scale"

"type"

filename

The "filename" property is an optional string that contains the name of the index file on the file system. It defaults to an empty string.

  • When creating a file, specify a non-zero-length string to assign the file to a specific location in the file system.
  • The file name may include an absolute or relative path.
  • If the filename is omitted or is a zero-length string, the server defines its own path and name for the file.
  • If "filename" is not specified, the index will be added to the existing index file.
  • The server adds the indexFileExtension to the end of the filename.
"params": {
  "filename": "admin_athlete_name_livedpast2000"
}
 "" string 0 to 2048 bytes

fixedOutput

The "fixedOutput" property is a Boolean that includes all properties in a data change event when true.

 false Boolean

true

false

folder

The "folder" property is an optional string from 0 to 2048 bytes. It defines the file system folder where an item will be stored. It defaults to an empty string.

Important If it is a zero-length string, the server chooses its own folder; otherwise, it uses this folder.

 

Request example

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "test_1",
    "folder": "Test_Folder"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "" string 0 to 2,048 bytes

forceRecordCount

 The optional "forceRecordCount" property forces a query to return a record count when true.

false

Boolean

true

false

forwardQos

The "forwardQos" property is an optional integer that specifies which quality of service (QoS) to use when forwarding messages to the external broker for the persisted topic.

 1 integer

0

1

2

forwardToExternalBrokers

The "forwardToExternalBrokers" property is optional. It can be omitted. It is an array of objects containing one or more brokers to forward the message to. All messages sent to this topic will be forwarded to each of these external brokers using the specified topic name. The default is an empty object.

  • If there are no items in the list, it is not an error, FairCom's servers simply do not set up any external forwards.  This is also how you can configure an existing topic to STOP forwarding to external brokers.
  • If this broker connection name does not already exist:
    • FairCom's servers do not set up the forward.
    • It logs an error stating, “Cannot forward to the external broker because the connection name xxx has not yet been defined by configureBrokerConnection.”
    • A failure does not stop FairCom's servers from trying to set up the next broker in the list.
  • Each time the "configureTopic" message is sent, FairCom's servers will completely replace its existing list for "forwardToExternalBrokers" with the new list.
    • Be careful not to create infinite message loops by forwarding topics to each other. For example, topic A forwards to topic B and topic B forwards to topic A. FairCom's servers currently do not detect or shut down infinite message loops.

 

Example

{ 
  "api": "mq", 
  "action": "configureTopic", 
  "params": 
  {
    "topic": "modbusdata1", 
    "tableName": "modbusTableTCP",
    "forwardToExternalBrokers": 
    [ 
      { 
        "brokerConnectionName": "Broker1", 
        "topic": "modbusdata2",
        "forwardQoS": 1
      } 
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

[]

 array of objects

Zero or more objects including some or all of the following properties:

"brokerConnectionName"

"forwardQos"

"topic"

forwardToTopics

The "forwardToTopics" property is an array of Topic Names. This property is optional. FairCom's servers will take all messages sent to this topic and automatically forward them to each of the topics in the array. These messages are forwarded within the same instance. The default is an empty array.

  • If a topic does not already exist, FairCom's servers create it as if an external client sent a message to the topic.
  • Each time the "ConfigureTopic" message is sent, FairCom's servers will completely replace its existing list for "forwardToTopics" with the new list.
  • FairCom's servers will not forward a topic to itself. Thus, if the "forwardToTopics" array contains the topic from "ConfigureTopic", FairCom's servers ignore it.
    • Be careful not to create infinite message loops by forwarding topics to each other.  For example, topic A forwards to topic B and topic B forwards to topic A.  FairCom's servers currently do not detect or shut down infinite message loops.
  • This feature is designed to ease the pain of topic migration, which occurs when clients begin publishing to different topics before subscribers can adjust.

[]

 array of strings One or more strings

group

The "group" property optionally groups labels into a lookup list or tag set. It is an optional namespace for a set of labels that identifies their purpose. You can use the "listLabelGroups" action to return the list groups. You can use the "listLabels" action to return labels in one or more groups. 

The "group" and "name" properties work together to uniquely identify each label. They are its natural key. A group assigned to the empty string ""  is the default group.

The group name may contain up to 64 bytes of UTF-8 encoded characters.

If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.

When you assign a group name to a label, the server automatically checks if the group name exists in the list of groups that the "listLabelGroups" action returns. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.

Tip If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name. In the "listLabels" action, you can use the "partialGroupFilter" filter to return subsets of groups in the hierarchy. For example, you if have groups named "product/size/", "product/weight/", "product/ranking/", "person/gender/", and "person/ranking/", you can set the "partialGroupFilter" to "product/" to return the product groups.

 "" string 1 to 64 bytes

groupFilter

The "groupFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings, such as "groupFilter": [ "myGroup1", "myGroup2", "" ]. Each string is the name of a group and may be up to 64 bytes long. A label's group must match one of the groups in the array to be included in the results. The empty string "" is a valid group name.

Note The "groupFilter" and "partialGroupFilter" properties are mutually exclusive.

This example uses a group filter to list all labels with the matching groups.

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "groupFilter": [ "myGroup1", "myGroup2", "" ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

This example uses a group filter to list all labels with the matching groups.

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "groupFilter": [ "myGroup1", "myGroup2" ],
    "partialNameFilter": "myNa"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 [] array of strings 1 or more strings, each up to 64 bytes long.

growthExtent

The "growthExtent" property is an optional integer from 0 to 2,147,483,647. It is the number of bytes that a server uses to increase a file's size. The default value is 0.

  • A file is extended when adding or updating a record, which requires the file to grow larger.
  • Use a larger number to minimize the number of times a file needs to be extended.
  • Use a smaller number to minimize the amount of unused space in a file.
{
  "api": "db",
  "action": "createTable",
  "params": {
    "growthExtent": 64000000
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 0 integer 0 to 2147483647

healthFilter

The "healthFilter" property is an optional array that filters the returned sessions by the selected session health statuses.

 [] array

"healthy"

"unhealthy"

"offline"

hierarchyDelimiter

The optional "hierarchyDelimiter" property is a string that delimits hierarchical levels in the key. It defaults to the empty string "", which defines no hierarchy. It may contain zero or more UTF-8 characters, such "/" or "||".

 

The "describeValues" action uses this string to calculate the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the delimiter. If the "hierarchyDelimiter" property is "" or the action cannot find the delimiter string, it sets the "keyWithoutHierarchy" property to the whole key because the key does not contain a hierarchy.


Examples

  • Given the key, "myKey" and a hierarchy delimiter of "", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myKey" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myApp/queries/" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp||queries||" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp/queries/My Favorite" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "My Favorite".
  • Given the key, "myApp||queries||My Favorite" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "My Favorite".
     
 "" string 1 byte

host

 The "host" property specifies the IP or hostname of the Rest resource, including the port. Required - No default string 1 to 1024 bytes

hostnames

The optional "hostnames" property is an array of strings that specifies zero or more hostnames assigned to the device. It defaults to the empty array []. Each item in the array should be a different hostname. Each hostname is a string from 1 to 64 bytes. NOTE: The API allows the same hostname to be assigned to many things.

 

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

 

The Thing API implements the "hostnames" property using the Label API. 

  • The API stores and manages hostnames in the label group, "faircom/hostnames".
  • An API client can retrieve a list of all hostnames by using the "listLabels" action with "partialGroupFilter": "faircom/hostnames".
  • An API client should use the Thing API's "hostnames" property to manage the host names assigned to a thing. It should not use the Label API to rename, link, or unlink host names to things.
 [] string Array of user-defined hostnames. Each hostname is a string from 0 to 64 bytes. Values are managed in the Label API with the group of "faircom/hostnames".

hostnamesFilter

The optional "hostnamesFilter" property finds things that contain one of the hostnames included in the property. It is an array of strings that defaults to the empty array []. Each string specifies a partial or complete hostname or IP Address that a thing uses. A thing may have zero or more hostnames. Each hostname is a string from 1 to 64 bytes.

 

Because the API does not prevent the same hostname from being assigned to many things, it may return multiple things assigned to the same hostname.

 [] array of strings Array containing zero or more hostnames.

id

The "id" property is a unique identifier. 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

idFilter

The "idFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to [], which provides no filtering. It is an array of integers with values from 0 to 2147483647. The "id" property of a label must match one of the integers in the array to be included in the results.

The "idFilter" property is mutually exclusive to the other filter properties. The "listLabels" action returns an error when it is used with other filter properties.

 

 [] array of integers Each array item is an integer from 0 to 2147483647

idleConnectionTimeoutSeconds

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

3600

integer

0 to 2147483647

idleCursorTimeoutSeconds

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds to keep a cursor open.

  • Each time a cursor retrieves records, the cursor timer restarts.
  • A value of -1 keeps a cursor open indefinitely.
  • A value of 0 immediately closes a cursor after the current operation.

600

 integer

0 to 2147483647

ids

The "ids" property is an array. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. Its default value is "null" but it is required if the "primaryKeys" property is "null" or not specified.

  • The "ids" property is mutually exclusive with the "primaryKeys" property meaning it is required when "primaryKeys" is omitted or an error is returned if both have values.
  • It is typically an array of integers ("ids": [1,3,5]).
  • It can be an array of an array of strings ("ids": ["9555444333222111","9555444333222112", "9555444333222113"]).
    • A string "id" supports numbers larger than 9,007,199,254,740,991.
    • This is the largest number supported by many programming languages and JSON parser implementations that use IEEE double-precision floats to hold numbers.
  • It can be the primary key value of another field in the table making it useful when your table is created by another API, such as SQL, that allows any field in the table to be the primary key.
    • If your table does not have an "id" field but uses a "vin" field as the primary key, you can use vin values to look up records ("ids": [ "4Y1SL65848Z411439", "1HGBH41JXMN109186" ]).
  • If your table uses more than one field as the primary key, you must use the "primaryKeys" property to look up records.

Tip The "getRecordsByIds'' action uses a primary key index to look up records. A primary key index must be a unique, non-null index without conditional filtering. For best performance and maximum simplicity, create tables using the JSON DB API because it automatically creates an auto increment "id" field that is indexed as a primary key.

 

"null"

Required when "primaryKeys" is omitted

 array 0 or more ids

ignoreChangeIdProtection

The "ignoreChangeIdProtection" property is an optional Boolean that causes the server to update the record regardless of the value of "changeId", when "true". It defaults to false.

  • Ignoring the "changeId" field is useful when a process wants to ensure its changes are always applied to a record.
  • However, ignoring the "changeId" field can cause an update to overwrite changes made by other processes. So, setting "ignoreChangeIdProtection" property to true is not recommended when an application reads a record so that a user can update it.
  • It is a best practice to read the record, let the user change values, and update the record using the same "changeId" value that was read.
  • If another process has changed the record in the interim, the server will not update the record and will return error 32602 indicating a missing "changeId" field or return error 1192 because the "changeId" value that was passed in matches the "changeId" value in the record.
 false Boolean

true

false

immediatelyCollectDataOnStart

The "immediatelyCollectDataOnStart" property controls how a connector first collects data after being started.

  • When true, it immediately collects and stores data and thereafter collects data according to the strategy specified in "dataPersistenceStrategy". In other words, it ignores the "dataPersistenceStrategy" for the initial data collection event and unconditionally stores the first set of data it collects. This setting allows subscribers to receive an initial data collection message each time the server or connector starts, which is useful for systems that display live status information.
  • When false, which is the default, it collects data according to the strategy specified in "dataPersistenceStrategy". For example, when the "dataPersistenceStrategy" is "onChange", the connector collects data on a schedule and persists it only when the data changes - even after a restart.
 false Boolean

true

false

immutableKeys

The "immutableKeys" property is an optional Boolean. When true, the server prevents the fields of an index from being updated. It defaults to false.

  • The server throws an error when an update action attempts to modify any of the fields in the index.
  • It allows a field to be set to an initial value when inserted.
"params": {
  "immutableKeys": true
}
 false Boolean

true

false

includeDeactivatedCode

The 

"includeDeactivatedCode" property is an optional query filter that is a Boolean value. It defaults to null. The results include activated and deactivated code packages if this value is null or omitted. If set to true, the results only include deactivated code packages. If set to false, the results only include activated code packages.

 

 null Boolean

true

false

includeDescription

The "includeDescription" property is an optional Boolean that specifies whether to include the "description" property in the response. It defaults to true.

true

Boolean

 

true

false

null

 

includedFields

The "includedFields" property is an array of strings that includes specified source table fields in the data change event or all fields when empty.

 [] array of strings 0 or more strings

includeExistingRecords

The "includeExistingRecords" property is a Boolean that returns streams that synchronize existing records if true.

 null Boolean

true

false

includeExistingRecordsFilter

The "includeExistingRecordsFilter" property is a Boolean that returns streams that synchronize existing records if true.

 null Boolean

true

false

includeExpiredMessages

Set the "includeExpiredMessages" property to true to include expired messages in a subscription. A message has expired when the "messageHasExpired" property in the response is true.

 

 true Boolean

true

false

includeInputConnectorProperties

The optional "includeInputConnectorProperties" property is an array of strings. Each string is the name of a connector property. 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.

 

If the "includeInputConnectorProperties" array is empty [], each object in the list contains the unique name of the connector, which you can use to look up additional information.

 

If the "includeInputConnectorProperties" array is omitted or null, the "inputConnectors" list is not included in the response.

 

Available properties include "connectorName", "connectorId", "settings", "serviceName", and "metadata". 

 

Note: inputs and outputs are included separately because they have different properties.

 

Request example 1

   "includeInputConnectorProperties": [],

Response example

   "inputConnectors": [
     { "connectorName": "Modbus1 Input" }
   ],

Request example 2 

   "includeInputConnectorProperties": [ "connectorName", "lastCollectedTimestamp" ],

Response example 2

   "inputConnectors": [
     {
       "connectorName": "Modbus1 Input", "lastCollectedTimestamp": "2025-08-28T10:47:13.041"
     }
   ],
 [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includeMessageMetadata

Set the "includeMessageMetadata" property to true to include the message's "id", "timestamp", "error", and "log" properties.

 false Boolean

true

false

includeMetadata

The "includeMetadata" property is an optional Boolean that specifies whether to include the "metadata" property in the response. It defaults to true.

true

Boolean

 

true

false

null

 

includeMetrics

The optional "includeMetrics" property includes dynamically calculated properties in the results when set to true. It defaults to false.

 

By default, dynamically calculated properties are not included in the results because they take extra time to retrieve.

 false Boolean

true

false

includeMqttProperties

Set the "includeMqttProperties" property to true to include the MQTT properties in the response. Otherwise, omit the property or set it to false or null. MQTT properties are helpful when you need to troubleshoot MQTT messages.

 false Boolean

true

false

includeOtherFields

Set the "includeOtherFields" property to true to include additional fields that are not the built-in integration table fields, transform fields, and MQTT fields. Otherwise, omit the property or set it to false or null.

 false Boolean

true

false

includeOutputConnectorProperties

The optional "includeOutputConnectorProperties" property is an array of strings. Each string is the name of a connector property. When it is included in the request, the response includes 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.

 

If the "includeOutputConnectorProperties" array is empty [], each object in the list contains the unique name of the connector, which you can use to look up additional information.

 

If the "includeOutputConnectorProperties" array is omitted or null, the "outputConnectors" list is not included in the response.

 

Available properties include "connectorName", "connectorId", "settings", "serviceName", and "metadata". 
 

Note: inputs and outputs are included separately because they have different properties.

Request example 1

   "includeOutputConnectorProperties": [],

Response example

   "outputConnectors": [
     { "connectorName": "Modbus1 Output" }
   ],

Request example 2 

   "includeOutputConnectorProperties": [ "connectorName", "lastDeliveredTimestamp" ],

Response example 2

   "outputConnectors": [
     {
       "connectorName": "Modbus1 Output", "lastDeliveredTimestamp": "2025-08-28T10:47:13.041"
     }
   ],
 [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includePrimaryKey

 (optional) specifies when to add the "pk" property to the data change event's "fields" object to indicate the field's position in the primary key. "forPrimaryKeyFields" string enum

"forEachField"

"forPrimaryKeyFields"

"never"

includePublishedTopics

Set the "includePublishedTopics" property to true for the response to include the "publishedTopics" property, which contains all topics a client's session has published since the session was created. To omit the list of published topics, omit this property or set it to false or null.

 true Boolean

true

false

includeStats

The "includeStats" property indicates whether or not the "stats" property will be returned in the response.

 true Boolean

true

false

includeSubscribedTopics

Set the "includeSubscribedTopics" property to true for the response to include the "subscribedTopics" property, which contains the topics a client's session is currently subscribed to. To omit the list of subscribed topics, omit this property or set it to false or null.

 true Boolean

true

false

includeSystemTables

When this property value is true, the server response includes system tables in the list of tables.

The default value is false.

 

Example

"params": {
  "includeSystemTables": true
}
 false Boolean

true

false

includeThingProperties

The optional "includeThingProperties" property is an array of strings. Each string is the name of a device property. When it is included in the request, the response includes a "things" list that contains all the devices and software related to the request. Each item in the list is an object that contains the specified properties.

 

If the "includeThingProperties" array is empty [], each object in the list contains the unique name of the device, which you can use to look up additional information.

 

If the "includeThingProperties" array is omitted or null, the "things" list is not included in the response.

 

Available properties include  "id", "thingName", "status", "manufacturer", "model", "serialNumber", "type", "purpose", "description", "location", "labels", "hostnames", "metadata", and "photo".


Request example 1

   "includeThingProperties": [],

Response example

   "things": [
     {
       "thingName": "plc 3"
     }
   ],

Request example 2 

   "includeThingProperties": [ "id", "thingName", "purpose", "location" ],

Response example 2

   "things": [
     {
       "id": 1,
       "thingName": "plc 3",
       "purpose": "Stamper temperature",
       "location": "factory1/line1/station1"
     }
   ],
 [] array of strings

"id"

"thingName"

"status"

"manufacturer"

"model"

"serialNumber"

"type"

"purpose"

"description"

"location"

"labels"

"hostnames"

"metadata"

"photo"

includeTopicProperties

The optional "includeTopicProperties" property is an array of strings. Each string is the name of a topic property. When it is included in the request, the response includes a "topics" list that contains all the MQTT topics related to the request. Each item in the list is an object that contains the specified properties.

 

If the "includeTopicProperties" array is empty [], each object in the list contains the unique topic name, which you can use to look up additional information.

 

If the "includeTopicProperties" array is omitted or null, the "topics" list is not included in the response.

 

For available properties, see the top-level properties in the "describeTopics" action's "results" list.


Request example 1

   "includeTopicProperties": [],

Response example

   "topics": [
     { "topic": "temperature" }
   ],

Request example 2 

   "includeTopicProperties": [ "id", "topic", "averageMessagesPerMinute" ],

Response example 2

   "topics": [
     {
       "id": 1,
       "topic": "temperature",
       "averageMessagesPerMinute": 12
     }
   ],
 [] array of strings zero or more of the properties in the results example of the describeTopics action

includeTransformFields

Set the "includeTransformFields" property to true to include custom transform fields (if any) that a customer added to the integration table. Otherwise, omit the property or set it to false or null. Custom transform fields are helpful when you want to see the outputs and inputs of transformations assigned to the integration table.maxMessages.

 false Boolean

true

false

indexFieldFilters

The "indexFieldFilters" is a required array containing at least one object. Each object is a field comparison operation. A comparison operation compares its value to the index key of a record. A record is included in the results when all the field comparison operations return true.

Example
      "indexFieldFilters": 
      [
        {
          "fieldName": "name",
          "operator": ">=",
          "value": "Michael"
        },
        {
          "fieldName": "rank",
          "operator": ">=",
          "value": "1"
        },
        {
          "fieldName": "rank",
          "operator": "<",
          "value": "3"
        }
      ]
 Required - No default value array of objects

"fieldName"

"operator"

"value"

indexFields

The "indexFields" property is a required field comparison array of objects in the "indexFilter" property of the "getRecordsStartingAtKey" method. It is used by an index to find a record.

  • It contains at least one object.
  • Each object is a field comparison operation.
  • The server compares the field value in this object to the corresponding field in the index key.
  • It then positions the query before or after this record.
  • The "fieldName" property in each object must be unique and be the name of a field in the index.
  • The "value" property must contain an appropriate value for the type of field.
      "indexFields": 
      [
        {
          "fieldName": "name",
          "value": "Michael"
        },
        {
          "fieldName": "rank",
          "value": "1"
        }
      ]
 Required - No default value array of objects

"fieldName"

"value"

indexFileExtension

The "indexFileExtension" property is an optional string from 0 to 64 bytes. It specifies the file system extension to use for a table's index files. If omitted, it defaults to ".idx".

Note If set to a zero-length string, then newly created index files will have no extension.

"params": {
  "indexFileExtension": ".tidx"
}
 ".idx" string 0 to 64 bytes

indexFilter

The "indexFilter" property selects an index and defines the lower and upper bounds of records to be returned from the index.

 

One-field index
"indexFilter":
    {
      "indexName": "name_livedpast2000",
      "partialKey": "Mi"
    }
Multi-field index
"indexFilter":
    {
      "indexName": "name_livedpast2000",
      "partialKey": [ "2023-09-22", "Mi" ] 
    }

Required - No default value

 object

"indexName"

"partialKey"

"indexFieldFilters"

 

indexName

The "indexName" property is a required string from 1 to 64 bytes. It is the name of an index. A zero-length "indexName" is invalid.

"params": {
  "indexName": "index1"
}

Required - No default value

 string 1 to 64 bytes

inParams

The "inParams" property is both an optional and required array of objects that specifies the values of input parameters. When optional it defaults to an empty array.

  • It must include one value for each input parameter in each SQL statement in the "sqlStatements" property.
  • It is optional when no SQL statements have named parameters.
    • A named parameter can be in SELECT and CALL statements.
  • It is required when one or more SQL statements have named parameters.
{
  "params": {
    "inParams": [
      {
        "name": "inIntParam1",
        "value": 3
      },
      {
        "name": "inoutBinaryParam3",
        "value": "54657374"
      },
      {
        "name": "mySqlNamedParam4",
        "value": "Ray"
      }
    ]
  }
}

[]

The is the default when no SQL statements have any named parameters. When one or more SQL statements have named parameters, this is required.

 array of objects

"name"

"value"

inputName

The "inputName" property is a required string that specifies the unique name of an input.

"params": {
    "inputName": "modbusTCP",
    "serviceName": "modbus"
}

A FairCom generated name that follows the pattern "Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>"

 string 1 to 100 bytes

inputNames

 The "inputNames" property is a required array of strings that specifies the names of the inputs you want to be described in the result. [] array 0 or more strings

integrationTableIdFilter

 The optional "integrationTableIdFilter" property is the unique integer ID of an integration table. The "listTags" action includes tags associated with the specified integration table. [] array of integers zero or more integration table id integers

ipAddress

 The "ipAddress" property specifies the PLC/Equipment IPV4 Address. Required - No default value string A valid IP address

keepAliveSeconds

The "keepAliveSeconds" property is an optional integer that specifies how often (in seconds) the broker expects a message to be sent. The server will retain a temporary session as long as the client performs an MQ Message action within the keep alive timeout period, which is "keepAliveSeconds" x 1.5. Once there is no activity, the server starts the session expiry timer to remove the temporary session. If there is no session activity within the number of seconds specified in the "sessionExpiryInternal" property, the server removes the session.

 0 integer No limit

key

The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value.

In the Key-Value API, this property is required.

""

Required in the Key-Value API 

 string 1 to 128 bytes

keys

 The required "keys" property contains an array of keys for an action to work on and return, such as [ "key1", "key2" ]. Required - No default value array of strings one or more key strings

keyStore

The required "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role.  An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 Required - No default value string enum

"global"

"role"

"user"

keyValuePairs

 The "keyValuePairs" property contains an array of objects. Each object represents a key-value pair and contains "key" and "value" properties, such as { "key": "k1",  "value": 1 }. Required - No default value array of key-value objects 
[
  { 
    "key": "myKey", 
    "value": 1
  }
]

label

The optional "label" property assigns a label to an object. The "label" object contains "group" and "name" properties that uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a valid group and name for a label.

A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as "listTopics" and "listMqSessions" to find objects with a specific label.

The "label" property is mutually exclusive from the "labelId" property.

 null object 
"label": {
  "group": "group name",
  "name": "label name"
}

labelID

The optional "labelId" property assigns a label to an object. The "labelId" property uniquely identifies a label.

A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as "listTopics" and "listMqSessions" to find objects with a specific label.

The "labelId" property is mutually exclusive with the "label" property.

 null integer 0 to 4294967296

labels

The "labels" property is a required array of label objects. 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

 

[] 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".

labelsFilter

The optional "labelsFilter" property finds tags that contain one of the labels included in the property. It is an array of strings that defaults to the empty array []. Each string is a label. A tag may have zero or more labels. Each label is a string from 1 to 64 bytes.

 

The API allows the same label to be assigned to many tags.

 [] array of strings zero or more label strings

length

This property is an integer that specifies the length of a table field. See also Data types.

It is required to set the length of the following fixed-length data types:

  • "char" (between 1 and 65,500 bytes).
  • "binary" (between 1 and 65,500 bytes).

It is required to set the maximum length for the following variable-length data types:

  • "varchar" (between 1 and 65,500 bytes).
  • "varbinary" (between 1 and 65,500 bytes).

It is optional to set the maximum length of the "json" data type, which defaults to 2 gigabytes. You may set its maximum length between 1 and 65,500 bytes.

It is optional to set the maximum length of the "number" and "money" data types, which default to 32 numeric digits. You can change the "length" to limit the precision of the number of digits to the left of the decimal point.

  • "number" and "money" are always stored as 32 decimal digits. Using a length less than 32 does not benefit storage.
  • You may optionally use "length" to specify fewer than 32 total digits to limit the maximum number of digits in the field. For example, a length of 4 allows numbers such as 12, 123, 1234, 12.34, and 0.1234, but not 12345, 123.45, or 0.12345.
  • You must always use "scale" to set the number of decimal places to the right of the decimal point, which must be less than or equal to the length. For example, "money" with a scale of 2, defaults to 30 digits to the left of the decimal point and 2 digits to the right, and "money" with a scale of 4, defaults to 28 digits to the left of the decimal point and 4 digits to the right.

 The "length" property is ignored for other data types because they have predefined lengths. For example, "lvarchar" and "lvarbinary" always have a maximum length of 2GB.

Note "nchar" and "nvarchar" are only supported in FairCom's special UCS-2 server edition. These field types allocate two bytes to each character. Because UCS-2 is inefficient, FairCom recommends its standard database, which supports modern, efficient, variable-length UTF-8 characters. 

"nchar" can be between 1 and 65,500 bytes. 

"nvarchar" can be between 1 and 65,500 bytes.

 

Request example

Create a table that contains all field types that use the "length" property.

"fields": [
  {
    "name": "a",
    "type": "char",
    "length": 16
  },
  {
    "name": "b",
    "type": "varchar",
    "length": 65500
  }
],
 null integer 1 to 65500

localDatabaseName

The "localDatabaseName" property is a string that specifies the database name of the table on the FairCom MQ server that stores the stream's data change events.

 Defaults to the "defaultDatabaseName" value that is set during "createSession". If no default is set during "createSession", then "faircom" is used. string 1 to 64 bytes

localDatabaseNameFilter

The "localDatabaseNameFilter" property is an optional string that specifies a partial match for the database name of the table on the FairCom MQ server that stores the stream's data change events.

 null string 1 to 64 bytes

localDataFilePath

The "localDataFilePath" property is a string that specifies the data file path of the table on the FairCom MQ server that stores the stream's data change events. It can be a full path or a relative path from the server's data directory.

 Required - if "localTableName" is not specified. string No limits

localDataFilePathFilter

The "localDataFilePathFilter" property is an optional string that specifies a partial match for the file name of the table on the FairCom MQ server that stores the stream's data change events.

 null string 1 to 64 bytes

localOwnerName

The "localOwnerName" property is a string that specifies the account that owns the table on the FairCom MQ server that stores the stream's data change events.

 Defaults to the "defaultOwnerName" value that is set during "createSession". If no default is set during "createSession", then "admin" is used. string 1 to 64 bytes

localOwnerNameFilter

The "localOwnerNameFilter" property is an optional string that specifies a partial match for the owner name of the table on the FairCom MQ server that stores the stream's data change events.

 null string 1 to 64 bytes

localTableName

The "localTableName" is a string that specifies the name of the table on the FairCom MQ server that stores the stream's data change events.

 Required if "localDataFilePath" is not specified string 1 to 64 bytes

localTableNameFilter

The "localTableNameFilter" property is an optional string that specifies a partial match for the table name of the table on the FairCom MQ server that stores the stream's data change events.

 null string 1 to 64 bytes

location

The optional "location" property specifies the item's location. A thing may have one location. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

This API uses the Label API to manage manufacturers.

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

1 to 64 bytes

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

locationFilter

 The optional "locationFilter" property is an array of strings. Each string is a partial or complete location name, such as, "locationFilter": [ "myLoca", "factory2-line6-station1" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. [] array zero or more location strings.

lockoutAfterNFailedAttempts

The "lockoutAfterNFailedAttempts" property is an optional integer that specifies the maximum number of consecutive times a failed login attempt can occur before the account is temporarily locked out for "lockoutWaitMinutes".

  • This value overrides the server's default value for this account, which is set by the configuration keyword LOGON_FAIL_LIMIT.
  • If omitted or set to null, it is not changed.
  • If present and set to a valid number, it is set to the new value.
 Defaults to the session's "LOGON_FAIL_LIMIT" property integer 0 to 2147483647

lockoutWaitMinutes

The "lockoutWaitMinutes" property is an optional integer that specifies the number of minutes an account remains temporarily locked out after the number of failed attempts defined by "lockoutAfterNFailedAttempts".

  • This value overrides the server's default value for this account, which is set by the configuration keyword LOGON_FAIL_TIME.
  • If omitted or set to null, it is not changed.
  • If present and set to a valid number, it is set to the new value.
 Defaults to the session's "LOGON_FAIL_TIME" property integer 0 to 2147483647

logLevel

 Defines what type of messages the replication agent will log. "warning" string enum

"off" - no messages logged

"debug" - logs debug, info, warning, and error messages

"info" - logs info, warning, and error messages

"warning" - logs warning and error messages

"error" - logs error messages

logTransformOverwrites

The optional "logTransformOverwrites" property has a true or false value and defaults to true. When true and a record is inserted into the integration table, the server adds log entries to the log field when a transform step overwrites a field that already contains a value. When true, it protects fields, such as source_payload, from being overwritten accidentally. 

You typically set "logTransformOverwrites" to true when testing transform steps. Once they are working as expected, you can set it to false.

If multiple "recordPath" properties write to the same JSON properties in a "tableFieldsToJson" transform, the server will return an error because "recordPath" cannot overwrite. Multiple occurrences of the "recordPath" property may reference the same property as long as the property is in different fields/tables.

Additionally, non-JavaScript transform steps cannot overwrite protected fields or the source_payload field. The only exception is that a single "tableFieldsToJson" transform step may write to the source_payload field.

You may create transform steps to take the value of one JSON property and store it in multiple fields as long as no previous transform steps have already put values in these fields. Conversely, you may take the value of one field and store it in multiple JSON properties.

Tip Ensure JavaScript transform steps do not overwrite fields updated by other transform steps. 

Do not use the "tableFieldsToJson" transform method to overwrite the source_payload field; instead, use "tableFieldsToJson" to write to a different field and use the "configureTopic" action with the "outputPayloadField" property to configure the MQTT topic to deliver that field's value to subscribers. 

Ensure SQL, JSON DB, and other APIs set the value of the source_payload field and do not set field values that transform steps update.

 false Boolean

true

false

manufacturer

The optional "manufacturer" property specifies the manufacturer of the thing. A thing may have one manufacturer. Many things can share the same manufacturer. It defaults to "unknown" and is a string from 1 to 64 bytes. You can use it to do exact lookups and filtering.

 

This API uses the Label API to manage manufacturers.

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

manufacturerFilter

 The optional "manufacturerFilter" property is an array of strings. Each string is a partial or complete manufacturer name, such as, "manufacturerFilter": [ "Siem", "Rockwell" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties.
 		 [] array zero or more manufacturer strings

mapOfPropertiesToFields

The "mapOfPropertiesToFields" property takes fields in the table and maps them to a field containing JSON properties. It is an array of property map objects. Each object maps a field in a table to a JSON property in another field.

  • Required properties
    • "recordPath"
    • "fieldName"
  • Optional properties
    • "binaryFormat"
    • "numberFormat"
    • "variantFormat"
    • "dateFormat"
    • “timeFormat”
 [] array

"binaryFormat"

"dateFormat"

"fieldName"

"numberFormat"

"recordPath"

"timeFormat"

"variantFormat"

maxCodeVersion

The 

"maxCodeVersion" property is an optional integer and defaults to the current version of the code package. If specified, the server returns code packages up to and including the specified version.

 

 Current version integer 1 to 2147483647

maxDaysBeforePasswordMustChange

The "maxDaysBeforePasswordMustChange" property is an optional integer that specifies the maximum number of days a user can wait to change their password before the account is automatically locked out. A value of zero disables this feature.

  • If omitted or set to null, it is not changed.
  • If present and set to a valid number, it is set to the new value.
 "" integer 0 to 2147483647

maxDeliveryRatePerSecond

The "maxDeliveryRatePerSecond" property sets the throttle rate for current and new subscribers of the topic. This property is optional. If omitted, it defaults to 0, which means no throttling is applied.

  • It must be a value between 0 and 2,147,483,647, but a more realistic range is between 0 and 1,000. It is useful to keep a client from being overwhelmed with too many messages sent too quickly.
  • You can set it to a number greater than 0 to throttle the delivery rate. This allows you to avoid saturating the network and other resources.
    • For example, you can set it to 100 to throttle the delivery to 100 messages per second. This is a maximum setting because the actual message delivery rate is bounded by the network, local resources, the hardware running FairCom's servers, and a client’s ability to process messages quickly.
 0

int32

0 to 2147483647

maxHealthyBacklogRatePerMinute

The "maxHealthyBacklogRatePerMinute" property sets the maximum number of backlog messages per minute for a healthy session. A backlog message is one the server has not yet published to subscribers. The backlog of a topic grows when the incoming message rate exceeds the outgoing. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.

A connected session is healthy when its message backlog rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthyBacklogRatePerMinute" property and the "sessionHealth" property to report the health of a session.

 0 integer  

maxHealthySendRatePerMinute

The "maxHealthySendRatePerMinute" property sets the maximum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.

A connected session is healthy when its message send rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.

 0 integer  

maxHealthySubscribedTopicFiltersCount

The "maxHealthySubscribedTopicFiltersCount" property sets the maximum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no upper bound.

A connected session is healthy when it has subscribed to at most the maximum number of topic filters. The "describeMqSessions" action returns the "maxHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.

A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "maxHealthySubscribedTopicFiltersCount" property does not limit the number of topics.

 0 integer  

maximumPacketSize

The "maximumPacketSize" property is an optional integer that specifies the maximum size of a single packet that the session can receive.

 1024 integer  

maxInflightMessages

The "maxInflightMessages" property protects subscribers from receiving messages faster than they can handle. The default value is 0. This property is optional.

  • The default value of 0 means there is no maximum limit.
  • This property defines the maximum number of unacknowledged messages that FairCom's servers will send to each subscriber of this topic.
    • For example, setting this property to 10 allows FairCom's servers to send up to 10 publish packets to a subscriber before the servers wait for the subscriber to acknowledge receipt of at least one publish packet.
 0

int32

0 to 2147483647

maxMessages

The "maxMessages" property is optional and defaults to 20. It has a minimum value of 1 and a maximum value of 100000. It specifies the number of messages to return from a "getMessages…" action. The number of returned messages will be equal to or less than this maximum.

 20 integer 0 to 100000

maxMinutesBeforeNextLogin

The "maxMinutesBeforeNextLogin" property is an optional integer >= 0 and <= 35791394 that specifies the maximum number of minutes the server will wait for an account to log in again before it locks the account out. The default value is 0, which disables this feature. It is useful for automatically disabling an account due to inactivity. For example, a value of 10080 minutes requires a user to log in at least once a week.

  • This value overrides the server's default value for this account, which is set by the configuration keyword LOGON_MUST_TIME.
  • If omitted or set to null, it is not changed.
  • If present and set to a valid number, it is set to the new value.
 Defaults to the session's "LOGON_MUST_TIME" property integer 0 to 35791394

maxRecords

The 

"maxRecords" property is an optional string value that defaults to 20. It is used with "skipRecords" to paginate the results. If the value is not null or omitted, the server returns the maximum number of results specified by "maxRecords".

 

 20  integer -1 to 65535

maxSecondsBeforeConnectingToNextServer

 The "maxSecondsBeforeConnectingToNextServer" property is an optional integer that specifies the maximum number of seconds the server will attempt to reconnect to the existing server before it attempts to connect to the next server in the "sourceServers" list. 30 int32 1 to 65535

maxUnsavedEvents

The optional "maxUnsavedEvents" property requires a connector to periodically write all collected tags to the integration table – even if their values have not changed. It specifies the maximum number of collection events before the connector unconditionally saves collected tags. 
The "maxUnsavedEvents" property is an integer number between 1 and 4294967296. Lower values are appropriate for infrequently collected tags and higher values for frequently collected tags. The default value is "disabled", which disables the feature. 
This property ensures the connector periodically saves infrequently changing data values. Because "onChange" rules can prevent collected data from being saved, the "maxUnsavedEvents" property is particularly important when you want to ensure values are periodically saved. 
The following chart shows a deadband covering the entire range of values, which normally prevents values from being saved. The Maximum Unsaved Events rule overrides the deadband (and all other rules) to ensure the connector saves values periodically. Because "maxUnsavedEvents" is set to 4, the connector ensures no more than 4 data collection events go unsaved. 

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The "dataCollectionIntervalMilliseconds" property specifies the number of milliseconds between each data collection cycle.
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • “normalLowerLimit”
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude"
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "disabled" integer 1 to 4294967296

memoryArea

 The "memoryArea" property specifies the type of memory area where the connector retrieves data. Required - No default value string
  • "pe" - Process Inputs
  • "pa" - Process Outputs
  • "mk" - Flags "Merkers" 
  • "db" - Data Block
  • "ct" - Counters
  • "tm" - Timers

memoryLimit

The "memoryLimit" property is an optional integer that specifies the maximum number of bytes the server will allocate to the account. Depending on the memory rule, it may override the default memory allocations set for each user by the server for all accounts or by a group for all its accounts.

  • If omitted or set to null, it is not changed.
  • If present and set to a valid number, it is set to the new value.
 Defaults to the session's "USR_MEMORY" property integer 0 to 2147483647

memoryRule

The "memoryRule" property is an optional enumerated string that uses one of the following values to specify additional rules that allow the account to exceed the memory limit defined by the "memoryLimit" property:

  1. "default"
  2. "absolute" sets the memory limit to no more than the value defined in "memoryLimit".
  3. "guideline" allows the server to allocate additional memory while attempting to keep memory below "memoryLimit".
  • If omitted or set to null, it is not changed.
  • If present and set to a valid string, it is updated.
 Defaults to the session's "USR_MEM_RULE" property string

"default"

"absolute"

"guideline"

messages

The "messages" property is a required array of objects that specifies the message to be published to MQ as well as information about the message.

 [] array of objects

1 or more objects including some or all of the following properties:

"binaryFormat"

"contentType"

"correlationData"

"expirySeconds"

"payload"

"responseTopic"

"retain"

"userProperties"

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

metadataFilter

The 

"metadataFilter" property is an optional string value that defaults to null. If the value is not null or omitted, the results only include code packages with metadata that match the full-text search specified in the "metadataFilter" property. A code package's "metadata" property contains a JSON object with user-defined key-value pairs. For example, to constrain results to include the key value pair "myProperty": "myValue" in the metadata, use the search string, "metadataFilter": "'myProperty' NEAR/0 'myValue'". Notice that NEAR/0 specifies no intervening words or phrases. If you want to allow a maximum of one intervening word, use NEAR/1. You can specify a maximum of any number of intervening words. 

 

 null string 1 to 65,500 bytes

minCodeVersion

The 

"minCodeVersion" property is an optional integer that defaults to the code package's first version. If specified, the server returns code packages starting with the specified version.

 

 First version integer 1 to 2147483647

minHealthySendRatePerMinute

The "minHealthySendRatePerMinute" property sets the minimum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no lower bound.

A connected session is healthy when its message send rate exceeds the minimum. The "describeMqSessions" action returns the "minHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.

 0 integer Any positive number

minHealthySubscribedTopicFiltersCount

The "minHealthySubscribedTopicFiltersCount" property sets the minimum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no lower bound.

A connected session is healthy when it has subscribed to at least the minimum number of topic filters. The "describeMqSessions" action returns the "minHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.

A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "minHealthySubscribedTopicFiltersCount" property does not limit the number of topics the wildcards match - rather, it establishes a lower bound on the number of subscribed topic filters an MQ Session is allowed to have.

 0 integer Any positive number

modbusBaudRate

 The optional "modbusBaudRate" property (RTU only) specifies the baud rate of the communication (9600, 19200, 57600, 115200, and so forth). 19200 int16 Any baud rate

modbusConvertToFloat

 The optional "modbusConvertToFloat" property causes the connector to convert one or two register values into a JSON floating point number. "no" string

"no"

"divideByInteger"

"appendAdjacentRegisters"

"appendAdjacentRegistersReversed"

modbusDataAccess

The "modbusDataAccess" property specifies the type of data structure to access. 

  • "coil" - 1 bit read-write
  • "discreteinput" - 1 bit read-only
  • "holdingregister" - 2 byte word read-write
  • "inputregister" - 2 byte word read-only
 Required - No default value string

"coil"

"discreteinput"

"holdingregister"

"inputregister"

modbusDataAddress

The "modbusDataAddress" property specifies where the Modbus protocol should read or write a value to a memory address on a device. By default it is zero-based and ranges from 0 to 65,535.

Some vendors document data addresses as one-based values. Set the "modbusDataAddressType" to "oneBased" to configure the "modbusDataAddress" property to use a one-based address, which ranges from 1 to 65,536.

 Required - No default value int16 0 to 65536

modbusDataAddressType

 The optional "modbusDataAddressType" property specifies if the modbusDataAddress is zero-based or one-based. "zeroBased" string

"zeroBased"

"oneBased"

modbusDataBits

 The optional "modbusDataBits" property (RTU only) specifies the number of bits of data. 8 int16 5, 6, 7, or 8

modbusDataLen

The "modbusDataLen" property specifies the number of 2-byte registers needed to hold the data — for example, if "modbusDataLen" is 2 the data is in 4 bytes (int32)

Note: if "modbusDataType" is specified, this value is ignored

 Required if "modbusDataType" is not specified integer 1, 2, or 4

modbusDataType

 The optional "modbusDataType" property specifies how to convert Modbus binary data types to JSON types. Choose a type that matches the byte order of the data type. The byte order is specified using the letters ABCDEFGH. For more detailed information about the "modbusDataType" property, read our documentation on Modbus data types. "" string

"bitBoolean"

"bitEnum"

"bitInt"

"bitString"

"int8Signed"

"int8Unsigned"

"int16SignedAB"

"int16UnsignedAB"

"int16SignedBA"

"int16UnsignedBA"

"int32SignedABCD"

"int32UnsignedABCD"

"int32SignedDCBA"

"int32UnsignedDCBA"

"int32SignedBADC"

"int32UnsignedBADC"

"int32SignedCDAB"

"int32UnsignedCDAB"

"int64SignedABCDEFGH"

"int64UnsignedABCDEFGH"

"int64SignedBADCFEHG"

"int64UnsignedBADCFEHG"

"int64SignedCDABGHEF"

"int64UnsignedCDABGHEF"

"int64SignedDCBAHGFE"

"int64UnsignedDCBAHGFE"

"int64SignedHGFEDCBA"

"int64UnsignedHGFEDCBA"

"int64SignedGHEFCDAB"

"int64UnsignedGHEFCDAB"

"int64SignedFEHGBADC"

"int64UnsignedFEHGBADC"

"int64SignedEFGHABCD"

"int64UnsignedEFGHABCD"

"ieeeFloat32ABCD"

"ieeeFloat32CDAB"

"ieeeFloat32DCBA"

"ieeeFloat32BADC"

"ieeeFloat64ABCDEFGH"

"ieeeFloat64BADCFEHG"

"ieeeFloat64CDABGHEF"

"ieeeFloat64DCBAHGFE"

"ieeeFloat64HGFEDCBA"

"ieeeFloat64GHEFCDAB"

"ieeeFloat64FEHGBADC"

"ieeeFloat64EFGHABCD"

modbusDecimalDigits

The "modbusDecimalDigits" property is an optional integer that specifies the number of floating-point fractional digits to retain in a floating-point number. Set it to null to retain all digits. Valid values are 0, 1, 2, 3, 4, or 5. The server truncates the floating-point number to the specified number of digits.

 2 integer 1 to 5

modbusDivisor

The "modbusDivisor" property is required when "modbusConvertToFloat" is set to "divideByInteger". It is the divisor the server uses to convert an integer value to a float. Use it when you set the "modbusDataType" to one of the integer types, and the server will convert the value to a floating point before writing it to the record.

 Required if "modbusConvertToFloat" is "divideByInteger". Defaults to 1 integer

1 to 65536

Typical values are 10, 100, 1000, and 10000

modbusParity

 The optional "modbusParity" property (RTU only) specifies the data parity. "even" string "none", "even", "odd"

modbusProtocol

 The "modbusProtocol" property specifies the protocol used to connect to the Modbus server. Required - No default value string

"TCP"

"RTU"

modbusSerialPort

The "modbusSerialPort" property (RTU only) specifies the name of the serial port handled by the OS (such as "/dev/ttyS0" or "/dev/ttyUSB0").

On Windows, it is necessary to prepend the COM name with "\\.\" if the COM number is greater than 9. For example, "\\\\.\\COM10".

For Windows naming conventions, see Naming Files, Paths, and Namespaces .

 Required - No default value string No limit

modbusServer

 The "modbusServer" property (TCP only) specifies the IP/hostname of the Modbus device. Required - No default value string No limit

modbusServerPort

 The "modbusServerPort" property (TCP only) specifies the IP Port for the Modbus device for modbusTCP. Required - No default value int16 0 to 65535

modbusStopBits

 The "modbusStopBits" property (RTU only) specifies the bits of stop. 1 int16 1 or 2

modbusUnitId

The optional "modbusUnitId" property specifies a device unit number that uniquely identifies a device. Modbus communicates to a device or gateway on one IP address and port. A device or gateway may proxy Modbus communications across multiple Modbus devices.

The unit number uniquely identifies each of these devices. This property also applies to serial communications.

For serial communication, the range is 1 to 255

Note: The original Modbus specification called this feature a slave address.

 1 int16 0 to 255

model

The optional "model" property specifies a thing's model. A thing may have one model. Many things can share the same model number. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

This API uses the Label API to manage models.

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

modelFilter

 The optional "modelFilter" property is an array of strings. Each string is a partial or complete model name, such as "modelFilter": [ "ACME-123", "mod_" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. [] array zero or more model strings

mqttPayloadType

(optional) specifies the variant type format of the "source_payload" field.

 "binary" string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

"variantObject"

mqttProtocol

 (optional) specifies the version of MQTT protocol to use in your session. 5.0 string enum

"3.1.1"

"5.0"

mtconnectDeviceUuid

The required "mtconnectDeviceUuid" property specifies the identifier of the device that supplies data to the connector. When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document, which contains data from one or more devices. The "mtconnectDeviceUuid" property uniquely identifies the data stream the FairCom connector should use to gather data.

The device identifier is located in the uuid attribute of the <DeviceStream> element in an <MTConnectStreams> XML document returned from the MTConnect protocol. 

If the MTConnect protocol returns the following MTConnectStreams XML, you should set the "deviceUuid" property to "X1_373f-4ab9-9c7a-173edd23e4f3".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 Required - No default value string No limit

mtconnectDataItemId

The required "mtconnectDataItemId" property specifies the identifier of the data that the MTConnect connector collects. 

When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document. Data is located in elements containing the dataItemId attribute. The element's name is its data type and its value is the data. The "mtconnectDataItemId" property identifies a data item by specifying the value of the data element's dataItemId attribute.

If the MTConnect protocol returned the following <MTConnectStreams> XML document, you should set the "mtconnectDataItemId" property to "X1_Stamper1_Temperature". The data element is named REAL, which is its data type, and has a data value of "20.1".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>

Note An <MTConnectStreams> XML document has no common element name for data elements because the element name for a data item is its data type. In addition, the parent element of data elements may have one of three names: <Samples>, <Events>, and <Condition>. Thus, the best way to identify a data element is the presence of the dataItemId attribute.

 Required - No default value string No limit

mtconnectCategoryPropertyPath

The optional "mtconnectCategoryPropertyPath" property specifies the location in the JSON document to store the MTConnect category of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the name of the parent element that contains the data item. The parent element may be <Samples>, <Events>, or <Condition>. The connector maps the element name to one of the following category strings: "SAMPLE", "EVENT", or "CONDITION". It then puts the category string in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureCategory", or a complex JSON path, such as "temperature.category". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named <Samples>, which maps to the category of "SAMPLE".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectComponentNamePropertyPath

The optional "mtconnectComponentNamePropertyPath" property specifies the location in the JSON document to store the MTConnect component name of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the name attribute of the <ComponentStream> element that contains the data item. It puts the component name in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureComponent", or a complex JSON path, such as "temperature.component". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The <componentStream> element containing the data element has a name attribute of "Stamper1", which is the component name.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        name="Stamper1" 
        component="Device" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectDataItemIdPropertyPath

The optional "mtconnectDataItemIdPropertyPath" property specifies the location in the JSON document to store the MTConnect dataItemID of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the dataItemID attribute of the element that contains the data item. It puts the dataItemID value in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDataItemID", or a complex JSON path, such as "temperature.dataItemID". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature".

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        name="Stamper1" 
        component="Device" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectDataNamePropertyPath

The optional "mtconnectDataNamePropertyPath" property specifies the location in the JSON document to store the MTConnect data name of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the name attribute of the element that contains the data item. It puts the data name in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDataName", or a complex JSON path, such as "temperature.dataName". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element containing the data item has a name attribute of "Temperature", which is the data name.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        name="Stamper1" 
        component="Device" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectDataTypePropertyPath

The optional "mtconnectDataTypePropertyPath" property specifies the location in the JSON document to store the MTConnect data type of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the name of the element that contains the data item and puts it in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDataType", or a complex JSON path, such as "temperature.dataType". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named REAL, which is the data type of the data value.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectDeviceNamePropertyPath

The optional "mtconnectDeviceNamePropertyPath" property specifies the location in the JSON document to store the MTConnect device name that provides the data item. Omitting this property removes it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the name attribute of the <DeviceStream> element that contains the data item. It puts the device name in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDevice", or a complex JSON path, such as "temperature.device". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The <DeviceStream> element containing the data element has a name attribute of "X1", which is the device name.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectDeviceUuidPropertyPath

The optional "mtconnectDeviceUuidPropertyPath" property specifies the location in the JSON document to store the MTConnect deviceUuid of the device that provides the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector extracts the value of the deviceUuid attribute of the <DeviceStream> element that contains the data item. It puts the deviceUuid in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureDeviceUuid", or a complex JSON path, such as "temperature.deviceUuid". For examples, see Example property paths that group related properties.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The <DeviceStream> element containing the data element has a deviceUuid attribute of "X1_373f-4ab9-9c7a-173edd23e4f3", which is the deviceUuid.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectSequencePropertyPath

The optional "mtconnectSequencePropertyPath" property specifies the location in the JSON document to store the integer sequence number of the data item. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector puts the value of the MTConnect sequence attribute in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureSequence", or a complex JSON path, such as "temperature.sequence". For examples, see Example property paths that group related properties.

When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document, which contains data elements. A data element contains the dataItemId and sequence attributes. The sequence attribute identifies the device's sequence number of the data value.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named REAL. The value of the sequence attribute is 5. The MTConnect connector converts the sequence number into a JSON integer.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

mtconnectTimestampPropertyPath

The optional "mtconnectTimestampPropertyPath" property specifies the location in the JSON document to store the timestamp of when the device collects the data item. In contrast, the timestamp built into FairCom's integration table tracks when the FairCom connector collects the data. When a device collects data infrequently, the device timestamp is more accurate than FairCom's built-in timestamp. Omit this property to omit it from the JSON document.

When the FairCom MTConnect connector collects data, it generates a JSON document and stores it in the database. The connector puts the value of the MTConnect timestamp in the JSON document at the location specified by this property. You may use a simple property name, such as "temperatureTimestamp", or a complex JSON path, such as "temperature.timestamp".  For examples, see Example property paths that group related properties.

When the FairCom MTConnect Connector requests data over the MTConnect protocol, the device returns an <MTConnectStreams> XML document, which contains data elements. A data element contains the dataItemId and timestamp attributes. The timestamp attribute identifies when the device collected the element's data value.

In the following MTConnectStreams XML document returned over the MTConnect protocol, the data element has a dataItemId of "X1_Stamper1_Temperature". The element is named REAL. The value of the timestamp attribute is "2010-04-06T06:19:35.153141", which is formatted in ISO8601 format.

<MTConnectStreams>
  <Streams>
    <DeviceStream 
      name="X1" 
      uuid="X1_373f-4ab9-9c7a-173edd23e4f3">
      <ComponentStream 
        component="Device" 
        name="Stamper1" 
        componentId="X1_Stamper1">
        <Samples>
          <REAL 
            dataItemId="X1_Stamper1_Temperature"
            name="Temperature"
            sequence="5" 
            timestamp="2010-04-06T06:19:35.153141"
            >20.1</REAL>
        </Samples>
      </ComponentStream>
    </DeviceStream>
  </Streams>
</MTConnectStreams>
 null string JSON path

name

The "name" property is the name of a label or field. It is a required UTF-8 string that is up to 64 bytes long.

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.

 

 Required - No default value string 1 to 64 bytes

nameFilter

The "nameFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings, such as "nameFilter": [ "myName1", "myName2" ]. Each string is the name of a label and may be up to 64 bytes long. A label's name must match one of the names in the array to be included in the results.

Note The "nameFilter" and "partialNameFilter" properties are mutually exclusive.

 

 [] array of strings Each array item is a label string from 1 to 64 bytes

newCodeName

 The "newCodeName" is an optional string. When present, the server renames the code package from the current "codeName" to the "newCodeName". The server does not change the "codeName" when null or omitted. null string 1 to 64 bytes

newDatabaseName

The 

"newDatabaseName" property is an optional string. When present, the server uses the new database as the target for the action. When null or omitted, the server runs the action in the current database.

 null string 1 to 64 bytes

newDeprecated

The "newDeprecated" property is available in the "changeLabels" action. It optionally updates the "deprecated" property of an existing label. It defaults to null, which means the action does not change the label's deprecated status.

 null Boolean

true

false

null

newDescription

The "newDescription" property is available in the "changeLabels" action. It optionally updates the "description" property of an existing label. It defaults to null, which means the action does not change the label's description.

 "" string 1 to 65,500 bytes

newEnum

The "newEnum" property is available in the "changeLabels" action. It optionally updates the "enum" property of an existing label with a new integer value. It defaults to null, which means the action does not change the label's enum value.

 null smallint -32768 to 32767

newGroup

The "newGroup" property is available in the "alterLabel" and "changeLabels" action. It optionally assigns a new group name to an existing label. It defaults to null, which means the action does not change the label's group.

 null string 1 to 64 bytes

newKey

 The "newKey" property is required by the "renameKeys" action to rename keys. It is part of a key-rename object and its value is a string. It specifies the new name of a key. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. Required - No default value string 1 to 128 bytes

newMetadata

The "newMetadata" property is available in the "changeLabels" action. It optionally updates the "metadata" property of an existing label. It defaults to null, which means the action does not change the label's metadata.

 {} JSON 0 to 65,500 bytes

newName

The "newName" property is available in the "alterLabel" and "changeLabels" actions, as well as the table actions. It optionally assigns a new label name to an existing label or table. It defaults to null, which means the action does not change the label's or table's name.

 

 null string 1 to 64 bytes

newOwnerName

The 

"newOwnerName" property is an optional string. When present, the server uses the new owner name as the target for the action. When null or omitted, the server runs the action using the current owner name.

 

 null string 1 to 64 bytes

newPosition

The optional "newPosition" property is a signed 16-bit integer from -1 to 2500. It changes the physical position of a field in a table. The first field is position 0. A field is not moved to a new position when its value is -1 or when "newPosition" is omitted. A table may contain up to 2500 fields..

 

Request example

"fields": [
  {
    "name": "field1",
    "type": "varchar",
    "newPosition": 100
  }
]
 -1 integer -1 to 2500

newSequence

The "newSequence" property is available in the "changeLabels" action. It optionally updates the "sequence" property of an existing label. It defaults to null, which means the action does not change the label's sequence number.

 null double Any floating point or integer number.

newSubscriberDeliveryMode

The "newSubscriberDeliveryMode" property defines how new subscribers receive messages. The default is "newMessages".

  • It may be set to one of two values:
    • "newMessages"
    • "storedMessages"
  • When set to "newMessages" new subscribers only receive new messages.
  • When set to "storedMessages" new subscribers will receive some or all previously sent messages. The "newSubscriberDeliveryMode" property defines the maximum number of messages.

"newMessages"

 string

"newMessages"

"storedMessages"

newSubscriberMaxDeliveredMessages

The "newSubscriberMaxDeliveredMessages" property is the maximum number of previously stored historical messages a client receives automatically when subscribing to a topic. The default is 0.

  • A value of -1 or "all" defaults to delivering all currently stored messages.
  • A non-negative number limits the delivery of currently stored messages to that number, which may be a maximum of 2,147,483,647 messages.
  • This property only applies when the "newSubscriberDeliveryMode" property is set to "storedMessages".
  • The broker can only send messages stored in the topic’s integration table. The table's retention policy automatically removes old messages.
  • Each time a client unsubscribes from a topic and then subscribes to the topic, the broker sends historical messages as specified by this property. A client can use this behavior to reprocess messages, such as refresh a local data cache or recalculate aggregates.

Note A topic’s "retentionPolicy", "retentionUnit", and "retentionPeriod" properties define how long the broker retains messages in a topic’s integration table.

 -1 integer or "all" -1 to 2147483647 or "all"

newTableName

The optional "newTableName" property is a string containing a new name for the table. Use the "newTableName" property to rename a table. 

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

"params": {
  "tableName": "old_table_name"
  "newTableName": "new_table_name"
}
 null string 1 to 64 bytes

newTagName

The "newTagName" property is a string that specifies the unique name of a tag that is created by a transform step.  

  • It is a string from 1 to 256 bytes. 
  • It cannot be the empty string "".
  • It is required when a transform step in the "createIntegrationTable" or "alterIntegrationTable" actions includes the "tagProvenance" property and one of its objects has "provenanceAction" set to "calculateNew".
  • It is included in the response to "describeTags", "alterTag", and "createTag" when the "includeTagProvenance" property is true and one of the "tagProvenance" objects has "provenanceAction" set to "calculateNew".

"tagProvenance" example in the response to "describeTags"

   "tagProvenance": [
     {
       "provenanceAction": "collect",
       "connectorName": "INPUT: PLC 74 & Modbus",
       "connectorId": 51,
       "targetRecordPath": "source_payload.tmp",
       "description": "Collect provenance steps come from input connectors."
     },
     {
       "provenanceAction": "calculateNew",
       "newTagName": "Temperature Fahrenheit",
       "sourceRecordPaths": [
         "source_payload.temperatures.celcius"
       ],
       "targetRecordPath": "source_payload.temperatures.fahrenheit",
       "description": "Provenance steps come from the javascript transform step."
     },
     {
       "provenanceAction": "deliver",
       "connectorName": "OUTPUT: PLC 74 & Modbus",
       "connectorId": 52,
       "sourceRecordPath": "source_payload.temperature",
       "description": "Deliver provenance steps come from output connectors."
     },
     {
       "provenanceAction": "deliver",
       "connectorName": "OUTPUT: MES & REST",
       "connectorId": 53,
       "sourceRecordPath": "source_payload.temperature",
       "description": "Deliver provenance steps come from output connectors."
     }
   ]

"tagProvenance" example in an integration table's "transformSteps" property

   "transformSteps": [
     {
       "transformStepName": "standardizeTemperature",
       "transformStepMethod": "javascript",
       "transformStepService": "v8TransformService",
       "codeName": "JavaScript Standardize Temperature",
       "ownerName": "admin",
       "databaseName": "faircom",
       
       "tagProvenance": [
         {
           "provenanceAction": "calculateNew",
           "newTagName": "Temperature Fahrenheit",
           "sourceRecordPaths": [
             "source_payload.temperatures.celcius"
           ],
           "targetRecordPath": "source_payload.temperatures.fahrenheit",
           "description": "Provenance steps come from the javascript transform step."
         }
       ]
       
     }
   ]
 Required when a transform step in the "createIntegrationTable" or "alterIntegrationTable" actions includes the "tagProvenance" property and one of its objects has "provenanceAction" set to "calculateNew". string 1 to 256 bytes

newThingName

The optional "newThingName" property is a string that specifies a new unique name of a thing.  

  • It is a string from 1 to 64 bytes. 
  • It cannot be the empty string "". 
  • It applies to the "alterThing" action.

If present, it must be a unique thing name

 

 string 1 to 64 bytes

newValue

The "newValue" property is available in the "changeLabels" action. It optionally updates the "value" property of an existing label. It defaults to null, which means the action does not change the label's value.

 null JSON 0 to 65,500 bytes

normalLowerLimit

The optional, inclusive "normalLowerLimit" property specifies the low range of a normal collected value. An outlier is below this range. A change is saveable when it is greater than or equal to the normal upper limit.


The following chart shows a connector not saving a tag's value because it is outside the normal range.

 

 

Scenario


A connector may collect a value from a water pressure sensor once every 100 milliseconds. The device's pressure is turbulent and has outliers. A normal pressure is between 30 and 50. To not persist outliers, set "normalLowerLimit" to 30 and "normalUpperLimit" to 50.


Code example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 100,      
   "dataPersistenceStrategy": "onChange",

   "maxUnsavedEvents": 360,
  
   "settings": {      
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "waterPressure",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int16Signed",

         "normalLowerLimit": 30,
         "normalUpperLimit": 50
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • "normalLowerLimit"
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude" 
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "disabled" integer No limit

normalUpperLimit

The optional, inclusive "normalUpperLimit" property specifies the high range of a normal collected value. An outlier is above this range.  A change is saveable when it is less than or equal to the normal upper limit.


The following chart shows a connector not saving a tag's value because it is outside the normal range.

 

 

Scenario


A connector may collect a value from a water pressure sensor once every 100 milliseconds. The device's pressure is turbulent and has outliers. A normal pressure is between 30 and 50. To not persist outliers, set "normalLowerLimit" to 30 and "normalUpperLimit" to 50.


Code example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 100,      
   "dataPersistenceStrategy": "onChange",

   "maxUnsavedEvents": 360,
  
   "settings": {      
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "waterPressure",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int16Signed",

         "normalLowerLimit": 30,
         "normalUpperLimit": 50
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • "normalLowerLimit"
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude" 
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "disabled" integer No limit

nullable

The "nullable" property is an optional Boolean. When true, it allows a field to contain a NULL value. To require a field to have a non-null value, set "nullable" to false.

"fields": [
  {
    "name": "company",
    "type": "varchar",
    "nullable": true 
  }
]
 true Boolean

true

false

numberFormat

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers. The default value for "numberFormat" is the "defaultNumberFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultNumberFormat" property in the <faircom>/config/services.json file.

When "numberFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode a number assigned to a JSON property.

For example, including "numberFormat" in a "tableFieldsToJson" transform step controls if the server encodes a number in a JSON property as a number or a number embedded in a string.

Possible values:
  • "number"
    • This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .
    • This is most efficient.
    • JSON represents numbers are base-ten numbers that may have any number of digits.
    • Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.
  • "string"
    • This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494".
    • This is slightly less efficient because it includes two extra double quote characters
    • Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.
  • Omitted or set to null
    • This defaults to "number".

 

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "number" string

"number"

"string"

offset

 The "offset" property specifies the offset to the starting byte in the memory area where the connector retrieves data. Required - No default value integer 0 to 4294967296

oldKey

 The "oldKey" property is required by the "renameKeys" action to rename keys. It is part of a key-rename object and its value is a string. It specifies the current key that will be renamed. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. Required - No default value string  1 to 128 bytes

onChangeScope

The optional "onChangeScope" property specifies which tags the connector saves to an integration table. 
It is an enumerated string with the following values:

  • "saveAllTags" (default) 
    • The connector saves all collected tags to the integration table. 
  • "saveOnlyChangedTags" 
    • The connector persists tags with values that have changed from their previous value. If no "onChange" rules are defined, then all values are considered changed.
  • "saveSpecificTags" 
    • The connector persists the tags specified in the "onChangeScopeTags" property. 
    • It requires the "onChangeScopeTags" property to exist and specify one or more tags. 

Use cases

  • When you want to consistently collect the same data, set "onChangeScope" to "saveAllTags". This approach ensures transforms and queries always have all the data. Unless the "onChangeTrigger" property is set to "saveWhenAllTagsHaveChanged" tags are saved even when their value has not changed. 
  • When you want to save space in an integration table, set "onChangeScope" to "saveOnlyChangedTags". This approach also saves space in MQTT messages and other services that FairCom Edge delivers to.
  • When you want to save space in the integration table while persisting the same subset of tags, set "onChangeScope" to "saveSpecificTags". This approach allows the connector to collect additional tags to trigger persistence without persisting those tags.

 

 

Code Example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,
   
   "dataPersistenceStrategy": "onChange",
   "onChangeScope": "saveSpecificTags", 
   "onChangeScopeTags": ["t1"],

   "settings": {
     
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed"
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 


NOTES
 

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • “normalLowerLimit”
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude"
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "saveAllTags" string enum

"saveAllTags"

"saveOnlyChangedTags"

"saveSpecificTags"

onChangeScopeTags

The conditional "onChangeScopeTags" property is an array of "propertyPath" values from the "propertyMapList" object. Each "propertyPath" value is the connector's unique identifier to a collected data item, which is commonly called a "tag". 


The conditional "onChangeScopeTags" property is required when the "onChangeScope" property is set to "saveSpecificTags". It specifies which tags the connector should save to the integration table when a save event occurs. 


The following code excerpt persists the "temperature", "pressure", and "humidity" tags when a save event occurs.


 "onChangeScope": "saveSpecificTags", 
 "onChangeScopeTags": [ "temperature", "pressure", "humidity" ]


Code Example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,
   
   "dataPersistenceStrategy": "onChange",
   "onChangeScope": "saveSpecificTags", 
   "onChangeScopeTags": ["t1"],

   "settings": {
     
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed"
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES
 

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The "createInput" and "alterInput" actions return an error wen aspecified tag name is not defined.
  • The "createInput" and "alterInput" actions return an error if you assign a value to "onChangeScopeTags" and the "onChangeScope" property is not set to "saveSpecificTags".
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • “normalLowerLimit”
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude"
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 Required when the "onChangeScope" property is set to "saveSpecificTags". array of strings 1 or more strings

onChangeTrigger

The optional "onChangeTrigger" property specifies when the connector saves collected tags to an integration table. 
It is an enumerated string with the following values:

  • "saveWhenAnyTagHasChanged" (default) 
    • The connector saves tags when at least one tag value collected by the connector has changed from its previous value. 
  • "saveWhenAllTagsHaveChanged" 
    • The connector saves tags when all tag values collected by the connector have changed from their previous value.
  • "saveWhenAnySpecifiedTagHasChanged" 
    • The connector saves tags when at least one collected tag included in the "onChangeTriggerTags" property has changed from its previous value. 
  • "saveWhenAllSpecifiedTagsHaveChanged" 
    • The connector saves tags when all collected tags in the "onChangeTriggerTags" property have changed from their previous value.  


Use cases

  • When you want to ensure collected data is persisted any time a tag value has changed, use "saveWhenAnyTagHasChanged". This is the default because it ensures no data changes are lost.
  • When you want to ensure each record in an integration table contains no repeated values compared to the previous record, you can use "saveWhenAllTagsHaveChanged". This approach may rarely persist data.
  • When you have several tags that work together, you can use "saveWhenAllSpecifiedTagsHaveChanged" to delay persisting changes until all their values have changed. This approach ignores data changes in other tags.
  • When you are tracking several important tags and you want to capture their data when any of them changes value, you can use "saveWhenAnySpecifiedTagHasChanged". This approach ignores data changes in other tags.


Code Example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,
   
   "dataPersistenceStrategy": "onChange",
   "onChangeTrigger": "saveWhenAnySpecifiedTagHasChanged",
   "onChangeTriggerTags": ["t1"],

   "settings": {
     
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed"
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES
 

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • “normalLowerLimit”
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude"
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 "saveWhenAnyTagHasChanged" string enum "saveWhenAnyTagHasChanged"
"saveWhenAllTagsHaveChanged"
"saveWhenAnySpecifiedTagHasChanged"
"saveWhenAllSpecifiedTagsHaveChanged"

onChangeTriggerTags

The conditional "onChangeTriggerTags" property is an array  of "propertyPath" values from the "propertyMapList" object. Each "propertyPath" value is the connector's unique identifier to a collected data item, which is commonly called a "tag".  These tags work with the "onChangeTrigger" property to control when a connector saves collected data to an integration table.


The conditional "onChangeTriggerTags" property is required when the "onChangeTrigger" property has one of the following values: "saveWhenAnySpecifiedTagHasChanged" or "saveWhenAllSpecifiedTagsHaveChanged".


The following code excerpt triggers a save event when the value of the "temperature" tag changes.

"onChangeTrigger": "saveWhenAnySpecifiedTagHasChanged",
"onChangeTriggerTags": [ "temperature" ]


Code Example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,
   
   "dataPersistenceStrategy": "onChange",
   "onChangeTrigger": "saveWhenAnySpecifiedTagHasChanged",
   "onChangeTriggerTags": ["t1"],

   "settings": {
     
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "temperature",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int8Signed"
       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES
 

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The "createInput" and "alterInput" actions return an error wen aspecified tag name is not defined.
  • The "createInput" and "alterInput" actions return an error if you assign a value to "onChangeTriggerTags" and the "onChangeTrigger" property is not set to "saveWhenAnySpecifiedTagHasChanged" or "saveWhenAllSpecifiedTagsHaveChanged".
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • “normalLowerLimit”
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude"
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
 required when the "onChangeTrigger" property has one of the following values: "saveWhenAnySpecifiedTagHasChanged" or "saveWhenAllSpecifiedTagsHaveChanged". array of strings 1 or more strings

onError

The "onError" property is an optional string that determines when to stop or continue the execution of all SQL statements. It defaults to "continue".

  • Possible values:
    • "stop"
      • Setting "onError" to "stop" causes the "runSqlStatements" action to stop executing SQL statements when it encounters an error. Stopping "runSqlStatements" on an error is useful when running subsequent steps that would cause problems or would consume server resources unnecessarily.
    • "continue"
      • Setting "onError" to "continue" causes the "runSqlStatements" action to continue executing SQL statements when it encounters an error. Continuing "runSqlStatements" on even when an error occurs is useful when you want to verify the viability of each specified statement, such as ensuring it uses the correct syntax and executes properly.
  • There are use cases in which use "onError" and "atEnd" together.
    • When prototyping code.
      • "onError": "continue ", "atEnd": "rollback" 
      • Use this sample when you want all statements to run and report errors, but you do not want to commit any changes. This is useful in development when you want to try out a number of SQL statements to check their syntax, performance, and proper execution and you do not yet want to commit changes because you are still developing the code. It is convenient since it eliminates the need to drop newly created objects and delete newly inserted records.
    • When developing code.
      • "onError": "continue", "atEnd": "rollbackOnError"
      • Use this sample when you want all statements to run so you can see and troubleshoot all errors and you want to commit all changes, but only when all SQL statements run successfully. This is the default setting because it is good for development and is still safe when these settings are accidentally deployed to production.
    • When running in production and test environments.
      • "onError": "stop", "atEnd": "rollbackOnError"
      • Use this sample when you want to immediately stop running SQL statements and rollback all changes when there is an error, but you want to commit all changes when all the SQL statements run successfully. This is useful in production because you want to commit a set of successfully executed SQL statements, but when a failure occurs, you want the server to immediately stop running the remaining SQL statements and roll back all changes. Immediately stopping execution and rolling back changes prevents server resources from being consumed unnecessarily.
    • When deploying database changes.
      • "onError": "continue", "atEnd": "commit"
      • Use this sample when you want to unconditionally commit all SQL statements even when an error occurs on one or more statements. This is useful for deploying database changes because it is common to ignore errors during a deployment process — for example, the DROP table command returns an error when dropping a table that does not exist. This error does not prevent a subsequent CREATE table from running successfully.
 "continue" string

"stop"

"continue"

opcNamespace

 The "opcNamescpace" property specifies the OPC UA namespace that this variable exists in. Required - No default value int16 0 to 32767

opcNodeName

 The "opcNodeName" property specifies the name of the OPC UA variable for this data. Required - No default value string No limit

opcServerUrl

 The "opcServerUrl" property specifies the IP or URL to your OPC UA device, including the port. Required - No default value string No limit

opcServerUser

 The optional "opcServerUser" property specifies the username for your OPC UA device. "" string No limit

opcServerPassword

 The optional "opcServerPassword" property specifies the password for your OPC UA device. "" string No limit

operationIntent

The "operationIntent" property is optional. It clarifies the intent of the method as an "insert", "update", or "upsert". The default intent is "upsert".

The "operationIntent" property values and their descriptions are as follows:
  • "upsert"
    • This is the default value. It treats this method as an "upsert". If the connection already exists, it updates it.  If the connection does not exist, it inserts it. It does not throw an error.
  • "insert"
    • It treats this method as an insert. If the connection already exists, FairCom's servers log an error stating, "Cannot insert service connection xxx because it already exists."
  • "update"
    • It treats this method as an update. If the connection does not already exist, FairCom's servers log an error stating, "Cannot update service connection xxx because it does not exist."
"upsert" string

"upsert"

"insert"

"update"

operator

The "operator" property is a required string enum. When the server filters records in a query, it goes through each record and uses the comparison operator to compare a field value to a constant value or expression. When the comparison evaluates to true, the record is included in the result.

The following comparison operators are available:
  • "="
    • This returns records equal to a value.
  • "<"
    • This returns records less than a value.
  • "<="
    • This returns records less than or equal to a value.
  • ">"
    • This returns records greater than a value.
  • ">="
    • This returns records greater than or equal to a value.
  • "<>"
    • This matches values not equal to the value specified in the "value" property.

Note The "<>" operator is not available for this method because it excludes a range of values.

 Required - No default value string

"="

"<"

"<="

">"

">="

"<>"

outputName

 The "outputName" property is an optional string that specifies a unique name for mapping an integration table to an output plugin to an external system.

A FairCom generated name that follows the pattern "Output #n from <databaseName>.<schemaName>.<tableName> to <pluginName>"

 string 1 to 64 bytes

outputNames

The "outputNames" property is an array of strings, each specifying the name of an output. The response will include details about all outputs with an "outputName" that matches one of the strings in the array.

 []

array

 1 or more strings

outputPayloadField

The "outputPayloadField" property specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers. If omitted or if it is an empty string, it defaults to "source_payload".

  • "outputPayloadField" must be one of the following values: 
    • "source_payload"
    • A user-defined field

This makes it possible for the output from any transform to be used as the payload delivered to subscribers.

"source_payload"

 string

"source_payload"

A user-defined field

ownerName

The "ownerName" property is an optional string from 1 to 64 bytes that specifies the account that owns an object, such as a table or code package. If it is set to null or is omitted, it defaults to the account that created the JSON Action session, see "createSession" and the "defaultOwnerName" property. 

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.

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

packageSize

The optional "packageSize" property specifies the package size in bytes used to communicate with the PLC. 

Higher numbers allow the connector to retrieve more data in fewer requests.

 If not specified, the PLD PDU size is used. integer 240 to 960

padValue

The "padValue" property is a decimal number from 0 to 255. It is optional. If omitted, it defaults to 0.

The server uses this decimal number as a byte value to pad all "char" and "binary" fields in a table when the contents of these fixed-length fields is shorter than the field size.

All fixed-length fields in a table are padded with the same pad value. 

Note Padding does not apply to the variable-length fields of the table, including "varchar", "lvarchar", "varbinary", and "lvarbinary".

Reasons to use fixed-length fields:
  • Fixed-length fields are an optimization for the specific use case of storing fixed-length data that matches the exact length of the field.
  • For fixed-length fields, the following use cases work well:
    • Bit flags
      • A "binary" field is useful for efficiently storing a fixed set of bit flags where each bit represents a different on/off setting.
    • Legacy identifiers
      • A "char" field is useful for efficiently storing legacy fixed-length identifiers, such as a VIN number, where characters in specific positions represent different subsets of data.
    • Very small strings
      • A "char" field is useful for efficiently storing strings that are smaller than six characters because they do not have the overhead of requiring two extra bytes to track the length of the field.
  • A fixed-length field is more efficient than a variable-length field because it does not require extra bytes to track the length of the field:
    • The "varchar" and "varbinary" fields require two extra bytes to track the length of the field, which can be up to 64K. 
    • The "lvarchar", "lvarchar",  and "lvarbinary" fields require four extra bytes to track the length of the field, which can be up to 2GB.
Reasons for padding fixed-length fields:
  • Padding is required for fixed-length fields because data can be assigned to a field with a shorter length than the field's length.
  • Padding is useful in the following use cases:
    • The default padding value of 0 in a "char" field makes a fixed-length string behave like a variable-length string. It works because the database can treat a fixed-length string as a null-terminated string that can be smaller than the fixed width.
    • A padding value of 32 in a "char" field is the ASCII space character, which automatically left-aligns fixed-length strings.
    • The default padding value of 0 in a "binary" field works for bit flags when zero is the desired default state of a bit. Otherwise, padding in a "binary" field is rarely a good thing because it alters the binary value.
How padding works:
  • When the server assigns a value to a "char" or "binary" field (which are fixed-length field types), it puts the value in the field starting on the left and uses the pad value to fill in any remaining bytes on the right.
  • In other words, when the number of bytes in a value being assigned to a "char" or "binary" field is less than the number of bytes in the field, the server fills in the remaining bytes with the pad value.
CHAR padding behavior:
  • The default pad value of 0 causes a special padding behavior for "char" fields.
    • It causes the JSON DB API to treat fixed-length string fields as if they were variable-length strings with a maximum length.
    • In other words, the same string value going into a "char" field comes out the same, no padding is added — for example, when a table's "padValue" is set to 0 and a JSON string of "12" is inserted into a "char" field, the JSON string of "12" is returned from that field.
  • When you want the server to add padding to strings that are stored in a "char" field, set the "padValue" property to a non-zero number that is the ASCII character you want to pad the string.
    • For example, set "padValue" to 32 to pad strings with the space character. When a table's "padValue" is set to 32 and a JSON string of "12" is inserted into a "char" field with a "length" of 4 bytes, the JSON string of "12 " is returned from that field.
BINARY padding behavior:
  • The server always applies padding when the number of bytes in a binary value is less than the number of bytes in the fixed-length, "binary" field. When the server adds padding to a binary value, it permanently modifies the binary value. If this is not desirable, ensure the binary value exactly matches the size of the "binary" field.
  • The JSON DB API always returns the entire stored value of a "binary" field. This binary value is encoded as a JSON array of bytes or a string containing a base64 or hexadecimal representation of the binary value. The length of the JSON string encoded in base64 or hexadecimal is always longer than the length of the binary field.
  • If a table's "padValue" is set to 0, and a binary value of 0x3132 is stored in a "binary" field with a "length" of 4 bytes, the server pads the value and stores the value of 0x31320000 into the field. When the value is returned by the JSON DB API, it is returned as 0x31320000. Thus, padding alters a binary value when the value is smaller than the field. The default padding behavior of a "binary" field is different from the default padding behavior of a "char" field because the server can assume that an ASCII NULL padding value is a string terminator, but it cannot assume the same for a binary value.
Example 1. Turning off padding

If a table's "padValue" is set to 0, the ASCII NULL character with the hexadecimal value of 0x00 is used to pad unfilled byte positions. So when the JSON string "12" is inserted into a "char" field that has a "length" of 4 bytes, the binary value of 0x31320000 is stored in the field. The value returned is a JSON string of "12" because it recognizes the ASCII NULL character as a string terminator.

In other words, the ASCII NULL character allows the server to automatically trim the length of a string that is stored in a fixed-length field before it returns the string in JSON. So, by default, the same JSON string inserted into a "char" field is always returned by the JSON DB API. This behavior is safe for UTF-8 strings, which is the string encoding used by JSON.

Example 2. Padding s a string with spaces

When a table's "padValue" is set to 32, which is hexadecimal 0x20, and a JSON string of "12" is assigned to a "char" field that has a "length" of 4 bytes, the binary value of 0x31322020 is stored in the field. When the JSON DB API retrieves the value, it returns it as a JSON string of "12". This is because the value 32 is the ASCII space character " ".

Example 3. Padding a string with hyphens

If a table's "padValue" is set to 54, which is hexadecimal 0x36, and a JSON string of "12" is assigned to a "char" field that has a "length" of 4 bytes, the binary value of 0x31323636 is stored in the field. When the JSON DB API retrieves the value, it returns it as a JSON string of "12--". This is because the value 54 is the ASCII character "-".

Example 4. Manually padding a string

Assigning "12**" to a "char" field that has a "length" of 4 bytes stores "12**" into the field regardless of the table's "padValue".

Example 5. Right-aligning a value in a string

Assigning " $12.34" to a "char" field that has a "length" of 8 bytes stores " $12.34" into the field regardless of the table's "padValue".

Example 6. Avoiding padding

Use the variable-length char and binary field types ("varchar", "lvarchar", "lvarchar", "varbinary", and "lvarbinary"). 

Each of these field types is stored in the table with length information, so the data returned matches the data stored.

 

Request example

{
  "api": "db",
  "action": "createTable",
  "params": {
    "padValue": 32
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 0 integer 0 to 255

partialClientName

The "partialClientName" property is a string that is used to specify which sessions to return from the "listMqSessions" action. This property behaves as a "begins with" search.

 "" string  

partialDatabaseName

The "partialDatabaseName" property filters the returned databases by applying partial matches to the beginning of database names. It is an optional string from 0 to 64 bytes. It defaults to an empty string.

  • The "listDatabases" action returns databases with names that match the beginning of this string.
  • A zero-length string matches all database names.
  • Since it defaults to an empty string you can omit the "partialDatabaseName" property to return all databases.
 "" string 0 to 64 bytes

partialGroupFilter

The "partialGroupFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is a string, such as "partialGroupFilter": "myGr". The string is the partial or full name of a group and may be up to 64 bytes long. A label's group must match the partial or complete value of this property to be included in the results. The empty string "" and null match all groups.

Note The "groupFilter" and "partialGroupFilter" properties are mutually exclusive.

Warning When deleting properties, ensure each partial and full group name in the array properly filters the labels; otherwise, the "changeLabels" action will delete more labels than you want.

 

 "" string 1 to 64 bytes

partialKey

The "partialKey" property is an optional string or array that defines the range of returned records. The "getRecordsByPartialKeyRange" action uses the "partialKey" to find a starting position in the index where it can start returning records. It defaults to an empty string or empty array.

  • When the index key is based on one field, the "partialKey" property can be a string that contains some or all of the key values. The value must start from the beginning of the key.
    • When a field is stored in the index in reverse order, the "partialKey" property must start with bytes from the end of the key in reverse order. This allows you to do a partial match starting from the end of the key. To create a reverse order key, create the index and set one or more fields in the index to "reverseCompare": true.
  • You must include one value for each field in the index in the order the fields are in the index. The last field in the index may be omitted or may contain a partial key.
  • There are two forms of the "partialKey" property a string and an array.
  • The method finds the starting record by matching all the bytes in the "partialKey" value to the initial bytes in the indexes' keys.
  • A zero-length value matches all index keys.
  • All values in the array, except for the last, must represent a complete field value.
  • Only the last value in the array may be a partial value.
  • The fields must be placed in the array in index order.
  • Each value in the array must be compatible with the data type of its corresponding field.
    • JSON true or false for "bit" field.
    • JSON number for all number fields.
    • JSON string for "char", "varchar", "lvarchar", "binary", "varbinary", and "lvarbinary" fields.
  • A binary value is embedded in a string and is encoded as "base64" or "hex" according to the setting of "binaryFormat".

Note The Array (multi-field) shows how to use "partialKey" when an index contains five fields ("date", "bit", "varchar", "double", and "varbinary"). The values for "date", "bit", "varchar", and "double" cannot be partial values because they occur before the last field. The binary value in the "varbinary" field is encoded as base64 and since it is the last field it can contain a partial binary key.

 

String

"partialKey": "Mi"

Array (multi-field)

"partialKey":
[
  "2023-01-01", true, "full string", -3.4, "TWk="
]

In the Key-Value API, the required "partialKey" property retrieves child keys from a key hierarchy. It defines the base hierarchical level of returned keys, such as "partialKey": "myApp/queries/". The action uses an index on the key to find all keys that match the characters specified in "partialKey". Keys are case sensitive.


To ensure the action matches the hierarchical levels you want, include the hierarchical delimiter at the end of the partial key, such as "myApp/queries/".


You can use "partialKey": "" to return all keys in the store.

"" or []

Required in the Key-Value API 

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

partialName

The "partialName" property is an optional query filter that returns code packages with code names that match the value of "partialName". The match starts at the name's beginning, making it a "starts with" match instead of a "substring" match. If the partial name is empty, null, or omitted, it matches all names.

 

 "" string 1 to 64 bytes

partialNameFilter

The "partialNameFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to null, which provides no filtering. It is an array of strings, such as "partialNameFilter": "myNa". Each string is the partial or full name and may be up to 64 bytes long. A label's name must partially match this value to be included in the results. The empty string "" and null match all groups.

Note The "nameFilter" and "partialNameFilter" properties are mutually exclusive.

Warning When deleting properties, ensure the partial name properly filters the labels; otherwise, the "changeLabels" action may delete more or fewer labels than you want.

This example uses a group filter to list all labels with the matching groups.

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "groupFilter": [ "myGroup1", "myGroup2", "" ],
    "partialNameFilter": "myNa"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

This example uses a partial name filter to list labels with matching names. The labels may be part of any group.

{
  "api":       "admin",
  "action":    "listLabels",
  "params":    {
    "partialNameFilter": "myNa"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 null array of strings 1 or more strings, each up to 64 bytes long. 

partialNames

The "partialNames" property is an optional query filter that returns accounts with usernames that match the specified partial usernames. The match starts at the name's beginning, making it a "starts with" match instead of a "substring" match. If the property is empty, null, or omitted, it returns all the accounts.

  "params": {
    "partialNames": [
      "adm",
      "NewAccount"
    ]
  },
 [] array 1 to 64 bytes

partialTableName

The "partialTableName" property is an optional string from 0 to 64 bytes that filters the returned databases by applying partial matches to database names. It defaults to an empty string.

  • The "listTables" action uses "partialTableName" to return all tables whose table names start with these same characters.
  • A zero-length string matches all table names.
 "" string 0 to 64 bytes

password

The "password" property is an optional string up to 256 bytes long. The server uses the password to authenticate the account.

  • If omitted, a password is not set.
  • If present, the password is changed to the specified password. If it is set to an empty string, the server authenticates the account without a password. This is not recommended because it allows anyone to log into the account without supplying a password.

""

Required for the "createSession" action

 string 0 to 256 bytes

path

The "path" property is a string that identifies the path of the database folder.

  • Do not include the name of the database file in the path because the database filename and the extension .dbs are automatically added to the path, see Create the test_db_max.dbs database in the c:\temp\ folder.
  • When "path" is omitted or set to null, the FairCom server creates the database in the <faircom>/data folder.
  • When you include the \ character in the "path" property, you must include two backslashes in a row because in JSON the single backslash character is an escape character— for example, "c:\\temp" designates the c:\temp path.
  • You can use forward slashes in the path property (even on Microsoft Windows) because the FairCom server correctly interprets them as backslashes on Windows and as forward slashes on Linux, MacOS, and Unix.

 

Create the test_db_max.dbs database in the c:\temp\ folder

{
    "action": "createDatabase",
    "params": {
        "databaseName": "test_db_max",
         "path": "c:\\temp"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

"path" omitted or set to null

If the FairCom server is installed in the C:\FairCom\FairCom-Edge.windows.64bit.v4.5.1.170\ folder, this code example creates the test3.dbs database in C:\FairCom\FairCom-Edge.windows.64bit.v4.5.1.170\data\.

{
    "action": "createDatabase",
    "params": {
        "databaseName": "test3"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Forward slash

{
    "action": "createDatabase",
    "params": {
        "databaseName": "test4",
         "path": "c:/temp"
    },
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "" string 0 to 2,048 bytes

payload

The "payload" property is a required string that specifies the actual payload of the message.

 Required - No default value string The message's payload

permanentlyDeleteLabels

The "permanentlyDeleteLabels" property is available in the "changeLabels" action. It optionally specifies for the server to permanently delete the labels specified by the label filter properties. It defaults to null.

 null Boolean

true

false

null

permanentlyDeleteSession

The "permanentlyDeleteSession" property is a Boolean that specifies whether or not you want to permanently delete the specified session.

When set to true, it permanently deletes a session and removes its data from the server.

When set to false, it marks a session as deleted without removing the session's data.

 false Boolean

true

false

permanentSession

The "permanentSession" property is an optional Boolean that indicates if a session is permanent. It defaults to false.

Important Before you can create permanent sessions, you must add "enablePermanentJsonApiSessions": true to the "jsonActionApiDefaults" section of the <faircom>/config/services.json file.

If "permanentSession" is set to true when "createSession" is called, the server sets the authtoken as permanent. The authtoken is associated with the settings and authorizations of the user who created the session. It is always valid even after the server restarts. A permanent authToken works like an API Key and authenticates an application without the need for a username/password or a client certificate. Multiple applications can use the same permanent authToken.

Warning A permanent "authToken" is potentially less secure than a temporary one.

  • A permanent "authToken" never becomes invalid, which makes it easier for an attacker to find it using brute force.
  • A permanent "authToken" is persisted by an application, which increases the opportunity for an attacker to find it.
  • A permanent "authToken" allows each application server to share the same session, which potentially allows an attacker to change session settings for all application servers.
  • When you set the "permanentSession" property to true in "createSession", it creates a permanent session and returns a permanent "authToken".
  • Developers and applications can use a permanent authToken in JSON actions without needing to call createSession to get a temporary authToken.
  • You must protect a permanent "authToken" as you would a password or API key because it represents a permanently authenticated server session.
  • A permanent session does not expire. You can also prevent a temporary session from expiring by setting its "idleConnectionTimeoutSeconds" property to 0.
  • A permanent "authToken" uses the authorization and settings of the account that originally created the session. All actions performed in the session are performed using that account's authorizations, and account settings, such as its default database and owner.
  • You can use "alterSession" to modify the settings of a permanent session, but you cannot use it to turn a temporary session into a permanent session.
  • If multiple application servers use the same permanent "authToken", they share the same permanent session settings. Consider the following:
    • If one application server uses "alterSession" to change a permanent session's settings, the other application servers automatically use the new settings. To avoid confusion and errors, applications must specify all JSON action property values and not rely on session defaults.
    • You cannot use different sessions to determine which app server executes an action. This makes troubleshooting more difficult.
    • An application must create and use a transaction to protect the visibility and integrity of multiple operations from other applications. This is true for permanent and temporary sessions.
  • The FairCom server securely stores each permanent "authToken" in the encrypted faircom.fcs file.
 false Boolean

true

false

photo

 The optional "photo" property contains a photo of a thing.  It defaults to null and is a binary value up to 2 GB in size. You cannot use it for lookups and filtering. null string containing a binary value Up to 2 GB

plcAddress

 The "plcAddress" property specifies the IP address or hostname and optional port from the PLC, in the format IPaddress:Port, with Port being optional.  Required - No default value string

Examples:

172.16.0.1

172.16.0.1:4401

plcType

The "plcType" property specifies the type of the PLC. 

  • "controllogix" - The tag is in a Control Logix-class PLC. Includes Logix, CompactLogix, Contrologix.
  • "plc5" - The tag is in a PLC/5 PLC.
  • "slc500" - The tag is in a SLC 500 PLC.
  • "logixpccc" - The tag is in a Control Logix-class PLC using the PLC/5 protocol.
  • "micro800" - The tag is in a Micro800-class PLC.
  • "micrologix" - The tag is in a Micrologix PLC.
  • "omron-njnx" - The tag is in an Omron NJ/NX PLC.
 Required - No default value string

"controllogix"

"plc5"

"slc500"

"logixpccc"

"micro800"

"micrologix"

"omron-njnx"

preserve

The "preserve" property is an optional, case-insensitive string enum that determines how data, if any, that is associated with an integration table or MQTT topic is preserved. It defaults to "data".

Possible values:
  • "data"
    • "data" is the default value, it preserves the entire table and its records.
  • "nothing"
    • "nothing" removes the table and its data.

"data"

 string enum

"data"

"nothing"

primaryKey

This optional property identifies a table's primary key.

Note The best practice is not to use the "primaryKeyFields" or "primaryKey" properties, so the "createTable" action will automatically create a primary key field named "id" with a unique index named "id_pk".

Each table created by the JSON DB API has a primary key that uniquely identifies each record.

"createTable" automatically adds the "id" field as the primary key to your table. It makes "id" an auto-increment bigint field and indexes the field with a unique index named "id_pk". Using the "id" field as the primary key is a best practice.

You can specify one or more fields to be the primary key of the table instead of the "id" field. To do so, you must add the "primaryKeyFields" property to "createTable" or use the "fields" property's "primaryKey" to specify which field(s) are in the primary key.

Note You should not use both the "primaryKeyFields" and "primaryKey" properties together.

If multiple fields are specified for the key, the index is named "pk". If only one field is specified for the key, the index is named "<fieldname>_pk".

If you use the "primaryKey" property to specify multiple fields as the primary key, the assigned value from 1 to n specifies the order of the fields in the primary key. Assign "primaryKey": 1 to the first field in the primary key, "primaryKey": 2 to the second, and so forth. If you create a primary key with multiple fields, the index is named "pk". If you specify just one field, the index is named "<fieldname>_pk".

 

Example

"fields": [
  {
    "name": "a",
    "type": "tinyint",
    "primaryKey": 1
  },
  {
    "name": "b",
    "type": "smallint",
    "primaryKey": 2
  },
  {
    "name": "c",
    "type": "integer",
    "primaryKey": 3
  }
]
 null integer 0 to 32

primaryKeyFields

This property specifies the fields to use for the table’s primary key.

The "primaryKeyFields" property creates a unique "primary key" index on these fields.

The index is named "field1_fieldN_pk" where field1 through fieldN are the names of the specified fields.

When the table already has a primary key index, altering a table with this property may create an additional "primary key index".

The user can use "deleteIndexes" to remove extra indexes.

 [] array of strings ["field1", …,"fieldN"]

primaryKeys

The "primaryKeys" property is an array of arrays containing key-value pairs. The default value is "null", but it is required if the "ids" property is omitted. It is used to specify search criteria and to show the results found.

  • "primaryKeys" is best used if tables were created with primary keys composed of multiple fields. If primary keys are composed of a single field, it is best to use "ids".
    • Tables created using JSON DB API actions cannot create primary keys composed of multiple fields.
  • A table must have a primary key defined in order to use "primaryKeys".
  • The "primaryKeys" property is mutually exclusive with the "ids" property, meaning it is required when "ids" is omitted, or an error is returned if both have values.
  • The "primaryKeys" property is an array of arrays.
    • The outer array contains one or more primary key definitions, enabling the server to retrieve multiple records simultaneously.
    • Each inner array is a primary key definition that specifies the values the server needs to retrieve one matching record.
    • A primary key definition consists of one or more objects where each object is a field-value pair that uses the following structure ({ "fieldName": "someField","value": "someValue" }).

If your table uses the "first_name" and "last_name" fields as the primary key, the following "primaryKeys" property will retrieve two records.

Note If your table does not have a primary key, its records cannot be retrieved, updated or deleted using the "getRecordsByIds", "updateRecords" and "deleteRecords" actions. Other getRecords actions can query its records.

   "primaryKeys": 
    [ 
      [
        { "fieldName": "first_name", "value": "Sam" },
        { "fieldName": "last_name",  "value": "I-am" }
      ],
      [
        { "fieldName": "first_name", "value": "The Cat" },
        { "fieldName": "last_name",  "value": "in the Hat" }
      ]
    ]

 

"null"

It is required when "ids" is omitted.

array of arrays

 1 or more array of key/value pairs.

privateKeyFilename

 The "privateKeyFilename" is an optional string that specifies the name and optional path of a server key file. "" string No limits

problemTypeFilter

The "problemTypeFilter" property is an optional array of strings that filters the response to match the specified types of problems. You may omit this property or set it to null to return all problem types.

 null array of strings

"diagnostic"

"information"

"warning"

"error"

"fatalException"

propertyMapList

 The "propertyMapList" property specifies which data the connector requests and where to put it in the generated JSON. Required - No default value array of objects

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

"propertyPath"

"tagElementCount" 

"tagName"

"tagPath"

"tagType"

"tagSize"

propertyPath

 The "propertyPath" property specifies the name of the data to be defined by "propertyValue". Required - No default string 0 to 256 bytes

propertyValue

This is a required object that contains properties that define the data values of a "propertyPath". It is required and has no default value.

The data values specified in the "propertyValue" object can be a string or an object.

  • "fromConstant" indicates the value is a string. For example —
    • "propertyValue": {"fromConstant": "0002"}
  • "fromSourcePropertyPath" indicates the value is an object. For example —
    • "propertyValue": {"fromSourcePropertyPath": { "formatString": "Temperature = <%input_temp%>" }}
    • Characters in the "formatString" value that are enclosed by "<%" and "%>", specify the name as an input property that will be replaced by an input property value.
    • Here is a REST command example for the "propertyPath" named "description", that received an input_temp value of 103:
    • {  description: "Temperature = 103."}
    • If the input value is not found, it is replaced with NULL:
    • {  description: "Temperature = NULL."}
 Required - No default object

"fromConstant": "yourString"

"fromSourcePropertyPath": { "key": "value"}

purpose

The "purpose" property is an optional string that provides a short description of the specified server's purpose.

 

In the Thing API, the optional "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. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

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.

""

"unknown" in the Thing API 

 string 1 to 64 bytes

purposeFilter

 The optional "purposeFilter" property is an array of strings. Each string is a partial or complete purpose, such as, "purposeFilter": [ "myPur", "Manage an Acid Bath" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. [] array of strings zero or more purpose strings

rack

 The "rack" property specifies the PLC Rack number. Required - No default value integer 0 to 7

rebuildTable

The "rebuildTable" property is an optional Boolean that defaults to false. When true, the server stops accepting read, insert, and update requests and rebuilds the table. Rebuilding a table creates new table files and writes existing records to the new files.

Warning Rebuilding a table interrupts data collection until the rebuilt operation finishes. The rebuild time is proportional to the number of table records.

Tip You may want to rebuild the table in the following cases: 

  • To apply a transform to previously inserted or updated records. 
  • To change the table's retention policy, period, or unit. 
  • To repair a data file corrupted by a storage failure.
 false Boolean

true

false

receiveMaximum

The "receiveMaximum" property is an optional integer that specifies the maximum number of QoS 1 and QoS 2 publish messages that the MQTT client is willing to process concurrently.

 1024 integer 1 to 65535

receiveMyMessages

The "receiveMyMessages" property is an optional Boolean property that allows a client's subscription to receive messages published by the client. It defaults to true.

 true Boolean

true

false

receiveRetainedFlagAsPublished

The "receiveRetainedFlagAsPublished" is an optional Boolean property that specifies how the FairCom server sets the "retain" property on messages it sends to subscribers. When a client publishes a message, it sets the "retain" property to true to tell the FairCom server that it should retain the message and publish this message on behalf of the client when another client subscribes to a topic. A retained message is typically a special message that provides a new subscriber with status information about the topic.

When "receiveRetainedFlagAsPublished" is true, the FairCom server follows the MQTT 3 specification and passes the value of the "retain" property set by the publisher to the subscriber. Thus, a subscriber sees the value of the "retain" property that is set by the publisher. This notifies the subscriber that the message is a special status message from the client. This approach has the downside that a subscriber does not know when it gets a message sent by the FairCom server on behalf of the client in response to subscribing to a topic.  

When "receiveRetainedFlagAsPublished" is false, the FairCom server follows the MQTT 5 specification and sets the "retain" property to true only when the FairCom server sends a retain message to a subscriber on behalf of a publisher, such as when a client subscribes to a topic. The MQTT 5 approach lets a subscriber know when it receives a retain message sent by the FairCom server vs. when it receives a normally published message from a client. This approach has the downside that a subscriber does not get the value of the "retain" property as set by the client who published the message. The MQTT 5 approach is generally better because the subscriber can tell when it is receiving a retained message in response to a subscription as opposed to a message published by a client.

 true Boolean

true

false

receiveRetainedMessages

The "receiveRetainedMessages" property is an optional enumerated string that specifies how MQTT 5 subscribers receive retained messages. It has three enumerated values: "onSubscription", "onNewSubscription", and "never". It defaults to "onSubscription".

  • "onSubscription" - the server sends a topic's retained message each time a client subscribes to a topic. Thus, a client can resubscribe to a topic to get the latest retained message.
  • "onNewSubscription" - the server only sends a topic's retained message when a client subscribes to a topic for the first time.
  • "never" - the server never sends a topic's retained message.
 "onSubscription" enum

"onSubscription"

"onNewSubscription"

"never"

reconnectFrequencySeconds

The "reconnectFrequencySeconds" property is the number of seconds that the broker waits between attempts to reconnect to an external broker. This property is optional. If omitted, it defaults to 15 seconds.

If it is set to 0, the broker does not attempt to reconnect when it loses a connection or fails to connect.

FairCom's servers attempt to connect to an external broker when it is configured as a subscriber to topics on an external broker or when it is configured to forward messages to an external broker.

To stop the reconnect process, send the "configureBrokerConnection" message with the command property set to "disconnect".

To restart the reconnect process, send the "configureBrokerConnection" message with the command property set to "reconnect".

 15 int32

1 to 65535

recordFilter

The "recordFilter" property is a string that specifies a FairCom expression that must match a record's field values before the record is included as a data change event.

 "" string 1 to 65,000 bytes

recordFormat

The "recordFormat" property is a string that includes the record's value in the data change event as a binary-encoded string or individual field values.

 "fields" string enum

"fields"

"buffer"

recordPath

The "recordPath" property specifies the location in a record where the server reads or writes a JSON value. It specifies a field name followed by an optional JSONPath. Depending on the context, it refers to a value the server reads or writes. 

For example, in the "tableFieldsToJson" transform method, "recordPath" is the location where the transform step writes a transformed value. In the "jsonToTableFields" and "jsonToDifferentTableFields" transform methods, "recordPath" is the location where the transform step reads the value that it transforms.

  • The "recordPath" property must always include a field name.
    • The server returns an error when the field name is missing or does not exist.
  • The "recordPath" property may include a JSONPath after the field name.
    • If no JSONPath follows the field, the "recordPath" property refers to the entire field, and the field is not required to contain a JSON document.
    • If a JSONPath follows the field, the "recordPath" property refers to a part of the JSON document inside the field.

Several FairCom APIs, such as the DB and Transform APIs, treat each record in each table as a JSON document. The top-level fields in the record are treated as top-level properties in the JSON document. In other words, you can think of each record as a JSON document, and you can use the "recordPath" property to refer to any field in the record and any JSON property or array item within a JSON field.

When the server writes a value to a "recordPath", it looks for the specified field and JSONPath and does the following.

  • If the specified field does not exist, the server returns an error.
  • If the JSONPath is not specified after the fieldname, the server writes the value directly to the field.
  • If the field's value does not contain a JSON document, the server returns an error.
  • If the JSONPath specifies a property or array item that does not exist in the field's JSON document, the server adds it.
  • If the JSONPath specifies a property or array item that already exists in the field's JSON document, the server replaces the value.

When the server reads a value from a "recordPath", it looks for the specified field and JSONPath and does the following.

  • If the specified field does not exist, the server returns an error.
  • If the JSONPath is not specified after the fieldname, the server reads the entire field value.
  • If the field's value does not contain a JSON document, the server returns an error.
  • If the JSONPath specifies a property or array item that does not exist in the field's JSON document, the server returns null because FairCom's data model treats a missing JSON property the same as one assigned to null.
  • If the JSONPath specifies a property or array item that already exists in the field's JSON document, the server replaces the value.

Note Unlike "propertyPath", a "recordPath" includes the name of the field that contains the JSON document.

 

Simple "recordPath" example

For example, a recordPath of "temperature" refers to a field named "temperature".

Example record in an integration table

The following record contains three fields: id, source_payload, and create_ts.

id source_payload create_ts
1 
{
  "humidity": 
  [
    {
      "temperature": 20.1,
      "pressure": 1003
    }
  ]
}
"2025-07-07T14:14:02.012"
JSON representation of the example record

The following JSON shows how the JSON DB and Transform APIs represent the previous record. The top-level properties are fields in the integration table.

{
  "id": 1,
  "source_payload": 
  {
    "humidity": 
    [
      {
        "temperature": 20.1,
        "pressure": 1003
      }
    ]
  },
  "create_ts": "2025-07-07T14:14:02.012"
}

"recordPath" properties for each value in the example record

"recordPath" Field Value
"recordPath": "id" 1
"recordPath": "source_payload" 
{
  "humidity": 
  [
    {
      "temperature": 20.1,
      "pressure": 1003
    }
  ]
}
"recordPath": "source_payload.humidity" 
[
  {
    "temperature": 20.1,
    "pressure": 1003
  }
]
"recordPath": "source_payload.humidity[0]" 
{
  "temperature": 20.1,
  "pressure": 1003
}
"recordPath": "source_payload.humidity[0].temperature" 20.1
"recordPath": "source_payload.humidity[0].pressure" 1003
"recordPath": "create_ts" "2025-07-07T14:14:02.012"

The required "recordPath" property specifies the location of a JSON property in a record. It starts with the name of a field in the table followed by an optional JsonPath to a JSON property within that field.

 

 Required - No default value string 0 to 256 bytes

remove

The optional "remove" property is an array of objects that specifies which roles will be removed from which accounts. You can specify the roles you want to remove with the "rolenames" property and the accounts to remove them from with the "usernames" property.

 {} array of objects

"rolenames"

"usernames"

renamedKeys

The "renamedKeys" property is required by the "renameKeys" action to rename keys. It contains an array of key-rename objects. Each key-rename object contains "oldKey" and "newKey" properties that specify the key's current and new names.
 

 { 
    "oldKey": "k1",
    "newKey": "k2"
  }
 Required - No default value array of key-rename objects 
[
  { 
    "oldKey": "k1", 
    "newKey": "k2"
  }
]

requestProblemInformation

The "requestProblemInformation" property is an optional Boolean that specifies whether or not to include problem Information in the response.

 true Boolean

true

false

requestResponseInformation

The "requestResponseInformation" property is an optional Boolean that specifies whether or not to include response information in the response.

 false Boolean

true

false

rerunTransformScope

The required "rerunTransformScope" property defines the scope of this action. It is a string enum with one of the following values:

  • "allRecords" returns immediately and asynchronously creates a background thread that runs the transform steps on all records in that table.
    • You can stop this action by calling the "rerunIntegrationTableTransformSteps" action with "rerunTransformScope": "stop".
    • The server regularly updates the "transformStatus" and the "transformPercentComplete" properties, which are returned by the "describeIntegrationTables" action.
    • If an integration table's background thread is already rerunning the transform steps, the action returns an error indicating the "rerunIntegrationTableTransformSteps" action is already running on the integration table. The user can decide if he wants to wait or stop the action.
  • "stop" stops the table's background thread that reruns transform steps on all its records. If the background thread is not running, the action does nothing and returns an error.
  • "firstRecord" immediately and synchronously runs the transform steps on the first record in the table.
    • This option does not interfere with a background thread that is currently rerunning the transform steps.
  • "lastRecord" immediately and synchronously runs the transform steps on the last record in the table.
    • This option does not interfere with a background thread that is currently rerunning the transform steps.
  • "specificRecords" immediately and synchronously runs the transform steps on the specified records in the table.
    • Each record has an "id" field containing an integer number that uniquely identifies it.
    • The action uses the "ids" property to specify the identifiers of one or more records to be transformed.
    • This option does not interfere with a background thread that is currently rerunning the transform steps.
 Required - No default value string enum

"allRecords"

"firstRecord"

"lastRecord"

"specifiedRecords"

"stop"

responseOptions

The "responseOptions" property is an optional object that configures the server to return a customized response.

  • None of these properties are required, but some are mutually exclusive:
    • "includeFields" and "excludeFields" are mutually exclusive.
      • Use "includeFields" or "excludeFields" to control which record fields are present in the data.
    • "includePaths" and "excludePaths" are mutually exclusive.
      • Use "includePaths" or "excludePaths" to control which JSON properties are included in the data.
  • A JSON path includes the JSON field name plus the path of the property within the JSON field.
  • Use "omit" to remove a property from a response, such as omitting "errorMessage".
  • Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
  • Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
  • Use "variantFormat" to control how the server formats the values of variant fields in its response.
Full example
    "responseOptions": 
    { 
     "omit": ["error", "fieldDefs" ]
     "dataFormat": "arrays", 
     "numberFormat": "number",
     "includeFields": [ "name", "email" ],
     "excludeFields": [],
     "includePaths": [],
     "excludePaths": [ "email.domain" ],
     "binaryFormat": "base64",
     "stringFormat": "json",
     "variantFormat": "json"
    }
 null object

"omit"

"dataFormat"

"numberFormat"

"includeFields"

"excludeFields"

"includePaths"

"excludePaths"

"binaryFormat"

"stringFormat"

"variantFormat"

responseTopic

The "responseTopic" property is an optional string containing a topic name. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include the "correlationData" value (if any) to connect the response to the published message.

 "" string topic name for the response

retain

The "retain" property is optional in the "publishMessagesToMq" action and defaults to false. When true, it tells the FairCom server to retain this message for automatically sending to new subscribers as the first message they receive. When an action returns the "retain" property, it indicates the publisher published the message as a retained message.

 false Boolean

true

false

retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It must be an integer value from 1 to 100. It refers to the unit of time specified by the "retentionUnit" property — for example, if "retentionPeriod" is 14 and "retentionUnit" is "day", then message data is retained for 14 days. This property is optional.

  • Periodically, the system increments the age of each table partition.
    • "Minute" units are incremented at the zero second of each minute, whether the table partition was created 1 second before or 59 seconds before.
    • "Day" units are incremented at midnight GMT, not midnight of the local UTC time zone. A table partition becomes one day old at midnight GMT, whether it was created one second before or 23 hours and 59 seconds before.
    • "Week" units are incremented at midnight GMT on the last day of each week, even if the table partition was created one second before. The last day of the week is Saturday GMT.
    • "Month" units are incremented at midnight GMT on the last day of each month.
    • "Year" units are incremented at midnight GMT on Dec 31.
  • "retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.
  • If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.
  • If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

When partitions are auto-purged, some data are maintained "forever" in a global index. Auto-purge does not prevent these files from growing without bounds and filling up your hard drive.

If not specified, the default found in the services.json file is used. Initially, it is 4 (weeks).

Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.

Note 

  • If the value is not an integer from 1 to 100, FairCom's servers set it to the default value.
  • Smaller numbers improve SQL performance.
  • Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
  • FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".
  • The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.
  • The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time. In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.
    • For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.
  • The current calendar date affects purging.
    • FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.
    • For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.

30

 integer 1 to 100

retentionPolicy

The "retentionPolicy" property controls how messages are persisted. This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.

"autoPurge"

 string

"autoPurge"

"neverPurge"

retentionUnit

Each time this unit cycles, FairCom purges expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".

"day"

string

"minute"

"hour"

"day"

"week"

"month"

"year"

retrySeconds

The "retrySeconds" property is the number of seconds that FairCom's MQTT broker will wait for the next expected packet from a client during a QoS 1 or QoS 2 PUBLISH packet exchange/PUBLISH handshake with an MQTT client. The default value is 5. It applies when a client is publishing to the broker and when the broker is publishing to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. "retrySeconds" is optional.

  • If the "retrySeconds" time expires, FairCom's broker will disconnect the MQTT client with MQTT error code 7.  MQTT 5 clients will also receive a Reason Code.  An error message will be logged to <faircom>/data/CTSTATUS.FCS explaining why the disconnect happened. For example: 
    • MQTT connection for client ID [myMqttClient7] has been disconnected due to inactivity timeout. retrySeconds is set to [25] seconds for topic [my/test/topic12].: 14226
    • When the MQTT client reconnects, FairCom's MQTT broker will attempt to resume the PUBLISH handshake by resending the unanswered packet to the client, hoping that the client will reply with the next step of the handshake.
  • The minimum value is 1 and the maximum value is 65535.
  • If "retrySeconds" is omitted or its range is exceeded, FairCom's broker uses the default value.
  • Note that this parameter is not related to MQTT Keep Alive or when PINGREQ packets should be sent by the client.

20

 integer

1 to 65535

returnCursor

The "returnCursor" property is an optional Boolean. When true, an action returns a cursor instead of directly returning records. It defaults to "false".

  • To retrieve records, call the "getRecordsFromCursor" action and pass the "cursorId" value into it.
  • When "returnCursor" is "true" and one of the "skipRecords", "maxRecords", and "reverseOrder" properties is specified, an error is returned.
    • "returnCursor" is mutually exclusive with the "skipRecords", "maxRecords", and "reverseOrder" properties.
 false Boolean

true

false

returnTagsBy

 The optional "returnTagsBy" property is an enumerated string with the following values: "tagName" and "id". It defaults to "id". It is used by the "listTags" action to specify whether it returns tags identified by ID or name. "id" string enum

"id"

"tagName"

returnThingsBy

 The optional "returnThingsBy" property is an enumerated string with the following values: "name" and "id". It defaults to "id". It is used by the "listThings" action to specify whether it returns things identified by ID or "name". null string enum

"id"

"name"

revealAfterValueOnFilteredDelete

The "revealAfterValueOnFilteredDelete" property is a Boolean that includes the "afterValue" property in the notification message when true. When "recordFilter" filters out a record based on field values, an update causes a deleted change event to occur when its field values no longer match the filter. The "afterValue" property, when present, reveals the new field values and leaks information.

 false Boolean

true

false

revealBeforeValueOnFilteredInsert

The "revealBeforeValueOnFilteredInsert" property is a Boolean that includes the "beforeValue" property in the notification message when true. When "recordFilter" filters out a record based on field values, an update causes an insert change event when previous field values did not match the filter but now match it. The "beforeValue" property, when present, reveals the old field values and leaks information.

 false Boolean

true

false

reverseCompare

This property is an optional boolean with a default of false, so bytes in an index key field are compared starting from the beginning to the end of the key

When true, bytes in an index key field are compared starting from the end to the beginning of the key. This speeds comparisons when the unique parts of the bytes are at the end of keys.

"fields": [
  {
    "reverseCompare": true
  }
]
 false Boolean

true

false

reverseOrder

The "reverseOrder" is an optional Boolean. When true, it is used in query actions to return results in reverse order. It defaults to "false".

  • It works with "maxRecords" and "skipRecords" to provide pagination.
  • An error is returned when "returnCursor" is true.
 false Boolean

true

false

roleName

The "roleName" property is required by the role keystore. It is not used with the other keystores. It specifies the key's role, which must match an RBAC role that exists in the server.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 Required when "keystore": "role" string 1 to 64 bytes

roleNames

The optional "roleNames" property specifies the roles to be added to or deleted from the accounts specified by the "usernames" property. This property can specify one or more roles, each between 1 and 64 bytes.

    "add": [
      {
        "roleNames": [
          "admin"
        ],
        "usernames": [
          "NewAccount1"
        ]
      }
    ]
 [] array 1 or more strings, each between 1 and 64 bytes.

scale

The "scale" property is required only for the "number" and "money" data types because they require fixed precision. It is ignored for all other data types. See also Data types. The scale specifies the number of fixed decimal places to the right of the decimal point. Its value must always be less than or equal to the field's length.

The value of "scale" must be an integer from 0 to the number of digits specified by the "length" property. The maximum length is 32, which allows the scale to have up to 32 digits. The default value of length is 32.

A scale of 0 creates an integer number. A scale equal to the length creates a number that can only have a fractional value.

The "money" field type must have a scale of 2 or 4. The default is 4.

You may optionally use the "length" property to specify fewer than 32 total digits to limit the total number of digits available to the number. A length limit reduces the maximum size of the scale. For example, a length of 3 allows the scale of a "number" to be 0, 1, 2, or 3. 

Example numbers allowed in "number" and "money" field types with a length of 4 and a scale from 0 to 4.

 

Request Example

Create a table that contains all field types that use the "scale" property.

"fields": [
  {
    "name": "j",
    "type": "number",
    "scale": 32
  },
  {
    "name": "k",
    "type": "number",
    "scale": 4
  }
],
 null integer 0 to 32

search

The "search" property is an optional string that searches the content of the "metadata" property that is part of each topic and integration table.

  • If there is nothing in the "metadata" property for a topic or an integration table, there is nothing to search for, resulting in an empty array in the "data" property in the response.
  • The "metadata" property is a JSON field, meaning you can put a valid JSON in it — for example, a string or object.
 "" string 0 to 64 bytes

sequence

The "sequence" property optionally assigns an order to the labels in a group. You can use a floating point or integer number. You may embed the number in a JSON string. It defines the order of labels in a group. It is a floating point number to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.

 0 double Any floating point or integer number.

sequenceFilter

The "sequenceFilter" property optionally filters the results of the "listLabels" and "changeLabels" actions. It defaults to [], which provides no filtering. It is an array of doubles. The "sequence" property of a label must match one of the doubles in the array to be included in the results.

 [] array of doubles Each array item is a floating-point or integer number. 

serialNumber

 The optional "serialNumber" property specifies a thing's serial number. Typically a serial number uniquely identifies a thing, but things from different manufacturers may have the same serial numbers.  It defaults to "unknown" and is a string from 1 to 64 bytes. You can use it to do partial lookups and filtering. "unknown" string 1 to 64 bytes

serialNumberFilter

 The optional "serialNumberFilter" property is a string that can be a complete or partial serial number, such as, "serialNumberFilter": "AB678". The action returns things that match the serial number, provided it also satisfies all other specified filter properties. "" string 1 to 64 bytes

serviceLibrary

The "serviceLibrary" property is an optional string that specifies the filename of a dynamic library that provides the API used by the web application.

Library files are located in the <faircom>/server/web/ folder.

The full path includes the "serviceLibrary" value — for example, the Monitor app has a "serviceLibrary" name of ctmonitor.dll, and its full path in the file system is  <faircom>/server/web/ctmonitor.dll.

 "" string no limits

serviceName

The "serviceName" property contains the name of a FairCom input or output service. This property is required.

See the "params" topic of each specific service for the requirements of this property.

The following services are available as of the V5 release:
  • "MODBUS"
  • "SIEMENSUDT2JSON"
  • "OPCUA"

Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration.

MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.

 Required - No default value string 1 to 64 bytes

sessionExpiryInterval

The "sessionExpiryInterval" property specifies the number of seconds that a temporary session can be inactive before the server deactivates it. This property defaults to 0 when "temporarySession" is true and to 4294967296 when "temporarySession" is false. When a temporary session expires, the server removes its subscriptions and message delivery queue. 

The "sessionExpiryInterval" property has no effect on a permanent session because it does not expire. 

  • Set "sessionExpiryInterval" to 0 to expire a temporary session when the JSON action session closes.
  • Set "sessionExpiryInterval" to a value between 0 and 4294967296 to expire the session when it has been inactive for the specified number of seconds.
  • Set "sessionExpiryInterval" to 4294967296 to never expire the session.

The "temporarySession" property sets the value of the "sessionExpiryInterval" property.

  • If "temporarySession" is true, the server defaults "sessionExpiryInterval" to 0 so that a temporary session expires by default when the JSON session expires.
  • If "temporarySession" is false, the server sets "sessionExpiryInterval" to 4294967296.
 If "temporarySession" is true, "sessionExpiryInterval" defaults to 0 to ensure the temporary session expires when the JSON session does. If "temporarySession" is false, it defaults to 4294967296 because a permanent session never expires. integer 0 to 4294967296

sessionHealth

The "sessionHealth" property is included in the response to the "describeMqSessions" action. It is an enumerated string with the following values: "healthy", "unhealthy", and "offline":

The server excludes a metric from the calculation when it is set to the default value of 0.

The session health properties include: 

  • "minHealthySendRatePerMinute" 
  • "maxHealthySendRatePerMinute" 
  • "maxHealthyBacklogRatePerMinute" 
  • "minHealthySubscribedTopicFiltersCount" 
  • “maxHealthySubscribedTopicFiltersCount”
 Required - No default value enum

"healthy"

"unhealthy"

"offline"

sessionStatus

The "sessionStatus" property specifies the status of an MQTT or MQ API session as "normal", "hidden", "banned", or "inactive" to hide its visibility in API results and the dashboard views, ban a client from connecting, or mark a client as inactive. A banned session prevents clients from using the session to publish and subscribe to messages. When "sessionStatus" is omitted, it defaults to "normal".

  • "normal" resets a client to its default normal state. The client is not hidden in API results and dashboard views and may connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to unhide, unban, and activate a client.
  • "hidden"  hides a client from most API results and dashboard views while allowing the client to connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to hide administrative client connections.
  • "banned"  prevents a client from connecting in the future while preserving all information about the client. Use it to prevent unwanted clients from connecting again using the session's "clientName" to publish and subscribe to messages.
  • "inactive" marks a client session as inactive while allowing the client to connect, publish, and subscribe to messages. The server does not remove an "inactive" session's data so that historical message data sent and received by the client can continue to be associated with the deleted client. If a client connects to an inactive session, the server changes the session to "normal".
    • Use the "deleteMqSession" action to permanently delete the session which removes all session information. The server can no longer associate sent and received messages with the client. The client can reconnect in the future to establish a new session, but this will create a new session. It is common to permanently delete temporary client connections created during testing and troubleshooting.
 "normal" string enum

"normal"

"hide"

"ban"

sessionStatusFilter

The "sessionStatusFilter" property is an optional array that filters the returned sessions by the selected session statuses.

 [] array

"normal"

"banned"

"hidden"

sessionTypeFilter

The "sessionTypeFilter" property is an optional array that filters the returned sessions by the selected session types.

 [] array

"mqtt"

"mqApi"

settings

The "settings" property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference "params" property of each connector for details of the "settings" property for that connector.

Connector-specific "settings"

 {} object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

significantMagnitude

The optional, inclusive "significantMagnitude" property specifies the minimum magnitude that a collected value must change to be meaningful. It causes the connector to ignore insignificant changes. In other words, a change is saveable when it is greater than or equal to the significant magnitude. Each saved event establishes the baseline value for measuring the next significant change. The magnitude is an absolute value that measures change in the positive or negative. It is also inclusive.


The "significantMagnitude" property must be a positive numeric value greater than 0. The default is "disabled", which lets the connector save insignificant changes.


The significant change rule saves the first collected value unless other rules prevent it. Afterwards, it compares the collected value with the previously saved value and determines if the magnitude of change is greater than or equal to "significantMagnitude". If so, the connector marks the value as saveable because the value has changed a significant amount. 


In other words, each saved value becomes the baseline for comparisons to subsequently collected values. The connector saves a collected value when its magnitude of change is greater than or equal to the "significantMagnitude" property.


The following chart shows a connector saving a tag's value because the previous saved change has an adequate magnitude.

 

 

  • The connector compares the current value to the previously saved value – not to the previously collected value. Thus, the connector ignores collected values until one varies significantly from the last saved value, then it saves that value as the new reference point for meaningful change.
  • You can configure the connector to collect many tags in one data collection event. Some tags may have significant changes while others may not. Regardless, the connector saves the current value of each tag specified in the "onChangeScope" property. Thus, the saved value of some tags may not have changed significantly. If this is not acceptable, create another input for tags that must only save significant changes.


Scenario
A connector may collect rotation speed from a sensor once a millisecond. The rotation speed has insignificant changes that vary by ±19 that you do not want to save. To ignore these insignificant changes, set "significantMagnitude" to 20. 


Code example

{
 "api": "hub",
 "action": "createInput",
 "params": {
   "inputName": "modbusTCP",
   "serviceName": "modbus",
   "tableName": "modbusTableTCP",
   
   "dataCollectionIntervalMilliseconds": 1000,      
   "dataPersistenceStrategy": "onChange",

   "maxUnsavedEvents": 3600,
  
   "settings": {      
     "modbusProtocol": "TCP",
     "modbusServer": "127.0.0.1",
     "modbusServerPort": 502,
     
     "propertyMapList": [
       {
         "propertyPath": "rotationSpeed",
         "modbusDataAccess": "holdingregister",
         "modbusDataAddress": 4003,
         "modbusDataType": "int16Signed",

         "significantMagnitude": 20

       }
     ]
     
   }
 },
 "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

NOTES

  • The connector uses this property only when the "dataPersistenceStrategy" is "onChange". 
  • The following properties work together to save meaningful data changes.
    • "dataPersistenceStrategy"
    • "maxUnsavedEvents"
    • "normalLowerLimit"
    • "normalUpperLimit"
    • "deadbandLowerLimit"
    • "deadbandUpperLimit"
    • "significantMagnitude" 
    • "onChangeScope"
    • "onChangeScopeTags"
    • "onChangeTrigger"
    • "onChangeTriggerTags"
      

skipRecords

 The "skipRecords" property is an optional string value that defaults to 0. It is used with "maxRecords" to paginate the results. If the value is not null or omitted, the server returns results from the beginning. If it is > 0, the server skips over the specified number of records and returns results starting from that point up until it returns the maximum number of results as defined by "maxRecords". 0 integer 0 to 9223372036854775807
slot The "slot" property specifies the PLC Slot number. Required - No default value integer 1 to 31

smallFile

The "smallFile" is an optional Boolean. When true, a table is optimized for data files that cannot grow larger than 4 GB. It defaults to false.

Note Small data files are faster and more efficient than huge files. They consume less disk space and less memory.

 

Example request

{
  "api": "db",
  "action": "createTable",
  "params": {
    "smallFile": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 false Boolean

true

false

sortAscending

The "sortAscending" property is an optional string that sorts the returned sessions in ascending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

 "" string

"lastConnect"

"lastDisconnect"

"clientName"

"ipAddress"

sortDescending

The "sortDescending" property is an optional string that sorts the returned sessions in descending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

"fields": [
  {
    "sortDescending": true
  }
]
 false Boolean

true

false

sourceData

 The optional "sourceData" property contains either an array of objects or an array of arrays (depending on the specified "dataFormat") in each object or nested array is the source data for an insert or update operation [] array An array of arrays or an array of objects

sourceDatabaseName

The "sourceDatabaseName" property is a string that specifies the database name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 Defaults to the "defaultDatabaseName" value that is set during "createSession". If no default is set during "createSession", then "faircom" is used. string 1 to 64 bytes

sourceDatabaseNameFilter

The "sourceDatabaseNameFilter" property is an optional string that specifies a partial match for the database name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 null string 1 to 64 bytes

sourceDataField

The "sourceDataField" property is an optional string that contains the name of a field from an integration table. It defaults to "source_payload".

Required - No default value

 string

"source_payload"

"t1"

"t2"

"t3"

"t4"

"t5"

"t6"

"t7"

"t8"

"t9"

sourceDataFilePath

The "sourceDataFilePath" property is a string that specifies the data file path of the table on the FairCom DB or RTG server that generates the stream's data change events. It can be a full path or a relative path from the server's data directory.

 Required - if "sourceTableName" is not specified string No limits

sourceDataFilePathFilter

The "sourceDataFilePathFilter" property is an optional string that specifies a partial match for the file name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 null string 1 to 64 bytes

sourceDataFormat

The "sourceDataFormat" property specifies the format of the "source_payload" field. You can set this property to any of the following values:

  • "json"
  • "xml"
  • "binary"
  • "jpeg"
  • "siemensUdt"
 "json" string

"binary"

"jpeg"

"json"

"siemensUdt"

"xml"

sourceFieldName

The optional "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

sourceFields

The optional "sourceFields" property specifies the fields the FairCom server makes available to the output connector. The server creates a JSON object from the fields you specify, and the output connector uses it as its source data. If "sourceFields" is omitted, set to null or [], the FairCom server defaults to creating a JSON document that contains all fields from the integration table. This default allows the output connector to send data to a device from any field in the table.

An integration table has many fields, such as fields populated by transforms and MQTT. Converting all fields into JSON is slower than converting only the fields needed by the output connector. For example, input connectors and MQTT messages store their data in the source_payload field. You can use "sourceFields": ["source_payload"] to make only the source_payload field available to the output connector.

When you configure an output connector, you add propertyMap objects to the "propertyMapList". Each propertyMap object extracts data from one field and writes that data to the connected device. The value of the "propertyPath" property is a string containing the path of the data. It always starts with a field name in the "sourceFields" property. For example, if "sourceFields" is set to ["pressure"], then you must set "propertyPath" to "pressure" to use the pressure field’s value in your output. If the value you want to extract is a JSON property nested inside a field, you must add its full path to the "propertyPath". For example, if "sourceFields" is set to ["source_payload"] and source payload contains a JSON object with a "temperature" property, then you must set "propertyPath" to "source_payload.temperature".

 [] array One or more fields form the integration table.

sourceHostname

 The "sourceHostname" property is a required string that specifies a unique host name or TCP/IP address of a FairCom DB or RTG server. Required - No default value string 1 to 255 bytes

sourceHostnameFilter

The "sourceHostnameFilter" property is an optional string that specifies a partial match for a hostname.

 null string 1 to 64 bytes

sourceOwnerName

The "sourceOwnerName" property is a string that specifies the account that owns the table on the FairCom DB or RTG server that generates the stream's data change events.

 Defaults to the "defaultOwnerName" value that is set during "createSession". If no default is set during "createSession", then "admin" is used. string 1 to 64 bytes

sourceOwnerNameFilter

The "sourceOwnerNameFilter" property is an optional string that specifies a partial match for the owner name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 null string 1 to 64 bytes

sourcePassword

 The "sourcePassword" property is an optional string that specifies the login password of a FairCom DB or RTG server. "ADMIN" string 1 to 128 bytes

sourcePayloadBinaryFormat

The optional "sourcePayloadBinaryFormat" specifies how the server encodes and decodes a binary value assigned to a tag. For example, it controls how a transform converts a binary value between a JSON property and a table field.

  • It applies only when the "tagDataType" property is "binary".
  • The default value is "hex".
  • Use one of the following values:
    • "hex" - hexadecimal encoding.
    • "base64" - Base64 encoding.
    • "byteArray" - Array of integer values where each integer represents one byte.
  • It applies to the tag's property in the source_payload field, which is specified by the "sourcePayloadPath" property.
  • It applies to the tag's field in the integration table, which is specified by the "sourceFieldName" property.
  • For example, "sourcePayloadBinaryFormat": "hex" causes a "jsonToTableFields" transform to read the value "BEEF" from the tag's property in the source_payload field, decode it into the binary value 0xBEEF, and store it in the tag's field in the integration table.
  • For example, "sourcePayloadBinaryFormat": "byteArray" causes a "tableFieldsToJson" transform to read the value 0xBEEF from the tag's field in the integration table, encode it into a JSON array of bytes [190, 239], and store it the tag's property in the source_payload field.
  • For example, "sourcePayloadBinaryFormat": "base64" causes a "tableFieldsToJson" transform to read the value 0xBEEF from the tag's field in the integration table, encode it into the Base64 value "vu8=", and store it the tag's property in the source_payload field.


For more details, see "binaryFormat".

 "hex" string enum

"base64"

"byteArray"

"hex"

sourcePayloadDateFormat

The optional "sourcePayloadDateFormat" specifies how the server encodes and decodes a date value assigned to a tag. For example, it controls how a transform converts a date value between a JSON property and a table field.

  • It applies to the tag's value only when the  "tagDataType" property is "date" or "timestamp".
  • The default value is "iso8601".
  • Use one of the following values (see "dateFormat"):
    • "ccyy.mm.dd"
    • "mm.dd.ccyy"
    • "mm.dd.yy"
    • "dd.mm.ccyy"
    • "dd.mm.yy"
    • "ccyymmdd"
    • "iso8601"
    • "yymmdd"
    • "utc"
  • For example, "sourcePayloadDateFormat":"iso8601" decodes "2025-07-11" into a date that can be stored in a date field.
  • It applies to the tag's property in the source_payload field, which is specified by the "sourcePayloadPath" property.
  • It applies to the tag's field in the integration table, which is specified by the "sourceFieldName" property.
  • For example, "sourcePayloadDateFormat": "iso8601" causes a "jsonToTableFields" transform to read the value "2026-03-23" from the tag's property in the source_payload field, decode it into the year 2026, month 3, and day 23, and store it in the tag's date or timestamp field in the integration table.
  • For example, "sourcePayloadDateFormat": "mm.dd.ccyy" causes a "jsonToTableFields" transform to read the value "03/23/2026" from the tag's property in the source_payload field, decode it into the year 2026, month 3, and day 23, and store it in the tag's date or timestamp field in the integration table.
  • For example, "sourcePayloadBinaryFormat": "yymmdd" causes a "tableFieldsToJson" transform to read the value year 2026, month 3, and day 23 from the tag's date or timestamp field in the integration table, encode it into "260323", and store it the tag's property in the source_payload field.
  • When combined with the "sourcePayloadTimeFormat" property, the server can properly encode and decode a date and time stored in a timestamp field.
 "iso8601" string enum "ccyy.mm.dd"
"mm.dd.ccyy"
"mm.dd.yy"
"dd.mm.ccyy"
"dd.mm.yy"
"ccyymmdd"
"iso8601"
"yymmdd"
"utc"

sourcePayloadNumberRounding

The optional "sourcePayloadNumberRounding" property specifies how the server rounds a number value when stored in a number field with less scale, such as converting a floating point number to an integer field. 

  • It applies only when the "tagDataType" property is "number".
  • It is a string enum with the following values: 
    • "truncate" - truncates numeric digits to fit the available scale.
    • "roundup" - rounds up numeric digits to fit the available scale.
    • "rounddown" - rounds down numeric digits to fit the available scale.
  • The default value is "truncate".
  • For example, "sourcePayloadNumberRounding":"roundup" converts the number -123.4567 to -123.46 when stored in a field that has the data type of NUMBER(32, 2). 
 "truncate" string enum

"truncate"

"roundup"

"rounddown"

sourcePayloadPath

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

  •  It is required by the "createTag" action; otherwise, it is optional.
  • 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 string 1 to 2048 bytes

sourcePayloadTimeFormat

The optional "sourcePayloadTimeFormat" specifies how the server encodes and decodes a time value assigned to a tag. For example, it controls how a transform converts a time value between a JSON property and a table field. 

  • It applies to the tag's value only when the  "tagDataType" property is "time" or "timestamp".
  • The default value is "iso8601".
  • Use one of the following values (see "timeFormat"):
    • "hh.mm.ss.ttt"
    • "hh.mm.am/pm"
    • "hh.mm.ss.am/pm"
    • "hh.mm.ss"
    • "hh.mm"
    • "hhmm"
    • "iso8601"
    • "utc"
  • When combined with the "sourcePayloadDateFormat" property, the server can properly decode a date and time that can be stored in a timestamp field.
  • For example, "sourcePayloadTimeFormat":"iso8601" properly decodes "16:18:33" into a time that can be stored in a time field. 
  • It applies to the tag's property in the source_payload field, which is specified by the "sourcePayloadPath" property.
  • It applies to the tag's field in the integration table, which is specified by the "sourceFieldName" property.
  • For example, "sourcePayloadTimeFormat": "iso8601" causes a "jsonToTableFields" transform to read the value "18:01:47" from the tag's property in the source_payload field, decode it into the hour 18, minute 1, and second 47, and store it in the tag's time or timestamp field in the integration table.
  • For example, "sourcePayloadTimeFormat": "hh.mm.am/pm" causes a "jsonToTableFields" transform to read the value "06:01:47 pm" from the tag's property in the source_payload field, decode it into the hour 18, minute 1, and second 47, and store it in the tag's time or timestamp field in the integration table.
  • For example, "sourcePayloadTimeFormat": "hhmm" causes a "tableFieldsToJson" transform to read the hour 18, minute 1, and second 47 from the tag's time or timestamp field in the integration table, encode it into "1801", and store it the tag's property in the source_payload field.
  • When combined with the "sourcePayloadTimeFormat" property, the server can properly encode and decode a date and time stored in a timestamp field.
 "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 optional "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".

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

sourcePort

 The "sourcePort" property is an optional integer that specifies the ISAM TCP/IP port of a FairCom DB or RTG server. 5597 int16 1 to 65535

sourcePortFilter

The "sourcePortFilter" property is an optional integer that specifies a complete match for a port number.

 null integer 1 to 65535

sourceServerName

 The "sourceServerName" property is a conditional string that specifies the server name of a FairCom DB or RTG server. It is the name specified by the SERVER_NAME keyword defined in the target server's configuration file, ctsrvr.cfg. The server name used by most FairCom DB and RTG servers is "FAIRCOMS". This property is required if the "sourceHostname" is not defined. Required if "sourceHostname" is not defined - No default value string 1 to 255 bytes

sourceServerNameFilter

The "sourceServerNameFilter" property is an optional string that specifies a partial match for a server name.

 null string 1 to 64 bytes

sourceServers

 The "sourceServers" property is a required array containing a list of FairCom DB or RTG server connection objects. FairCom MQ attempts to connect to the first server in the list. If that fails, it attempts to connect to the next one. If it reaches the last server in the list, it attempts to connect to the first. Required - No default value array of server connection objects 
{
  "purpose": "Primary Server",
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  }
}

sourceTableName

The "sourceTableName" property is a string that specifies the name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 Required if "sourceDataFilePath" is not specified string 1 to 64 bytes

sourceTableNameFilter

The "sourceTableNameFilter" property is an optional string that specifies a partial match for the table name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 null string 1 to 64 bytes

sourceUsername

The "sourceUsername" property is a required string up to 31 bytes long that specifies the source account to be cloned.

Note See System limits for user name and other system properties requirements.

 Required - No default value string 1 to 31 bytes

sourceUsernameFilter

The "sourceUsernameFilter" property is an optional string that specifies a partial match for a user name.

 null string 1 to 64 bytes

sql

The "sql" property specifies an SQL statement.

Required - No default value

 string 1 to 32,000,000 bytes

sqlForwardOnly

The optional "sqlForwardOnly" property returns records in forward-only order.

false

Boolean

true

false

sqlParams

The "sqlParams" is an optional array of values. Each value becomes a parameter in the SQL statement.

  • Each value may be a string, number, integer, true, false, or null.
  • The same value may be repeated within the array.
  • The order of the values must match the order of the SQL parameters.
  • The type of each value must correspond to the field type of the corresponding SQL parameter.
  • It is an error if the number of SQL parameters do not match the number of items in this array.
  • It is a best practice to use SQL parameters rather than embedding values in a SQL query.
  • It prevents SQL injection attacks.
  • Because the same value may be applied to multiple SQL parameters, items in the "sqlParams" array can have the same value.
 [] array An array of values

sqlStatements

The "sqlStatements" property specifies SQL statements that the server will execute.

There is one SQL statement per string.

Required - No default value

 array of strings 1 or more sql statements

startFrom

 The optional "startFrom" property sets the cursor to a known position. "currentPosition" string

"currentPosition"

"beforeFirstRecord"

"afterLastRecord"

startTimestamp

The "startTimestamp" property is an optional string that contains an ISO8601 timestamp, which filters the response to return problems that started on or after its value. If any parts of the timestamp are missing or omitted, the server defaults the remaining parts to 0.

 null string containing an ISO8601 timestamp

"2025-08-19"

"2025-08-19T00:00:00.000"

"2025-08-19T01:13"

"2025-08-19T01:13:59"

"2025-08-19T01:13:59.853"

status

The optional "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.

 "active" string enum

"active"

"inactive"

statusFilter

The "statusFilter" is an optional query filter consisting of an array of status values. If the array is empty, null, or omitted, it matches all status values; otherwise, it returns code packages only when their status matches one of the values in the array. If "includeDeactivatedCode" is set to true or false, it overrides conflicting status codes.

 

When using the tag actions, this property finds tags based on their status. You can include zero or more status values. The "listTags" action returns tags that match at least one of the specified status values. An empty array or null value matches all status values.

  • Use "statusFilter": "active" to return active tags.
  • Use "statusFilter": "inactive" to return inactive tags.
  • The "listTags" action returns tags that match at least one of the specified status values.
  • Omitting the property or setting it to null matches all tags.
 [] array

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

 

When using tag actions, "inactive" and "active" are the only valid statuses 

streamingConnectionName

 The "streamingConnectionName" property is a required string that specifies a unique, user-defined name for a streaming connection. The API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server. Required - No default value string 1 to 64 characters

streamingConnectionNameFilter

The "streamingConnectionNameFilter" property is an optional string that specifies a partial match for a connection name.

 null string 1 to 64 bytes

streamParallelism

 The "streamParallelism" property is an optional integer that specifies the number of parallel streams the server uses to deliver data changes to the FairCom MQ server. You typically use a number that does not exceed the number of cores on the FairCom MQ server. 8 integer 1 to 65535

streams

 specifies an array of stream definitions. Required - No default value Array of stream definitions 1 or more stream definitions

stringFormat

The optional "stringFormat" property in "responseOptions" changes how "char", "varchar", "lvarchar", and "variant" string field values are returned.

This property applies to all "getRecords..." actions, except for "getRecordsUsingSql" because SQL controls the format of strings it returns.

 "json" string

"json"

"hex"

subscribeToExternalBroker

The "subscribeToExternalBroker" property is optional. When this property is set to a valid broker connection, FairCom 's servers connect to the external MQTT broker and subscribes to this topic on that broker. Thus, these servers become a client to another MQTT broker. Each message sent to this topic on the external broker becomes an incoming message in FairCom 's servers – as if it were sent directly to them . The topic works the same as any other topic.

  • Any client can publish messages to this topic.
  • A valid Broker Connection must be created before you set "subscribeToExternalBroker" to a value (see "configureBrokerConnection").
  • If this broker connection name does not already exist, it does not set up an external subscription and it logs an error stating, “Cannot subscribe to the external broker because the Broker Connection name xxx has not yet been defined by ConfigureBrokerConnection.”
"" string

Any previously defined name of a broker connection (see "configureBrokerConnection")

subscriptionActions

The "subscriptionActions" property is an array of subscription objects that add or remove a topic filter from a client's subscriptions. Each subscription object contains a "topicFilter" and an optional "subscriptionIdentifier".

  • Use the required "subscriptionAction" property to add or remove a topic filter: "add" adds a topic filter to the subscription and "remove" removes it. 
  • Use the required "topicFilter" property to a wildcard topic to subscribe to multiple topics. 
  • Use the optional "subscriptionIdentifier" property to assign a unique identifier to the subscription. When the FairCom server sends an MQTT 5 message to the client, it includes the subscription identifier to help the client identify the subscription quickly and easily.
  • Use the optional "receiveRetainedMessages" property to control when the FairCom server sends the retained message to a topic subscription event, which includes never sending the retained message, sending it only when the client subscribes for the first time, or sending it each time the client subscribes. 
  • Use the optional "receiveMyMessages" property to prevent or allow the FairCom server to send messages to a client that the client published. 
  • Use the optional "userProperties" property to set user-defined subscription properties.
 [] array

"binaryFormat"

"includeExpiredMessages"

"receiveMyMessages"

"receiveRetainedFlagAsPublished"

"receiveRetainedMessages"

"subscriptionIdentifier"

"topicFilter"

"userProperties"

subscriptionIdentifier

The "subscriptionIdentifier" is an integer number from 1 to 268435455 optionally provided by the subscriber that uniquely identifies the "topicFilter" to the subscriber. Each subscriber may assign its own "subscriptionIdentifier" to each "topicFilter". When the FairCom server delivers a message to the subscriber, it includes the "subscriptionIdentifier" with the message. The purpose of Subscription Identifiers is to make it easy and fast for an MQTT 5 client to process an incoming message. The client can use the Subscription Identifier in a message to associate a message with a specific handler. A client receiving a message with multiple Subscription Identifiers can send the message to multiple handlers – one for each Subscription Identifier.

 268435455 integer 0 to 268435455

tableFileExtension

The "tableFileExtension" property is an optional string from 0 to 64 bytes. It specifies the file system extension to use for a table's data files. If omitted, it defaults to ".dat".

Note If set to a zero-length string, then newly created data files will have no extension.

 

Example request

"params": {
  "tableName": "test1",
  "tableFileExtension": ".dat"
}
 ".dat" string 0 to 64 bytes

tableFilter

The "tableFilter" property is an optional string with no practical size limit. No table filter is applied when it is an empty string, a null value, or is omitted. It is a server-side filter of the records in a table. It includes records in the result only when they match the filter requirements. It works like a SQL WHERE clause except for using C syntax and C functions.

  • See Use Table Filters for more information and examples.
  • It uses FairCom's expression language, which is based on C syntax and supports arbitrarily nested expressions, operators, and functions, such as:
    • "tableFilter": "((name IS NOT NULL && name != \"Michael Jordan\" && strnicmp( name, \"m\", 1 ) == 0 && (ranking - 5) * 2 <= 6 && livedPast2000 ) || ( earnings < 1000000 && ! livedPast2000 )) && (ranking % 2 == 1)"
  • A zero-length table filter, such as "tableFilter": "" does not filter any records.
  • A "tableFilter" can be combined with other query techniques. For example, the "getRecordsInKeyRange" action can be used to retrieve a limited range of records that are further filtered by a "tableFilter".
  • To include a double quote character in a "tableFilter" expression, precede it with the backslash (escape) character, \".
  • The first time you include a "tableFilter" string in a "getRecords..." action, the server processes the string to produce an optimized filter. The server automatically reuses the optimized filter in subsequent calls to eliminate the initial processing overhead.
 "" string 0 to unlimited bytes

tableName

The required "tableName" property is a string containing the 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

tableNames

The "tableNames" property is a required array of strings. Each string is a table name.

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

  • Contains at least one string.
  • A zero-length "tableName" is invalid.
  • A client should force the uniqueness of items in the array because the server ignores duplicate items.
  • Including table names that do not exist will not result in an error. However, the "warnings" array in the reply will contain an object for each missing table.

Required - No default value

 array 1 to 64 bytes

tables

The "tables" property contains an array of objects. Each object identifies a table. It defaults to a single default object. Each object in the "tables" array contains three properties:

  • databaseName
  • ownerName
  • tableName
 {} array of objects

0 or more objects containing the following properties:

"databaseName"

"ownerName"

"tableName"

tagChanges

The "tagChanges" property is a string that specifies when to add "changed": true to field objects in the data change event to indicate when a field changed value.

 "forEachField" string enum

"forEachField"

"forPrimaryKeyFields"

"never"

tagDataType

The optional "tagDataType" property is an enumerated string that specifies the data type of the tag.  

  • It defines the data type of the tag's value. 
  • The default value is "json", which can represent a string, number, true, false, null, an object, and an array.
  • 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.
 "json" string enum "string"
"number" 
"boolean" 
"date" 
"time" 
"timestamp" 
"json" 
"variant" 
"binary" 

tagDataTypeFilter

 The optional "tagDataTypeFilter" property is an array of strings that specifies one or more tag data types. Each item in the array is the exact name of a tag data type. It is a string from 1 to 64 bytes. The "listTags" action returns tags that match one of the specified values.  [] array of strings 1 to 64 bytes

tagElementCount

 The optional "tagElementCount" property specifies the number of elements in the tag. All tags are treated as arrays. Tags that are not arrays are considered to have a length of one element. 1 int32 0 and negative values are invalid.

tagName

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

  • It is a string from 1 to 256 bytes. 
  • It is required and cannot be the empty string "".
  • 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.

When using connectors, this property specifies the full name of a tag, such as MyTag[10,42] for CIP-based PLCs. 

For  CIP-based PLCs, use the format Program:<program name>.<tag>.

  • <program name> is the program name in which the tag is created
  • <tag> is the name in the program

Examples: Program:MyProgram.MyTag accesses the tag MyTag in the program MyProgram. 

PCCC-based PLC examples include N7:4, ST18:26, L20:2, MG14:6.en, B3:4/2, and so forth. Many common field name abbreviations are supported.

 Required - No default value string 1 to 256 bytes

tagNameFilter

 The optional "tagNameFilter" property specifies a partial or full name of a tag to describe. It is a string from 1 to 64 bytes. The action returns tags that match the partial or full name of the tag, provided it satisfies all other specified filter properties. "" string 1 to 64 bytes

tagNames

The required "tagNames" property is an array of strings that specifies one or more tag names. You can use it to describe or delete tags. 

  • Each item in the array is the exact name of a tag. 
  • It is a string from 1 to 256 bytes.
 Required - No default value string 1 to 256 bytes

tagPath

The optional "tagPath" property specifies additional connection information with the  format "p,s"

p is the communication Port Type

1 for Backplane
2 for Control Net/Ethernet, DH+ Channel A, or DH+ Channel B
3 for Serial

s is the slot number where the PLC is installed, such as 0, 1, 2.

 "1,0" string String with the format "p,s"

tagType

 The "tagType" property specifies the binary format of the PLC data represented by the tag. Required - No default value string

"bit"

"int8"

"uint8"

"int16"

"uint16"

"int32"

"uint32"

"int64"

"uint64"

"float32"

"float64"

"byte"

"string"

tagSize

The "tagSize" property specifies the buffer size in bytes to handle tag data.

If not specified, the buffer size is defined based on the tagType. For example, 1 for int8 and 4 for int64.

For string tagType, the default value is 0 which will set the buffer to the maximum string size for the device.

Let the server define this property. and set it yourself only when necessary.

 Optional - depending on the dataType value Integer 0, 1, 2, 4 or 8

targetDatabaseName

The "targetDatabaseName" property is the optional name of the database that contains the target table. See

"databaseName" for more information.

 "" string 1 to 64 bytes

targetOwnerName

The "targetOwnerName" property is the optional name of the account that owns the target table. See "ownerName" for more information.

 "" string 1 to 64 bytes

targetTableName

The required "targetTableName" property specifies the name of the target table that has its transform steps replaced by this action.

Note The fully qualified name of a table includes the database, owner, and table names.

 "" string 1 to 64 bytes

temporarySession

The "temporarySession" property is an optional Boolean property that defaults to false when omitted or set to null. It is used in the "createMqApiSession" and "alterMqSession" actions to make a session temporary or permanent. When set to true, the session is temporary; otherwise, it is permanent.

When true, the MQ engine resets the current session, and when the client disconnects, the engine removes the session's settings, subscriptions, and message position. Because you normally want the engine to remember your message position between sessions, you rarely set "temporarySession" to true.

Use the "temporarySession" property to control session permanency rather than the "cleanSession" property because its name is more intuitive. The server returns an error if you include both and set them to opposite values.

 false Boolean

true

false

testDatabaseName

The optional "testDatabaseName" property specifies the database of the test table where this action tests the transform steps.  

When set to null or omitted, the server uses the default "databaseName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultDatabaseName" property.

Note The fully qualified name of a table includes the database, owner, and table names.

 Defaults to the "defaultDatabaseName" defined in the "createSession" action. string 1 to 64 bytes

testOwnerName

The optional "testOwnerName" property specifies the owner account of the test table where this action tests the transform steps.  

When set to null or omitted, the server uses the default "ownerName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultOwnerName" property.

Note The fully qualified name of a table includes the database, owner, and table names.

 Defaults to the "defaultOwnerName" defined in the "createSession" action. string 1 to 64 bytes

testTableName

The required "testTableName" property specifies the name of the test table where this action tests the transform steps.

Note The fully qualified name of a table includes the database, owner, and table names.

 Required - No default value string 1 to 64 bytes

testTransformScope

The required "testTransformScope" property defines the behavior of this action. It is a string enum with one of the following values:

  • "allRecords" returns immediately and creates a background thread that asynchronously creates a test table, copies all records to it, and runs the transform steps on all records in that table.
    • This option applies only to the "testIntegrationTableTransformSteps" action.
    • Once records are copied to the test table, it applies the transform steps.
    • You can stop this action by calling this action with "testTransformScope": "stop".
    • It regularly updates the "transformStatus" and the "transformPercentComplete" properties, which are returned by the "describeIntegrationTables" action.
    • If the test table's background thread is already running, the action returns an error indicating the "testIntegrationTableTransformSteps" action is already running on the integration table. The user can decide if he wants to wait or stop the action.
  • "stop" immediately stops the background thread assigned to the test table.
    • If no background thread is running, the action does nothing and returns an error.
    • The action may be stopped while it is creating the test table, copying records to the test table, or running transform steps on the test table's records.
    • It always deletes the test table because the action is incomplete. Otherwise, the action could leave the test table in an unexpected state, such as not being created, incompletely copying records, or incompletely transforming records.
  • "firstRecord" returns the first record's fields before and after being modified by the transform steps.
    • It returns two properties: "recordBeforeBeingTransformed" and "recordAferBeingTransformed".
    • It runs synchronously and does not change the record in the database.
    • You can repeatedly run this scope because it will not affect your data, does not interfere with the "rerunIntegrationTableTransformSteps" action, and does not interfere with the test table's background thread.
  • "lastRecord" returns the last record's fields before and after being modified by the transform steps.
    • It returns two properties: "recordBeforeBeingTransformed" and "recordAferBeingTransformed".
    • It runs synchronously and does not change the record in the database.
    • You can repeatedly run this scope because it will not affect your data, does not interfere with the "rerunIntegrationTableTransformSteps" action, and does not interfere with the test table's background thread.
  • "specificRecords" returns the specified record's fields before and after being modified by the transform steps.
    • Each record has an "id" field containing an integer number that uniquely identifies it. The action uses the "id" property to specify the ID number of the record.
    • It returns two properties for each record listed in the "ids" property: "recordBeforeBeingTransformed" and "recordAferBeingTransformed".
    • It runs synchronously and does not change the record in the database.
    • You can repeatedly run this scope because it will not affect your data, does not interfere with the "rerunIntegrationTableTransformSteps" action, and does not interfere with the test table's background thread.

The "logTransformOverwrites" property, when true, causes the action to log attempts by JavaScript to overwrite a field value.

 Required - No default value string enum

"allRecords"

"stop"

"firstRecord"

"lastRecord"

"specificRecords"

thingIdFilter

 The optional "thingIdFilter" property is the unique integer ID of a thing. The "listTags" action includes tags associated with the specified thing, which is a device or software application. [] array of integers zero or more thing id integers

thingName

 The required "thingName" property is a string that specifies the unique name of a thing.  It is a string from 1 to 64 bytes. It cannot be the empty string "". Required - No default value string 1 to 64 bytes

thingNameFilter

 The optional "thingNameFilter" property specifies a partial or full name of a thing to describe. It is a string from 1 to 64 bytes. The action returns things that match the specified partial or full name of the thing, provided it satisfies all other specified filter properties. "" string 1 to 64 bytes

thingNames

 The required "thingNames" property is an array of strings that specifies one or more thing names. Each item in the array is the exact name of a thing. It is a string from 1 to 64 bytes. You can use it to describe or delete things. Required - No default value array one or more thing name strings

thingType

The optional "thingType" property specifies the thing's type, which is a generic description of what the thing is, such as "plc". A thing may have one type. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

This API uses the Label API to manage types.

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

thingTypeFilter

 The optional "thingTypeFilter" property is an array of strings. Each string is a partial or complete type, such as, "thingTypeFilter": [ "myTy", "PLC" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. [] array of strings zero or more type strings

threads

The "threads" property is the number of threads assigned to a topic to write published messages to disk. This property is optional. The default value is 1.

  • The default of 1 is enough to handle typical workloads.
  • For heavy workloads, you may increase the number of threads to 2 or 3.
 1 integer

1

2

3

timeFormat

The optional "timeFormat" property specifies the format of a time or a datetime embedded in a JSON string. The server uses it when it needs to transform or convert a time or datetime embedded in a JSON string into a FairCom time or timestamp. It also uses it when it needs to convert a time or datetime field value into a time embedded in a JSON string.

It is an enumerated string with one of the following values: "hh.mm.ss.ttt", "hh.mm.am/pm", "hh.mm.ss.am/pm", "hh.mm.ss", "hh.mm", "hhmm", "iso8601", and "utc".

The default value for "timeFormat" is the "defaultTimeFormat" property defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultTimeFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "iso8601" because the ISO8601 date is the defacto standard in JSON.

The enumerated string defines how the server parses a time in a JSON string. The following key explains the parts of each enumerated value:

  • hh is a one- or two-digit hour (0-24).
  • mm is a two-digit minute (00-59).
  • ss is a two-digit second (00-59).
  • ttt is a fraction of a second with up to 3 digits of precision (.0-.999).
  • . represents one character that can be one of the following values: :, ., -, or /.
  • "utc", "iso8601", and "hh.mm.ss.ttt" are the same.
UTC datetime format

Coordinated Universal Time (UTC) is an industry-standard for dates and times that uses the ISO8601 datetime format: "ccyy-mm-ddThh:mi:ss.fffz" or "ccyy-mm-ddThh:mi:ss.fff±hh:mi":

  • Variable parts
    • ccyy is a four-digit year.
    • mm is a two-digit month (01-12).
    • dd is a two-digit day of the month (01-31).
    • hh is a two-digit hour (00-23).
    • T is the letter T or the space character. It is required only when the time is present.
    • mi is a two-digit minute (00-59).
    • ss is a two-digit second (00-59).
    • fff is an optional fraction of a second with up to three digits of precision.
    • ± is an optional + or - character representing a positive or negative timezone offset. It is required only when a timezone offset is present.
  • Constant parts
    • - separates the year, month, and day.
    • : separates the hour, minute, and second.
    • . separates the second from a fraction of a second. It is required when the fraction is present.
    • Z is optional and represents the UTC timezone (also called Zulu time), which represents the timezone offset of +00:00.
  • Examples
    • 2025-07-11T16:18:33Z
    • 2025-07-11T16:18:33+00:00
    • 2025-07-11 16:18:33.9-07:00
 "hh.mm.am/pm" string

"hh.mm.am/pm"

"hh.mm.ss.am/pm"

"hh.mm.ss"

20:15:30

20.15&30

20H15M30S

"hh.mm"

"hhmm"

tls

 The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the cipher suites that are allowed, and whether the client certificate is required. This property is optional. It defaults to an empty object.  {} object

"allowedCipherSuites"

"certificateAuthoritiesFilename"

"certificateFilename"

"privateKeyFilename"

topic

The "topic" property is a unique user-defined name for the topic.

  • The "topic" name may be up to 65,500 characters long, but it is typically less than 150 characters.
  • The "topic" name will be used in all subsequent references to the topic, such as when re-configuring or deleting the topic.

 

 "" string 1 to 65,500 bytes

topicAliasMaximum

The "topicAliasMaximum" property is an optional integer that specifies the maximum number of topic aliases that the MQTT client can support.

 0 integer 0 to 65535

topicFilter

The "topicFilter" property is an optional UTF-8 string containing a topic filter, which may contain MQTT wildcard characters, #, and +. Without wildcard characters, it matches one topic. When containing wildcard characters, it may match one or more topics.

 "" UTF-8 string topic names

topicIdFilter

 The optional "topicIdFilter" property is the unique integer ID of an MQTT topic. The "listTags" action includes tags associated with the specified topic. [] array of integers zero or more topic id integers

topics

The "topics" property specifies the name of each "topic" that you want to be described in the results.

 []

array

 0 or more topic strings

transactionDescription

 The "transactionDescription" property identifies the object by this description.

""

 string 0 to 65,500 bytes

transactionId

 The "transactionId" property optionally identifies a transaction in which the specified action will be included. "" string 0 to 255 bytes

transactionModel

The "transactionModel" property is an optional, case-insensitive, string enum. It defines how the server processes transactions for a table. The default is "logTransactions".

Possible values:
  • "logTransactions"
    • This persists data to data files and writes transaction changes to transaction logs. It supports commit and rollback transactions and data replication. It will not lose data during an unplanned outage. It provides the most durability and the most capabilities, but is slower than the other settings.
  • "ramTransactions"
    • This supports commit and rollback transactions in RAM while persisting data to data files. It does not use a transaction log, which makes it even faster, but an unplanned outage may lose or corrupt unwritten data.
  • "noTransactions"
    • This does not support transactions but still persists data to disk, making it even faster. However, an unplanned outage may lose or corrupt unwritten data.

 

Example request

{
  "api": "db",
  "action": "createTable",
  "params": {
    "transactionModel": "noTransactions"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 "logTransactions" string

"logTransactions"

"ramTransactions"

"noTransactions"

transactionSavepointId

The "transactionSavepointId" is a string that the server generates and returns in a "createTransactionSavepoint" action. The generated ID represents a point in a transaction's progress. In requests, it defaults to an empty string.

  • A transaction savepoint represents the current point in the transaction process.
  • A client can roll back a transaction to any savepoint by calling the "rollbackTransaction" action with the desired "transactionSavepointId" property.
  • A client can commit a transaction to any savepoint by calling the "commitTransaction" action with the desired "transactionSavepointId" property.
  • A zero-length string returned in a response means the "transactionSavepointId" provided in the request is invalid.
  • Do not assume that the "transactionSavepointId" is a number in a string.

""

 string 0 to 255 bytes

transformBufferInitialBytes

 The "transformBufferInitialBytes" property is optional and defaults to 0. It is a positive integer that specifies the number of bytes for the session to allocate initially for its transform buffer. Omit this property or set it to 0 when you do not plan on using the "transformCodeName" property to transform the JSON returned from the "getRecords..." actions. If you plan on transforming the JSON, you can set the "transformBufferInitialBytes" property to the number of bytes that you anticipate the server will need to store the results of each transform. If the server needs more memory, it automatically increases the buffer size; thus, this property is an optimization that helps prevent the server from doing expensive memory allocations. 0  integer 0 or more bytes

transformCodeName

The "transformCodeName" property is an optional string that specifies the name of an existing code package with a "codeType" of "getRecordsTransform".

When this property is present in a "getRecords..." transform, the server passes the query results to the code package as an array of objects. The code transforms the records and returns a valid JSON value. The server places the value in the "data" property of the response to the "getRecords..." action.

 Optional name of a code package string The string must contain the name of an existing code package with a "codeType" of "getRecordsTransform"

transformName

(deprecated) specifies the name of a transform process you have created. Replaced by the "transformSteps" property.

 "" string 1 to 64 bytes

transformNameFilter

The "transformNameFilter" property is an optional string that specifies which assigned transform the response will be filtered by. If no integration tables are assigned to the transform, the action returns no tables. If omitted or set to null, the "listIntegrationTables" action will not filter by transform name.

 "" string 1 to 64 bytes

transformStepMethod

The "transformStepMethod" property is a required string that specifies the type of transform, such as the "javascript" transform method that runs JavaScript to change the table's data or the "jsonToTableFields" transform method that extracts values from properties in a JSON field and stores them in other fields.

Note The "transformStepMethod" property replaces the deprecated "transformActionName" property.

The value of the "transformStepMethod" affects the value of the "transformService" property. The following table defines the possible values of the "transformService" property when combined with the "transformStepMethod". Notice that some transform step methods are built into the server and do not require you to specify the "transformService".

"transformStepMethod" value "transformService" value
"jsonToTableFields" null or omitted
"tableFieldsToJson" null or omitted
"jsonToDifferentTableFields" null or omitted
"javascript" "v8TransformService"
"siemensUdtPayloadToJson" "siemensUdtPayloadToJson"

Note If the "transformStepMethod" property is set to "javascript", the "transformService" property must be set to "v8TransformService".

 

 Required - No default value string enum

"javascript"

"jsonToDifferentTableFields"

"jsonToTableFields"

"tableFieldsToJson"

transformStepName

The "transformStepName" property is an optional string that assigns a name to each transform step.

 "" string 1 to 64 bytes

transformSteps

 specifies an array of transform objects. Required - No default value array of objects

0 or more objects containing 1 or more of the following properties:

"codeName"

"databaseName"

"ownerName"

"mapOfPropertiesToFields"

"targetDatabaseName"
"targetOwnerName"

"targetTableName"

"transformStepMethod"

"transformStepName"

"transformStepService"

transformStepService

The "transformStepService" property is an optional string that specifies the name of a transform service, which is the user-defined name for a library (.dll, .so, .dylib) that implements the transform step method.

This property allows you to register your own transform libraries or use an older version of a FairCom library for backward compatibility.

Transform services are defined in the services.json file under the "transformServices" section. You can add and remove transform libraries to this list, such as your own transform libraries or specific versions of FairCom's transform libraries. Use the "serviceName" property to give each transform library a unique transform service name and use the "serviceLibrary" property to specify the filename of the library that implements the transform step method. On Windows the library filename ends with .dll. On Linux it ends with .so. On MacOS it ends with .dylib. Lastly, you must enable the transform service by setting "enabled" to true.

Example "transformServices" section in the services.json file.

"transformServices": [
  {
    "serviceName": "v8TransformService",
    "serviceLibrary": "v8transformservice.dll",
    "enabled": true
  }
],

Note If the "transformStepMethod" property is set to "javascript", the "transformStepService" property must be set to "v8TransformService" or to a user-defined transform service name associated with the "v8transformservice.dll" service library.

 

 "" string 1 to 64 bytes

triggers

The "triggers" property is an array of enumerated strings that specifies a list of events on a table that create data change events.

 [ "insert", "update", "delete" ] array of enum strings

"delete"

"insert"

"update"

type

The required "type" property specifies the field's data type. It has no default value. See Data types for the limits, valid values, and whether "length" and "scale" are required.

 

Request example

"fields": [
  {
    "name": "j",
    "type": "number"
  }
]
 Required - No default value string

"json"

"bit"

"tinyint"

"smallint"

"integer"

"bigint"

"real"

"float"

"number"

"money"

"date"

"time"

"timestamp"

"char"

"varchar"

"lvarchar"

"binary"

"varbinary"

"lvarbinary"

unique

The "unique" property is an optional Boolean. When true, the "createIndex" action creates a unique index, which requires the columns in the index to have a unique value for each record in the table. It defaults to false.

"params": {
  "unique": true
}
 false Boolean

true

false

unsetHealthMeasures

The "unsetHealthMeasures" property is an optional Boolean that specifies whether or not to include sessions without health measures in the response.

 true Boolean

true

false

uri

 The "uri" property specifies the identifier name of the Rest resource. Required - No default string 1 to 1024 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

Required - No default value

 

Defaults to the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

usernameFilter

The "usernameFilter" property is an optional array containing usernames that filter the returned list of sessions by the accounts associated with those usernames.

 [] array 1 to 64 bytes

usernames

 The optional "usernames" property specifies the names of the accounts that the action will target. [] array 0 or more usernames, each between 1 and 64 bytes.

userProperties

The "userProperties" property is optional in the "publishMessagesToMq" action and defaults to null. When present, it is an array of key-value objects. A key-value object contains a "key" property and a "value" property with string values. You can assign multiple key-value pairs to an MQTT 5 message; the server includes them in the messages it delivers to subscribers. The server may process specific key-value pairs as instructions that modify its behavior.

"userProperties": [
  {
    "key": "some key",
    "value": "some value"
  }
]
 null array 0 or more key/value pairs

validateMqttPayload

The optional "validateMqttPayload" property is a Boolean property that defaults to the value of  "defaultValidateMqttPayload" in the services.json settings file, which is true by default.

  • When true, the MQTT broker validates the payload of each MQTT message to verify that it matches the type specified by the "mqttPayloadType" property.
    • If a payload fails validation, the message is delivered without change to all subscribers. The broker also sets the error field to true and adds an error object to the log field (see the error object example). Users, applications, and JavaScript transform steps can read the values of the error and log fields to know when incoming content is invalid.
  • When false, the MQTT broker does not validate the payload. This increases message throughput because validation increases the time it takes to process each message. Without validation, the broker cannot update the error and log fields to indicate when content is invalid. Lastly, invalid content can cause problems for subscribers and JavaScript transforms that expect valid content.

 

Example error object describing an invalid MQTT payload

[
  {
    "errorCode": 12046,
    "errorMessage": "Payload is not a valid JSON.",
    "errorSource": "MQTT payload format"
  }
]
 Defaults to the "defaultValidateMqttPayload" value in the services.json file, which is true by default. Boolean

true

false

value

The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records.

 

In Key-Value actions, the required "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

variantFormat

The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request.

The "variantFormat" property has one of the following values: "binary", "json", "string", and "variantObject". It tells the server how to store and return values stored in variant fields. 

The server applies the "variantFormat" property to all variant fields affected by a JSON action, such as all variant fields inserted by the "insertRecord" action or all variant fields returned by the "getRecordsByIndex" action. If you want more control, set the "variantFormat" property to "variantObject" and you can use variant objects to independently set the variant type and encoding of each variant field in a JSON action.

A variant field is a flexible, strongly-typed field. It is flexible because each variant field in each record can store any type of data. It is strongly typed because each variant field in each record stores the type of value it contains.

A variant field's type can currently be set to "binary", "json", "string", and "boolean" values. In the future, you will be able to set it to other values, such as "jpeg", "xml", and user-defined types.

The following sections describe each value of the "variantFormat" property.

 

"variantFormat": "binary"

  • Use the "variantFormat": "binary" setting to store and return variant field values as binary values embedded in JSON strings.
  • The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.
  • When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.
  • The binary value can be any sequence of bytes.
  • The server does not validate the binary value.
  • The "binaryFormat" property specifies how the client and server format binary value. For example, the "hex" value embeds hexadecimal numbers in a JSON string.

 

"variantFormat": "json"

  • Use the "variantFormat": "json" setting to store and return variant field values as JSON values.
  • The "json" variant type provides maximum convenience in FairCom's JSON APIs.
  • The server validates JSON before it assigns it to a variant field.
  • The server converts a variant field to valid JSON before it returns the value of a variant field.
    • The "binaryFormat" property specifies the format of a binary variant value embedded in a JSON string.
    • The "numberFormat" property causes the server to return numbers as JSON numbers or JSON strings containing embedded numbers. All languages and JSON parsers work well with strings containing embedded numbers – even extremely large and small numbers.
  • When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.
    • The server does not store a JSON null; instead it marks the variant field as NULL. If the field is not nullable, the API returns an error.
    • The server stores a JSON string in the variant field as is. It includes the double quotes before and after the string's value and stores escaped characters without decoding them. For example, the server stores the JSON string, "my // string",  as "my // string". The server returns a JSON string exactly as it stores it.
    • The server stores a JSON number in the variant field as is. A number consists of the following ASCII characters 1234567890+-.eE. For example, the server stores the JSON number -123.45 as the ASCII characters -123.45. The server returns a JSON string exactly as it stores it.
    • The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.
    • The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the ASCII characters representing the actual object or array. For example, the server stores the array [1,2,3]  as the ASCII characters [1,2,3].

 

"variantFormat": "variantObject"

  • Use the "variantFormat": "variantObject" setting to store and return variant field values as a variant object.
  • The variant object defines everything the server and client need to know about a variant, including its type, value, value encoding, and storage encoding.
  • The "variantObject" variant type provides maximum flexibility across all FairCom APIs and programming languages.
  • A variant object is a JSON object containing the following properties: "schema", "value", "valueEncoding", and "type". The "schema" property must have the value "jsonaction.org/schemas/variantObject".
  • When "variantFormat" is "variantObject", the server parses the variant object and uses its properties to determine how to store the variant value.
    • The "value" property contains the variant field's value .
    • The "valueEncoding" property specifies how the value is encoded so the server and client can decode the value. For example, assigning "hex" to "valueEncoding" indicates the "value" property contains a binary value embedded in a string as hexadecimal characters. The server decodes the value before storing it in the variant field. In FairCom's JSON APIs, the "binaryFormat" property in the "responseOptions" object specifies how the server encodes the binary value before returning it.
    • The "type" property specifies the variant's type, such as "json", "binary", and "string". In the future, the FairCom server will support additional types, such as "jpeg", "xml", and user-defined types.
  • When the "insertRecords" and "updateRecords" actions have "variantFormat": "variantObject" in "params", you must assign a variant object to each variant field.
  • A JSON action returns a variant object for a variant field value when you put "variantFormat": "variantObject" in "responseOptions".

 

Variant object examples

 

Binary value in a variant object

Add "binaryFormat": "base64" to "responseOptions" to tell the server to encode the variant value as Base64.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "ewogICJrZXkiOiAidmFsdWUiCn0=",
  "valueEncoding": ["base64"],
  "type": "binary"
}

 

Number in a variant object

Add "numberFormat": "string" to "responseOptions" to tell the server to embed the number in a string.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "123.45",
  "valueEncoding": ["string"],
  "type": "number"
}

 

Add "numberFormat": "number" to "responseOptions" to tell the server to encode the number as a JSON number.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 123.45,
  "type": "number"
}

 

Boolean in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": true,
  "type": "boolean"
}

 

String in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "A JSON string with embedded \" double quote.",
  "type": "string"
}

 

JSON in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": [1,"2",{"key": "value"}],
  "type": "json"
}
 "json" string

"json"

"binary"

"string"

"variantObject"

The "verifyLinks" property is an optional Boolean property. When omitted or null, it defaults to true. When true, the action verifies that the specified labels, records, and tables exist. If your application has already validated that the labels, records, and tables exist, it can set "verifyLinks" to false, which provides a performance boost because the action does not need to look up this information.

 true Boolean

true

false

waitToBeLoaded

The "waitToBeLoaded" property is an optional Boolean. When true, the "createIndex" action will not return until the index is created. It defaults to false.

  • Waiting for a large index to be created may cause an API timeout.
  • The default is to return immediately and create the index in the background.
"params": {
  "waitToBeLoaded": true
}
 true Boolean

true

false

willContentType

The "willContentType" property is an optional string that specifies the content type of the last will message.

 "" string

IanaMediaType

CustomType

willCorrelationData

The "willCorrelationData" property is an optional JSON value that can be used to set will request-response messages.

 "" JSON 0 to 65,500 bytes

willDelaySeconds

The "willDelaySeconds" property is an optional integer that specifies the number of seconds the server will wait before sending the last will message.

 60 integer  

willExpirySeconds

The "willExpirySeconds" property is an optional integer that specifies the number of seconds before the last will message expires.

 60 integer  

willPayload

The "willPayload" property is required when a will message is present. It contains the payload of the last will message. You can set it to any JSON value, including binary values embedded in a JSON string or array.

 Required - No default value JSON  

willPayloadFormatIndicator

The "willPayloadFormatIndicator" property is an optional enumerated value that specifies the payload format for the last will message.

 "none" ENUM

"none"

"utf8"

willQoS

The property "willQoS" is reserved. The server sets it to 2.

 2 integer  

willResponseTopic

The "willResponseTopic" property is an optional string that specifies the topic for the last will message response.

 "" string  

willRetain

The "willRetain" property is optional. It defaults to false. When true, it tells the FairCom server to send the will message to new subscribers as the first message they receive when subscribing to a topic.

 false Boolean

true

false

willTopic

The "willTopic" property is optional. It is a UTF-8 string containing the topic that the FairCom server will use to publish the will message. If you set it to an empty string, "", null, or omit it, the FairCom server will not add the will message to the connection.

 "" UTF-8 string  

willUserProperties

The "willUserProperties" property is an optional array that assigns key-value pairs to the last will messages.

 [] array  
 
 

 

 

Response examples

Note If the target object does not exist, the response returns success, and the debug property contains a warning that the object was not found.

Minimal

{
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "databaseName",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "path",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "uid",
        "type": "bigint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "databaseName": "test_db_min",
        "path": ".\\test_db_min.dbs\\SQL_SYS",
        "uid": 1005
      }
    ]
  },
  "requestId": "1",
  "debugInfo": {
    "request": {
      "action": "deleteDatabase",
      "params": {
        "databaseName": "test_db_min"
      },
      "requestId": "00000014",
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "result": {
    "dataFormat": "objects",
    "fields": [
      {
        "name": "databaseName",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "path",
        "type": "varchar",
        "length": 8192,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      },
      {
        "name": "uid",
        "type": "bigint",
        "length": null,
        "scale": null,
        "defaultValue": null,
        "nullable": false,
        "primaryKey": 0,
        "autoValue": "none"
      }
    ],
    "data": [
      {
        "databaseName": "test_db_max",
        "path": "c:\\\\test_db_max.dbs\\SQL_SYS",
        "uid": 1007
      }
    ]
  },
  "requestId": "2",
  "debugInfo": {
    "request": {
      "api": "db",
      "action": "deleteDatabase",
      "params": {
        "databaseName": "test_db_maxasdfasdf"
      },
      "apiVersion": "1.0",
      "requestId": "2",
      "responseOptions": {
        "binaryFormat": "hex",
        "dataFormat": "objects",
        "numberFormat": "string"
      },
      "debug": "max",
      "authToken": "replaceWithAuthTokenFromCreateSession"
    },
    "serverSuppliedValues": {
      "databaseName": null,
      "ownerName": null
    },
    "errorData": {
      "errorData": null
    },
    "warnings": []
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response properties

Response properties

Universal response properties list

Property Description Type Contents

accounts

The "accounts" property returns each account that matches one of the usernames or partial usernames specified in the request. Each account is returned as an object, containing all the properties relevant to the account.

    "accounts": [
      {
        "username": "admin",
        "accountDescription": "",
        "lockoutAfterNFailedAttempts": 0,
        "maxDaysBeforePasswordMustChange": 0,
        "maxMinutesBeforeNextLogin": 0,
        "memoryLimit": 0,
        "memoryRule": "default",
        "roles": [
          {
            "roleName": "ADMIN"
          }
        ]
      }

 

 array of objects One object per matching account.

affectedRows

 The "affectedRows" property specifies the number of records that were affected by the SQL statement. integer number of records affected by the statement.

allowedCipherSuites

The "allowedCiperSuites" property is an optional string that specifies an array of ciphers that the server will accept for communications with clients. It defaults to an empty string.

  • It specifies the encryption ciphers that are allowed to be used for encrypting a TLS (SSL) connection.
  • A client is allowed to connect to the server only if it uses one of the ciphers in this list.
  • The default setting of an empty string supports industry-standard secure connections.
  • The default value requires clients to use full AES 256-bit encryption when they talk to the server.
  • If a client cannot support AES 256-bit encryption, a lower encryption level should be added to the list.
    • This is undesirable because malicious users will attempt to connect at the lowest possible level so they can harm the system (for more information, see ciphers main page at OPENSSL.org.
  • Example settings:
    • Maximally secure example:
      • This example only allows clients to connect securely.
      • ["AES256-SHA256", "AES256-GCM-SHA384", "DHE-RSA-AES256-SHA256"]
    • Minimally secure example with the broadest client support:
      • ["!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
    • Insecure example allowing clients to connect using any level of security from  none to the maximal:
      • ["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • Add @STRENGTH to the end of the list to force the server to prioritize the strongest algorithms first. 
  • Place an exclamation point before a cipher to disable it. 
 string No limits

applicationRoot

The "applicationRoot" property is a string that specifies the location of web applications relative to <faircom>/server/.

The default value of "./web/apps/" translates to the folder <faircom>/server/web/apps.

There is rarely a reason to change the "applicationRoot".

For information on how to add your own web applications, which can use any of FairCom's jsonAction APIs, contact FairCom.

 string The filepath to the folder where FairCom's apps are located.

applications

The "applications" property is an array of objects that describes and controls web applications that can run with the FairCom server. It defaults to an empty array which means no applications are configured to run.

FairCom and other custom web applications are single-page, browser-based applications served from folders in the default <faircom>/server/web/apps/ folder.

An app server is a backend service used by one or more web applications. It listens to HTTP and/or WebSocket requests and then returns results.

Contact FairCom for information on how to build and add your own app servers using C or C++.

The following "applications" properties should be considered for each web app:

  • "enabled"
  • "folderName"
  • "serviceLibrary"
  • "serviceName"
  • "uriPath"
 array of objects One object per application.

authToken

The "authToken" property signifies that the client is authenticated and authorized. It is required.

It is supplied by the server in response to the connect action.

Clients must include it in all subsequent requests to validate that they are authenticated and authorized. If the client does not supply the correct values, the server returns an unauthorized error.

 string 0 to 255 bytes

autoValue

The optional "autoValue" property indicates when and how the server automatically sets the field value.

Only one of these values is allowed per field.

  • "none" indicates that the server does not automatically set the field's value.
  • "incrementOnInsert" indicates that the server automatically increments a field’s value each time the server inserts a new record. It applies to fields that are of the type of decimal or one of the integer types, such as "bigint". Only one field per table can have this attribute. The server returns an error when assigning this attribute to multiple fields. The JSON DB API automatically creates the "id" field as an "incrementOnInsert" field. If you apply this attribute to another field, it becomes the only automatically incremented field in the table. If you want that field to be the primary key, assign "primaryKey": 1 to it.
  • "timestampOnInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert. It applies only to fields with a type of "timestamp".
    • If you attempt to insert a record and specify a timestamp for a field that has "autoValue" set to "timestampOnInsert", the timestamp you specified is ignored, and the current date and time are assigned to the field.
  • "timestampOnUpdate" indicates that the server automatically sets a field’s value to the current date and time of an update. This setting applies only to timestamp fields.
  • "timestampOnUpdateAndInsert" indicates that the server automatically sets a field’s value to the current date and time of an insert and an update. It applies only to fields with a type of "timestamp".
  • "changeId" indicates the server uses the field for optimistic locking. The server automatically sets the field's value to the internal transaction number used during the last update of the record. This value changes each time the server updates the record. A table may only have one change tracking field. The field type must be "bigint".
    • The JSON DB API automatically creates a "changeid" field with change-tracking functionality.
    • Change tracking is optional in the CTDB and ISAM APIs. The application must create a 64-bit integer field and assign change-tracking functionality to it.

Request

"fields": [
  {
    "name": "signed_int32",
    "type": "integer",
    "autoValue": "incrementOnInsert"
  }
]

Response

{
  "result": {
    "dataFormat": "objects",
    "data": [
      {
        "changeIdField": "changeId",
        "createRecByteIndex": false,
        "databaseName": "ctreeSQL",
        "fieldDelimiterValue": 0,
        "fields": [
          {
            "autoValue": "incrementOnInsert",
            "defaultValue": null,
            "length": null,
            "name": "signed_int32",
            "nullable": true,
            "primaryKey": 0,
            "scale": null,
            "type": "integer"
          }
        ]
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 string

"none"

"incrementOnInsert"

"timestampOnInser"

"timestampOnUpdate"

"timestampOnUpdateAndInsert"

"changeid"

averageMessagesPerDay

 The "averageMessagesPerDay" property describes how many messages the specified topic publishes per day on average. integer The average number of messages published per day

averageMessagesPerHour

 The "averageMessagesPerHour" property describes how many messages the specified topic publishes per hour on average. integer The average number of messages published per hour

averageMessagesPerMinute

 The "averageMessagesPerMinute" property describes how many messages the specified topic publishes per minute on average. integer The average number of messages published per minute

binaryFormat

The "binaryFormat" property designates the format of binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

  • The "binaryFormat" property may occur inside "params",  "responseOptions", "defaultResponseOptions", "result", and "mapOfPropertiesToFields".
    • It occurs in "params" when actions create or change values.
    • It occurs in "responseOptions" when actions return values.
  • When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
    • For example, when  "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
  • When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
    • For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
  • When "binaryFormat" occurs in "result", it signifies how binary values are represented.
    • For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
  • When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a JSON property.
    • For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
    • For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields"  transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
  • The following are the possible values for each format.
    • "base64"
      • When the server reads and writes from a binary field, it represents the binary value as a base64 string.
      • Base64 is harder for people to read and convert to binary.
      • Base64 creates the smallest payload for the most efficient data transmission in JSON.
      • "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
    • "hex"
      • When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
      • Hexadecimal is easier for people to read and convert to binary.
      • Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
      • Hexadecimal strings contain the characters 0 - 9 and A - F.
    • "byteArray"
      • When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
      • An array of bytes is easiest for a program to manipulate.
      • An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
      • An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
        • "aBinaryField": [ 255, 0, 255 ]

 

Example requests

 
Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Response examples

Note Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 string One of the following: "base64", "hex", or "byteArray".

body

 The "body" property specifies information to send to a REST server by defining the "propertyPath" and "propertyValue" properties. array of objects

"propertyPath"

"propertyValue"

brokerConnectionNames

The "brokerConnectionNames" property is a required array that contains a list of "brokerConnectionName" strings. It defaults to an empty array.

  • Must contain at least one string.
  • Each string is the name of a table.
  • A zero-length string is invalid.
  • A client should force uniqueness of the items in the array because the server ignores duplicate items.
 array of objects

1 object for each broker connection matching the request containing some or all of the following properties:

"brokerHostname"

"brokerPort"

"brokerUserName"

"reconnectFrequencySeconds"

"isConnected"

"statusCode"

"statusMessage"

brokerHostname

The "brokerHostname" property is required. It must not be a zero-length string or contain only whitespace.  It has a maximum length of 255 characters.

When these rules are violated the following errors will be displayed:
  • When creating a new broker connection, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because brokerHostname is empty."
  • When updating an existing broker connection, FairCom's servers log an error stating, "Cannot update the broker connection named xxx because the new "brokerHostname" is empty. The current brokerHostname xxx and brokerPort xxx remain unchanged."
string the unique broker host name or TCP/IP address of the specified broker connection.

brokerPort

The "brokerPort" property is optional. It defines the TCP/IP port. If it is not present, it defaults to 1883.

  • If present, it must be a number between 1 and 65535 inclusive.
  • If the port is already in use, FairCom's server will not be able to run.
  • When it is set to a non-numeric value, or is out of range, FairCom's servers log an error stating, “Cannot create the broker connection named xxx because the brokerPort property is missing or is set to an invalid value. It must be present and set to a number greater than zero and less than 65536.”
integer the TCP/IP port of the specified broker connection.

brokerUserName

The "brokerUsername" property is the login name to the external broker. This property is an optional string from 1 to 64 bytes. If omitted, it defaults to an empty string.

Note Unlike some other properties containing the "name", the "name" in "brokerUsername" is all lowercase.

  • A zero-length username is invalid.
  • It is VARCHAR(500).
 string the login name to the external broker.

caCertificateFilename

The "caCertificateFilename" property is an optional string that specifies the name and optional path of the CA certificate file (such as "ca.pem"). It defaults to an empty string.

  • You must include "caCertificateFilename" to allow clients to use X509 certificates to authenticate with the server.
  • The certificate authorities file contains the list of certificate authorities the server uses to validate X509 certificates that clients present as authentication credentials.
  • In order for an X509 certificate to be accepted by the server, the certificate must be signed by a certificate authority that is present in the certificate authorities certificate file.
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
 string No limits

certificateFilename

The "certificateFilename" property is an optional string that specifies the name and optional path of a server certificate file.

    "tls": {
      "allowedCipherSuites": "",
      "certificateAuthoritiesFilename": "",
      "certificateFilename": "",
      "privateKeyFilename": ""
    },
 string No limits

changedLabels

The "changedLabels" property lists an object for each label that has been updated with new values. Each object contains the "id", "group", "name", "value", "enum", "sequence", "deprecated", "description", and "metadata" properties and their new values for the label that was updated.

    "changedLabels": [
      {
        "id": 4,
        "group": "myLabelGroupName",
        "name": "myLabelName",
        "value": 99,
        "enum": 0,
        "sequence": 1.2,
        "deprecated": false,
        "description": "My label description.",
        "metadata": {}
      }
    ]
 array of objects An object for each changed label.

changeIdField

This property's value designates the name of the field used for change-tracking functionality if you are not using the "changeId" field for change tracking.

"createTable" automatically creates the "changeId" field to hold the change tracking number used for optimistic locking. Using the "changeId" field for optimistic locking is a best practice.

However, if you use the name "changeId" for another purpose, you can use the "changeIdField" property to designate a different field as the change tracking number field.

 

Request example

"params": {
  "changeIdField": "changetrackingid"
  }
 string 1 to 64 bytes

clientCertificateEnabled

 The "clientCertificateEnabled" property is an optional boolean that enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates. boolean

true

false

clientCertificateFilename

The "clientCertificateFilename" property is an optional string that specifies the name of the client certificate file. It defaults to an empty string.

 string The file name of a client certificate.

clientPrivateKeyFilename

The "clientPrivateKeyFilename" property is an optional string that specifies the name of the client private key file. It defaults to an empty string.

 string The file name of a client certificate private key file.

clientName

 uniquely identifies an MQ session. string  

clonedCodeId

The "clonedCodeId" indicates which copy the specified code package is out of all existing code package clones. If the specified code package is the original one, its value will be 0.

  "result": {
    "data": [
      {
        "codeId": 1,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 1,
        "clonedCodeId": 0
    ]
  },
 integer The cloned code ID.

codeServices

The "codeServices" property is an optional array of objects that specifies which programming languages are available in the product.

 array of objects

"serviceName"

"serviceLibrary"

"enabled"

codeVersion

The "codeVersion" property indicates the version of the specified code package.

  "result": {
    "data": [
      {
        "codeId": 1,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 1,
        "clonedCodeId": 0
    ]
  },
 integer The version of the specified code package.

collectStats

 identifies whether usage statistics are being collected and stored. boolean

true

false

compression

 identifies whether the index is compressed. string

"on"

"off"

"auto"

conditionalExpression

 identifies an optional conditional expression that filters which records are included in the index. It is null when there is no conditional expression. string

null

or a string containing a conditional expression.

connectionStatus

The "connectionStatus" property is returned by the "describeMqSessions" action to indicate if and how a client is connected to an MQ session. It has the following values:

  • "disconnected" indicates no device or software is connected to the MQ session.
  • "connected" indicates a device or software has established a permanent connection to the MQ session.
  • "connectedTemporarily" indicates a device or software has established a temporary connection to the MQ session. When the device or software disconnects, the server removes the data associated with the MQ session.
 string

"disconnected"

"connected"

"connectedTemporarily"

connectorName

In the Tag actions, the "connectorName" property is a string that identifies the connector in the "tagProvenance" objects returned from the "alterTag" and "describeTags" actions when the "includeTagProvenance" property is true. 

  • Its length is from 1 to 64 bytes.
  • For the tag's provenance to include a connector, one of the "createInput", "alterInput", "createOutput", "alterOutput" actions must assign the "tagName" or "tagId" property to the connector.

"tagProvenance" example in the response to "describeTags" or "alterTag"

   "tagProvenance": [
     {
       "provenanceAction": "collect",
       "connectorName": "INPUT: PLC 74 & Modbus",
       "connectorId": 51,
       "targetRecordPath": "source_payload.tmp",
       "description": "Collect provenance steps come from input connectors."
     },
     {
       "provenanceAction": "deliver",
       "connectorName": "OUTPUT: MES & REST",
       "connectorId": 53,
       "sourceRecordPath": "source_payload.temperature",
       "description": "Deliver provenance steps come from output connectors."
     }
   ]
 string 1 to 64 bytes

connectorId

The "connectorId" property is an integer that identifies the connector in the "tagProvenance" objects returned from the "alterTag" and "describeTags" actions when the "includeTagProvenance" property is true. 

  • It is an integer from 0 to 9223372036854770000.
  • For the tag's provenance to include a connector, one of the "createInput", "alterInput", "createOutput", "alterOutput" actions must assign the "tagName" or "tagId" property to the connector.


"tagProvenance" example in the response to "describeTags" or "alterTag"

   "tagProvenance": [
     {
       "provenanceAction": "collect",
       "connectorName": "INPUT: PLC 74 & Modbus",
       "connectorId": 51,
       "targetRecordPath": "source_payload.tmp",
       "description": "Collect provenance steps come from input connectors."
     },
     {
       "provenanceAction": "deliver",
       "connectorName": "OUTPUT: MES & REST",
       "connectorId": 53,
       "sourceRecordPath": "source_payload.temperature",
       "description": "Deliver provenance steps come from output connectors."
     }
   ]
 integer 0 to 9223372036854770000

createdBy

The "createdBy" property indicates the name of the account used to create the specified code package.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 string The name of the account used to create the code package.

createdOn

The "createdOn" property indicates the date and time the code package was created.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 timestamp The date and time when the code package was created.

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

creationTime

 The "creationTime" property details the date and time when the specified topic was created. This property stores the creation date in an ISO 8601 timestamp. timestamp An ISO 8601 timestamp

cursorid

The "cursorId" property is a required string from 0 to 255 bytes. It is a unique identifier returned by the server.

  • The "getRecordsFromCursor" action uses it to quickly and efficiently retrieve paginated records.
  • Setting a zero-length "cursorId" in the request is invalid.
  • It is not returned when "returnCursor" is false.

Important Do not assume the "cursorId" is a number embedded in a string.

 string 0 to 255 bytes

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

databaseConnectionString

 The "databaseConnectionString" property specifies the connection string for the database that holds the persistence table. string No limits

databaseName

The "databaseName" property is an optional string that specifies the database that contains the tables. It defaults to the database name supplied at login.

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

  • A zero-length "databaseName" is invalid.
  • Its length limit is from 0 to 64 bytes.
  • 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. 
"params": {
  "databaseName": "mainDatabase"
  }
 string 1 to 64 bytes

databaseUserName

 The "databaseUserName" property specifies the user name of the account logged into the database that holds the persistence table. string 0 to 64 bytes

dataChangeStreamFirstStartTimestamp

The "dataChangeStreamFirstStartTimestamp" property specifies the UTC date and time in ISO-8601 format when the stream first started.

 

 string timestamp "2025-06-07T12:23:19.275"

dataChangeStreamLastPausedTimestamp

The "dataChangeStreamLastPausedTimestamp" property specifies the UTC date and time in ISO-8601 format when the stream last paused.

 

 string timestamp "2025-06-07T12:23:19.275"

dataChangeStreamLastStartTimestamp

The "dataChangeStreamLastStartTimestamp" property specifies the UTC date and time in ISO-8601 format when the stream last restarted.

 

 string timestamp "2025-06-07T12:23:19.275"

dataChangeStreams

 lists the data change streams that match the filters in the request as separate objects. array of objects

0 or more objects including 1 or more of the following properties: 
"dataChangeStreamStatus"

"description"

"id"

dataChangeStreamStatus

 The "dataChangeStreamStatus" property specifies the status of the data change stream. It may specify any of the following states: string enum

"failed"

"initializing"

"jumpstarting"

"paused"

"pausing"

"running"

"scheduled"

dataFormat

The "dataFormat" property is a case-insensitive string enum that defines the format of the "data" property. The default format is an array of arrays. The alternative is an array of objects. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
    • Possible values include:
      • "arrays"
        • This causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
      • "autoDetect"
        • This is the default, and the server automatically detects the format of the data in the "sourceData" property.
  • "dataFormat" in the response shows the client how the server formatted the "data" property.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
 string

"autoDetect"

"arrays"

"objects"

defaultApi

The "defaultApi" property specifies the default value of the "api" property when it is omitted from an action request. The default value for "defaultApi" is "admin", which is the API used by all session actions.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

The "binaryFormat" property designates the formatof binary values embedded in JSON strings. The default value for "binaryFormat" is the "defaultBinaryFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultBinaryFormat" property in the <faircom>/config/services.json file. If it is not there, the FairCom server defaults it to "hex". Prior to version 13.0.4, the server defaulted it to "base64".

Note Typically, response options apply only to the server’s response, but the "binaryFormat" property applies to both the request and the response.

  • The "binaryFormat" property may occur inside "params",  "responseOptions", "defaultResponseOptions", "result", and "mapOfPropertiesToFields".
    • It occurs in "params" when actions create or change values.
    • It occurs in "responseOptions" when actions return values.
  • When "binaryFormat" occurs in "params" it specifies how the sender represents binary values.
    • For example, when "binaryFormat" is set to "hex", the FairCom server expects the binary values of fields and keys to be represented in strings with hexadecimal format.
  • When "binaryFormat" occurs in "responseOptions" or "defaultResponseOptions" it specifies how the FairCom server should represent binary values in responses.
    • For example, when "binaryFormat" is set to "hex", the FairCom server represents binary values in strings with hexadecimal format.
  • When "binaryFormat" occurs in "result", it signifies how binary values are represented.
    • For example, when "binaryFormat" is set to "base64", the FairCom server represents binary values in the response in base64 format.
  • When "binaryFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode the binary value in a  JSON property.
    • For example, including "binaryFormat" in a "tableFieldsToJson" transform step controls how the server takes a raw binary field value and encodes it as a JSON property.
    • For example, including "binaryFormat" in a "jsonToTableFields" or "jsonToDifferentTableFields"  transform step controls how the server decodes a binary value in a JSON property so it can store the raw binary value in a field.
  • The following are the possible values for each format.
    • "base64"
      • When the server reads and writes from a binary field, it represents the binary value as a base64 string.
      • Base64 is harder for people to read and convert to binary.
      • Base64 creates the smallest payload for the most efficient data transmission in JSON.
      • "base64" strings contain the characters 0 - 9 , A - Z, a - z, +, /, and =.
    • "hex"
      • When the server reads and writes from a binary field, it represents the binary value as a hexadecimal string.
      • Hexadecimal is easier for people to read and convert to binary.
      • Hexadecimal creates a 30% larger payload than "base64", which makes it less efficient for data transmission.
      • Hexadecimal strings contain the characters 0 - 9 and A - F.
    • "byteArray"
      • When the server reads and writes from a binary field, it represents the binary value as an array of bytes.
      • An array of bytes is easiest for a program to manipulate.
      • An array of bytes creates a larger payload than "base64" and "hex", which makes it less efficient for data transmission.
      • An array of bytes returns a JSON array containing one integer number between 0 and 255 for each byte in the binary value:
        • "aBinaryField": [ 255, 0, 255 ]

 

Example requests

 

Create a "binary_test" table

This example creates a table containing one binary field named "bin" with a fixed length of 5 bytes.

{
  "api": "db",
  "action": "createTable",
  "params": {
    "tableName": "binary_test",
    "fields": [
      {
        "name": "bin",
        "type": "binary",
        "length": 5
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using an array of bytes format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as an array of bytes.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "sourceData": [
      {
        "bin": [49,50,51]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using hexadecimal format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in hexadecimal format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "hex",
    "sourceData": [
      {
        "bin": "313233"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Insert a record into the "binary_test" table using base64 format

This example inserts a record with the ASCII characters "123" in the "bin" field. The value of "bin" is represented as a string in base64 format.

{
  "api": "db",
  "action": "insertRecords",
  "params": {
    "tableName": "binary_test",
    "dataFormat": "objects",
    "binaryFormat": "base64",
    "sourceData": [
      {
        "bin": "MTIz"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Retrieve a record with "binaryFormat" as an array of bytes

This example requests the first record in the "binary_test" table with the value of "bin" represented as an array of bytes.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "byteArray",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

Responses

Note Our examples insert only 3 bytes into "bin". Because the "bin" field has a fixed length of 5 bytes, the server pads unused bytes with 0x00 and stores the result. When a record is retrieved, the server returns all 5 bytes.

{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": [49,50,51,0,0],
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Retrieve a record with "binaryFormat" as hexadecimal

This example requests the first record in the "binary_test" table with the value of "bin" represented as a hexadecimal string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "3132330000",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Retrieve a record with "binaryFormat" as base64

This example requests the first record in the "binary_test" table with the value of "bin" represented as a base64 string.

{
  "api": "db",
  "action": "getRecordsByTable",
  "params": {
    "tableName": "binary_test",
    "maxRecords": 1
  },
  "responseOptions": {
    "binaryFormat": "base64",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
Response
{
  "result": {
    "dataFormat": "objects",
    "binaryFormat": "byteArray",
    "fields": [
      { "name": "id",       "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": false, "primaryKey": 1 },
      { "name": "changeId", "type": "bigint", "length": null, "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 },
      { "name": "bin",      "type": "binary", "length": 5,    "scale": null, "autoTimestamp": "none", "defaultValue": null, "nullable": true,  "primaryKey": 0 }
    ],
    "data": [
      {
        "bin": "MTIzAAA=",
        "changeId": 50217,
        "id": 1
      }
    ],
    "moreRecords": true,
    "requestedRecordCount": 1,
    "returnedRecordCount": 1,
    "totalRecordCount": 3
  },
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

 

 string One of the following: "base64", "hex", or "byteArray".

defaultDatabaseName

The "defaultDatabaseName" property is an optional string that specifies which database name to use when the "databaseName" property is omitted. Its value is case insensitive.

  "params": {
    "username": "CHANGE",
    "password": "CHANGE",
    "description": "optional user description of session for troubleshooting",
    "defaultApi": "db",
    "defaultDebug": "max",
    "defaultDatabaseName": "ctreeSQL",
    "defaultOwnerName": "admin",
    "defaultBinaryFormat": "hex"
    },
 string 1 to 64 bytes

defaultDebug

The "defaultDebug" property is an optional string that defines the default value of the "debug" property for all requests in a session. It defaults to "max".

Important This is different than the "debug" property in that the "debug" property can be universally used in any action while the "defaultDebug" property is only set in the "createSession" action and sets the "debug" property for any action run using the session being created.

  • Possible values include:
    • "none"
    • "max"
  • If "defaultDebug" is omitted or set to null, it defaults to "max".
    • This causes the server to include the "debugInfo" property in the response.
    • This setting is typically used in development environments and for temporarily troubleshooting issues in production environments.
  • For maximum performance set "defaultDebug" to "none".
    • This causes the server to omit the "debugInfo" property in the response.
    • This setting is typically used in production and staging environments where it is desirable to have maximum performance and minimal network traffic.
 string enum

"none"

"max"

defaultOwnerName

The optional "defaultOwnerName" property is is used by "createSession" and "alterSession" to specify the default owner of objects created by the session. Its value must be a valid username of an account. If it is omitted, null, or "", it defaults to the value of the session's "username" property.

  • See Object owner in the JSON DB Concepts section for an explanation of how to use the "defaultOwnerName" and "ownername" properties to specify the owner of objects.
  • When "ownerName" is omitted the server uses the "defaultOwnerName" property value set during login.
  • In "createSession" and "alterSession" when "defaultOwnerName" is omitted or set to null:
    • In the JSON DB API, the server sets "defaultOwnerName" to the "username" of the logged-in user. Thus, by default, the logged-in account owns the objects it creates.
    • In the JSON Hub API and JSON MQ API, the server sets "defaultOwnerName" to "admin" allowing the server to own the objects it creates.
  • Actions that create objects, such as "createTable" and "createIntegrationTable", can omit the "ownerName" property making the server set "ownerName" to the value of "defaultOwnerName".
  • When an action that creates an object sets the "ownerName" property to a valid account name, the specified account owns the created object and an account that owns an object has full management rights over the object. You can use object ownership as a simple way to control access to objects.
  • When "ownerName" is set to the empty string, then no account owns the object. Unowned objects can be managed by administrator accounts and by accounts assigned to roles that grant access rights to the object making it useful when you want to prevent an account from owning an object and inheriting full management rights to that object.
 string 1 to 64 bytes

defaultValue

 The optional "defaultValue" property identifies the default value of the field. string 0 to 65,500 bytes

defaultVariantFormat

The "defaultVariantFormat" property sets the default value of the "variantFormat" property when a JSON Action request does not include it.

 string

"json"

"binary"

"string"

"variantObject"

defaultResponseOptions

The "defaultResponseOptions" property is a "responseOptions" object. It defines a default value for "responseOptions" that is used by default in all other action calls. It defaults to an empty object.

JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.

The example omits the error object in all responses which makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

 "defaultResponseOptions": {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number",
      "variantFormat": "json"
    }
 object

"binaryFormat"

"dataFormat"

"numberFormat"

defaultRetentionPeriod

The "defaultRetentionPeriod" property specifies how many retention units will be retained if the "retentionPeriod" property is omitted. It is used in tandem with "defaultRetentionUnit", the retention period describing how many units, and the retention unit describing what kind of unit of measurement. For example, if the "defaultRetentionPeriod" is set to 4, and the "defaultRetentionUnit" is set to "week", the server will purge messages once 4 weeks have passed by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },
 integer 1 to 100

defaultRetentionPolicy

The "defaultRetentionPolicy" property specifies the default way in which messages are persisted if the "retentionPolicy" property is omitted. Using this property, you can configure messages to persist indefinitely, be purged according to the retention unit and period, or be immediately purged by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },
 string enum

"doNotPersist"

"neverPurge"

"autoPurge"

defaultRetentionUnit

The "defaultRetentionUnit" property specifies the type of retention unit if the "retentionUnit" property is omitted. It is used in tandem with "defaultRetentionUnit", the retention period describing how many units, and the retention unit describing what kind of unit of measurement. For example, if the "defaultRetentionPeriod" is set to 4, and the "defaultRetentionUnit" is set to "week", the server will purge messages once 4 weeks have passed by default.

  "params": {
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4
  },
 string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

defaultValue

 specifies the default value of a field. string 0 to 65,500 bytes

deferindexing

 identifies whether deferred indexing is enabled. A deferred index builds and updates asynchronously. This speeds up inserts, updates, and deletes, with a slight delay from including the changes in the index. boolean

true

false

deletedLabels

The "deletedLabels" property lists an object for each label that has been deleted. Each object contains the "id", "group", "name", "value", "enum", "sequence", "deprecated", "description", and "metadata" properties and their values for the label that was deleted.

    "deletedLabels": [
      {
        "id": 4,
        "group": "myLabelGroupName",
        "name": "myLabelName",
        "value": 99,
        "enum": 0,
        "sequence": 1.2,
        "deprecated": false,
        "description": "My label description.",
        "metadata": {}
      }
    ]
 array of objects An object for each deleted label. 

deletedTags

 The "deletedTags" property is an array of objects that describe the tags that were deleted. array of objects

zero or more objects containing the following properties:

"id"

"tagName"

deprecated

The "deprecated" property optionally deprecates a label. Set it to true to deprecate a label and false to preserve it. It defaults to false. Deprecating a label is similar to marking a label as deleted.

 Boolean

true

false

null

description

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

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

elapsedMilliseconds

 The "elapsedMilliseconds" property specifies the number of milliseconds it took for the server to execute the SQL statement. integer The number of seconds it took to execute the statement.

enabled

The "enabled" property is an optional Boolean that specifies whether or not the feature is enabled. The example below enables the TLS feature.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
 Boolean

true

false

enablePermanentJsonApiSessions

The "enablePermanentJsonApiSessions" property enables or disables permanent sessions. When set to false, permanent sessions cannot be created.

 Boolean

true

false

endTimestamp

The "endTimestamp" property is an optional string that contains an ISO8601 timestamp, which filters the response to return problems that ended before or on its value. If any parts of the timestamp are missing or omitted, the server defaults the remaining parts to 0.

 

 string containing an ISO8601 timestamp

"2025-08-19"

"2025-08-19T00:00:00.000"

"2025-08-19T01:13"

"2025-08-19T01:13:59"

"2025-08-19T01:13:59.853"

enum

The "enum" property optionally assigns an integer from -32768 to 32767 to a label. By default, this property is set to 0. You can use this property to assign an application's hardcoded enumerated value to a label.

 

 smallint -32768 to 32767

errorCode

 The "errorCode" property indicates an error when set to a non-zero integer or success when 0. integer -2147483648 to 2147483647

errorMessage

 The "errorMessage" property displays a human-readable error message. string 0 to 256 bytes

estimatedBacklogSeconds

The "estimatedBacklogSeconds" property is an integer that reports the approximate time, in seconds, needed by the FairCom MQ server to apply data changes from the source server.

 integer 0 to 4294967296

fields

The "fields" property is an array of objects. It is required when creating a table. Each object in the array defines a field by specifying its properties.

 

"fields": [
  {
    "autoValue": "none",
    "name": "name",
    "type": "varchar",
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false
  }
]
 array

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

fixedOutput

 includes all properties in a data change event when true. Boolean

true

false

group

The "group" property optionally groups labels into a lookup list or tag set. It is an optional namespace for a set of labels that identifies their purpose. You can use the "listLabelGroups" action to return the list groups. You can use the "listLabels" action to return labels in one or more groups. 

The "group" and "name" properties work together to uniquely identify each label. They are its natural key. A group assigned to the empty string "" is the default group.

The group name may contain up to 64 bytes of UTF-8 encoded characters.

If the "group" property is omitted when creating a label, the group defaults to the empty string, "", which is the catch-all group.

When you assign a group name to a label, the server automatically checks if the group name exists in the list of groups that the "listLabelGroups" action returns. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.

Tip If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name. In the "listLabels" action, you can use the "partialGroupFilter" filter to return subsets of groups in the hierarchy. For example, you if have groups named "product/size/", "product/weight/", "product/ranking/", "person/gender/", and "person/ranking/", you can set the "partialGroupFilter" to "product/" to return the product groups.

 

 string 1 to 64 bytes

hierarchyDelimiter

The optional "hierarchyDelimiter" property is a string that delimits hierarchical levels in the key. It defaults to the empty string "", which defines no hierarchy. It may contain zero or more UTF-8 characters, such "/" or "||".

 

The "describeValues" action uses this string to calculate the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the delimiter. If the "hierarchyDelimiter" property is "" or the action cannot find the delimiter string, it sets the "keyWithoutHierarchy" property to the whole key because the key does not contain a hierarchy.


Examples

  • Given the key, "myKey" and a hierarchy delimiter of "", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myKey" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myApp/queries/" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp||queries||" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp/queries/My Favorite" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "My Favorite".
  • Given the key, "myApp||queries||My Favorite" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "My Favorite".
     
 string 1 byte

host

 The "host" property specifies the IP or hostname of the Rest resource, including the port. string 1 to 1024 bytes

hostIpAddresses

The "hostIpAddresses" property specifies the IP addresses of the sessions host.

    "sessions": [
      {
        "hostname": "host's name",
        "hostUuid": "561d3f41-37da-4d03-bcc2-9cf2b671119f",
        "hostIpAddresses": [
          "fe80::7b21:ec4f:fbb0:7d45",
          "169.254.188.125",
          "fe80::62c9:6f17:6132:d13f",
          "169.254.150.200",
          "fe80::6e3f:653a:ac7b:3074",
          "169.254.169.237",
          "fe80::c98f:a8f0:25c5:91e4",
          "10.250.250.201",
          "fe80::48d2:30ab:3798:6a6d",
          "169.254.35.210"
        ],
        "hostServerNamePort": "FAIRCOMS",
        "hostSQLPort": 6597
      }
    ]
 array of strings The host's IP addresses

hostname

The "hostname" property specifies the name of the host device.

    "sessions": [
      {
        "hostname": "host's name",
        "hostUuid": "561d3f41-37da-4d03-bcc2-9cf2b671119f",
        "hostIpAddresses": [
          "fe80::7b21:ec4f:fbb0:7d45",
          "169.254.188.125",
          "fe80::62c9:6f17:6132:d13f",
          "169.254.150.200",
          "fe80::6e3f:653a:ac7b:3074",
          "169.254.169.237",
          "fe80::c98f:a8f0:25c5:91e4",
          "10.250.250.201",
          "fe80::48d2:30ab:3798:6a6d",
          "169.254.35.210"
        ],
        "hostServerNamePort": "FAIRCOMS",
        "hostSQLPort": 6597
      }
    ]
 string The name of the host device.

hostnames

The optional "hostnames" property is an array of strings that specifies zero or more hostnames assigned to the device. It defaults to the empty array []. Each item in the array should be a different hostname. Each hostname is a string from 1 to 64 bytes. NOTE: The API allows the same hostname to be assigned to many things.

 

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

 

The Thing API implements the "hostnames" property using the Label API. 

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

hostServerNamePort

The "hostServerNamePort" property specifies the server's ISAM port or server name.

    "sessions": [
      {
        "hostname": "host's name",
        "hostUuid": "561d3f41-37da-4d03-bcc2-9cf2b671119f",
        "hostIpAddresses": [
          "fe80::7b21:ec4f:fbb0:7d45",
          "169.254.188.125",
          "fe80::62c9:6f17:6132:d13f",
          "169.254.150.200",
          "fe80::6e3f:653a:ac7b:3074",
          "169.254.169.237",
          "fe80::c98f:a8f0:25c5:91e4",
          "10.250.250.201",
          "fe80::48d2:30ab:3798:6a6d",
          "169.254.35.210"
        ],
        "hostServerNamePort": "FAIRCOMS",
        "hostSQLPort": 6597
      }
    ]
 string The name of the server or ISAM port.

hostSQLPort

The "hostSQLPort" property contains the server's SQL port.

    "sessions": [
      {
        "hostname": "host's name",
        "hostUuid": "561d3f41-37da-4d03-bcc2-9cf2b671119f",
        "hostIpAddresses": [
          "fe80::7b21:ec4f:fbb0:7d45",
          "169.254.188.125",
          "fe80::62c9:6f17:6132:d13f",
          "169.254.150.200",
          "fe80::6e3f:653a:ac7b:3074",
          "169.254.169.237",
          "fe80::c98f:a8f0:25c5:91e4",
          "10.250.250.201",
          "fe80::48d2:30ab:3798:6a6d",
          "169.254.35.210"
        ],
        "hostServerNamePort": "FAIRCOMS",
        "hostSQLPort": 6597
      }
    ]
 string The name of the server's SQL port.

hostUuid

The "hostUuid" property specifies the universal identifier of the server instance.

    "sessions": [
      {
        "hostname": "host's name",
        "hostUuid": "561d3f41-37da-4d03-bcc2-9cf2b671119f",
        "hostIpAddresses": [
          "fe80::7b21:ec4f:fbb0:7d45",
          "169.254.188.125",
          "fe80::62c9:6f17:6132:d13f",
          "169.254.150.200",
          "fe80::6e3f:653a:ac7b:3074",
          "169.254.169.237",
          "fe80::c98f:a8f0:25c5:91e4",
          "10.250.250.201",
          "fe80::48d2:30ab:3798:6a6d",
          "169.254.35.210"
        ],
        "hostServerNamePort": "FAIRCOMS",
        "hostSQLPort": 6597
      }
    ]
 string A UUID

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 

idleConnectionTimeoutSeconds

The "idleConnectionTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

 integer 0 to 2147483647

idleCursorTimeoutSeconds

The "idleCursorTimeoutSeconds" property is an optional integer from 0 to 2147483647. It is the number of seconds to keep a cursor open.

  • Each time a cursor retrieves records, the cursor timer restarts.
  • A value of -1 keeps a cursor open indefinitely.
  • A value of 0 immediately closes a cursor after the current operation.
 integer 0 to 2147483647

ids

The "ids" property is an array. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. Its default value is "null" but it is required if the "primaryKeys" property is "null" or not specified.

  • The "ids" property is mutually exclusive with the "primaryKeys" property meaning it is required when "primaryKeys" is omitted or an error is returned if both have values.
  • It is typically an array of integers ("ids": [1,3,5]).
  • It can be an array of an array of strings ("ids": ["9555444333222111","9555444333222112", "9555444333222113"]).
    • A string "id" supports numbers larger than 9,007,199,254,740,991.
    • This is the largest number supported by many programming languages and JSON parser implementations that use IEEE double-precision floats to hold numbers.
  • It can be the primary key value of another field in the table making it useful when your table is created by another API, such as SQL, that allows any field in the table to be the primary key.
    • If your table does not have an "id" field but uses a "vin" field as the primary key, you can use vin values to look up records ("ids": [ "4Y1SL65848Z411439", "1HGBH41JXMN109186" ]).
  • If your table uses more than one field as the primary key, you must use the "primaryKeys" property to look up records.

Tip The "getRecordsByIds" action uses a primary key index to look up records. A primary key index must be a unique, non-null index without conditional filtering. For best performance and maximum simplicity, create tables using the JSON DB API because it automatically creates an auto increment "id" field that is indexed as a primary key.

 array 0 or more ids

immutableKeys

 identifies whether the key's values can be changed. boolean

true

false

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

includedFields

The "includedFields" property is an array of strings that includes specified source table fields in the data change event or all fields when empty.

 array of strings 0 or more strings

includeExistingRecordsFilter

The "includeExistingRecordsFilter" property is a Boolean that returns streams that synchronize existing records if true.

 Boolean

true

false

includeMetadata

The "includeMetadata" property is an array of metadata objects that adds user-defined properties to each data change event.

 array of metadata objects 
[
  {
    "propertyPath": "myPath",
    "propertyValue": "myValue"
  }
]

includePrimaryKey

The "includePrimaryKey" property is an enumerated string that specifies when to add the "pk" property to the data change event's "fields" object to indicate the field's position in the primary key.

 string

"forEachField"

"forPrimaryKeyFields"

"never"

indexes

 is an array of objects where each object identifies the characteristics of each index in the table. array

"collectStats"

"compression"

"conditionalExpression"

"deferindexing"

"fields"

"immutableKeys"

inputConnectors

The "inputConnectors" property occurs in the response to Tag API actions when the "includeInputConnectorProperties" property is in the request. It is an array of objects that 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"

inputName

 The "inputName" property is a required string that specifies the unique name of an input. string 1 to 64 bytes

integrationServices

The "integrationServices" property is an array of objects that describes and controls FairCom's integration services. It defaults to an empty array.

  • An integration service is a connector that uses a protocol to collect information from devices and/or deliver information to devices — for example, FairCom Edge includes connectors that collect data from Modbus and OPC UA.
  • For information on how to build and add your own connectors using C or C++, contact FairCom.
  • Do not change the settings of the object properties unless disabling an unused connector.
 array of objects

"enabled"

"schemaName"

"serviceLibrary"

"serviceName"

isConnected

 The "isConnected" property indicates whether the specified broker connection is active. Boolean

true

false

jsonActionApiDefaults

The default settings for the FairCom jsonAction APIs and browser-based applications are specified in the services.json file in the "jsonActionApiDefaults" property.

Note Use the Google Chrome browser for FairCom browser-based tools. Other browsers may cause unexpected behavior.

 

Default settings for jsonAction APIs

"jsonActionApiDefaults": {
    "defaultApi": "db",
    "defaultBinaryFormat": "hex",
    "defaultVariantFormat": "json",
    "defaultDatabaseName": "faircom",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions": 
    {
      "binaryFormat": "hex",
      "variantFormat": "json",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy":"autoPurge",
    "defaultRetentionPeriod":"4",
    "defaultRetentionUnit":"week"
  }

 

The property names and values in "jsonActionApiDefaults" are identical to those in the "params" property of "createSession", "alterSession", and "describeSessions". Each FairCom product ships with different default settings that make sense for that product — for example, in FairCom DB, the "defaultAPI" property is set to "db", in FairCom MQ it is set to "mq", and in FairCom Edge it is set to "hub".

You can change the values of the properties in services.json, and all jsonAction APIs and browser-based user interfaces will use these properties as their default. If any of the properties in "jsonActionApiDefaults" are omitted from services.json, the property values may vary depending on the JSON action performed.

Note FairCom's core configuration file, ctsrvr.cfg, contains a SQL_DATABASE setting. You can set SQL_DATABASE to the name of a database and when the FairCom server starts, it creates a database with that name if it does not already exist. 

By default, ctsrvr.cfg sets SQL_DATABASE to "ctreeSQL". If you change SQL_DATABASE to use another database name, it is a good practice to put the same name in the "defaultDatabaseName" property in services.json. This makes your newly created database the default database in all of FairCom's jsonActionAPIs and browser-based applications.

 

Keeping SQL_DATABASE and "jsonActionApiDefaults" in sync

ctsrvr.cfg 

SQL_DATABASE my_new_database

services.json 

"": {
    "defaultApi": "db",
    "defaultBinaryFormat": "hex",
    "defaultDatabaseName": "my_new_database",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions": 
    {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy":"autoPurge",
    "defaultRetentionPeriod":"4",
    "defaultRetentionUnit":"week"
  }
 object

"defaultApi"

"defaultBinaryFormat"

"defaultDatabaseName"

"defaultDebug"

"defaultOwnerName"

"defaultResponseOptions"

"defaultRetentionPeriod"

"defaultRetentionPolicy"

"defaultRetentionUnit"

"defaultVariantFormat"

"enablePermanentJsonApiSessions"

"idleConnectionTimeoutSeconds"

"idleCursorTimeoutSeconds"

"maxJsonApiSessions"

"maxJsonApiSessionsPerIpAddress"

"maxJsonApiSessionsPerUsername"

key

The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value.

In the Key-Value API, this property is required.

 string 1 to 128 bytes

keys

 The required "keys" property contains an array of keys for an action to work on and return, such as [ "key1", "key2" ]. array of strings one or more key strings

keyStore

The required "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role.  An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 string enum

"global"

"role"

"user"

keyValuePairDetails

The "keyValuePairDetails" property contains an array of objects. Each object represents a key-value pair and contains extended information about a key and its value, including the "key", "value", "keyWithoutHierarchy", "username", "createdTimestamp", and "updatedTimestamp" properties.
 

{
  "key": "myKey",
  "value": {"my": "value"},
  "keyWithoutHierarchy": "myKey",
  "username": "some_user", 
  "createdTimestamp": "2025-09-04T15:35:21.014",
  "updatedTimestamp": "2025-09-04T15:35:21.014"
}
array of objects 
[
  { 
    "key": "k1",
    "value": 1,
    "keyWithoutHierarchy": "myKey",
    "username": "some_user",
    "createdTimestamp": "2025-09-04T15:35:21.014",
    "updatedTimestamp": "2025-09-04T15:35:21.014" 
  }
]

keyValuePairs

 The "keyValuePairs" property contains an array of objects. Each object represents a key-value pair and contains "key" and "value" properties, such as { "key": "k1",  "value": 1 }. array of key-value objects 
[
  { 
    "key": "myKey", 
    "value": 1
  }
]

keyWithoutHierarchy

The "keyWithoutHierarchy" property contains the leaf part of a hierarchical key, which is the last part of a key following the hierarchical delimiter. For example, given the key "myApp/queries/My Favorite" and a / delimiter, the leaf part of the key is "My Favorite".


The "describeValuesFromHierarchy" action populates the "keyWithoutHierarchy" property with the part of the key following the value of the "partialKey" property.


The "describeValues" action populates the "keyWithoutHierarchy" property with the part of the key following the "hierarchyDelimiter" property.


How to use "keyWithoutHierarchy"


The "keyWithoutHierarchy" property is useful when an application lets users save items with user-defined names. An application defines the base part of a hierarchical key and the user defines the rest. For example, an application defines a base key of "myApp/queries/" and the user specifies a name, such as "My Favorite". The complete key is "myApp/queries/My Favorite". The "keyWithoutHierarchy" property contains the user-defined name, such as "My Favorite".


An application can use the "describeValuesFromHierarchy" action to return user-defined items that match a base key. Each match contains a "keyWithoutHierarchy" property, which is the user-defined name of an item. 

 string 1 to 128 bytes

labels

The "labels" property is a required array of label objects. 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.
 array of objects

1 or more label objects

 

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

lastCollectedTimestamp

The "lastCollectedTimestamp" property is a dynamically calculated property that is optionally returned in the "inputConnectors" list from the "describeTags", and "alterTag" actions.

 

It returns the ISO 8601 date and time of the last data collected by the input connector. If no data has been collected, the value is null. The following string is an example of an ISO 8601 timestamp: "2025-08-28T10:47:13.041".

 ISO 8601 timestamp The ISO 8601 date and time of the last data collected by the input connector.

lastDeliveredTimestamp

The "lastDeliveredTimestamp" property is a dynamically calculated property that is optionally returned in the "outputConnectors" list from the "describeTags", and "alterTag" actions.

 

It returns the ISO 8601 date and time of the last data delivered by the output connector. If no data has been delivered, the value is null. The following string is an example of an ISO 8601 timestamp: "2025-08-28T10:47:13.041".

 ISO 8601 timestamp The ISO 8601 date and time of the last data delivered by the output connector.

length

 Identifies the length of the field. integer 1 to 65500 

listeners

The "listeners" property is an array of objects that describes and controls FairCom's listeners. It defaults to an empty array.

  • A listener is a service that listens on a specified TCP/IP port for a specified protocol.
  • FairCom servers provide listeners for the protocols:
    • "http"
    • "https"
    • "mqtt"
    • "mqtts"
    • "mqttws"
    • "mqttwss"
  • Each protocol is hardwired to a specific set of backend services:
    • The HTTP and HTTPS protocols are hardwired to support the jsonAction APIs and web applications. 
    • The MQTT and MQTTS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over TCP/IP.
    • The MQTTWS and MQTTWSS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over WebSocket.
  • For information on how to build and add your own listeners using C or C++, contact FairCom.
  • Do not change the object property settings unless disabling an unused listener.
  • Each protocol can listen with TLS authentication for secure communications.
 array of objects

"enabled"

"description"

"port"

"protocol"

"serviceLibrary"

"serviceName"

"tls"

localDatabaseName

The "localDatabaseName" property is a string that specifies the database name of the table on the FairCom MQ server that stores the stream's data change events.

 string 1 to 64 bytes

localDataFilePath

The "localDataFilePath" property is a string that specifies the data file path of the table on the FairCom MQ server that stores the stream's data change events. It can be a full path or a relative path from the server's data directory.

 string No limits

localOwnerName

The "localOwnerName" property is a string that specifies the account that owns the table on the FairCom MQ server that stores the stream's data change events.

 string 1 to 64 bytes

localTableName

The "localTableName" is a string that specifies the name of the table on the FairCom MQ server that stores the stream's data change events.

 string 1 to 64 bytes

location

The optional "location" property specifies the item's location. A thing may have one location. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

This API uses the Label API to manage manufacturers.

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

logLevel

 Defines what types of messages the replication agent will log.  string enum

"off" - no messages logged

"debug" - logs debug, info, warning, and error messages

"info" - logs info, warning, and error messages

"warning" - logs warning and error messages

"error" - logs error messages

manufacturer

The optional "manufacturer" property specifies the manufacturer of the thing. A thing may have one manufacturer. Many things can share the same manufacturer. It defaults to "unknown" and is a string from 1 to 64 bytes. You can use it to do exact lookups and filtering.

 

This API uses the Label API to manage manufacturers.

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

maxConnectionsPerIpAddress

The "maxConnectionsPerIpAddress" property is the number of TCP/IP connections the app server will accept from a single TCP/IP address.

This feature is implemented at the FairCom App Server level to prevent the app server from being overwhelmed by a DoS attack. It protects against simultaneous DoS attacks across multiple protocols: HTTP, HTTPS, MQTT, MQTTS, WS, and WSS.

The default is 25 connections.

A value of 0 disables this protection.

This property can be added to the top level of the services.json file and/or to each listener object in the "listeners" array. At the top level, the property applies to all listeners. Within a listener, it applies only to that listener.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

 

{
  "maxConnectionsPerIpAddress": 5,
    "listeners": [
    {
      "serviceName": "https8443",
      "description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
      "port": 8443,
      "protocol": "https",
      "enabled": true,
      "maxConnectionsPerIpAddress": 5,
      "tls": {
        "certificateFilename": "./web/fccert.pem"
      }
    }
  ]
}
 integer 1 to 2147483647

maxDeliveryRatePerSecond

The "maxDeliveryRatePerSecond" property sets the throttle rate for current and new subscribers of the topic. This property is optional. If omitted, it defaults to 0, which means no throttling is applied.

  • It must be a value between 0 and 2,147,483,647, but a more realistic range is between 0 and 1,000. It is useful to keep a client from being overwhelmed with too many messages sent too quickly.
  • You can set it to a number greater than 0 to throttle the delivery rate. This allows you to avoid saturating the network and other resources.
    • For example, you can set it to 100 to throttle the delivery to 100 messages per second. This is a maximum setting because the actual message delivery rate is bounded by the network, local resources, the hardware running FairCom's servers, and a client’s ability to process messages quickly.
 integer 0 to 2147483647

maxJsonApiSessions

The "maxJsonApiSessions" property is the total number of JSON API sessions the app server will accept. This setting ensures the server does not consume so many resources that it becomes unstable.

The default value is the maximum number of JSON API connections allowed by the license.

A value of 0 disables this protection and allows JSON API sessions up to the maximum number of connections allowed by the license file.

This property is added to the "jsonActionApiDefaults" object.

 integer 1 to 2147483647

maxJsonApiSessionsPerIpAddress

The "maxJsonApiSessionsPerIpAddress" property is the number of JSON API sessions the app server will accept from the same client IP Address.

The default value is 50.

The maximum possible number of connections is determined by the license file.

A value of 0 disables this protection and allows JSON API sessions with the same IP Address up to the maximum number of connections allowed by the license file.

This property is added to the "jsonActionApiDefaults" object.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

 integer 1 to 2147483647

maxJsonApiSessionsPerUsername

The "maxJsonApiSessionsPerUsername" property is the number of JSON API sessions the app server will accept with the same username. Because of this, an application may use a different account for each JSON API session.

The default value is 50.

The maximum possible number of connections is determined by the license file.

A value of 0 disables this protection and allows unlimited sessions with the same username up to the maximum number of connections allowed by the license file.

If your application uses one account for all JSON API sessions, this feature will need to be disabled.

This property is added to the "jsonActionApiDefaults" object. See the example below.

 

"jsonActionApiDefaults":
{
  "maxJsonApiSessions": 500,
  "maxJsonApiSessionsPerIpAddress": 20,
  "maxJsonApiSessionsPerUsername": 20,
    "defaultApi": "hub",
  "defaultBinaryFormat": "hex",
  "defaultDatabaseName": "faircom",
  "defaultDebug": "max",
  "defaultOwnerName": "admin",
  "defaultResponseOptions":
  {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "idleConnectionTimeoutSeconds": 3600,
  "idleCursorTimeoutSeconds": 600,
  "defaultRetentionPolicy": "autoPurge",
  "defaultRetentionUnit": "week",
  "defaultRetentionPeriod": 4
}
 integer 1 to 2147483647

maxSecondsBeforeConnectingToNextServer

 The "maxSecondsBeforeConnectingToNextServer" property is an optional integer that specifies the maximum number of seconds the server will attempt to reconnect to the existing server before it attempts to connect to the next server in the "sourceServers" list. int32 1 to 65535

messageCount

 The "messageCount" property defines the total number of messages published by the topic. BigInteger 0 to 9223372036854775807

metadata

The "metadata" field optionally allows a customer to add a JSON value to an object such as a label or thing. It is typically a JSON object, but may be any JSON value. It defaults to null. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

model

The optional "model" property specifies a thing's model. A thing may have one model. Many things can share the same model number. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

This API uses the Label API to manage models.

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

mqttPayloadType

The "mqttPayloadType" property is an optional string that specifies the expected data type of the MQTT payload. When omitted or set to null, it defaults to "binary". 

It defines the expected data type of message payloads sent to a topic. It controls how the MQTT broker stores and validates the MQTT payload. 

It also determines how the payload is delivered to JavaScript transform steps. For example, if "mqttPayloadType" is set to "json", an MQTT message containing a JSON payload is delivered to transform steps as a JavaScript object; otherwise, it is delivered as a variant object.

This property is useful because the FairCom server allows you to configure each topic to receive a specific type of data in MQTT payloads. Different topics may expect different types of payloads. For example, one topic may expect to receive JSON and another may expect images. The server can validate the expected type and log errors in the error and log fields, which allows users, applications, and JavaScript transform steps to identify and troubleshoot invalid MQTT messages.

When the server receives an MQTT message, it takes the binary value from the MQTT payload and stores it in the source_payload field. The source_payload field is a variant, which means it stores the value along with its data type. If there are no errors in validating the MQTT payload to match the type specified in "mqttPayloadType", the server assigns the value of "mqttPayloadType" as the variant field's type. 

If "validateMqttPayload" is true, the server validates the MQTT payload to ensure it matches the type specified by "mqttPayloadType". The server may also convert the MQTT payload into another form before storing it. If the MQTT payload does not match the type or cannot be converted, the server stores the payload in the source_payload field, sets its variant type to "binary", and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field. 

  • This property is a hint to the server about the format and type of the MQTT message payload.
  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, setting the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.
  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.
  • The transform engine may use the value of this property to help it transform the source payload.

FairCom's MQTT server does the following when a topic receives an MQTT message and "mqttPayloadType" is set to one of the following values:

  • "binary" - The server stores the MQTT payload in the source_payload field with no validation or conversion and assigns the "binary" type to the source_payload field. It ignores the value of "validateMqttPayload".
  • "json" - The server stores the MQTT payload in the source_payload field.
    • If "validateMqttPayload" is true, it validates the MQTT payload as JSON.
      • If successful, it assigns the "json" type to the source_payload field.
      • If unsuccessful, the server assigns a "binary" type to the source_payload field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.
    • If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "json" type to the source_payload field. 
      • The publisher must send MQTT messages containing valid JSON, or database queries may return errors.
  • "utf8" - The server stores the MQTT payload in the source_payload field.
    • If "validateMqttPayload" is true, it validates the MQTT payload as a UTF-8 string.
      • If successful, it assigns the "string" type to the source_payload field.
      • If unsuccessful, the server assigns a "binary" type to the field and sets the error field to 1 to indicate there is an error. It also adds an error object to the JSON array in the log field.
    • If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "utf8" type to the source_payload field.
      • The publisher must send MQTT messages containing valid UTF-8, or database queries and transform steps may return errors.
  • "variantObject" - The server validates the payload as a variant object.
    • If successful, the server extracts the value from the variant object’s "value" property and assigns it to the value of the source_payload field. It also assigns the variant object’s type to the type of the source_payload field.
    • If unsuccessful, the server writes the MQTT payload to the source_payload field, assigns a "binary" type to the field, and sets the error field to 1, to indicate that it also adds an error object to the JSON array in the log field.
    • The server always validates a “variantObject”, and thus ignores the value of “validateMqttPayload”. 
  • "siemensUdt" - The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the source_payload field. It ignores the value of "validateMqttPayload".
  • "jpeg" - The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the source_payload field. It ignores the value of "validateMqttPayload".
  • "xml" - The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the source_payload field. It ignores the value of "validateMqttPayload".
 string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

name

The "name" property is the name of a label or field. It is a required UTF-8 string that is up to 64 bytes long.

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label so you can rename a label's group and name without breaking "id" references to the label.

 

 string 1 to 64 bytes

newKey

 The "newKey" property is required by the "renameKeys" action to rename keys. It is part of a key-rename object and its value is a string. It specifies the new name of a key. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. string 1 to 128 bytes

newSubscriberDeliveryMode

The "newSubscriberDeliveryMode" property defines how new subscribers receive messages. The default is "newMessages".

  • It may be set to one of two values:
    • "newMessages"
    • "storedMessages"
  • When set to "newMessages" new subscribers only receive new messages.
  • When set to "storedMessages" new subscribers will receive some or all previously sent messages. The "newSubscriberDeliveryMode" property defines the maximum number of messages.
 string enum

"newMessages"

"storedMessages"

newSubscriberMaxDeliveredMessages

The "newSubscriberMaxDeliveredMessages" property is the maximum number of previously stored historical messages a client receives automatically when subscribing to a topic. The default is 0.

  • A value of -1 or "all" defaults to delivering all currently stored messages.
  • A non-negative number limits the delivery of currently stored messages to that number, which may be a maximum of 2,147,483,647 messages.
  • This property only applies when the "newSubscriberDeliveryMode" property is set to "storedMessages".
  • The broker can only send messages stored in the topic’s integration table. The table's retention policy automatically removes old messages.
  • Each time a client unsubscribes from a topic and then subscribes to the topic, the broker sends historical messages as specified by this property. A client can use this behavior to reprocess messages, such as refresh a local data cache or recalculate aggregates.

Note A topic’s "retentionPolicy", "retentionUnit", and "retentionPeriod" properties define how long the broker retains messages in a topic’s integration table.

 integer -1 to 2147483647

nullable

 Identifies whether a field can contain a NULL value. Boolean

true

false

numberFormat

The "numberFormat" property is an optional, case-insensitive string enum. It defines the format of JSON numbers. The default value for "numberFormat" is the "defaultNumberFormat" defined in the "createSession" or "alterSession" actions. If it is omitted there, it defaults to the value of the "defaultNumberFormat" property in the <faircom>/config/services.json file.

When "numberFormat" occurs in "mapOfPropertiesToFields", it tells the server how to encode or decode a number assigned to a JSON property.

For example, including "numberFormat" in a "tableFieldsToJson" transform step controls if the server encodes a number in a JSON property as a number or a number embedded in a string.

Possible values:
  • "number"
    • This causes the server to return numeric values as JSON numbers, such as -18446744073709551616.000144722494 .
    • This is most efficient.
    • JSON represents numbers are base-ten numbers that may have any number of digits.
    • Large numbers, such as 18446744073709551616.000144722494 are known to cause problems with JSON parsers and some programming languages, such as JavaScript, which are limited to the smaller range and binary rounding errors of IEEE floating point numbers.
  • "string"
    • This returns the server to embed numeric values in JSON strings, such as "18446744073709551616.000144722494".
    • This is slightly less efficient because it includes two extra double quote characters
    • Returning numbers embedded in strings ensures JSON parsers and programming languages will not automatically convert the number to a numeric representation that loses precision, introduces rounding errors, truncates values, or generates errors. This allows your application to control how numbers are processed.
  • Omitted or set to null
    • This defaults to "number".

 

Example request

{
  "action": "someAction",
  "responseOptions":
  {
    "numberFormat": "string"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 string

"number"

"string"

oldKey

 The "oldKey" property is required by the "renameKeys" action to rename keys. It is part of a key-rename object and its value is a string. It specifies the current key that will be renamed. Each key-rename object contains "oldKey" and "newKey" properties that specify the current key's name and its new name. See the "renamedKeys" property for more information. string  1 to 128 bytes

outParams

 The "outParams" property specifies the output values of a stored procedure. array of objects

"binaryFormat"

"length"

"name"

"scale"

"type"

"value"

output

 The "output" property specifies the results returned by a stored procedure or SELECT statement. object

"data"

"dataFormat"

"fields"

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"

outputName

 The "outputName" property is an optional string that specifies a unique name for mapping an integration table to an output plugin to an external system. string 1 to 64 bytes

outputPayloadField

The "outputPayloadField" property specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers. If omitted or if it is an empty string, it defaults to "source_payload".

  • "outputPayloadField" must be one of the following values: 
    • "source_payload"
    • A user-defined field

This makes it possible for the output from any transform to be used as the payload delivered to subscribers.

 string "source_payload" or a user-defined field

ownerName

The "ownerName" property is an optional string from 1 to 64 bytes that identifies the user who owns an object (see Object owner). If it is omitted or set to "" or null, the server uses the default owner name supplied during the "createSession" action or uses the account's "username" as the owner name.

"params": {
  "ownerName": "SuperUser"
}
 string 0 to 64 bytes

partialKey

The "partialKey" property is an optional string or array that defines the range of returned records. The "getRecordsByPartialKeyRange" action uses the "partialKey" to find a starting position in the index where it can start returning records. It defaults to an empty string or empty array.

  • When the index key is based on one field, the "partialKey" property can be a string that contains some or all of the key values. The value must start from the beginning of the key.
    • When a field is stored in the index in reverse order, the "partialKey" property must start with bytes from the end of the key in reverse order. This allows you to do a partial match starting from the end of the key. To create a reverse order key, create the index and set one or more fields in the index to "reverseCompare": true.
  • You must include one value for each field in the index in the order the fields are in the index. The last field in the index may be omitted or may contain a partial key.
  • There are two forms of the "partialKey" property a string and an array.
  • The method finds the starting record by matching all the bytes in the "partialKey" value to the initial bytes in the indexes' keys.
  • A zero-length value matches all index keys.
  • All values in the array, except for the last, must represent a complete field value.
  • Only the last value in the array may be a partial value.
  • The fields must be placed in the array in index order.
  • Each value in the array must be compatible with the data type of its corresponding field.
    • JSON true or false for "bit" field.
    • JSON number for all number fields.
    • JSON string for "char", "varchar", "lvarchar", "binary", "varbinary", and "lvarbinary" fields.
  • A binary value is embedded in a string and is encoded as "base64" or "hex" according to the setting of "binaryFormat".

Note The Array (multi-field) shows how to use "partialKey" when an index contains five fields ("date", "bit", "varchar", "double", and "varbinary"). The values for "date", "bit", "varchar", and "double" cannot be partial values because they occur before the last field. The binary value in the "varbinary" field is encoded as base64 and since it is the last field it can contain a partial binary key.

 

String

"partialKey": "Mi"

Array (multi-field)

"partialKey":
[
  "2023-01-01", true, "full string", -3.4, "TWk="
]

In the Key-Value API, the required "partialKey" property retrieves child keys from a key hierarchy. It defines the base hierarchical level of returned keys, such as "partialKey": "myApp/queries/". The action uses an index on the key to find all keys that match the characters specified in "partialKey". Keys are case sensitive.


To ensure the action matches the hierarchical levels you want, include the hierarchical delimiter at the end of the partial key, such as "myApp/queries/".


You can use "partialKey": "" to return all keys in the store.

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

password

The "password" property is a required string from 0 to 256 bytes. "password" authenticates an account.

  • The "password" property is required by the "createSession" action for authentication.
  • It is possible, but not recommended, for a password policy to allow a zero-length string.

Note See System limits for requirements of this and all other system properties.

 string 0 to 256 bytes

permanentSession

The "permanentSession" property is an optional Boolean that indicates if a session is permanent. It defaults to false.

Important Before you can create permanent sessions, you must add "enablePermanentJsonApiSessions": true to the "jsonActionApiDefaults" section of the <faircom>/config/services.json file.

If "permanentSession" is set to true when "createSession" is called, the server sets the authtoken as permanent. The authtoken is associated with the settings and authorizations of the user who created the session. It is always valid even after the server restarts. A permanent authToken works like an API Key and authenticates an application without the need for a username/password or a client certificate. Multiple applications can use the same permanent authToken.

Warning A permanent "authToken" is potentially less secure than a temporary one.

  • A permanent "authToken" never becomes invalid, which makes it easier for an attacker to find it using brute force.
  • A permanent "authToken" is persisted by an application, which increases the opportunity for an attacker to find it.
  • A permanent "authToken" allows each application server to share the same session, which potentially allows an attacker to change session settings for all application servers.
  • When you set the "permanentSession" property to true in "createSession", it creates a permanent session and returns a permanent "authToken".
  • Developers and applications can use a permanent authToken in JSON actions without needing to call createSession to get a temporary authToken.
  • You must protect a permanent "authToken" as you would a password or API key because it represents a permanently authenticated server session.
  • A permanent session does not expire. You can also prevent a temporary session from expiring by setting its "idleConnectionTimeoutSeconds" property to 0.
  • A permanent "authToken" uses the authorization and settings of the account that originally created the session. All actions performed in the session are performed using that account's authorizations, and account settings, such as its default database and owner.
  • You can use "alterSession" to modify the settings of a permanent session, but you cannot use it to turn a temporary session into a permanent session.
  • If multiple application servers use the same permanent "authToken", they share the same permanent session settings. Consider the following:
    • If one application server uses "alterSession" to change a permanent session's settings, the other application servers automatically use the new settings. To avoid confusion and errors, applications must specify all JSON action property values and not rely on session defaults.
    • You cannot use different sessions to determine which app server executes an action. This makes troubleshooting more difficult.
    • An application must create and use a transaction to protect the visibility and integrity of multiple operations from other applications. This is true for permanent and temporary sessions.
  • The FairCom server securely stores each permanent "authToken" in the encrypted faircom.fcs file.
 Boolean

true

false

persistence

 The "persistence" property is an object that defines the parameters of the persistence table. object

"databaseConnectionString"

"databaseName"

"databaseUserName"

"maxDeliveryRatePerSecond"

"mqttPayloadType"

"newSubscriberDeliveryMode"

"newSubscriberMaxDeliveredMessages"

"outputPayloadField"

"ownerName"

"retentionPeriod"

"retentionPolicy"

"retentionUnit"

"retrySeconds"

"tableName"

"tableReplicationReady"

"threads"

"topic"

“validateMqttPayload”

photo

 The optional "photo" property contains a photo of a thing. It defaults to null and is a binary value up to 2 GB in size. You cannot use it for lookups and filtering. string up to 2 GB

port

The "port" property is an integer that specifies the port number.

 integer an integer port number

previousTransformSteps

 The "previousTransformSteps" property is a JSON array that contains the transform step objects assigned to the integration table before they were replaced by the "copyIntegrationTableTransformSteps" action. array the transform step objects of the specified transform before they were replaced by the action.

primaryKey

 When > 0, the "primaryKey" property identifies the ordinal position of the field within the table's primary key. integer 0 to 32

primaryKeys

This optional property identifies a table's primary key.

Note The best practice is not to use the "primaryKeyFields" or "primaryKey" properties, so the "createTable" action will automatically create a primary key field named "id" with a unique index named "id_pk".

Each table created by the JSON DB API has a primary key that uniquely identifies each record.

"createTable" automatically adds the "id" field as the primary key to your table. It makes "id" an auto-increment bigint field and indexes the field with a unique index named "id_pk". Using the "id" field as the primary key is a best practice.

You can specify one or more fields to be the primary key of the table instead of the "id" field. To do so, you must add the "primaryKeyFields" property to "createTable" or use the "fields" property's "primaryKey" to specify which field(s) are in the primary key.

Note You should not use both the "primaryKeyFields" and "primaryKey" properties together.

If multiple fields are specified for the key, the index is named "pk". If only one field is specified for the key, the index is named "<fieldname>_pk".

If you use the "primaryKey" property to specify multiple fields as the primary key, the assigned value from 1 to n specifies the order of the fields in the primary key. Assign "primaryKey": 1 to the first field in the primary key, "primaryKey": 2 to the second, and so forth. If you create a primary key with multiple fields, the index is named "pk". If you specify just one field, the index is named "<fieldname>_pk".

 

Example

"fields": [
  {
    "name": "a",
    "type": "tinyint",
    "primaryKey": 1
  },
  {
    "name": "b",
    "type": "smallint",
    "primaryKey": 2
  },
  {
    "name": "c",
    "type": "integer",
    "primaryKey": 3
  }
]
 array of arrays an array of arrays

primaryKeyFields

This optional property specifies the fields of the table’s primary key when multiple fields are combined to form the primary key.

Note The best practice is not to use the "primaryKeyFields" or "primaryKey" properties, so the "createTable" action will automatically create a primary key field named "id" with a unique index named "id_pk".

The order of fields in this property is the order of fields in the primary key index. The "fields" property contains the name and type of each field that is specified in the "primaryKeyFields" array. 

A primary key with multiple fields has an index named "pk". If you specify just one field, the index is named "<fieldname>_pk".

If only one field is used as the primary key, the "primaryKey" property defines the primary key.

Note The "primaryKeyFields" and "primaryKey" properties cannot be used together.

 

Example

"primaryKeyFields": [
  "a",
  "b",
  "c"
],
"fields": [
  {
    "name": "a",
    "type": "tinyint"
  },
  {
    "name": "b",
    "type": "smallint"
  },
  {
    "name": "c",
    "type": "integer"
  }
]
 array an array

privateKeyFilename

The "privateKeyFilename" is an optional string that specifies the name and optional path of a server key file.

    "tls": {
      "allowedCipherSuites": "",
      "certificateAuthoritiesFilename": "",
      "certificateFilename": "",
      "privateKeyFilename": ""
    },
 string No limits

problemCode

The "problemCode" property is an integer that specifies a unique code number that identifies the type of problem.

 integer A unique code number

problemData

The "problemData" property is an object that contains data about the problem stored in a JSON object. The data is stored in the object as key/value pairs.

 object 1 or more key/value pairs

problemMessage

The "problemMessage" property is a string that contains a message describing the problem.

 string A message detailing the problem

problems

 The "problems" property is an array of objects that lists problems that match the request parameters. Each problem is contained in a separate object. array of objects

0 or more objects containing 1 or more of the following properties:
"problemCode"

"problemData"

"problemMessage"

"problemTimestamp"

"problemType"

problemTimestamp

The "problemTimestamp" property is a string that lists the date and time the problem occurred. The timestamp is formatted as an ISO8601 timestamp embedded in the string.

 string containing an ISO8601 timestamp

"2025-08-19"

"2025-08-19T00:00:00.000"

"2025-08-19T01:13"

"2025-08-19T01:13:59"

"2025-08-19T01:13:59.853"

problemType

The "problemType" property is a string that details the type of problem that occurred, such as an error or warning.

 string

"diagnostic"

"information"

"warning"

"error"

"fatalException"

propertyPath

 The "propertyPath" property specifies the name of the data to be defined by "propertyValue". string 0 to 256 bytes

propertyValue

This is a required object that contains properties that define the data values of a "propertyPath". It is required and has no default value.

The data values specified in the "propertyValue" object can be a string or an object.

  • "fromConstant" indicates the value is a string. For example —
    • "propertyValue": {"fromConstant": "0002"}
  • "fromSourcePropertyPath" indicates the value is an object. For example —
    • "propertyValue": {"fromSourcePropertyPath": { "formatString": "Temperature = <%input_temp%>" }}
    • Characters in the "formatString" value that are enclosed by "<%" and "%>", specify the name as an input property that will be replaced by an input property value.
    • Here is a REST command example for the "propertyPath" named "description", that received an input_temp value of 103:
    • {  description: "Temperature = 103."}
    • If the input value is not found, it is replaced with NULL:
    • {  description: "Temperature = NULL."}
 object

"fromConstant": "yourString"

"fromSourcePropertyPath": { "key": "value"}

protocol

The "protocol" property is a string that specifies the name of a protocol.

 string the name of a protocol

publishedTopics

The "publishedTopics" property returns a list of the topics the client has published since the session was first created.

 string 1 to 65,500 bytes

purpose

The "purpose" property is an optional string that provides a short description of the specified server's purpose.

 

In the Thing API, the optional "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. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

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

reactions

 The "reactions" property contains the data returned by a SQL SELECT statement. array of objects

"affectedRows"

"elapsedMilliseconds"

"errorCode"

"errorMessage"

"outParams"

"rows"

"startTimestamp"

"sql"

reconnectFrequencySeconds

The "reconnectFrequencySeconds" property is the number of seconds that the broker waits between attempts to reconnect to an external broker. This property is optional. If omitted, it defaults to 15 seconds.

  • If it is set to 0, the broker does not attempt to reconnect when it loses a connection or fails to connect.
  • FairCom's servers attempt to connect to an external broker when it is configured as a subscriber to topics on an external broker or when it is configured to forward messages to an external broker.
    • To stop the reconnect process, send the "configureBrokerConnection" message with the command property set to "disconnect".
  • To restart the reconnect process, send the "configureBrokerConnection" message with the command property set to "reconnect".
 int32 the number of seconds the broker will wait between attempts to reconnect to an external broker.

recordAfterBeingTransformed

The "recordAfterBeingTransformed" property contains an object with one property for each field in the record. Each property value is from the record after it was modified by the transform steps.

 object 0 or more properties

recordBeforeBeingTransformed

The "recordBeforeBeingTransformed" property contains an object with one property for each field in the record. Each property value is from the record before it was modified by the transform steps.

 object 0 or more properties

recordFilter

The "recordFilter" property is a string that specifies a FairCom expression that must match a record's field values before the record is included as a data change event.

 string 1 to 65,000 bytes

recordFormat

The "recordFormat" property is a string that includes the record's value in the data change event as a binary-encoded string or individual field values.

 string

"fields"

"buffer"

renamedKeys

The "renamedKeys" property is required by the "renameKeys" action to rename keys. It contains an array of key-rename objects. Each key-rename object contains "oldKey" and "newKey" properties that specify the key's current and new names.
 

 { 
    "oldKey": "k1",
    "newKey": "k2"
  }
 array of key-rename objects 
[
  { 
    "oldKey": "k1", 
    "newKey": "k2"
  }
]

requestedRecordCount

The "requestedRecordCount" property is a signed, 32-bit integer set by the server in response to the "getRecordsFromCursor" method.

  • It makes it easy to know how many records were requested in the last call to "getRecordsFromCursor".
  • An application can use "requestedRecordCount" in conjunction with "returnedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.
 integer

0 to 2147483647

requestIterationMilliseconds

The "requestIterationMilliseconds" property specifies the number of milliseconds the server will wait between attempting the request.

 integer 1 to 2147483647

requestMaxThreads

The "requestMaxThreads" property specifies the maximum number of threads allowed in the request.

 integer 1 to 2147483647

retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It must be an integer value from 1 to 100. It refers to the unit of time specified by the "retentionUnit" property — for example, if "retentionPeriod" is 14 and "retentionUnit" is "day", then message data is retained for 14 days. This property is optional.

  • Periodically, the system increments the age of each table partition.
    • "Minute" units are incremented at the zero second of each minute, whether the table partition was created 1 second before or 59 seconds before.
    • "Day" units are incremented at midnight GMT, not midnight of the local UTC time zone. A table partition becomes one day old at midnight GMT, whether it was created one second before or 23 hours and 59 seconds before.
    • "Week" units are incremented at midnight GMT on the last day of each week, even if the table partition was created one second before. The last day of the week is Saturday GMT.
    • "Month" units are incremented at midnight GMT on the last day of each month.
    • "Year" units are incremented at midnight GMT on Dec 31.
  • "retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.
  • If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.
  • If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

When partitions are auto-purged, some data are maintained "forever" in a global index. Auto-purge does not prevent these files from growing without bounds and filling up your hard drive.

If not specified, the default found in the services.json file is used. Initially, it is 4 (weeks).

Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.

Note 

  • If the value is not an integer from 1 to 100, FairCom's servers set it to the default value.
  • Smaller numbers improve SQL performance.
  • Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
  • FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".
  • The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.
  • The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time. In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.
    • For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.
  • The current calendar date affects purging.
    • FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.
    • For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.
 integer 1 to 100

retentionPolicy

The "retentionPolicy" property controls how messages are persisted. This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.
 string enum

"autoPurge"

"neverPurge"

retentionUnit

Each time this unit cycles, FairCom purges expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
 string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

retrySeconds

The "retrySeconds" property is the number of seconds that FairCom's MQTT broker will wait for the next expected packet from a client during a QoS 1 or QoS 2 PUBLISH packet exchange/PUBLISH handshake with an MQTT client. The default value is 5. It applies when a client is publishing to the broker and when the broker is publishing to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. "retrySeconds" is optional.

  • If the "retrySeconds" time expires, FairCom's broker will disconnect the MQTT client with MQTT error code 7.  MQTT 5 clients will also receive a Reason Code.  An error message will be logged to <faircom>/data/CTSTATUS.FCS explaining why the disconnect happened. For example: 
    • MQTT connection for client ID [myMqttClient7] has been disconnected due to inactivity timeout. retrySeconds is set to [25] seconds for topic [my/test/topic12].: 14226
    • When the MQTT client reconnects, FairCom's MQTT broker will attempt to resume the PUBLISH handshake by resending the unanswered packet to the client, hoping that the client will reply with the next step of the handshake.
  • The minimum value is 1 and the maximum value is 65535.
  • If "retrySeconds" is omitted or its range is exceeded, FairCom's broker uses the default value.
  • Note that this parameter is not related to MQTT Keep Alive or when PINGREQ packets should be sent by the client.
 integer 1 to 65535

returnedRecordCount

The "returnedRecordCount" is a 32-bit integer set by the server in response to the "getRecordsFromCursor" method.

  • It makes it easy to know how many records were returned from the last call to "getRecordsFromCursor".
  • An application can use "returnedRecordCount" in conjunction with "requestedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.
 integer

0 to 2147483647

returnTagsBy

 The optional "returnTagsBy" property is an enumerated string with the following values: "tagName" and "id". It defaults to "id". It is used by the "listTags" action to specify whether it returns tags identified by ID or name. string enum

"id"

"tagName"

returnThingsBy

 The optional "returnThingsBy" property is an enumerated string with the following values: "name" and "id". It defaults to "id". It is used by the "listThings" action to specify whether it returns things identified by ID or "name". string enum

"name"

"id"

revealAfterValueOnFilteredDelete

The "revealAfterValueOnFilteredDelete" property is a Boolean that includes the "afterValue" property in the notification message when true. When "recordFilter" filters out a record based on field values, an update causes a deleted change event to occur when its field values no longer match the filter. The "afterValue" property, when present, reveals the new field values and leaks information.

 Boolean

true

false

revealBeforeValueOnFilteredInsert

The "revealBeforeValueOnFilteredInsert" property is a Boolean that includes the "beforeValue" property in the notification message when true. When "recordFilter" filters out a record based on field values, an update causes an insert change event when previous field values did not match the filter but now match it. The "beforeValue" property, when present, reveals the old field values and leaks information.

 Boolean

true

false

roleName

The "roleName" property is required by the role keystore. It is not used with the other keystores. It specifies the key's role, which must match an RBAC role that exists in the server.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 string 1 to 64 bytes

roleNames

The "roleNames" property lists the roles given to the accounts specified by the "partialNames" property. This property can specify one or more roles, each between 1 and 64 bytes.

  "params": {
    "partialNames": [
      "adm",
      "NewAccount"
    ]
  },
 array of strings An array of 1 or more strings between 1 and 64 bytes.

rows

 The "rows" property specifies the rows returned by a stored procedure of a SELECT statement and metadata about the results. object The rows returned by a stored procedure.

scale

 If the type is "number" or "money", the "scale" property identifies the number of places to the right of the decimal point,. integer 0 to 32

schemaName

The "schemaName" property is an optional string from 1 to 64 bytes that specifies the unique name of the account that owns an object. The default value is the "username" of the logged-in account.

Things to know:
  • About "schemaName":
    • If the "schemaName" property is omitted, set to "", or null, the server uses the default schema name supplied at login (if any) or uses the user’s username as the schema name.
    • For legacy support, "schemaName" can be "", which means a table has no schema.
  • About how schemas work:
    • If there is no table with the specified schema name, but there is a table that does not belong to any schema, it belongs to all schemas and that table will match. A table can belong to one schema or all schemas, but not more than one schema.
    • The fully qualified name of an object includes "databaseName", "schemaName", and the object's name, such as "tableName".
    • Queries and scripts are often written without specifying "databaseName" and/or "schemaName". This allows queries and scripts to work properly when run in different databases or in different schemas.
    • The default database name is supplied by the "defaultDatabaseName" property, and the default schema name is supplied by the "defaultSchemaName" property.
 string 1 to 64 bytes

sequence

The "sequence" property optionally assigns an order to the labels in a group. You can use a floating point or integer number. You may embed the number in a JSON string. It defines the order of labels in a group. It is a floating point number to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.

 float Any floating point or integer number.

serialNumber

 The optional "serialNumber" property specifies a thing's serial number. Typically a serial number uniquely identifies a thing, but things from different manufacturers may have the same serial numbers.  It defaults to "unknown" and is a string from 1 to 64 bytes. You can use it to do partial lookups and filtering. string 1 to 64 bytes

serviceLibrary

The "serviceLibrary" property is a string that specifies the filename of a dynamic library that provides the API used by the web application.

Library files are located in the <faircom>/server/web/ folder.

The full path includes the "serviceLibrary" value — for example, the Monitor app has a "serviceLibrary" name of ctmonitor.dll, and its full path in the file system is <faircom>/server/web/ctmonitor.dll.

 string The file name for the service library.

serviceName

The "serviceName" property contains the name of a FairCom input or output service. This property is required.

See the "params" topic of each specific service for the requirements of this property.

The following services are available as of the V5 release:
  • "MODBUS"
  • "SIEMENSUDT2JSON"
  • "OPCUA"

Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration.

Note MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.

 string A service name between 1 and 64 bytes.

serverVersion

The "serverVersion" property indicates which version of the FairCom server the request was made to.

  "result": {
    "sessionStartTimestamp": "2025-08-28T15:44:56",
    "sessionLastAccessedTimestamp": "2025-08-28T18:07:07",
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4,
    "serverVersion": "FairCom EDGE Server - V4.2.4.109(Build-250819)"
  },
 string The name of the version of the FairCom server to which the request was made.

sessionLastAccessedTimestamp

The "sessionLastAccessedTimestamp" property indicates the date/time when the session was last accessed.

"result": {
  "sessionStartTimestamp": "2025-08-27T20:26:25",
  "sessionLastAccessedTimestamp": "2025-08-27T20:56:25"
  },
 timestamp An ISO 8601 timestamp

sessionPresent

Boolean that specifies whether the broker will use a previously stored session state, including the client's previous descriptions. 

 Boolean

true

false

sessions

The "sessions" property is an array of session objects where each session object minimally describes a session.

 array of objects

"authToken"

"defaultApi"

"defaultBinaryFormat"

"defaultDatabaseName"

"defaultDebug"

"defaultOwnerName"

"defaultResponseOptions"

"defaultRetentionPeriod"

"defaultRetentionPolicy"

"defaultRetentionUnit"

"defaultVariantFormat"

"description"

"hostIpAddresses"

"hostname"

"hostServerNamePort"

"hostSQLPort"

"hostUuid"

"idleConnectionTimeoutSeconds"

"idleCursorTimeoutSeconds"

"permanentSession"

"serverVersion"

"sessionLastAccessedTimestamp"

"sessionStartTimestamp"

"transformBufferInitialBytes"

"username"

sessionStartTimestamp

The "sessionStartTimestamp" property indicates the date/time when the session was first initialized.

"result": {
  "sessionStartTimestamp": "2025-08-27T20:26:25",
  "sessionLastAccessedTimestamp": "2025-08-27T20:56:25"
  },
 timestamp An ISO 8601 timestamp

sessionType

 specifies which type of session the requested client is currently running. string

"mqApi"

"mqtt"

"both"

settings

The "settings" property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference "params" property of each connector for details of the "settings" property for that connector.

Connector-specific "settings"

 object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

sourceDatabaseName

The "sourceDatabaseName" property is a string that specifies the database name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 string 1 to 64 bytes

sourceDataField

The "sourceDataField" property is an optional string that contains the name of a field from an integration table. It defaults to "source_payload".

 string

"source_payload"

"t1"

"t2"

"t3"

"t4"

"t5"

"t6"

"t7"

"t8"

"t9"

sourceDataFilePath

The "sourceDataFilePath" property is a string that specifies the data file path of the table on the FairCom DB or RTG server that generates the stream's data change events. It can be a full path or a relative path from the server's data directory.

 string No limits

sourceDataFormat

The "sourceDataFormat" property specifies the format of the "source_payload" field. You can set this property to any of the following values:

  • "json"
  • "xml"
  • "binary"
  • "jpeg"
  • "siemensUdt"
 string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

sourceFieldLength

The "sourceFieldLength" property is the number of bytes consumed by the tag's primary field. A tag's primary field is defined by the "sourceFieldName" property.

  • When a primary field is assigned to a tag, it is returned in the response to "describeTag", "createTag", "alterTag", and "deleteTag".
  • If a tag is not linked to a field, the "sourceFieldLength" is omitted in the response.
  • It returns the field's length as defined by the integration table.

The following field types have a user-defined length:

  • "char" between 1 and 65,500 bytes.
  • "varchar" between 1 and 65,500 bytes.
  • "binary" between 1 and 65,500 bytes.
  • "varbinary" between 1 and 65,500 bytes.
  • "json" between 1 and 65,500 bytes, or up to 2GB if the length is null or omitted.
  • "number" between 1 and 32.
  • "money" between 1 and 32.


The remaining field types have a fixed length.

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.

 integer The field's length as defined by the integration table. 

sourceFieldName

The optional "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

sourceFields

The optional "sourceFields" property specifies the fields the FairCom server makes available to the output connector. The server creates a JSON object from the fields you specify, and the output connector uses it as its source data. If "sourceFields" is omitted, set to null or [], the FairCom server defaults to creating a JSON document that contains all fields from the integration table. This default allows the output connector to send data to a device from any field in the table.

An integration table has many fields, such as fields populated by transforms and MQTT. Converting all fields into JSON is slower than converting only the fields needed by the output connector. For example, input connectors and MQTT messages store their data in the source_payload field. You can use "sourceFields": ["source_payload"] to make only the source_payload field available to the output connector.

When you configure an output connector, you add propertyMap objects to the "propertyMapList". Each propertyMap object extracts data from one field and writes that data to the connected device. The value of the "propertyPath" property is a string containing the path of the data. It always starts with a field name in the "sourceFields" property. For example, if "sourceFields" is set to ["pressure"], then you must set "propertyPath" to "pressure" to use the pressure field’s value in your output. If the value you want to extract is a JSON property nested inside a field, you must add its full path to the "propertyPath". For example, if "sourceFields" is set to ["source_payload"] and source payload contains a JSON object with a "temperature" property, then you must set "propertyPath" to "source_payload.temperature".

 array One or more fields from the integration table.

sourceFieldScale

The "sourceFieldScale" property is the fixed scale of the tag's primary field. A tag's primary field is defined by the "sourceFieldName" property.

  • When a primary field is assigned to a tag, it is returned in the response to "describeTag", "createTag", "alterTag", and "deleteTag".
  • If a tag is not linked to a field, the "sourceFieldScale" is omitted in the response.
  • It returns the field's scale as defined by the integration table.
  • It defines the fixed number of digits to the right of the decimal place.
  • For example, the number -12.34 has a fixed scale of 2.
  • Only the following field types have a scale:
    • "number" between 0 and 32.
    • "money" between 0 and 32.

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.

 

 integer The field's scale as defined by the integration table.

sourceFieldType

The "sourceFieldType" property is the type of the tag's primary field. A tag's primary field is defined by the "sourceFieldName" property.

  • When a primary field is assigned to a tag, it is returned in the response to "describeTag", "createTag", "alterTag", and "deleteTag".
  • If a tag is not linked to a field, the "sourceFieldType" is omitted in the response.
  • It returns the field's type as defined by the integration table.
  • See the list of field types for available values.

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 The field's type as defined by the integration table.

sourceHostname

 The "sourceHostname" property is a required string that specifies a unique host name or TCP/IP address of a FairCom DB or RTG server. string 1 to 255 bytes

sourceOwnerName

The "sourceOwnerName" property is a string that specifies the account that owns the table on the FairCom DB or RTG server that generates the stream's data change events.

 string 1 to 64 bytes

sourcePassword

 The "sourcePassword" property is an optional string that specifies the login password of a FairCom DB or RTG server. string 1 to 128 bytes

sourcePayloadBinaryFormat

The optional "sourcePayloadBinaryFormat" specifies how the server encodes and decodes a binary value assigned to a tag. For example, it controls how a transform converts a binary value between a JSON property and a table field.

  • It applies only when the "tagDataType" property is "binary".
  • The default value is "hex".
  • Use one of the following values:
    • "hex" - hexadecimal encoding.
    • "base64" - Base64 encoding.
    • "byteArray" - Array of integer values where each integer represents one byte.
  • It applies to the tag's property in the source_payload field, which is specified by the "sourcePayloadPath" property.
  • It applies to the tag's field in the integration table, which is specified by the "sourceFieldName" property.
  • For example, "sourcePayloadBinaryFormat": "hex" causes a "jsonToTableFields" transform to read the value "BEEF" from the tag's property in the source_payload field, decode it into the binary value 0xBEEF, and store it in the tag's field in the integration table.
  • For example, "sourcePayloadBinaryFormat": "byteArray" causes a "tableFieldsToJson" transform to read the value 0xBEEF from the tag's field in the integration table, encode it into a JSON array of bytes [190, 239], and store it the tag's property in the source_payload field.
  • For example, "sourcePayloadBinaryFormat": "base64" causes a "tableFieldsToJson" transform to read the value 0xBEEF from the tag's field in the integration table, encode it into the Base64 value "vu8=", and store it the tag's property in the source_payload field.


For more details, see "binaryFormat".

 string enum

"base64"

"byteArray"

"hex"

sourcePayloadDateFormat

The optional "sourcePayloadDateFormat" specifies how the server encodes and decodes a date value assigned to a tag. For example, it controls how a transform converts a date value between a JSON property and a table field.

  • It applies to the tag's value only when the  "tagDataType" property is "date" or "timestamp".
  • The default value is "iso8601".
  • Use one of the following values (see "dateFormat"):
    • "ccyy.mm.dd"
    • "mm.dd.ccyy"
    • "mm.dd.yy"
    • "dd.mm.ccyy"
    • "dd.mm.yy"
    • "ccyymmdd"
    • "iso8601"
    • "yymmdd"
    • "utc"
  • For example, "sourcePayloadDateFormat":"iso8601" decodes "2025-07-11" into a date that can be stored in a date field.
  • It applies to the tag's property in the source_payload field, which is specified by the "sourcePayloadPath" property.
  • It applies to the tag's field in the integration table, which is specified by the "sourceFieldName" property.
  • For example, "sourcePayloadDateFormat": "iso8601" causes a "jsonToTableFields" transform to read the value "2026-03-23" from the tag's property in the source_payload field, decode it into the year 2026, month 3, and day 23, and store it in the tag's date or timestamp field in the integration table.
  • For example, "sourcePayloadDateFormat": "mm.dd.ccyy" causes a "jsonToTableFields" transform to read the value "03/23/2026" from the tag's property in the source_payload field, decode it into the year 2026, month 3, and day 23, and store it in the tag's date or timestamp field in the integration table.
  • For example, "sourcePayloadBinaryFormat": "yymmdd" causes a "tableFieldsToJson" transform to read the value year 2026, month 3, and day 23 from the tag's date or timestamp field in the integration table, encode it into "260323", and store it the tag's property in the source_payload field.
  • When combined with the "sourcePayloadTimeFormat" property, the server can properly encode and decode a date and time stored in a timestamp field.
 string enum "ccyy.mm.dd"
"mm.dd.ccyy"
"mm.dd.yy"
"dd.mm.ccyy"
"dd.mm.yy"
"ccyymmdd"
"iso8601"
"yymmdd"
"utc"

sourcePayloadFormat

 deprecated version of "mqttPayloadType". Please use "mqttPayloadType". string

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

sourcePayloadNumberRounding

The optional "sourcePayloadNumberRounding" property specifies how the server rounds a number value when stored in a number field with less scale, such as converting a floating point number to an integer field. 

  • It applies only when the "tagDataType" property is "number".
  • It is a string enum with the following values: 
    • "truncate" - truncates numeric digits to fit the available scale.
    • "roundup" - rounds up numeric digits to fit the available scale.
    • "rounddown" - rounds down numeric digits to fit the available scale.
  • The default value is "truncate".
  • For example, "sourcePayloadNumberRounding":"roundup" converts the number -123.4567 to -123.46 when stored in a field that has the data type of NUMBER(32, 2). 
 string enum

"truncate"

"roundup"

"rounddown"

sourcePayloadPath

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

  •  It is required by the "createTag" action; otherwise, it is optional.
  • 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 optional "sourcePayloadTimeFormat" specifies how the server encodes and decodes a time value assigned to a tag. For example, it controls how a transform converts a time value between a JSON property and a table field. 

  • It applies to the tag's value only when the  "tagDataType" property is "time" or "timestamp".
  • The default value is "iso8601".
  • Use one of the following values (see "timeFormat"):
    • "hh.mm.ss.ttt"
    • "hh.mm.am/pm"
    • "hh.mm.ss.am/pm"
    • "hh.mm.ss"
    • "hh.mm"
    • "hhmm"
    • "iso8601"
    • "utc"
  • When combined with the "sourcePayloadDateFormat" property, the server can properly decode a date and time that can be stored in a timestamp field.
  • For example, "sourcePayloadTimeFormat":"iso8601" properly decodes "16:18:33" into a time that can be stored in a time field. 
  • It applies to the tag's property in the source_payload field, which is specified by the "sourcePayloadPath" property.
  • It applies to the tag's field in the integration table, which is specified by the "sourceFieldName" property.
  • For example, "sourcePayloadTimeFormat": "iso8601" causes a "jsonToTableFields" transform to read the value "18:01:47" from the tag's property in the source_payload field, decode it into the hour 18, minute 1, and second 47, and store it in the tag's time or timestamp field in the integration table.
  • For example, "sourcePayloadTimeFormat": "hh.mm.am/pm" causes a "jsonToTableFields" transform to read the value "06:01:47 pm" from the tag's property in the source_payload field, decode it into the hour 18, minute 1, and second 47, and store it in the tag's time or timestamp field in the integration table.
  • For example, "sourcePayloadTimeFormat": "hhmm" causes a "tableFieldsToJson" transform to read the hour 18, minute 1, and second 47 from the tag's time or timestamp field in the integration table, encode it into "1801", and store it the tag's property in the source_payload field.
  • When combined with the "sourcePayloadTimeFormat" property, the server can properly encode and decode a date and time stored in a timestamp field.
 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 optional "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"

sourcePort

 The "sourcePort" property is an optional integer that specifies the ISAM TCP/IP port of a FairCom DB or RTG server. int16 1 to 65535

sourceServerName

 The "sourceServerName" property is a conditional string that specifies the server name of a FairCom DB or RTG server. It is the name specified by the SERVER_NAME keyword defined in the target server's configuration file, ctsrvr.cfg. The server name used by most FairCom DB and RTG servers is "FAIRCOMS". This property is required if the "sourceHostname" is not defined. string 1 to 255 bytes

sourceServers

 The "sourceServers" property is a required array containing a list of FairCom DB or RTG server connection objects. FairCom MQ attempts to connect to the first server in the list. If that fails, it attempts to connect to the next one. If it reaches the last server in the list, it attempts to connect to the first. array of server connection objects 
{
  "purpose": "Primary Server",
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  }
}

sourceTableName

The "sourceTableName" property is a string that specifies the name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 string 1 to 64 bytes

sourceUsername

 The "sourceUsername" property is an optional string that specifies the name of a FairCom DB or RTG server. string 1 to 64 bytes

sql

 The "sql" property specifies the original SQL statement that was executed. string The original SQL statement

startTimestamp

 The "startTimestamp" property specifies the time at which the query was initiated. timestamp A timestamp

stats

 contains stats about describeMqSessions. object

"currentDeliveryBacklogged"

"deliveryBacklogRatePerDay"

"deliveryBacklogRatePerHour"

"deliveryBacklogRatePerMinute"

"deliveryBacklogRatePerMinuteInSession"

"deliveryBacklogRatePerMinuteLast10Minutes"

"maxHealthyBacklogRatePerMinute"

"maxHealthySendRatePerMinute"

"maxHealthySubscribedTopicFiltersCount"

"minHealthySendRatePerMinute"

"minHealthySubscribedTopicFiltersCount"

"publishedTopics"

"publishRatePerHour"

"publishRatePerMinute"

"publishRatePerMinuteInSession"

"publishRatePerMinuteLast10Minutes"

"receiveMessagesPerHour"

"receiveMessagesPerMinute"

"receiveMessagesPerMinuteLast10Minutes"

"receiveMessagesPerMinuteSinceInSession"

"sessionHealth"

"totalMessagesPublished"

"totalMessagesReceived"

status

The optional "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"

statusCode

 The "statusCode" property displays the status code for the specified broker connection. integer See error codes

statusMessage

 The "statusMessage" property describes the status code with a written explanation. string 0 to 1024 bytes

streamingConnection

The "streamingConnection" property is an object that contains the current values of the streaming connection object that connects FairCom MQ to the source FairCom DB or RTG server.

 object 
"streamingConnection": {
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "maxSecondsBeforeConnectingToNextServer": 15,
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  },
  "metadata": {}
}

streamingConnectionName

 The "streamingConnectionName" property is a required string that specifies a unique, user-defined name for a streaming connection. The API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server. string 1 to 64 characters

streamParallelism

 The "streamParallelism" property is an optional integer that specifies the number of parallel streams the server uses to deliver data changes to the FairCom MQ server. You typically use a number that does not exceed the number of cores on the FairCom MQ server. integer 1 to 65535

streamingConnectionName

 The "streamingConnectionName" property is a required string that specifies a unique, user-defined name for a streaming connection. The API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server. string 1 to 64 characters

streamingConnectionNameFilter

 The "streamingConnectionNameFilter" property is an optional string that specifies a partial match for a connection name. string 1 to 64 bytes

streamingConnections

The "streamingConnections" property is an array of objects that list the streaming connections that match the filters in the request as separate objects.

 array of objects

0 or more objects containing 1 or more of the following properties:

"estimatedBacklogSeconds"

"metadata"

"sourceServers"

"streamingConnectionName"

"streamParallelism"

streamParallelism

 The "streamParallelism" property is an optional integer that specifies the number of parallel streams the server uses to deliver data changes to the FairCom MQ server. You typically use a number that does not exceed the number of cores on the FairCom MQ server. integer 1 to 65535

stringFormat

The optional "stringFormat" property in "responseOptions" changes how "char", "varchar", "lvarchar", and "variant" string field values are returned.

This property applies to all "getRecords..." actions, except for "getRecordsUsingSql" because SQL controls the format of strings it returns.

 string

"json"

"hex"

subscribedTopics

 The "subscribedTopics" property lists the topics that the specified topic is subscribed to. array No limits

subscriberCount

 specifies the number of subscribers integer Number of subscribers

tableName

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

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

"params": {
  "tableName": "ctreeTable"
}
 string 1 to 64 bytes

tableReplicationReady

 The "tableReplicationReady" property enables the transaction log on the persistence table. Transaction logs must be enabled before a table can be replicated. Boolean

true

false

tagChanges

The "tagChanges" property is a string that specifies when to add "changed": true to field objects in the data change event to indicate when a field changed value.

 string

"forEachField"

"forPrimaryKeyFields"

"never"

tagDataType

The optional "tagDataType" property is an enumerated string that specifies the data type of the tag.  

  • It defines the data type of the tag's value. 
  • The default value is "json", which can represent a string, number, true, false, null, an object, and an array.
  • 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.
 string enum "string"
"number" 
"boolean" 
"date" 
"time" 
"timestamp" 
"json" 
"variant" 
"binary" 

tagName

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

  • It is a string from 1 to 256 bytes. 
  • It is required and cannot be the empty string "".
  • 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

tagNames

The required "tagNames" property is an array of strings that specifies one or more tag names. You can use it to describe or delete tags. 

  • Each item in the array is the exact name of a tag. 
  • It is a string from 1 to 256 bytes. 
 string 1 to 256 bytes

thingName

 The required "thingName" property is a string that specifies the unique name of a thing.  It is a string from 1 to 64 bytes. It cannot be the empty string "". string 1 to 64 bytes

thingNames

 The required "thingNames" property is an array of strings that specifies one or more thing names. Each item in the array is the exact name of a thing. It is a string from 1 to 64 bytes. You can use it to describe or delete things. array of strings 1 or more thingName strings

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.

thingType

The optional "thingType" property specifies the thing's type, which is a generic description of what the thing is, such as "plc". A thing may have one type. It defaults to "unknown" and is a string from 1 to 64 bytes.

 

This API uses the Label API to manage types.

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

testDatabaseName

The optional "testDatabaseName" property specifies the database of the test table where this action tests the transform steps.  

When set to null or omitted, the server uses the default "databaseName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultDatabaseName" property.

Note The fully qualified name of a table includes the database, owner, and table names.

 string 1 to 64 bytes

testOwnerName

The optional "testOwnerName" property specifies the owner account of the test table where this action tests the transform steps.  

When set to null or omitted, the server uses the default "ownerName" defined in the "createSession" action. For more information, see the "createSession" action and the "defaultOwnerName" property.

Note The fully qualified name of a table includes the database, owner, and table names.

 string 1 to 64 bytes

testTableName

The required "testTableName" property specifies the name of the test table where this action tests the transform steps.

Note The fully qualified name of a table includes the database, owner, and table names.

 

 string 1 to 64 bytes

testTransformScope

 The "testTransformScope" property is the same value specified in the call to the "testIntegrationTableTransformSteps" to the action. string enum

"allRecords"

"stop"

"firstRecord"

"lastRecord"

"specificRecords"

threads

The "threads" property is the number of threads assigned to a topic to write published messages to disk. This property is optional. The default value is 1.

  • The default of 1 is enough to handle typical workloads.
  • For heavy workloads, you may increase the number of threads to 2 or 3.
 integer

1

2

3

tls

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the cipher suites that are allowed, and whether the client certificate is required. This property is optional. It defaults to an empty object. 

 

"tls": { "serverCertificateFilename": "server.crt", "privateKeyFilename": "server.key", "caCertificateFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" "requireClientCertificate": "true"
}
 object

"allowedCipherSuites"

"caCertificateFilename"

"certificateFilename"

"privateKeyFilename"

topic

The "topic" property is an optional string that specifies the MQTT topic on the external broker to which messages will be forwarded.

 string A topic name between 1 and 65,500 bytes

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.

totalRecordCount

The "totalRecordCount" property contains the total available number of records that can be returned from a query.

  • The "totalRecordCount" is set to -1, when the server does not know the total record count.
  • A very fast way to get the total number of records in a table is to call the "getRecordsByTable" method without applying a "tableFilter". This immediately returns the count without reading and counting records.
  • For most methods, the server does not calculate "totalRecordCount" because calculating it requires walking all records in the query, which may take a significant amount of time.
  • When the result is returned as a cursor, "totalRecordCount" is the total number of records that the cursor can traverse.
    • This does not apply to cursor responses.
  • When the result returns records directly, "totalRecordCount" is the total number of records that can be retrieved – not necessarily the number of records returned.
 integer

-1 to 99999999999999999999999999999999

transactionId

The "transactionId" property identifies a server-generated ID that represents a point in the progress of a transaction.

 string 0 to 255 bytes

transactionSavePointId

The "transactionSavepointId" is a string that the server generates and returns in a "createTransactionSavepoint" action. The generated ID represents a point in a transaction's progress. In requests, it defaults to an empty string.

  • A transaction savepoint represents the current point in the transaction process.
  • A client can roll back a transaction to any savepoint by calling the "rollbackTransaction" action with the desired "transactionSavepointId" property.
  • A client can commit a transaction to any savepoint by calling the "commitTransaction" action with the desired "transactionSavepointId" property.
  • A zero-length string returned in a response means the "transactionSavepointId" provided in the request is invalid.
  • Do not assume that the "transactionSavepointId" is a number in a string.
 string 0 to 255 bytes

transformBufferInitialBytes

The "transformBufferInitialBytes" property is optional and defaults to 0. It is a positive integer that specifies the number of bytes for the session to allocate initially for its transform buffer. Omit this property or set it to 0 when you do not plan on using the "transformCodeName" property to transform the JSON returned from the "getRecords..." actions. If you plan on transforming the JSON, you can set the "transformBufferInitialBytes" property to the number of bytes that you anticipate the server will need to store the results of each transform. If the server needs more memory, it automatically increases the buffer size; thus, this property is an optimization that helps prevent the server from doing expensive memory allocations.

 integer 0 or more bytes

transformPercentComplete

The "transformPercentComplete" property is an integer between 0 and 99 that is an estimate of the transformation progress when either the "rerunIntegrationTableTransformSteps" or "testIntegrationTableTransformSteps" action is transforming existing records in the integration table.

  • It is 0 when the action has finished, has not started, or is not transforming existing records.
  • It is between 1 and 99 while existing records are being transformed.
 integer 0 to 99

transformServices

The "transformServices" property is an optional array of objects that describes and controls FairCom's transform services. It defaults to the services connected when the server last started up.

"transformServices" [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": true
  }
],
 array of objects

"enabled"

"serviceLibrary"

"serviceName"

transformStatus

 The "transformStatus" property is a string that describes the state of the transform process. Example values include "running" and "done". string the status of the transform

transformStepMethod

The "transformStepMethod" property is a required string that specifies the type of transform, such as the "javascript" transform method that runs JavaScript to change the table's data or the "jsonToTableFields" transform method that extracts values from properties in a JSON field and stores them in other fields.

Note The "transformStepMethod" property replaces the deprecated "transformActionName" property.

The value of the "transformStepMethod" affects the value of the "transformService" property. The following table defines the possible values of the "transformService" property when combined with the "transformStepMethod". Notice that some transform step methods are built into the server and do not require you to specify the "transformService".

"transformStepMethod" value "transformService" value
"jsonToTableFields" null or omitted
"tableFieldsToJson" null or omitted
"jsonToDifferentTableFields" null or omitted
"javascript" "v8TransformService"
"siemensUdtPayloadToJson" "siemensUdtPayloadToJson"

Note If the "transformStepMethod" property is set to "javascript", the "transformService" property must be set to "v8TransformService".

 

 string enum

"javascript"

"jsonToDifferentTableFields"

"jsonToTableFields"

"tableFieldsToJson"

transformStepName

The "transformStepName" property is an optional string that assigns a name to each transform step.

 string 1 to 64 bytes

transformSteps

 specifies an array of transform objects. array of objects 0 or more objects

transformStepService

The "transformStepService" property is an optional string that specifies the name of a transform service, which is the user-defined name for a library (.dll, .so, .dylib) that implements the transform step method.

This property allows you to register your own transform libraries or use an older version of a FairCom library for backward compatibility.

Transform services are defined in the services.json file under the "transformServices" section. You can add and remove transform libraries to this list, such as your own transform libraries or specific versions of FairCom's transform libraries. Use the "serviceName" property to give each transform library a unique transform service name and use the "serviceLibrary" property to specify the filename of the library that implements the transform step method. On Windows the library filename ends with .dll. On Linux it ends with .so. On MacOS it ends with .dylib. Lastly, you must enable the transform service by setting "enabled" to true.

Example "transformServices" section in the services.json file.

"transformServices": [
  {
    "serviceName": "v8TransformService",
    "serviceLibrary": "v8transformservice.dll",
    "enabled": true
  }
],

Note If the "transformStepMethod" property is set to "javascript", the "transformStepService" property must be set to "v8TransformService" or to a user-defined transform service name associated with the "v8transformservice.dll" service library.

 string 1 to 64 bytes

triggers

 The "triggers" property is an array of enumerated strings that specifies a list of events on a table that create data change events. array of enum strings

"delete"

"insert"

"update"

type

 Identifies the type of the field. See Data types. string

"bit"

"tinyint"

"smallint"

"integer"

"bigint"

"real"

"float"

"number"

"money"

"date"

"time"

"timestamp"

"char"

"varchar"

"lvarchar"

"binary"

"varbinary"

"lvarbinary"

"json"

unmatchedKeys

The "unmatchedKeys" property is an array of key strings returned in a response. It contains a list of keys that an action could not find. An application can check this property to troubleshoot issues with key names.


The following actions look up keys by exact match and return this property:

  • "getValues"
  • "describeValues"
  • "deleteValues"
  • "renameKeys"
     
 array of strings zero or more key strings

updatedBy

The "updatedBy" property indicates the name of the account last used to update the code package.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 string The name of the account last used to update the code package.

updatedOn

The "updatedOn" property indicates the date and time the code package was last updated.

  "result": {
    "data": [
      {
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109"
      },
    ]
 timestamp The date and time the code package was last updated.

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

uri

 The "uri" property specifies the identifier name of the Rest resource. string 1 to 1024 bytes

uriPath

The "uriPath" property is optional. It is a string that indicates the path where the "serviceLibrary" file is stored. If specified, this value is appended to the default <faircom>/server/web/ folder path.

 string The file path for the service library.

username

The "username" property is a required string from 1 to 64 bytes. It is the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

Defaults to the account name of the currently logged-in user for Key-Value actions

 1 to 64 bytes

validateMqttPayload

 The "validateMqttPayload" property determines whether the FairCom server will attempt to validate the incoming MQTT message payload against the expected data type specified in the "mqttPayloadType" property. Boolean

true

false

value

The "value" property associates a value with a label. It is an optional JSON value that is associated with a label. It can be any JSON value. It defaults to null. 

 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 

In Key-Value actions, the required "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 JSON 0 to 65,500 bytes

variantFormat

 

The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request.

The "variantFormat" property has one of the following values: "binary", "json", "string", and "variantObject". It tells the server how to store and return values stored in variant fields. 

The server applies the "variantFormat" property to all variant fields affected by a JSON action, such as all variant fields inserted by the "insertRecord" action or all variant fields returned by the "getRecordsByIndex" action. If you want more control, set the "variantFormat" property to "variantObject" and you can use variant objects to independently set the variant type and encoding of each variant field in a JSON action.

A variant field is a flexible, strongly-typed field. It is flexible because each variant field in each record can store any type of data. It is strongly typed because each variant field in each record stores the type of value it contains.

A variant field's type can currently be set to "binary", "json", "string", and "boolean" values. In the future, you will be able to set it to other values, such as "jpeg", "xml", and user-defined types.

The following sections describe each value of the "variantFormat" property.

 

"variantFormat": "binary"

  • Use the "variantFormat": "binary" setting to store and return variant field values as binary values embedded in JSON strings.
  • The "binary" variant type ensures maximum compatibility and performance across all FairCom APIs, including JSON DB, SQL, CTDB, and ISAM.
  • When "variantFormat" is "binary", the server sets the variant's type to "binary" and stores raw bytes in the variant field.
  • The binary value can be any sequence of bytes.
  • The server does not validate the binary value.
  • The "binaryFormat" property specifies how the client and server format binary value. For example, the "hex" value embeds hexadecimal numbers in a JSON string.

 

"variantFormat": "json"

  • Use the "variantFormat": "json" setting to store and return variant field values as JSON values.
  • The "json" variant type provides maximum convenience in FairCom's JSON APIs.
  • The server validates JSON before it assigns it to a variant field.
  • The server converts a variant field to valid JSON before it returns the value of a variant field.
    • The "binaryFormat" property specifies the format of a binary variant value embedded in a JSON string.
    • The "numberFormat" property causes the server to return numbers as JSON numbers or JSON strings containing embedded numbers. All languages and JSON parsers work well with strings containing embedded numbers – even extremely large and small numbers.
  • When "variantFormat" is "json", the server sets the variant's type to "json" and stores a JSON value in the variant field.
    • The server does not store a JSON null; instead it marks the variant field as NULL. If the field is not nullable, the API returns an error.
    • The server stores a JSON string in the variant field as is. It includes the double quotes before and after the string's value and stores escaped characters without decoding them. For example, the server stores the JSON string, "my // string",  as "my // string". The server returns a JSON string exactly as it stores it.
    • The server stores a JSON number in the variant field as is. A number consists of the following ASCII characters 1234567890+-.eE. For example, the server stores the JSON number -123.45 as the ASCII characters -123.45. The server returns a JSON string exactly as it stores it.
    • The server stores a JSON true and false in the variant field as is. It stores and returns the ASCII characters true or false.
    • The server stores a JSON object and array as is. When it validates the JSON, it minimizes whitespace while preserving the ASCII characters representing the actual object or array. For example, the server stores the array [1,2,3]  as the ASCII characters [1,2,3].

 

"variantFormat": "variantObject"

  • Use the "variantFormat": "variantObject" setting to store and return variant field values as a variant object.
  • The variant object defines everything the server and client need to know about a variant, including its type, value, value encoding, and storage encoding.
  • The "variantObject" variant type provides maximum flexibility across all FairCom APIs and programming languages.
  • A variant object is a JSON object containing the following properties: "schema", "value", "valueEncoding", and "type". The "schema" property must have the value "jsonaction.org/schemas/variantObject".
  • When "variantFormat" is "variantObject", the server parses the variant object and uses its properties to determine how to store the variant value.
    • The "value" property contains the variant field's value .
    • The "valueEncoding" property specifies how the value is encoded so the server and client can decode the value. For example, assigning "hex" to "valueEncoding" indicates the "value" property contains a binary value embedded in a string as hexadecimal characters. The server decodes the value before storing it in the variant field. In FairCom's JSON APIs, the "binaryFormat" property in the "responseOptions" object specifies how the server encodes the binary value before returning it.
    • The "type" property specifies the variant's type, such as "json", "binary", and "string". In the future, the FairCom server will support additional types, such as "jpeg", "xml", and user-defined types.
  • When the "insertRecords" and "updateRecords" actions have "variantFormat": "variantObject" in "params", you must assign a variant object to each variant field.
  • A JSON action returns a variant object for a variant field value when you put "variantFormat": "variantObject" in "responseOptions".

 

Variant object examples

 

Binary value in a variant object

Add "binaryFormat": "base64" to "responseOptions" to tell the server to encode the variant value as Base64.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "ewogICJrZXkiOiAidmFsdWUiCn0=",
  "valueEncoding": ["base64"],
  "type": "binary"
}

 

Number in a variant object

Add "numberFormat": "string" to "responseOptions" to tell the server to embed the number in a string.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "123.45",
  "valueEncoding": ["string"],
  "type": "number"
}

 

Add "numberFormat": "number" to "responseOptions" to tell the server to encode the number as a JSON number.

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 123.45,
  "type": "number"
}

 

Boolean in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": true,
  "type": "boolean"
}

 

String in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "A JSON string with embedded \" double quote.",
  "type": "string"
}

 

JSON in a variant object

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": [1,"2",{"key": "value"}],
  "type": "json"
}
 string

"json"

"binary"

"string"

"variantObject"
The "verifyLinks" property is an optional Boolean property. When omitted or null, it defaults to true. When true, the action verifies that the specified labels, records, and tables exist. If your application has already validated that the labels, records, and tables exist, it can set "verifyLinks" to false, which provides a performance boost because the action does not need to look up this information. Boolean

true

false

willPayload

The "willPayload" property is required when a will message is present. It contains the payload of the last will message. You can set it to any JSON value, including binary values embedded in a JSON string or array.

 JSON  

willQoS

The property "willQoS" is reserved. The server sets it to 2.

 integer  

willRetain

The "willRetain" property is optional. It defaults to false. When true, it tells the FairCom server to send the will message to new subscribers as the first message they receive when subscribing to a topic.

 Boolean

true

false

willTopic

 The "willTopic" property is optional. It is a UTF-8 string containing the topic that the FairCom server will use to publish the will message. If you set it to an empty string, "", null, or omit it, the FairCom server will not add the will message to the connection. UTF-8 string  
 
 

 

 

 

Was this article helpful?

Give feedback about this article

Related Articles