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  
 
 

 

 

behavior reaction

Was this article helpful?

Give feedback about this article

Related Articles