Fields to JSON API reference

API reference for the fields/table to JSON transform method

Request examples

Minimal

{
  "api": "hub",
  "apiVersion": "1.0",
  "action": "createIntegrationTable",
  "params": {
    "tableName": "test1",

    "fields": [
      {
        "name": "In1",
        "type": "varchar"
      },
      {
        "name": "Out1",
        "type": "json"
      }
    ],

    "transformSteps": [
      {
        "transformStepMethod": "tableFieldsToJson",
        "mapOfPropertiesToFields": [
            {
                "fieldName": "in1",
                "recordPath": "out1.in1"
            }
        ]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

The following example is not the maximal example for creating an integration table; rather, it is the maximal example for creating a table to JSON API transform.

{
  "api": "hub",
  "apiVersion": "1.0",
  "action": "createIntegrationTable",
  "params": {
    "tableName": "test1",
    "ownerName": "admin",
    "databaseName": "faircom",

    "fields": [
      {
        "name": "In1",
        "type": "varchar"
      },
      {
        "name": "In2",
        "type": "float"
      },
      {
        "name": "In3",
        "type": "integer"
      },
      {
        "name": "In4",
        "type": "varchar"
      },
      {
        "name": "Out1",
        "type": "json"
      },
      {
        "name": "Out2",
        "type": "json"
      }
    ],

    "transformSteps": [
      {
        "transformStepMethod": "tableFieldsToJson",
        "mapOfPropertiesToFields": [
            {
                "fieldName": "in1",
                "recordPath": "out1.in1"
            },
            {
                "fieldName": "in2",
                "recordPath": "out1.in2"
            }
        ]
      },
      {
        "transformStepMethod": "tableFieldsToJson",
        "mapOfPropertiesToFields": [
            {
                "fieldName": "in3",
                "recordPath": "out2.in3"
            },
            {
                "fieldName": "in4",
                "recordPath": "out2.in4"
            }
        ]
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Request properties

Request properties

Accordion Title

Property Description Default Type Limits (inclusive)

accountDescription

The "accountDescription" property defines the account.

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

add

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

 Optional with default of {} array of objects

"rolenames"

"usernames"

addFields

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

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

"autoValue"

"defaultValue"

"length"

"name"

"newName"

"newPosition"

"nullable"

"scale"

"type"

allowedCipherSuites

The "allowedCiperSuites" property 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. 
 Optional with default of "" string No limits

alterFields

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

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

 

Example

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

amount

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

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

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

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

 Optional with default of 1 integer 1 to 65535

api

 The "api" property specifies which api the action will run on. Optional with default of "" string enum

"admin"

"db"

"hub"

"mq"

atEnd

 The "atEnd" property defines how the action commits or rolls back the statement it runs. For more details, see “atEnd”.  Optional with default of "rollbackOnError" string

"commit"

"rollbackOnError"

"rollback"

authTokens

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

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

autoTimeStamp

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

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

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

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

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

"fields": [
  {
    "name": "name",
    "type": "timestamp",
    "autoTimeStamp": "onupdate"
  }
]
 Optional with default of "none" string

"none"

"onInsert"

"onUpdate"

"onUpdateAndInsert"

autoValue

 The "autoValue" property indicates when and how the server automatically sets the field value. For more details, see “autoValue”.  Optional with default of "none" string

"none"

"incrementOnInsert"

"timestampOnInsert"

"timestampOnUpdate"

"timestampOnUpdate AndInsert"

"changeid"

 

binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  Optional with default of "hex" string One of the following: "base64", "hex", or "byteArray".

bitBooleanZeroValue

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

 Optional with default of false Boolean

true

false

bitEndPosition

The "bitEndPosition" must be greater than or equal to "modbusStartBitPosition" when present. When omitted, it defaults to the value of the "bitStartPosition" property.

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

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

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

For examples, see Modbus data types.

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

bitEnumValues

The "bitEnumValues" property specifies enumerated values that will be used to convert bits into readable text. The server retrieves bits from the address specified by "modbusDataAddress". The bits start from the offset specified by "bitStartPosition" and end at the offset defined by "bitEndPosition". The server converts these bits into an unsigned integer number, looks up the string in the "bitEnumValues" array, and writes the enumerated string value on the record. The server sets the value to null if the "bitEnumValues" array does not contain a string value corresponding to the integer value. You can optionally use the "bitLittleEndian" and "bitReversedOrder" properties to change how the server converts the value into an integer.

For examples, see Modbus data types.

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

bitIntSigned

The "bitIntSigned" property determines if bits will be interpreted as a signed integer value.

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

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

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

For examples, see Modbus data types.

 Optional with default of false Boolean

true

false

bitLittleEndian

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

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

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

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

For examples, see Modbus data types.

 Optional with default of false Boolean

true

false

bitPosition

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

bitReverseOrder

The "bitReverseOrder" property specifies whether or not the bit values will be read in reverse order. When true, the connector assigns bit values to the integer value starting from the end bit position to the start bit position; otherwise, it starts with the start bit position. It places bit values into the integer, starting from the rightmost bit to the leftmost.

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

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

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

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

For examples, see Modbus data types.

 Optional with default of false Boolean

true

false

bitStartPosition

The "bitStartPosition" property specifies where bits will start to be collected from.

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

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

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

For examples, see Modbus data types.

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

bitStringOneValue

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

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

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

For examples, see Modbus data types.

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

bitStringZeroValue

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

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

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

For examples, see Modbus data types.

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

body

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

"propertyPath"

"propertyValue"

bookmark

or

_bookmark_

The "bookmark" (or in some cases "_bookmark_") property designates a universal record identifier (aka bookmark). You can always use a bookmark to identify a record, even when the table lacks a primary key. 

 

The "bookmark" value is used when "startFrom": "bookmark", in which case the user will receive records starting from the value specified by the "bookmark" property (this does not apply to "_bookmark_"). This allows applications to quickly jump to a specific record and retrieve it along with its surrounding data.

 

Using "bookmark" to position the starting record:

{
  "api": "db",
  "action": "getRecordsFromCursor",
  "params": {
    "cursorId": "replaceWithCursorIdFromGetRecords",
    "startFrom": "bookmark",
    "bookmark": "000000FF",
    "skipRecords": -3,
    "fetchRecords": 6
  },
  "responseOptions": {
    "includeBookmarks": true,
    "dataFormat":     "objects"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 Optional with default of "" string 0 to 2048 bytes

bookmarks

The "bookmarks" property designates one or more universal record identifiers (aka bookmarks). You can always use a "bookmark" to identify a record, even when the table lacks a primary key. 

 

Example

{
   "api": "db",
   "action": "getRecordsByIds",
    "params": {
        "tableName": "no_key",
        "bookmarks": [
            "00000001",
            "00000002"
        ]
    },
    "authToken": "anAuthorizationTokenFromTheServer"
}
 Optional with default of [] array of strings 0 to 2048 bytes

brokerConnectionName

The "brokerConnectionName" property specifies a unique user-defined name for the connection. 

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

brokerConnectionNames

The "brokerConnectionNames" property contains a list of "brokerConnectionName" strings. 

  • 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.
 Optional with default of []

array

"brokerHostname"

"brokerPort"

"brokerUserName"

"isConnected"

"reconnectFrequencySeconds"

"statusCode"

"statusMessage"

brokerHostname

The "brokerHostname" property specifies the hostname of the broker. It must not be a zero-length string or contain only whitespace. It has a maximum length of 255 characters.

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

Required - No default value

 string 1 to 255 bytes

brokerPort

The "brokerPort" property specifies the TCP/IP port. 

  • 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.”
Optional with default of 1883 integer

2 to 65534

brokerUserName

The "brokerUsername" property specifies 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).

Optional with default of ""

 string 1 to 64 bytes

brokerUserPassword

The "brokerUserPassword" property contains the login password to the external broker and information about how that password might be encrypted. It is VARCHAR(500). Additional specifications may be added in the future.

 

Example

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

Optional with default of ""

 string 0 to 256 bytes

caCertificateFilename

The "caCertificateFilename" property specifies the name and optional path of the CA certificate file (such as "ca.pem").

  • 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.
 Optional with default of "" string No limits

caseInsensitive

The "caseInsensitive" property determines if case comparisons for index key values accounts for case. When false, the server stores index key values in mixed case for comparisons.

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

"fields": [
  {
    "caseInsensitive": true
  }
]
 Optional with default of false Boolean

true

false

certificateAuthoritiesFilename

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

certificateFilename

 The "certificateFilename" property specifies the name and optional path of a server certificate file. Optional with default of "" string No limits

changeIdField

The "changeIdField" property specifies the name of the field used for the change-tracking functionality.

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

 Optional with default of "" string 1 to 64 bytes

cleanSession

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

The "cleanSession" property specifies whether or not to clean the session after the client disconnects. When true, the MQ engine resets the current session, and when the client disconnects, the engine removes the session's settings, subscriptions, and message position. Because you normally want the engine to remember your message position between sessions, you rarely set "cleanSession" to true.

 Optional with default of false Boolean

true

false

clientCertificateEnabled

 The "clientCertificateEnabled" property enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates. Optional with default of false boolean

true

false

clientCertificateFilename

The "clientCertificateFilename" property specifies the name of the client certificate file. 

 Required - No default value string No limits

clientPrivateKeyFilename

The "clientPrivateKeyFilename" property specifies the name of the client private key file.

 Required - No default value string No limits

clientName

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

clientNames

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

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

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

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

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

 Optional with default of "" an array of "clientName" strings 0 or more strings

cloneUsername

The "cloneUsername" property specifies the new of name of the clone account.

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

 

 Required - No default value string 1 to 31 bytes

clonePassword

The "clonePassword" property specifies the code used to authenticate the clone account.

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

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

 

 Required - No default value string 1 to 63 bytes

cloneRoles

The "cloneRoles" property specifies whether the cloned account will also have the roles assigned to the source account.

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

 

 Optional with default of true Boolean

true

false

cloneDescription

The "cloneDescription" property specifies the "accountDescription" for the clone account.

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

 

 Optional with default of "" string 0 to 31 bytes

cloneMetadata

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

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

code

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

codeFormat

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

codeLanguage

 The "codeLanguage" property specifies the programming language of the code contained in the "code" property . Any string value is accepted. Currently, "javascript" and "json" are the only types of code the FairCom server can use. Required - No default value string

"javascript"

"json"

codeName

The "codeName" property contains the user-defined name for the code package.

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

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

 Required - No default value string 1 to 64 bytes

codeNames

The "codeNames" property specifies the names of the code packages you want to be described.

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

codeServices

 The "codeServices" property specifies which programming languages are available in the product. Optional with default of [] array of objects

"serviceName"

"serviceLibrary"

"enabled"

codeStatus

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

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

codeType

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

 Required - No default value string

"integrationTableTransform"

"getRecordsTransform"

codeTypeFilter

 The "codeTypeFilter" property filters results by the value in the "codeType" property. If the array is empty, null, or omitted, it matches all code types; otherwise, it returns code packages with a code type that matches one of the array's values. Optional with default of "" array

"integrationTableTransform"

"expression"

"getRecordsTransform"

"globalFunction"

"module"

"event"

"beforeTrigger"

"afterTrigger"

"job"

codeVersion

 The "codeVersion" property specifies the code's version stored in the version history. Required - No default value integer 0 to 2147483647

collectStats

The "collectStats" property determines whether the server collects statistics. When set to false , the server does not collect statistics. If set to true, the server will collect statistics that it uses to maximize performance.

"params": {
  "collectStats": true
}
 Optional with default of true Boolean

true

false

command

The "command" property specifies a preset action that modifies the broker connection. If set to a valid command string, it executes the command.

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

Optional with default of "applySettingsWhenDisconnected"

 string

"disconnect"

"reconnect"

"applySettingsNow"

"applySettingsWhenDisconnected"

comment

 The "comment" property explains the code change. Optional with default of "" string 1 to 65,535 bytes

commentFilter

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

compression

The "compression" property defines how an index key is compressed. The default value is "auto".

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

"on"

"off"

"auto"

conditionalExpression

The "conditionalExpression" property contains an expression using FairCom's expression language. It applies a filter to the index, which prevents the index from including records that do not match the expression.

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

connectionStatusFilter

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

 Optional with default of [] array

"disconnected"

"connected"

"connectedTemporarily"

"unknown"

connectorId

        

connectorIdFilter

 The "connectorIdFilter" property filters the response by the specified unique integer ID of a connector. The "listTags" action includes the tag associated with the specified connector. Optional with default of [] array zero or more connector id integers

containsTransformSteps

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

 Optional with default of null Boolean

true

false

contentType

The "contentType" property specifies the content type, typically set to an IANA media type or a custom type you define. It is used by MQTT 5.

 Optional with default of "" string an IANA media or custom type

correlationData

The "correlationData" property can be used to set a useful value when using MQTT for request-response messages. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include this "correlationData" value (if any) to connect the response to the published message.

 Optional with default of "" JSON 0 to 65,500 bytes

createRecByteIndex

The "createRecByteIndex" property creates a special index for quickly walking variable-length records backward when set to true. 

Note It is not needed for fixed-length records.

"params": {
  "createRecByteIndex": true
  }
 Optional with default of false Boolean

true

false

cursorId

The "cursorId" property specifies a unique cursor identifier returned by the server.

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

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

Required - No default value

 string 0 to 225 bytes

databaseName

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

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

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

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

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

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

databaseNameFilter

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

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

string

 1 to 64 bytes

dataBlockNumber

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

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

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

dataChangeStreamStatusFilter

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

"scheduled"

"jumpstarting"

"running"

"failed"

"initializing"

"pausing"

"paused"

dataCollectionIntervalMilliseconds

The "dataCollectionIntervalMilliseconds" property schedules the connector to collect data periodically using the specified number of milliseconds. 

 Optional with default of 10000 (10 seconds). integer 0 and negative values are invalid.

dataCollectionBufferCount

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

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

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

 Optional with default of 1 integer 1 to 65535

dataFormat

The "dataFormat" property 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.
 Optional with default of "arrays" string

"default"

"arrays"

"objects"

dataPersistenceStrategy

The "dataPersistenceStrategy" property controls when a connector writes collected data to a record in the input table specified by "tableName". 

  • The "onSchedule" setting causes the connector to persist each collected value, which occurs on the schedule set by the "dataCollectionIntervalMilliseconds" property. This setting is useful for continuously collecting device data for trend analysis and machine learning.
  • The "onChange" setting causes the connector to collect data on the schedule set by the "dataCollectionIntervalMilliseconds" property, but it only persists data when it changes. This allows the connector to detect and store data changes as events, such as alerts and status updates. This setting greatly reduces data storage for infrequently changing telemetry, such as changes to a temperature sensor.

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

 Optional with default of "onSchedule" string

"onSchedule"

"onChange"

dataReadingTimeoutMilliseconds

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

dataType

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

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

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

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

dateFormat

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

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

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

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

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

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

"ccyy.mm.dd"

"mm.dd.ccyy"

"mm.dd.yy"

"dd.mm.ccyy"

"dd.mm.yy"

"ccyymmdd"

"yymmdd"

"iso8601"

"utc"

deadbandLowerLimit

 The "deadbandLowerLimit" property specifies the value of the deadband's lower limit. A change is saveable when it is less than the deadband lower limit. For more details, see “deadbandLowerLimit”. Optional with default of "disabled" integer No limit

deadbandUpperLimit

 The "deadbandUpperLimit" property specifies the value of the deadband's upper limit. A change is saveable when it exceeds the deadband upper limit. For more details, see “deadbandUpperLimit”.  Optional with default of "disabled" integer No limit

defaultApi

The "defaultApi" property specifies the default value of the "api" property when it is omitted from an action request. 

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

FairCom DB defaults to "db"

FairCom Edge defaults "hub"

FairCom MQ defaults "mq"

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

 Defines the default value of “binaryFormat”. 

Optional with default of "hex"

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

defaultDatabaseName

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

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

FairCom DB defaults to "ctreeSQL"

FairCom Edge defaults to "faircom"

FairCom MQ defaults to "faircom"

 string 1 to 64 bytes

defaultDebug

The "defaultDebug" property defines the default value of the "debug" property for all requests in a session. 

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.
 Optional with default of "max" string enum

"none"

"max"

defaultOwnerName

The "defaultOwnerName" property 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. 

  • 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.

Optional with default of the session's "username" property.

 string 1 to 64 bytes

defaultResponseOptions

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

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"
    }

Optional with default of {}

 object

"binaryFormat"

"dataFormat"

"numberFormat"

"stringFormat"

"variantFormat"

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
  },
 Optional with default of 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
  },
 Optional with default of "autoPurge" string enum

"doNotPersist"

"neverPurge"

"autoPurge"

defaultRetentionUnit

The "defaultRetentionUnit" property specifies the type of retention unit if the "retentionUnit" property is omitted. It is used in tandem with "defaultRetentionUnit". The retention period describes how many units, and the retention unit describes 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
  },
 Optional with default of "week" string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

defaultValue

 The "defaultValue" property specifies the default value of a field. It is used when a record is inserted without specifying a value for the field. The server coerces the string value into the proper field type.  Optional with default of "" 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.

 Optional with default of "json" string

"json"

"binary"

"string"

"variantObject"

deleteAllRecords

The "deleteAllRecords" property deletes all records in a table when set it to true.

 Required - No default value Boolean

true

false

deleteFields

The "deleteFields" property specifies the names of fields to remove from a table.

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

deprecated

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

 

 Optional with default of false Boolean

true

false

null

deprecatedFilter

The "deprecatedFilter" property filters the results of the action by the value in the "deprecated" property. When set to null, the response includes deprecated and non-deprecated labels. Set it to true to include only deprecated labels and false to include only non-deprecated labels.

 

 Optional with default of false Boolean

true

false

null

description

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

Optional with default of "".

"unknown" for Thing API 

 string

0 to 65,500 bytes

1 to 512 bytes for the Thing API 

descriptionFilter

The 

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

 

 Optional with default of null string 1 to 65,500 bytes

disableDatetime

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

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

disableTransformSteps

The "disableTransformSteps" property determines if the transform steps are active without removing them from the integration table. When true, it prevents the server from running an integration table's transform steps on newly inserted records. When false, the transform steps run normally. It is useful to quickly stop a broken transform process.

 Optional with default of false Boolelan

true

false

downgradeQoS

The "downgradeQoS" property controls how FairCom's servers manage the Quality of Service (QoS) of subscriptions to this topic. 

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

true

false

eipTagElementCount

 The "eipTagElementCount" property specifies the number of elements in the tag. All tags are treated as arrays. Tags that are not arrays are considered to have a length of one element. Optional with default of 1 int32 0 and negative values are invalid.

eipTagName

The "eipTagName" property specifies the full name of a tag, such as MyTag[10,42] for CIP-based PLCs.

For CIP-based PLCs, use the format Program:<program name>.<tag>.

<program name> is the program name in which the tag is created
<tag> is the name in the program.
Examples: Program:MyProgram.MyTag accesses the tag MyTag in the program MyProgram.

PCCC-based PLC examples include N7:4, ST18:26, L20:2, MG14:6.en, B3:4/2, and so forth. Many common field name abbreviations are supported.

 Required - No default value string No limit

eipTagPath

The "eipTagPath" property specifies additional connection information with the format "p,s"

p is the communication Port Type

1 for Backplane
2 for Control Net/Ethernet, DH+ Channel A, or DH+ Channel B
3 for Serial
s is the slot number where the PLC is installed, such as 0, 1, 2.

 Optional with default of "1,0" string String with the format "p,s"

eipTagSize

 The "eipTagSize" property specifies the binary format of the PLC data represented by the tag. Required - No default value string "bit"
"int8"
"uint8"
"int16"
"uint16"
"int32"
"uint32"
"int64"
"uint64"
"float32"
"float64"
"byte"
"string"

eipTagType

The "eipTagType" property specifies the buffer size in bytes to handle tag data.

If not specified, the buffer size is defined based on the tagType. For example, 1 for int8 and 4 for int64.

For string tagType, the default value is 0 which will set the buffer to the maximum string size for the device.

Let the server define this property. and set it yourself only when necessary.

 Optional - depending on the dataType value Integer 0, 1, 2, 4, or 8

enabled

The "enabled" property determines whether or not the specified 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"
        }
 Optional with default of true Boolean

true

false

enableDatetime

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

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

endTimestamp

The "endTimestamp" property 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.

 Optional with default of null string containing an ISO8601 timestamp

"2025-08-19"

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

"2025-08-19T01:13"

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

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

enum

The "enum" property assigns an integer from -32768 to 32767 to a label. You can use this property to assign an application's hardcoded enumerated value to a label.

 

 Optional with default of 0 smallint -32768 to 32767

enumFilter

The "enumFilter" property filters the results of the action by the value of the "enum" property. When null, this property provides no filtering. The "enum" property of a label must match one of the integers in the array to be included in the results.

 

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

expiredMessagesFilter

The "expiredMessagesFilter" property indicates whether the response should include expired messages. 

  • "include" returns expired messages in the results.
  • "exclude" omits expired messages from the results.
  • "only" returns only expired messages in the results.
 Optional with default of "include" string

"include"

"exclude"

"only"

expirySeconds

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

 Optional with default of null integer No limits

fetchRecords

The "fetchRecords" property specifies which direction the server will fetch records. A positive integer fetches that number of records forward. A negative integer fetches that number of records backward. 

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

fieldDelimiterValue

The "fieldDelimiterValue" property should only be changed for backward compatibility with legacy c-tree files.

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

"params": {
  "fieldDelimiterValue": 255
}
 Optional with default of 32 integer 0 to 255

fieldName

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

fieldNames

The "fieldNames" property specifies 1 or more field names.

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

Optional with default of [].

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

 array 1 to 64 bytes

fields

The "fields" property specifies which fields in a table are included in the index and how each field should be indexed.

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

Required - No default value

 array of objects

"caseInsensitive"

"name"

"reverseCompare"

"sortDescending"

"autotimestamp"

"autoValue"

"defaultValue"

"length"

"name"

"nullable"

"primaryKey"

"scale"

"type"

filename

The "filename" property contains the name of the index file on the file system. 

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

fixedLengthCharFormat

The "fixedLengthCharFormat" property controls how the "getRecords" actions return values from fields with the "char" data type (CT_FSTRING), which is FairCom's fixed-length string field. It does not apply to other field types, such as "varchar", "lvarchar", "binary", "varbinary", and "lvarbinary".

 

For more details, see “fixedLengthCharFormat”. 

 Optional with default “sql” string

“sql”

“trimTrailingSpaces”

“trimTrailingPadding”

fixedOutput

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

 Optional with default of false Boolean

true

false

folder

The "folder" property defines the file system folder where an item will be stored. 

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

 

Request example

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

forceRecordCount

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

Optional with default of false

Boolean

true

false

forwardQos

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

 Optional with default of 1 integer

0

1

2

forwardToExternalBrokers

 The "forwardToExternalBrokers" property specifies one or more brokers to forward the message to. All messages sent to this topic will be forwarded to each of these external brokers using the specified topic name. For more details, see “forwardToExternalBrokers”.

Optional with default of []

 array of objects

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

"brokerConnectionName"

"forwardQos"

"topic"

forwardToTopics

The "forwardToTopics" property causes FairCom's servers to take all messages sent to this topic and automatically forward them to each of the topics specified in the array. These messages are forwarded within the same instance. 

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

Optional with default of []

 array of strings One or more strings

group

The "group" property groups labels into a lookup list or tag set. It is a 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. 

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.

 Optional with default of "" string 1 to 64 bytes of UTF-8 encoded characters

groupFilter

The "groupFilter" property filters the results of the action by the value of the "group" property. When null, this property provides no filtering. Each string is the name of a group and may be up to 64 bytes long. A label's group must match one of the groups in the array to be included in the results. The empty string "" is a valid group name.

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

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

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

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

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

growthExtent

The "growthExtent" property specifies the number of bytes that a server uses to increase a file's size. 

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

healthFilter

The "healthFilter" property filters the returned sessions by the selected "sessionHealth" statuses.

 Optional with default of [] array

"healthy"

"unhealthy"

"offline"

hierarchyDelimiter

The "hierarchyDelimiter" property delimits hierarchical levels in the key. When set to "", this property 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".
     
 Optional with default of "" string 1 byte

host

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

hostnames

The "hostnames" property specifies zero or more hostnames assigned to the device. Each item in the array should be a different hostname. 

 

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.
 Optional with default of [] string Array of user-defined hostnames. Each hostname is a string from 0 to 64 bytes. Values are managed in the Label API with the group of "faircom/hostnames".

hostnamesFilter

The "hostnamesFilter" property finds things that contain one of the hostnames included in the property. Each string specifies a partial or complete hostname or IP Address that a thing uses. A thing may have zero or more hostnames. 

 

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

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

id

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

 

 Automatically generated by the server integer

0 to 2147483647

0 to 9223372036854770000 in the Thing API

ids

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

 

 Automatically generated by the server array of integers Each array item is an integer from 0 to 2147483647

idFilter

The "idFilter" property filters the results of the action by the value of the "id" property. It defaults to [], which provides no filtering. The "id" property of a label must match one of the integers in the array to be included in the results.

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

 

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

idleConnectionTimeoutSeconds

The "idleConnectionTimeoutSeconds" property specifies the number of seconds that a session with no activity will stay open.

A value of 0 keeps a session open indefinitely.

Optional with default of 3600

integer

0 to 2147483647

idleCursorTimeoutSeconds

The "idleCursorTimeoutSeconds" property specifies the number of seconds to keep a cursor with no activity 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.

Optional with default of 600

 integer

0 to 2147483647

ids

The "ids" property specifies 0 or more ids. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. 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.

Optional with default of "null".

Required when "primaryKeys" is omitted

 array 0 or more ids

ignoreChangeIdProtection

The "ignoreChangeIdProtection" property causes the server to update the record regardless of the value of "changeId", when "true". 

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

true

false

immediatelyCollectDataOnStart

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

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

true

false

immutableKeys

The "immutableKeys" property prevents the fields of an index from being updated when true. 

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

true

false

includeBookmarks

The "includeBookmarks" property causes the server to add the "_bookmark_" field to each record returned by a query when set to true. See "_bookmark_" for more info and a usage example. 

 Optional with default of false Boolean

true

false

includeDeactivatedCode

The "includeDeactivatedCode" property specifies whether to include deactivated code packages in the response. The results include activated and deactivated code packages if this value is null or omitted. If set to true, the results only include deactivated code packages. If set to false, the results only include activated code packages.

 

 Optional with default of null Boolean

true

false

includeDescription

The "includeDescription" property specifies whether to include the "description" property in the response. 

Optional with default of true

Boolean

 

true

false

null

 

includedFields

The "includedFields" property determines which source table fields in the data change event will be included. When empty, this property includes all fields.

 Optional with default of [] array of strings 0 or more strings

includeExistingRecords

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

 Optional with default of null Boolean

true

false

includeExistingRecordsFilter

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

 Optional with default of null Boolean

true

false

includeExpiredMessages

The "includeExpiredMessages" property includes expired messages in a subscription when set to true. A message has expired when the "messageHasExpired" property in the response is true.

 

 Optional with default of true Boolean

true

false

includeInputConnectorProperties

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

 

For more details, see "includeInputConnectorProperties".

 Optional with default of [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includeMessageMetadata

The "includeMessageMetadata" property includes the message's "id", "timestamp", "error", and "log" properties when set to true.

 Optional with default of false Boolean

true

false

includeMetadata

The "includeMetadata" property specifies whether to include the "metadata" property in the response.

Optional with default of true

Boolean

 

true

false

null

 

includeMetrics

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

 

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

 Optional with default of false Boolean

true

false

includeMqttProperties

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

 Optional with default of false Boolean

true

false

includeOtherFields

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

 Optional with default of false Boolean

true

false

includeOutputConnectorProperties

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

 

For more details, see "includeOutputConnectorProperties".

 Optional with default of [] array of strings

"connectorName"

"connectorId"

"settings"

"serviceName"

"metadata"

includePrimaryKey

 The "includePrimaryKey" property 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. Optional with default of "forPrimaryKeyFields" string enum

"forEachField"

"forPrimaryKeyFields"

"never"

includePublishedTopics

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

 Optional with default of true Boolean

true

false

includeStats

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

 Optional with default of true Boolean

true

false

includeSubscribedTopics

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

 Optional with default of true Boolean

true

false

includeSystemTables

The "includeSystemTables" property causes the server response to include system tables in the list of tables when set to true.

 

Example

"params": {
  "includeSystemTables": true
}
 Optional with default of false Boolean

true

false

includeThingProperties

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

"id"

"thingName"

"status"

"manufacturer"

"model"

"serialNumber"

"type"

"purpose"

"description"

"location"

"labels"

"hostnames"

"metadata"

"photo"

includeTopicProperties

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

includeTransformFields

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

 Optional with default of false Boolean

true

false

indexFieldFilters

The "indexFieldFilters" causes records to be included in the results when all the field comparison operations return true. Each object is a field comparison operation. A comparison operation compares its value to the index key of a record. 

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

"fieldName"

"operator"

"value"

indexFields

The "indexFields" property is used by an index to find a record with matching field names and values. 

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

"fieldName"

"value"

indexFileExtension

The "indexFileExtension" property specifies the file system extension to use for a table's index files. If omitted, it defaults to ".idx".

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

"params": {
  "indexFileExtension": ".tidx"
}
 Optional with default of ".idx" string 0 to 64 bytes

indexFilter

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

 

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

Required - No default value

 object

"indexName"

"partialKey"

"indexFieldFilters"

 

indexName

The "indexName" property specifies the name of an index. A zero-length "indexName" is invalid.

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

Required - No default value

 string 1 to 64 bytes

inParams

The "inParams" property specifies the values of input parameters. 

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

[]

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

 array of objects

"name"

"value"

inputName

The "inputName" property specifies the unique name of an input. A FairCom generated name follows the pattern "Input #n from <pluginName> to <databaseName>.<ownerName>.<tableName>".

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

Required - No default value

 string 1 to 100 bytes

inputNames

 The "inputNames" property specifies the names of the inputs you want to be described in the result. Optional with default of [] array 0 or more strings

integrationTableIdFilter

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

ipAddress

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

isPrimaryIndex

The “isPrimaryIndex” property specifies whether or not the index being created will be the primary key index of its table:

  • If “true”, the new index will be primary. 
  • If “false”, it will not. 
  • If an index does not meet the following criteria required to be a primary index, and you attempt to make it one, an error will be returned: 
    • It must be a unique index
    • Its fields must be non-nullable
    • It cannot have a conditional table filter expression
    • It cannot be a temporary index
 Optional with default of false Boolean

true

false

keepAliveSeconds

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

 Optional with default of 0 integer No limit

key

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

Optional with default of "".

 

Required in the Key-Value API 

 string 1 to 128 bytes

keys

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

keyStore

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


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


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


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


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


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

 Required - No default value string enum

"global"

"role"

"user"

keyValuePairs

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

label

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

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

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

 Optional with default of null object 
"label": {
  "group": "group name",
  "name": "label name"
}

labelID

The "labelId" property uniquely identifies a label.

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

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

 Optional with default of null integer 0 to 4294967296

labels

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

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

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

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

 

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

 

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

 

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

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

Required - No default value

 

Defaults to

[] when using tag actions

 array of objects

1 or more label objects

 

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

labelsFilter

The "labelsFilter" property finds tags that contain one of the labels included in the property. Each string is a label. A tag may have zero or more labels. Each label is a string from 1 to 64 bytes.

 

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

 Optional with default of [] array of strings zero or more label strings

length

The "length" property specifies the length of a table field. For more details, see “length”.

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

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

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

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

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

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

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

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

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

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

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

 

Request example

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

"fields": [
  {
    "name": "a",
    "type": "char",
    "length": 16
  },
  {
    "name": "b",
    "type": "varchar",
    "length": 65500
  }


],
 Optional with default of null integer 1 to 65500

localDatabaseName

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

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

localDatabaseNameFilter

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

 Optional with default of null string 1 to 64 bytes

localDataFilePath

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

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

localDataFilePathFilter

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

 Optional with default of null string 1 to 64 bytes

localOwnerName

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

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

localOwnerNameFilter

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

 Optional with default of null string 1 to 64 bytes

localTableName

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

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

localTableNameFilter

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

 Optional with default of null string 1 to 64 bytes

location

The "location" property specifies the item's location. A thing may have one location. 

 

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.
 Optional with default of "unknown" string

1 to 64 bytes

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

locationFilter

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

lockoutAfterNFailedAttempts

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

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

lockoutWaitMinutes

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

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

logLevel

 The "logLevel" property defines what type of messages the replication agent will log. Optional with default of "warning" string enum

"off" - no messages logged

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

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

"warning" - logs warning and error messages

"error" - logs error messages

logTransformOverwrites

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

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

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

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

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

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

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

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

 Optional with default of false Boolean

true

false

manufacturer

The "manufacturer" property specifies the manufacturer of the thing. A thing may have one manufacturer. Many things can share the same manufacturer. 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.
     
 Optional with default of "unknown" string 1 to 64 bytes

manufacturerFilter

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

mapOfPropertiesToFields

The "mapOfPropertiesToFields" property takes fields in the table and maps them to a field containing JSON properties. Each object maps a field in a table to a JSON property in another field.

  • Required properties
    • "recordPath"
    • "fieldName"
  • Optional properties
    • "binaryFormat"
    • "numberFormat"
    • "variantFormat"
    • "dateFormat"
    • "timeFormat"
 Optional with default of [] array

"binaryFormat"

"dateFormat"

"fieldName"

"numberFormat"

"recordPath"

"timeFormat"

"variantFormat"

maxCodeVersion

The "maxCodeVersion" property causes the server to return code packages up to and including the specified version.

 

 Optional with default of the current version integer 1 to 2147483647

maxDaysBeforePasswordMustChange

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

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

maxDeliveryRatePerSecond

The "maxDeliveryRatePerSecond" property sets the throttle rate for current and new subscribers of the topic. 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.
 Optional with default of 0

int32

0 to 2147483647

maxHealthyBacklogRatePerMinute

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

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

 Optional with default of 0 integer Any positive integer

maxHealthySendRatePerMinute

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

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

 Optional with default of 0 integer Any positive integer

maxHealthySubscribedTopicFiltersCount

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

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

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

 Optional with default of 0 integer Any positive integer

maximumPacketSize

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

 Optional with default of 1024 integer  

maxInflightMessages

The "maxInflightMessages" property protects subscribers from receiving messages faster than they can handle.

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

int32

0 to 2147483647

maxMessages

The "maxMessages" property specifies the number of messages to return from a "getMessages…" action. The number of returned messages will be equal to or less than this maximum.

 Optional with default of 20 integer 1 to 100000

maxMinutesBeforeNextLogin

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

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

maxRecords

 The "maxRecords" property specifies the maximum number of records to be returned. It is used with "skipRecords" to paginate the results. If the value is not null or omitted, the server returns the maximum number of results specified by "maxRecords". Optional with default of 20  integer -1 to 65535

maxSecondsBeforeConnectingToNextServer

 The "maxSecondsBeforeConnectingToNextServer" property 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. Optional with default of 30 int32 1 to 65535

maxUnsavedEvents

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

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

memoryArea

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

memoryLimit

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

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

memoryRule

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

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

"default"

"absolute"

"guideline"

messages

The "messages" property specifies the message to be published to MQ as well as information about the message.

 Optional with default of [] array of objects

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

"binaryFormat"

"contentType"

"correlationData"

"expirySeconds"

"payload"

"responseTopic"

"retain"

"userProperties"

metadata

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

metadataFilter

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

minCodeVersion

 The "minCodeVersion" property causes the server to return code packages starting with the specified version. Optional with default of the first version integer 1 to 2147483647

minHealthySendRatePerMinute

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

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

 Optional with default of 0 integer Any positive number

minHealthySubscribedTopicFiltersCount

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

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

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

 Optional with default of 0 integer Any positive number

modbusBaudRate

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

modbusConvertToFloat

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

"no"

"divideByInteger"

"appendAdjacentRegisters"

"appendAdjacentRegistersReversed"

modbusDataAccess

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

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

"coil"

"discreteinput"

"holdingregister"

"inputregister"

modbusDataAddress

The "modbusDataAddress" property specifies where the Modbus protocol should read or write a value to a memory address on a device. 

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

 Required - No default value int16 0 to 65536

modbusDataAddressType

 The "modbusDataAddressType" property specifies if the modbusDataAddress is zero-based or one-based. Optional with default of "zeroBased" string

"zeroBased"

"oneBased"

modbusDataBits

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

modbusDataLen

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

Note If "modbusDataType" is specified, this value is ignored

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

modbusDataType

 The "modbusDataType" property specifies how to convert Modbus binary data types to JSON types. Choose a type that matches the byte order of the data type. The byte order is specified using the letters ABCDEFGH.  Optional with default of "" string Any Modbus Data Type

modbusDecimalDigits

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

 Optional with default of 2 integer 1 to 5

modbusDivisor

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

 Required if "modbusConvertToFloat" is "divideByInteger". Otherwise defaults to 1 integer

1 to 65536

Typical values are 10, 100, 1000, and 10000

modbusParity

 The "modbusParity" property (RTU only) specifies the data parity. Optional with default of "even" string "none", "even", "odd"

modbusProtocol

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

"TCP"

"RTU"

modbusSerialPort

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

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

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

 Required - No default value string No limit

modbusServer

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

modbusServerPort

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

modbusStopBits

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

modbusUnitId

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

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

For serial communication, the range is 1 to 255

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

 Optional with default of 1 int16 0 to 255

model

The "model" property specifies a thing's model. A thing may have one model. Many things can share the same model number.

 

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.
 Optional with default of "unknown" string 1 to 64 bytes

modelFilter

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

mqttPayloadType

The "mqttPayloadType" property specifies the variant type format of the "source_payload" field. For more details, see mqttPayloadType. 

 Optional with default of "binary" string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

"variantObject"

mqttProtocol

 The "mqttProtocol" property specifies the version of MQTT protocol to use in your session. Optional with default of 5.0 string enum

"3.1.1"

"5.0"

mtconnectDeviceUuid

The "mtconnectDeviceUuid" property specifies the identifier of the device that supplies data to the connector. For more details, see "mtconnectDeviceUuid".

 Required - No default value string No limit

mtconnectDataItemId

 The "mtconnectDataItemId" property specifies the identifier of the data that the MTConnect connector collects. For more details, see "mtconnectDataItemId". Required - No default value string No limit

mtconnectCategoryPropertyPath

The "mtconnectCategoryPropertyPath" property specifies the location in the JSON document to store the MTConnect category of the data item. For more details, see "mtconnectCategoryPropertyPath".

 Optional with default of null string JSON path

mtconnectComponentNamePropertyPath

The "mtconnectComponentNamePropertyPath" property specifies the location in the JSON document to store the MTConnect component name of the data item. For more details, see "mtconnectComponentNamePropertyPath".

 Optional with default of null string JSON path

mtconnectDataItemIdPropertyPath

The "mtconnectDataItemIdPropertyPath" property specifies the location in the JSON document to store the MTConnect dataItemID of the data item. For more details, see "mtconnectDataItemIdPropertyPath".

 Optional with default of null string JSON path

mtconnectDataNamePropertyPath

The "mtconnectDataNamePropertyPath" property specifies the location in the JSON document to store the MTConnect data name of the data item. For more details, see "mtconnectDataNamePropertyPath".

 Optional with default of null string JSON path

mtconnectDataTypePropertyPath

The "mtconnectDataTypePropertyPath" property specifies the location in the JSON document to store the MTConnect data type of the data item. For more details, see "mtconnectDataTypePropertyPath".

 Optional with default of null string JSON path

mtconnectDeviceNamePropertyPath

The "mtconnectDeviceNamePropertyPath" property specifies the location in the JSON document to store the MTConnect device name that provides the data item. For more details, see "mtconnectDeviceNamePropertyPath".

 Optional with default of null string JSON path

mtconnectDeviceUuidPropertyPath

The "mtconnectDeviceUuidPropertyPath" property specifies the location in the JSON document to store the MTConnect deviceUuid of the device that provides the data item. For more details, see "mtconnectDeviceUuidPropertyPath".

 Optional with default of null string JSON path

mtconnectSequencePropertyPath

The "mtconnectSequencePropertyPath" property specifies the location in the JSON document to store the integer sequence number of the data item. For more details, see "mtconnectSequencePropertyPath".

 Optional with default of null string JSON path

mtconnectTimestampPropertyPath

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

 Optional with default of null string JSON path

name

The "name" property is the name of a label or field. 

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

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

 

 Required - No default value string 1 to 64 bytes

nameFilter

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

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

 

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

newCodeName

 The "newCodeName" property causes the server to rename the code package from the current "codeName" to the "newCodeName". The server does not change the "codeName" when null or omitted. Optional with default of null string 1 to 64 bytes

newDatabaseName

 The "newDatabaseName" property causes the server to use the new database as the target for the action. When null or omitted, the server runs the action in the current database. Optional with default of null string 1 to 64 bytes

newDeprecated

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

 Optional with default of null Boolean

true

false

null

newDescription

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

 Optional with default of "" string 1 to 65,500 bytes

newEnum

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

 Optional with default of null smallint -32768 to 32767

newGroup

The "newGroup" property assigns a new group name to an existing label. It defaults to null, which means the action does not change the label's group. 

 Optional with default of null string 1 to 64 bytes

newKey

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

newMetadata

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

 Optional with default of {} JSON 0 to 65,500 bytes

newName

The "newName" property assigns a new label name to an existing label or table. It defaults to null, which means the action does not change the label's or table's name. 

 

 Optional with default of null string 1 to 64 bytes

newOwnerName

 The "newOwnerName" property causes the server to use the new owner name as the target for the action. When null or omitted, the server runs the action using the current owner name. Optional with default of null string 1 to 64 bytes

newPosition

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

 

Request example

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

newSequence

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

 Optional with default of null double Any floating point or integer number.

newSubscriberDeliveryMode

The "newSubscriberDeliveryMode" property defines how new subscribers receive messages. 

  • 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.

Optional with default of "newMessages"

 string

"newMessages"

"storedMessages"

newSubscriberMaxDeliveredMessages

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

  • 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.

 Optional with default of -1 integer or "all" -1 to 2147483647 or "all"

newTableName

The optional "newTableName" property specifies a new name for the table. Use the "newTableName" property to rename a table. 

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

"params": {
  "tableName": "old_table_name"
  "newTableName": "new_table_name"
}
 Optional with default of null string 1 to 64 bytes

newTagName

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

newThingName

The "newThingName" property specifies a new unique name of a thing. If present, it must be a unique thing name.

  • It cannot be the empty string "". 
  • It applies to the "alterThing" action.
 Optional with default of "" string 1 to 64 bytes

newValue

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

 Optional with default of null JSON 0 to 65,500 bytes

normalLowerLimit

 The "normalLowerLimit" property specifies the low range of a normal collected value. An outlier is below this range. A change is saveable when it is greater than or equal to the normal upper limit. For more details, see "normalLowerLimit".  Optional with default of "disabled" integer No limit

normalUpperLimit

 The "normalUpperLimit" property specifies the high range of a normal collected value. An outlier is above this range. A change is saveable when it is less than or equal to the normal upper limit. For more details, see "normalUpperLimit".  Optional with default of "disabled" integer No limit

nullable

The "nullable" property allows a field to contain a NULL value when true. To require a field to have a non-null value, set "nullable" to false.

"fields": [
  {
    "name": "company",
    "type": "varchar",
    "nullable": true 
  }
]
 Optional with default of true Boolean

true

false

numberFormat

The "numberFormat" property defines the format of JSON numbers. For more details, see "numberFormat". 

 Optional with default of "number" string

"number"

"string"

offset

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

oldKey

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

onChangeScope

 The "onChangeScope" property specifies which tags the connector saves to an integration table. For more details, see "onChangeScope". Optional with default of "saveAllTags" string enum

"saveAllTags"

"saveOnlyChangedTags"

"saveSpecificTags"

onChangeScopeTags

 The "onChangeScopeTags" property specifies which tags the connector should save to the integration table when a save event occurs. Each "propertyPath" value is the connector's unique identifier to a collected data item, which is commonly called a "tag". For more details, see "onChangeScopeTags". Required when the "onChangeScope" property is set to "saveSpecificTags". array of strings 1 or more strings

onChangeTrigger

 The "onChangeTrigger" property specifies when the connector saves collected tags to an integration table. For more details, see "onChangeTrigger". Optional with default of "saveWhenAnyTagHasChanged" string enum "saveWhenAnyTagHasChanged"
"saveWhenAllTagsHaveChanged"
"saveWhenAnySpecifiedTagHasChanged"
"saveWhenAllSpecifiedTagsHaveChanged"

onChangeTriggerTags

 The "onChangeTriggerTags" property specifies tags to work with the "onChangeTrigger" property to control when a connector saves collected data to an integration table. Each "propertyPath" value is the connector's unique identifier to a collected data item, which is commonly called a "tag". For more details, see "onChangeTriggerTags". Required when the "onChangeTrigger" property has one of the following values: "saveWhenAnySpecifiedTagHasChanged" or "saveWhenAllSpecifiedTagsHaveChanged". array of strings 1 or more strings

onError

The "onError" property determines when to stop or continue the execution of all SQL statements. For more details, see "onError".

 Optional with default of "continue" string

"stop"

"continue"

opcNamespace

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

opcNodeName

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

opcServerUrl

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

opcServerUser

 The "opcServerUser" property specifies the username for your OPC UA device. Optional with default of "" string No limit

opcServerPassword

 The "opcServerPassword" property specifies the password for your OPC UA device. Optional with default of "" string No limit

operationIntent

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

 

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

"upsert"

"insert"

"update"

operator

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

 

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

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

 Required - No default value string

"="

"<"

"<="

">"

">="

"<>"

outputName

 The "outputName" property specifies a unique name for mapping an integration table to an output plugin to an external system. A FairCom generated name follows the pattern "Output #n from <databaseName>.<schemaName>.<tableName> to <pluginName>".

Optional with default of ""

 string 1 to 64 bytes

outputNames

The "outputNames" property specifies the names of outputs to be used to filter the response. The response will include details about all outputs with an "outputName" that matches one of the strings in the array.

 Optional with default of []

array

 1 or more strings

outputPayloadField

The "outputPayloadField" property specifies the field that the MQTT Subscription service should use as the payload when it sends the payload to subscribers.

  • "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.

Optional with default of "source_payload"

 string

"source_payload"

A user-defined field

ownerName

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

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

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

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

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

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

packageSize

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

Higher numbers allow the connector to retrieve more data in fewer requests. If not specified, the PLD PDU size is used.

 Optional with default between 240 and 960 integer 240 to 960

padValue

The "padValue" property is used by the server as a byte value to pad all "char" and "binary" fields in a table when the contents of these fixed-length fields is shorter than the field size.

All fixed-length fields in a table are padded with the same pad value. For more details, see "padValue".

 Optional with default of 32 integer 0 to 255

partialClientName

The "partialClientName" property specifies which sessions to return from the "listMqSessions" action. This property behaves as a "begins with" search.

 Optional with default of "" string  

partialDatabaseName

The "partialDatabaseName" property filters the returned databases by applying partial matches to the beginning of database names. 

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

partialGroupFilter

The "partialGroupFilter" property filters the results of the action. It defaults to null, which provides no filtering. The string is the partial or full name of a group. A label's group must match the partial or complete value of this property to be included in the results. The empty string "" and null match all groups.

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

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

 Optional with default of "" string 1 to 64 bytes

partialKey

The "partialKey" property defines the range of returned records. For more details, see "partialKey". 

Optional with default of "" or []

Required in the Key-Value API 

 string or array

1 or more strings/arrays

1 to 128 bytes in the Key-Value API 

partialName

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

 Optional with default of "" string 1 to 64 bytes

partialNameFilter

The "partialNameFilter" property filters the results of the action. It defaults to null, which provides no filtering. Each string is the partial or full name and may be up to 64 bytes long. A label's name must partially match this value to be included in the results. The empty string "" and null match all groups.

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

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

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

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

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

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

partialNames

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

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

partialTableName

The "partialTableName" property filters the returned databases by applying partial matches to database names.

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

password

The "password" property is a user-defined password that the server uses to authenticate the account.

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

Optional with default of "".

Required for the "createSession" action

 string 0 to 256 bytes

path

The "path" property identifies the path of the database folder. For more details, see "path".

 Optional with default of "" string 0 to 2,048 bytes

payload

The "payload" property specifies the actual payload of the message.

 Required - No default value string The message's payload

permanentlyDeleteLabels

The "permanentlyDeleteLabels" property specifies for the server to permanently delete the labels specified by the label filter properties.  

 Optional with default of null Boolean

true

false

null

permanentlyDeleteSession

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

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

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

 Optional with default of false Boolean

true

false

permanentSession

The "permanentSession" property indicates if a session is permanent. For more details, see "permanentSession".

 Optional with default of false Boolean

true

false

photo

 The "photo" property contains a photo of a thing. You cannot use it for lookups and filtering. Optional with default of null string containing a binary value Up to 2 GB

plcAddress

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

Examples:

172.16.0.1

172.16.0.1:4401

plcType

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

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

"controllogix"

"plc5"

"slc500"

"logixpccc"

"micro800"

"micrologix"

"omron-njnx"

preserve

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

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

Optional with default of "data"

 string enum

"data"

"nothing"

primaryKey

The "primaryKey" property identifies a table's primary key. For more details, see "primaryKey".

 Optional with default of null integer 0 to 32

primaryKeyFields

 The "primaryKeyFields" property specifies the fields to use for the table’s primary key. For more details, see "primaryKeyFields". Optional with default of [] array of strings ["field1", …,"fieldN"]

primaryKeys

The "primaryKeys" property specifies primary keys to use as search criteria and to show the results found. For more details, see "primaryKeys".

Optional with default of "null".

Required when "ids" is omitted.

array of arrays

 1 or more array of key/value pairs.

privateKeyFilename

 The "privateKeyFilename" property specifies the name and optional path of a server key file. Optional with default of "" string No limits

problemTypeFilter

The "problemTypeFilter" property filters the response to match the specified types of problems. You may omit this property or set it to null to return all problem types.

 Optional with default of null array of strings

"diagnostic"

"information"

"warning"

"error"

"fatalException"

propertyMapList

 The "propertyMapList" property specifies which data the connector requests and where to put it in the generated JSON. Required - No default value array of objects

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

"propertyPath"

"tagElementCount" 

"tagName"

"tagPath"

"tagType"

"tagSize"

propertyPath

 The "propertyPath" property specifies the name of the data to be defined by "propertyValue". Required - No default value string 0 to 256 bytes

propertyValue

The "propertyValue" property contains properties that define the data values of a "propertyPath". 

The data values specified in the "propertyValue" object can be a string or an object.

  • "fromConstant" indicates the value is a string. For example —
    • "propertyValue": {"fromConstant": "0002"}
  • "fromSourcePropertyPath" indicates the value is an object. For example —
    • "propertyValue": {"fromSourcePropertyPath": { "formatString": "Temperature = <%input_temp%>" }}
    • Characters in the "formatString" value that are enclosed by "<%" and "%>", specify the name as an input property that will be replaced by an input property value.
    • Here is a REST command example for the "propertyPath" named "description", that received an input_temp value of 103:
    • {  description: "Temperature = 103."}
    • If the input value is not found, it is replaced with NULL:
    • {  description: "Temperature = NULL."}
 Required - No default value object

"fromConstant": "yourString"

"fromSourcePropertyPath": { "key": "value"}

purpose

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

 

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

 

The Thing API uses the Label API to manage purposes.

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

Optional with default of "". Defaults to

"unknown" in the Thing API 

 string 1 to 64 bytes

purposeFilter

 The "purposeFilter" property returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. Each string is a partial or complete purpose, such as, "purposeFilter": [ "myPur", "Manage an Acid Bath" ]. Optional with default of [] array of strings zero or more purpose strings

rack

 The "rack" property specifies the PLC Rack number. Required - No default value integer 0 to 7

rebuildTable

The "rebuildTable" property causes the server to stop accepting read, insert, and update requests and rebuilds the table when true. Rebuilding a table creates new table files and writes existing records to the new files.

Warning Rebuilding a table interrupts data collection until the rebuilt operation finishes. The rebuild time is proportional to the number of table records.

Tip You may want to rebuild the table in the following cases: 

  • To apply a transform to previously inserted or updated records. 
  • To change the table's retention policy, period, or unit. 
  • To repair a data file corrupted by a storage failure.
 Optional with default of false Boolean

true

false

receiveMaximum

The "receiveMaximum" property specifies the maximum number of QoS 1 and QoS 2 publish messages that the MQTT client is willing to process concurrently.

 Optional with default of 1024 integer 1 to 65535

receiveMyMessages

The "receiveMyMessages" property allows a client's subscription to receive messages published by the client.

 Optional with default of true Boolean

true

false

receiveRetainedFlagAsPublished

The "receiveRetainedFlagAsPublished" specifies how the FairCom server sets the "retain" property on messages it sends to subscribers. When a client publishes a message, it sets the "retain" property to true to tell the FairCom server that it should retain the message and publish this message on behalf of the client when another client subscribes to a topic. A retained message is typically a special message that provides a new subscriber with status information about the topic.

When "receiveRetainedFlagAsPublished" is true, the FairCom server follows the MQTT 3 specification and passes the value of the "retain" property set by the publisher to the subscriber. Thus, a subscriber sees the value of the "retain" property that is set by the publisher. This notifies the subscriber that the message is a special status message from the client. This approach has the downside that a subscriber does not know when it gets a message sent by the FairCom server on behalf of the client in response to subscribing to a topic.

When "receiveRetainedFlagAsPublished" is false, the FairCom server follows the MQTT 5 specification and sets the "retain" property to true only when the FairCom server sends a retain message to a subscriber on behalf of a publisher, such as when a client subscribes to a topic. The MQTT 5 approach lets a subscriber know when it receives a retain message sent by the FairCom server vs. when it receives a normally published message from a client. This approach has the downside that a subscriber does not get the value of the "retain" property as set by the client who published the message. The MQTT 5 approach is generally better because the subscriber can tell when it is receiving a retained message in response to a subscription as opposed to a message published by a client.

 Optional with default of true Boolean

true

false

receiveRetainedMessages

The "receiveRetainedMessages" property specifies how MQTT 5 subscribers receive retained messages. It has three enumerated values: "onSubscription", "onNewSubscription", and "never". 

  • "onSubscription" - the server sends a topic's retained message each time a client subscribes to a topic. Thus, a client can resubscribe to a topic to get the latest retained message.
  • "onNewSubscription" - the server only sends a topic's retained message when a client subscribes to a topic for the first time.
  • "never" - the server never sends a topic's retained message.
 Optional with default of "onSubscription" enum

"onSubscription"

"onNewSubscription"

"never"

reconnectFrequencySeconds

The "reconnectFrequencySeconds" property specifies the number of seconds that the broker waits between attempts to reconnect to an external broker. 

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

 Optional with default of 15 int32

1 to 65535

recordFilter

The "recordFilter" property specifies a FairCom expression that must match a record's field values before the record is included as a data change event.

 Optional with default of "" string 1 to 65,000 bytes

recordFormat

The "recordFormat" property includes the record's value in the data change event as a binary-encoded string or individual field values.

 Optional with default of "fields" string enum

"fields"

"buffer"

recordPath

The "recordPath" property specifies the location in a record where the server reads or writes a JSON value. It specifies a field name followed by an optional JSONPath. For more details, see "recordPath".

 

 Required - No default value string 0 to 256 bytes

remove

The "remove" property specifies which roles will be removed from which accounts. You can specify the roles you want to remove with the "rolenames" property and the accounts to remove them from with the "usernames" property.

 Optional with default of {} array of objects

"rolenames"

"usernames"

renamedKeys

The "renamedKeys" property contains an array of key-rename objects. Each key-rename object contains "oldKey" and "newKey" properties that specify the key's current and new names.
 

 { 
    "oldKey": "k1",
    "newKey": "k2"
  }
 Required - No default value array of key-rename objects 
[
  { 
    "oldKey": "k1", 
    "newKey": "k2"
  }
]

requestProblemInformation

The "requestProblemInformation" property specifies whether or not to include problem Information in the response.

 Optional with default of true Boolean

true

false

requestResponseInformation

The "requestResponseInformation" property specifies whether or not to include response information in the response.

 Optional with default of false Boolean

true

false

rerunTransformScope

The "rerunTransformScope" property defines the scope of this action. It has one of the following values:

  • "allRecords" returns immediately and asynchronously creates a background thread that runs the transform steps on all records in that table.
    • You can stop this action by calling the "rerunIntegrationTableTransformSteps" action with "rerunTransformScope": "stop".
    • The server regularly updates the "transformStatus" and the "transformPercentComplete" properties, which are returned by the "describeIntegrationTables" action.
    • If an integration table's background thread is already rerunning the transform steps, the action returns an error indicating the "rerunIntegrationTableTransformSteps" action is already running on the integration table. The user can decide if he wants to wait or stop the action.
  • "stop" stops the table's background thread that reruns transform steps on all its records. If the background thread is not running, the action does nothing and returns an error.
  • "firstRecord" immediately and synchronously runs the transform steps on the first record in the table.
    • This option does not interfere with a background thread that is currently rerunning the transform steps.
  • "lastRecord" immediately and synchronously runs the transform steps on the last record in the table.
    • This option does not interfere with a background thread that is currently rerunning the transform steps.
  • "specificRecords" immediately and synchronously runs the transform steps on the specified records in the table.
    • Each record has an "id" field containing an integer number that uniquely identifies it.
    • The action uses the "ids" property to specify the identifiers of one or more records to be transformed.
    • This option does not interfere with a background thread that is currently rerunning the transform steps.
 Required - No default value string enum

"allRecords"

"firstRecord"

"lastRecord"

"specifiedRecords"

"stop"

responseOptions

The "responseOptions" property configures the server to return a customized response.

  • None of these properties are required, but some are mutually exclusive:
    • "includeFields" and "excludeFields" are mutually exclusive.
      • Use "includeFields" or "excludeFields" to control which record fields are present in the data.
    • "includePaths" and "excludePaths" are mutually exclusive.
      • Use "includePaths" or "excludePaths" to control which JSON properties are included in the data.
  • A JSON path includes the JSON field name plus the path of the property within the JSON field.
  • Use "omit" to remove a property from a response, such as omitting "errorMessage".
  • Use "dataFormat" to control whether data comes back as an array of arrays or an array of objects.
  • Use "numberFormat" to control whether JSON numbers are rendered as digits or digits embedded in a string.
  • Use “stringFormat” to change how “char”, “varchar”, “lvarchar”, and “variant” string field values are returned. 
  • Use "variantFormat" to control how the server formats the values of variant fields in its response.
Full example
    "responseOptions": 
    { 
     "omit": ["error", "fieldDefs" ]
     "dataFormat": "arrays", 
     "numberFormat": "number",
     "includeFields": [ "name", "email" ],
     "excludeFields": [],
     "includePaths": [],
     "excludePaths": [ "email.domain" ],
     "binaryFormat": "base64",
     "stringFormat": "json",
     "variantFormat": "json"
    }
 Optional with default of null object

"omit"

"dataFormat"

"numberFormat"

"includeFields"

"excludeFields"

“includeBookmarks”

"includePaths"

"excludePaths"

"binaryFormat"

"stringFormat"

"variantFormat"

 

responseTopic

The "responseTopic" property contains a topic name. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include the "correlationData" value (if any) to connect the response to the published message.

 Optional with default of "" string topic name for the response

retain

The "retain" property tells the FairCom server to retain this message for automatically sending to new subscribers as the first message they receive when set to true. When an action returns the "retain" property, it indicates the publisher published the message as a retained message.

 Optional with default of false Boolean

true

false

retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It refers to the unit of time specified by the "retentionUnit" property. For more details, see "retentionPeriod".

Optional with default of 30

 integer 1 to 100

retentionPolicy

The "retentionPolicy" property controls how messages are persisted. 

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.

Optional with default of "autoPurge"

 string

"autoPurge"

"neverPurge"

retentionUnit

The "retentionUnit" property specifies a unit of time that the server will use to purge 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".

Optional with default of "day"

string

"minute"

"hour"

"day"

"week"

"month"

"year"

retrySeconds

The "retrySeconds" property specifies 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. 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.

Optional with default of 20

 integer

1 to 65535

returnCursor

The "returnCursor" property causes the action to return a cursor instead of directly returning records when set to true.

  • To retrieve records, call the "getRecordsFromCursor" action and pass the "cursorId" value into it.
  • When "returnCursor" is "true" and one of the "skipRecords", "maxRecords", and "reverseOrder" properties is specified, an error is returned.
    • "returnCursor" is mutually exclusive with the "skipRecords", "maxRecords", and "reverseOrder" properties.
 Optional with default of false Boolean

true

false

returnTagsBy

 The "returnTagsBy" property specifies whether to return tags identified by ID or name. Optional with default of "id" string enum

"id"

"tagName"

returnThingsBy

 The "returnThingsBy" property specifies whether to returns things identified by ID or "name". Optional with default of null string enum

"id"

"name"

revealAfterValueOnFilteredDelete

The "revealAfterValueOnFilteredDelete" property includes the "afterValue" property in the notification message when set to 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.

 Optional with default of false Boolean

true

false

revealBeforeValueOnFilteredInsert

The "revealBeforeValueOnFilteredInsert" property includes the "beforeValue" property in the notification message when set to 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.

 Optional with default of false Boolean

true

false

reverseCompare

The "reverseCompare" property specifies whether the bytes in an index key field are compared starting from the beginning to the end of the key.

When true, bytes in an index key field are compared starting from the end to the beginning of the key. This speeds comparisons when the unique parts of the bytes are at the end of keys.

"fields": [
  {
    "reverseCompare": true
  }
]
 Optional with default of false Boolean

true

false

reverseOrder

The "reverseOrder" returns results in reverse order when set to true. 

  • It works with "maxRecords" and "skipRecords" to provide pagination.
  • An error is returned when "returnCursor" is true.
 Optional with default of false Boolean

true

false

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other 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.

 Required when "keystore": "role" string 1 to 64 bytes

roleNames

The "roleNames" property specifies the roles to be added to or deleted from the accounts specified by the "usernames" property. This property can specify one or more roles, each between 1 and 64 bytes.

    "add": [
      {
        "roleNames": [
          "admin"
        ],
        "usernames": [
          "NewAccount1"
        ]
      }
    ]
 Optional with default of [] array 1 or more strings, each between 1 and 64 bytes.

scale

The "scale" property specifies the number of fixed decimal places to the right of the decimal point. Its value must always be less than or equal to the field's length. It is required only for the "number" and "money" data types because they require fixed precision. It is ignored for all other data types. See also Data types. The scale 

The value of "scale" must be an integer from 0 to the number of digits specified by the "length" property. 

A scale of 0 creates an integer number. A scale equal to the length creates a number that can only have a fractional value.

The "money" field type must have a scale of 2 or 4. The default is 4.

You may optionally use the "length" property to specify fewer than 32 total digits to limit the total number of digits available to the number. A length limit reduces the maximum size of the scale. For example, a length of 3 allows the scale of a "number" to be 0, 1, 2, or 3. 

Example numbers allowed in "number" and "money" field types with a length of 4 and a scale from 0 to 4.

 

Request Example

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

"fields": [
  {
    "name": "j",
    "type": "number",
    "scale": 32
  },
  {
    "name": "k",
    "type": "number",
    "scale": 4
  }


],
 Optional with default of null integer 0 to 32

search

The "search" property searches the content of the "metadata" property that is part of each topic and integration table.

  • If there is nothing in the "metadata" property for a topic or an integration table, there is nothing to search for, resulting in an empty array in the "data" property in the response.
  • The "metadata" property is a JSON field, meaning you can put a valid JSON in it — for example, a string or object.
 Optional with default of "" string 0 to 64 bytes

sequence

The "sequence" property assigns an order to the labels in a group. You may embed the number in a JSON string. It defines the order of labels in a group. It is a double 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.

 Optional with default of 0 double Any floating point or integer number.

sequenceFilter

The "sequenceFilter" property filters the results of the action. It defaults to [], which provides no filtering. The "sequence" property of a label must match one of the doubles in the array to be included in the results.

 Optional with default of [] array of doubles Each array item is a floating-point or integer number. 

serialNumber

 The "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. You can use it to do partial lookups and filtering. Optional with default of "unknown" string 1 to 64 bytes

serialNumberFilter

 The "serialNumberFilter" property specifies a complete or partial serial number, such as, "serialNumberFilter": "AB678". The action returns things that match the serial number, provided it also satisfies all other specified filter properties. Optional with default of "" string 1 to 64 bytes

serviceLibrary

The "serviceLibrary" property 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.

 Optional with default of "" string no limits

serviceName

The "serviceName" property contains the name of a FairCom input or output service. 

See the "params" topic of each specific service for the requirements of this property.

The following services are available as of the V5 release:
  • "MODBUS"
  • "SIEMENSUDT2JSON"
  • "OPCUA"

Note The SQL, JSON RPC, and REST services can automatically query any integration table in FairCom's servers without requiring configuration.

MQTT always represents both input and output services. This is because once a topic is created and assigned to an integration table, any MQTT client can publish messages to it and subscribe to those messages.

 Required - No default value string 1 to 64 bytes

sessionExpiryInterval

The "sessionExpiryInterval" property specifies the number of seconds that a temporary session can be inactive before the server deactivates it. When a temporary session expires, the server removes its subscriptions and message delivery queue. 

The "sessionExpiryInterval" property has no effect on a permanent session because it does not expire. 

  • Set "sessionExpiryInterval" to 0 to expire a temporary session when the JSON action session closes.
  • Set "sessionExpiryInterval" to a value between 0 and 4294967296 to expire the session when it has been inactive for the specified number of seconds.
  • Set "sessionExpiryInterval" to 4294967296 to never expire the session.

The "temporarySession" property sets the value of the "sessionExpiryInterval" property.

  • If "temporarySession" is true, the server defaults "sessionExpiryInterval" to 0 so that a temporary session expires by default when the JSON session expires.
  • If "temporarySession" is false, the server sets "sessionExpiryInterval" to 4294967296.
 If "temporarySession" is true, "sessionExpiryInterval" defaults to 0 to ensure the temporary session expires when the JSON session does. If "temporarySession" is false, it defaults to 4294967296 because a permanent session never expires. integer 0 to 4294967296

sessionHealth

The "sessionHealth" property describes the session health. For more details, see "sessionHealth". 

 Required - No default value enum

"healthy"

"unhealthy"

"offline"

sessionStatus

The "sessionStatus" property specifies the status of an MQTT or MQ API session as "normal", "hidden", "banned", or "inactive" to hide its visibility in API results and the dashboard views, ban a client from connecting, or mark a client as inactive. A banned session prevents clients from using the session to publish and subscribe to messages. When "sessionStatus" is omitted, it defaults to "normal".

  • "normal" resets a client to its default normal state. The client is not hidden in API results and dashboard views and may connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to unhide, unban, and activate a client.
  • "hidden" hides a client from most API results and dashboard views while allowing the client to connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to hide administrative client connections.
  • "banned" prevents a client from connecting in the future while preserving all information about the client. Use it to prevent unwanted clients from connecting again using the session's "clientName" to publish and subscribe to messages.
  • "inactive" marks a client session as inactive while allowing the client to connect, publish, and subscribe to messages. The server does not remove an "inactive" session's data so that historical message data sent and received by the client can continue to be associated with the deleted client. If a client connects to an inactive session, the server changes the session to "normal".
    • Use the "deleteMqSession" action to permanently delete the session which removes all session information. The server can no longer associate sent and received messages with the client. The client can reconnect in the future to establish a new session, but this will create a new session. It is common to permanently delete temporary client connections created during testing and troubleshooting.
 Optional with default of "normal" string enum

"normal"

"hide"

"ban"

sessionStatusFilter

The "sessionStatusFilter" property filters the returned sessions by the selected session statuses.

 Optional with default of [] array

"normal"

"banned"

"hidden"

sessionTypeFilter

The "sessionTypeFilter" property filters the returned sessions by the selected session types.

 Optional with default of [] array

"mqtt"

"mqApi"

settings

The "settings" property contains properties that are specific for each connector type. Settings for Modbus are different than settings for OPC UA, and so forth. See the API reference "params" property of the relevant connector for details of the "settings" property for that connector.

 Optional with default of {} object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params"

significantMagnitude

 The "significantMagnitude" property specifies the minimum magnitude that a collected value must change to be meaningful. It causes the connector to ignore insignificant changes. In other words, a change is saveable when it is greater than or equal to the significant magnitude. Each saved event establishes the baseline value for measuring the next significant change. The magnitude is an absolute value that measures change in the positive or negative. It is also inclusive. For more details, see "significantMagnitude". Optional with default of "disabled" Integer Positive integer greater than 0

skipRecords

 The "skipRecords" property specifies the number of records to skip over when paginating the results. It is used with "maxRecords" to paginate the results. If the value is not null or omitted, the server returns results from the beginning. If it is > 0, the server skips over the specified number of records and returns results starting from that point up until it returns the maximum number of results as defined by "maxRecords". Optional with default of 0 integer 0 to 9223372036854775807

slot

 The "slot" property specifies the PLC Slot number. Required - No default value integer 1 to 31

smallFile

The "smallFile" causes a table to be optimized for data files that cannot grow larger than 4 GB when set to true.

Note Small data files are faster and more efficient than huge files. They consume less disk space and less memory.

 

Example request

{
  "api": "db",
  "action": "createTable",
  "params": {
    "smallFile": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 Optional with default of false Boolean

true

false

sortAscending

The "sortAscending" property sorts the returned sessions in ascending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

 Optional with default of "" string

"lastConnect"

"lastDisconnect"

"clientName"

"ipAddress"

sortDescending

The "sortDescending" property sorts the returned sessions in descending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

"fields": [
  {
    "sortDescending": true
  }
]
 Optional with default of false Boolean

true

false

sourceData

 The "sourceData" property contains source data for an insert or update operation Optional with default of [] array An array of arrays or an array of objects

sourceDatabaseName

The "sourceDatabaseName" property specifies the database name of the table on the FairCom DB or RTG server that generates the stream's data change events.

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

sourceDatabaseNameFilter

The "sourceDatabaseNameFilter" property specifies a partial match for the database name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 Optional with default of null string 1 to 64 bytes

sourceDataField

The "sourceDataField" property contains the name of a field from an integration table. 

Required - No default value

 

It defaults to "source_payload".

 string

"source_payload"

"t1"

"t2"

"t3"

"t4"

"t5"

"t6"

"t7"

"t8"

"t9"

sourceDataFilePath

The "sourceDataFilePath" property specifies the data file path of the table on the FairCom DB or RTG server that generates the stream's data change events. It can be a full path or a relative path from the server's data directory.

 Required - if "sourceTableName" is not specified string No limits

sourceDataFilePathFilter

The "sourceDataFilePathFilter" property specifies a partial match for the file name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 Optional with default of null string 1 to 64 bytes

sourceDataFormat

 The "sourceDataFormat" property specifies the format of the "source_payload" field.  Optional with default of "json" string

"binary"

"jpeg"

"json"

"siemensUdt"

"xml"

sourceFieldName

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

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

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

 Optional with default of "" string 1 to 64 bytes

sourceFields

The "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".

 Optional with default of [] array One or more fields form the integration table.

sourceHostname

 The "sourceHostname" property specifies a unique host name or TCP/IP address of a FairCom DB or RTG server. Required - No default value string 1 to 255 bytes

sourceHostnameFilter

The "sourceHostnameFilter" property specifies a partial match for a hostname.

 Optional with default of null string 1 to 64 bytes

sourceOwnerName

The "sourceOwnerName" property specifies the account that owns the table on the FairCom DB or RTG server that generates the stream's data change events.

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

sourceOwnerNameFilter

The "sourceOwnerNameFilter" property specifies a partial match for the owner name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 Optional with default of null string 1 to 64 bytes

sourcePassword

 The "sourcePassword" property specifies the login password of a FairCom DB or RTG server. Optional with default of "ADMIN" string 1 to 128 bytes

sourcePayloadBinaryFormat

 The "sourcePayloadBinaryFormat" property specifies how the server encodes and decodes a binary value assigned to a tag. For more details, see "sourcePayloadBinaryFormat". Optional with default of "hex" string enum

"base64"

"byteArray"

"hex"

sourcePayloadDateFormat

 The "sourcePayloadDateFormat" property specifies how the server encodes and decodes a date value assigned to a tag. For more details, see "sourcePayloadDateFormat". Optional with default of "iso8601" string enum "ccyy.mm.dd"
"mm.dd.ccyy"
"mm.dd.yy"
"dd.mm.ccyy"
"dd.mm.yy"
"ccyymmdd"
"iso8601"
"yymmdd"
"utc"

sourcePayloadNumberRounding

The "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). 
 Optional with default of "truncate" string enum

"truncate"

"roundup"

"rounddown"

sourcePayloadPath

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

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


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

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

sourcePayloadTimeFormat

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

sourcePayloadVariantFormat

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

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


Examples

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


For more details, see "variantFormat".

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

sourcePort

 The "sourcePort" property specifies the ISAM TCP/IP port of a FairCom DB or RTG server. Optional with default of 5597 int16 1 to 65535

sourcePortFilter

The "sourcePortFilter" property specifies a complete match for a port number.

 Optional with default of null integer 1 to 65535

sourceServerName

 The "sourceServerName" property 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". Required if "sourceHostname" is not defined - No default value string 1 to 255 bytes

sourceServerNameFilter

The "sourceServerNameFilter" property specifies a partial match for a server name.

 Optional with default of null string 1 to 64 bytes

sourceServers

 The "sourceServers" property contains a list of FairCom DB or RTG server connection objects. FairCom MQ attempts to connect to the first server in the list. If that fails, it attempts to connect to the next one. If it reaches the last server in the list, it attempts to connect to the first. Required - No default value array of server connection objects 
{
  "purpose": "Primary Server",
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  }
}

sourceTableName

The "sourceTableName" property specifies the name of the table on the FairCom DB or RTG server that generates the stream's data change events.

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

sourceTableNameFilter

The "sourceTableNameFilter" property specifies a partial match for the table name of the table on the FairCom DB or RTG server that generates the stream's data change events.

 Optional with default of null string 1 to 64 bytes

sourceUsername

The "sourceUsername" property specifies the source account to be cloned.

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

 Required - No default value string 1 to 31 bytes

sourceUsernameFilter

The "sourceUsernameFilter" property specifies a partial match for a user name.

 Optional with default of null string 1 to 64 bytes

sql

The "sql" property specifies a SQL statement.

Required - No default value

 string 1 to 32,000,000 bytes

sqlForwardOnly

The "sqlForwardOnly" property returns records in forward-only order.

Optional with default of false

Boolean

true

false

sqlParams

The "sqlParams" property specifies values that become parameters in the SQL statement.

  • Each value may be a string, number, integer, true, false, or null.
  • The same value may be repeated within the array.
  • The order of the values must match the order of the SQL parameters.
  • The type of each value must correspond to the field type of the corresponding SQL parameter.
  • It is an error if the number of SQL parameters do not match the number of items in this array.
  • It is a best practice to use SQL parameters rather than embedding values in a SQL query.
  • It prevents SQL injection attacks.
  • Because the same value may be applied to multiple SQL parameters, items in the "sqlParams" array can have the same value.
 Optional with default of [] array An array of values

sqlStatements

The "sqlStatements" property specifies SQL statements that the server will execute.

There is one SQL statement per string.

Required - No default value

 array of strings 1 or more sql statements

startFrom

The "startFrom" property sets the cursor to a known position.

 

In "getRecordsByTable" and "getRecordsFromCursor" only, when "startFrom": "id" or "startFrom": "bookmark", the user will receive records starting from the value specified by the "id" or "bookmark" property. 

 Optional with default of "currentPosition" string

"currentPosition"

"beforeFirstRecord"

"afterLastRecord"

“id”

“bookmark”

startTimestamp

The "startTimestamp" property filters the response to return problems that started on or after its value. If any parts of the timestamp are missing or omitted, the server defaults the remaining parts to 0.

 Optional with default of null string containing an ISO8601 timestamp

"2025-08-19"

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

"2025-08-19T01:13"

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

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

status

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

 

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

 

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

 Optional with default of "active" string enum

"active"

"inactive"

statusFilter

The "statusFilter" property filters results based on the value of the "status" property. If the array is empty, null, or omitted, it matches all status values; otherwise, it returns code packages only when their status matches one of the values in the array. If "includeDeactivatedCode" is set to true or false, it overrides conflicting status codes.

 

When using the tag actions, this property finds tags based on their status. You can include zero or more status values. The "listTags" action returns tags that match at least one of the specified status values. An empty array or null value matches all status values.

  • Use "statusFilter": "active" to return active tags.
  • Use "statusFilter": "inactive" to return inactive tags.
  • The "listTags" action returns tags that match at least one of the specified status values.
  • Omitting the property or setting it to null matches all tags.
 Optional with default of [] array

"developing"

"deleted"

"inactive"

"deprecated"

"testing"

"active"

 

When using tag actions, "inactive" and "active" are the only valid statuses 

streamingConnectionName

 The "streamingConnectionName" property specifies a unique, user-defined name for a streaming connection. The API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server. Required - No default value string 1 to 64 characters

streamingConnectionNameFilter

The "streamingConnectionNameFilter" property specifies a partial match for a connection name.

 Optional with default of null string 1 to 64 bytes

streamParallelism

 The "streamParallelism" property 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. Optional with default of 8 integer 1 to 65535

streams

 The "streams" property specifies an array of stream definitions. Required - No default value Array of stream definitions 1 or more stream definitions

stringFormat

The "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.

  • Defaults to "json", which returns "char", "varchar" and "lvarchar" values as JSON strings. If the string contains non-compliant UTF-8 characters, the action returns an error. 
  • The "binary" option only applies to variant fields that contain a string value. 
 Optional with default of "json" string

"json"

"binary"

"hex"

"base64"

"byteArray"

subscribeToExternalBroker

The "subscribeToExternalBroker" property causes FairCom's servers to connect to the external MQTT broker and subscribe to this topic on that broker when it is set to a valid broker connection. Thus, these servers become a client to another MQTT broker. Each message sent to this topic on the external broker becomes an incoming message in FairCom 's servers – as if it were sent directly to them. The topic works the same as any other topic.

  • Any client can publish messages to this topic.
  • A valid Broker Connection must be created before you set "subscribeToExternalBroker" to a value (see "configureBrokerConnection").
  • If this broker connection name does not already exist, it does not set up an external subscription and it logs an error stating, “Cannot subscribe to the external broker because the Broker Connection name xxx has not yet been defined by ConfigureBrokerConnection.”
Optional with default of "" string

Any previously defined name of a broker connection (see "configureBrokerConnection")

subscriptionActions

The "subscriptionActions" property adds or removes a topic filter from a client's subscriptions. Each subscription object contains a "topicFilter" and an optional "subscriptionIdentifier".

  • Use the required "subscriptionAction" property to add or remove a topic filter: "add" adds a topic filter to the subscription and "remove" removes it. 
  • Use the required "topicFilter" property to a wildcard topic to subscribe to multiple topics. 
  • Use the optional "subscriptionIdentifier" property to assign a unique identifier to the subscription. When the FairCom server sends an MQTT 5 message to the client, it includes the subscription identifier to help the client identify the subscription quickly and easily.
  • Use the optional "receiveRetainedMessages" property to control when the FairCom server sends the retained message to a topic subscription event, which includes never sending the retained message, sending it only when the client subscribes for the first time, or sending it each time the client subscribes. 
  • Use the optional "receiveMyMessages" property to prevent or allow the FairCom server to send messages to a client that the client published. 
  • Use the optional "userProperties" property to set user-defined subscription properties.
 Optional with default of [] array

"binaryFormat"

"includeExpiredMessages"

"receiveMyMessages"

"receiveRetainedFlagAsPublished"

"receiveRetainedMessages"

"subscriptionIdentifier"

"topicFilter"

"userProperties"

subscriptionIdentifier

The "subscriptionIdentifier" property is provided by the subscriber and uniquely identifies the "topicFilter" to the subscriber. Each subscriber may assign its own "subscriptionIdentifier" to each "topicFilter". When the FairCom server delivers a message to the subscriber, it includes the "subscriptionIdentifier" with the message. The purpose of Subscription Identifiers is to make it easy and fast for an MQTT 5 client to process an incoming message. The client can use the Subscription Identifier in a message to associate a message with a specific handler. A client receiving a message with multiple Subscription Identifiers can send the message to multiple handlers – one for each Subscription Identifier.

 Optional with default of 268435455 integer 0 to 268435455

tableFileExtension

The "tableFileExtension" property specifies the file system extension to use for a table's data files. 

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

 

Example request

"params": {
  "tableName": "test1",
  "tableFileExtension": ".dat"
}
 Optional with default of ".dat" string 0 to 64 bytes

tableFilter

The "tableFilter" property filters the results by the value of the "tableName" property. No table filter is applied when it is an empty string, a null value, or is omitted. It is a server-side filter of the records in a table. It includes records in the result only when they match the filter requirements. It works like a SQL WHERE clause except for using C syntax and C functions.

  • See Use Table Filters for more information and examples.
  • It uses FairCom's expression language, which is based on C syntax and supports arbitrarily nested expressions, operators, and functions, such as:
    • "tableFilter": "((name IS NOT NULL && name != \"Michael Jordan\" && strnicmp( name, \"m\", 1 ) == 0 && (ranking - 5) * 2 <= 6 && livedPast2000 ) || ( earnings < 1000000 && ! livedPast2000 )) && (ranking % 2 == 1)"
  • A zero-length table filter, such as "tableFilter": "" does not filter any records.
  • A "tableFilter" can be combined with other query techniques. For example, the "getRecordsInKeyRange" action can be used to retrieve a limited range of records that are further filtered by a "tableFilter".
  • To include a double quote character in a "tableFilter" expression, precede it with the backslash (escape) character, \".
  • The first time you include a "tableFilter" string in a "getRecords..." action, the server processes the string to produce an optimized filter. The server automatically reuses the optimized filter in subsequent calls to eliminate the initial processing overhead.
 Optional with default of "" string 0 to unlimited bytes

tableName

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

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

 

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

tableNames

The "tableNames" property specifies multiple table names.

Note See table name in System specifications for table naming requirements and limitations.

  • Contains at least one string.
  • A zero-length "tableName" is invalid.
  • A client should force the uniqueness of items in the array because the server ignores duplicate items.
  • Including table names that do not exist will not result in an error. However, the "warnings" array in the reply will contain an object for each missing table.

Required - No default value

 array 1 to 64 bytes

tables

The "tables" property contains an array of table objects. Each object identifies a table. Each object in the "tables" array contains three properties:

  • databaseName
  • ownerName
  • tableName
 Optional with default of {} array of objects

0 or more objects containing the following properties:

"databaseName"

"ownerName"

"tableName"

tagChanges

The "tagChanges" property specifies when to add "changed": true to field objects in the data change event to indicate when a field changed value.

 Optional with default of "forEachField" string enum

"forEachField"

"forPrimaryKeyFields"

"never"

tagDataType

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

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

tagDataTypeFilter

 The "tagDataTypeFilter" property specifies one or more tag data types. Each item in the array is the exact name of a tag data type. The "listTags" action returns tags that match one of the specified values.  Optional with default of [] array of strings 1 to 64 bytes

tagElementCount

 The "tagElementCount" property specifies the number of elements in the tag. All tags are treated as arrays. Tags that are not arrays are considered to have a length of one element. Optional with default of 1 int32 0 and negative values are invalid.

tagName

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

tagNameFilter

 The "tagNameFilter" property specifies a partial or full name of a tag to describe. The action returns tags that match the partial or full name of the tag, provided it satisfies all other specified filter properties. Optional with default of "" string 1 to 64 bytes

tagNames

The "tagNames" property 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. 
 Required - No default value string 1 to 256 bytes

tagPath

The "tagPath" property specifies additional connection information with the format "p,s"

p is the communication Port Type

1 for Backplane
2 for Control Net/Ethernet, DH+ Channel A, or DH+ Channel B
3 for Serial

s is the slot number where the PLC is installed, such as 0, 1, 2.

 Optional with default of "1,0" string String with the format "p,s"

tagType

 The "tagType" property specifies the binary format of the PLC data represented by the tag. Required - No default value string

"bit"

"int8"

"uint8"

"int16"

"uint16"

"int32"

"uint32"

"int64"

"uint64"

"float32"

"float64"

"byte"

"string"

tagSize

The "tagSize" property specifies the buffer size in bytes to handle tag data.

If not specified, the buffer size is defined based on the tagType. For example, 1 for int8 and 4 for int64.

For string tagType, the default value is 0 which will set the buffer to the maximum string size for the device.

Let the server define this property. and set it yourself only when necessary.

 Optional with default depending on the dataType value Integer 0, 1, 2, 4 or 8

targetDatabaseName

The "targetDatabaseName" property specifies the name of the database that contains the target table. See

"databaseName" for more information.

 Optional with default of "" string 1 to 64 bytes

targetOwnerName

The "targetOwnerName" property specifies the name of the account that owns the target table. See "ownerName" for more information.

 Optional with default of "" string 1 to 64 bytes

targetTableName

The "targetTableName" property specifies the name of the target table that has its transform steps replaced by this action.

Note The fully qualified name of a table includes the database, owner, and table names.

 Optional with default of "" string 1 to 64 bytes

temporarySession

The "temporarySession" property makes a session temporary or permanent. When set to true, the session is temporary; otherwise, it is permanent.

When true, the MQ engine resets the current session, and when the client disconnects, the engine removes the session's settings, subscriptions, and message position. Because you normally want the engine to remember your message position between sessions, you rarely set "temporarySession" to true.

Use the "temporarySession" property to control session permanency rather than the "cleanSession" property because its name is more intuitive. The server returns an error if you include both and set them to opposite values.

 Optional with default of false Boolean

true

false

testDatabaseName

The "testDatabaseName" property specifies the database of the test table where this action tests the transform steps.

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.

 Optional with default of the "defaultDatabaseName" defined in the "createSession" action. string 1 to 64 bytes

testOwnerName

The "testOwnerName" property specifies the owner account of the test table where this action tests the transform steps.

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.

 Optional with default of the "defaultOwnerName" defined in the "createSession" action. string 1 to 64 bytes

testTableName

The "testTableName" property specifies the name of the test table where this action tests the transform steps.

Note The fully qualified name of a table includes the database, owner, and table names.

 Required - No default value string 1 to 64 bytes

testTransformScope

The "testTransformScope" property defines the behavior of this action. For more details, see "testTransformScope".

 Required - No default value string enum

"allRecords"

"stop"

"firstRecord"

"lastRecord"

"specificRecords"

thingIdFilter

 The "thingIdFilter" property specifies zero or more unique integers ID of a thing which will be used to filter the results. The "listTags" action includes tags associated with the specified thing, which is a device or software application. Optional with default of [] array of integers zero or more thing id integers

thingName

 The "thingName" property specifies the unique name of a thing. It cannot be the empty string "". Required - No default value string 1 to 64 bytes

thingNameFilter

 The "thingNameFilter" property specifies a partial or full name of a thing to describe. The action returns things that match the specified partial or full name of the thing, provided it satisfies all other specified filter properties. Optional with default of "" string 1 to 64 bytes

thingNames

 The "thingNames" property specifies one or more thing names. Each item in the array is the exact name of a thing. You can use it to describe or delete things. Required - No default value array one or more thing name strings

thingType

The "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. 

 

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.
 Optional with default of "unknown" string 1 to 64 bytes

thingTypeFilter

 The "thingTypeFilter" property filters the results by the value of the "thingType" property. Each string is a partial or complete type, such as, "thingTypeFilter": [ "myTy", "PLC" ]. The action returns things that match at least one item in the array, provided it also satisfies all other specified filter properties. Optional with default of [] array of strings zero or more type strings

threads

The "threads" property specifies the number of threads assigned to a topic to write published messages to disk. 

  • The default of 1 is enough to handle typical workloads.
  • For heavy workloads, you may increase the number of threads to 2 or 3.
 Optional with default of 1 integer

1

2

3

timeFormat

The "timeFormat" property specifies the format of a time or a datetime embedded in a JSON string. The server uses it when it needs to transform or convert a time or datetime embedded in a JSON string into a FairCom time or timestamp. It also uses it when it needs to convert a time or datetime field value into a time embedded in a JSON string. For more details, see "timeFormat".

 Optional with default of "hh.mm.am/pm" string

"hh.mm.am/pm"

"hh.mm.ss.am/pm"

"hh.mm.ss"

20:15:30

20.15&30

20H15M30S

"hh.mm"

"hhmm"

tls

 The "tls" property 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.  Optional with default of {} object

"allowedCipherSuites"

"certificateAuthoritiesFilename"

"certificateFilename"

"privateKeyFilename"

topic

The "topic" property specifies the unique, user-defined name for the topic.

  • The "topic" name is typically less than 150 characters.
  • The "topic" name will be used in all subsequent references to the topic, such as when re-configuring or deleting the topic.

 

 Optional with default of "" string 1 to 65,500 bytes

topicAliasMaximum

The "topicAliasMaximum" property specifies the maximum number of topic aliases that the MQTT client can support.

 Optional with default of 0 integer 0 to 65535

topicFilter

The "topicFilter" property contains a topic filter, which may contain MQTT wildcard characters, #, and +. Without wildcard characters, it matches one topic. When containing wildcard characters, it may match one or more topics.

 Optional with default of "" UTF-8 string topic names

topicIdFilter

 The "topicIdFilter" property specifies the unique integer ID of an MQTT topic. The "listTags" action includes tags associated with the specified topic. Optional with default of [] array of integers zero or more topic id integers

topics

The "topics" property specifies the name of each "topic" that you want to be described in the results.

 Optional with default of []

array

 0 or more topic strings

transactionDescription

 The "transactionDescription" property identifies the object by this description.

Optional with default of ""

 string 0 to 65,500 bytes

transactionId

 The "transactionId" property identifies a transaction in which the specified action will be included. Optional with default of "" string 0 to 255 bytes

transactionModel

The "transactionModel" property defines how the server processes transactions for a table. It is case-insensitive. 

Possible values:
  • "logTransactions"
    • This persists data to data files and writes transaction changes to transaction logs. It supports commit and rollback transactions and data replication. It will not lose data during an unplanned outage. It provides the most durability and the most capabilities, but is slower than the other settings.
  • "ramTransactions"
    • This supports commit and rollback transactions in RAM while persisting data to data files. It does not use a transaction log, which makes it even faster, but an unplanned outage may lose or corrupt unwritten data.
  • "noTransactions"
    • This does not support transactions but still persists data to disk, making it even faster. However, an unplanned outage may lose or corrupt unwritten data.

 

Example request

{
  "api": "db",
  "action": "createTable",
  "params": {
    "transactionModel": "noTransactions"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 Optional with default of "logTransactions" string

"logTransactions"

"ramTransactions"

"noTransactions"

transactionSavepointId

The "transactionSavepointId" property is generated by the server. 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.

Optional with default of ""

 string 0 to 255 bytes

transformBufferInitialBytes

 The "transformBufferInitialBytes" property 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. Optional with default of 0  integer 0 or more bytes

transformCodeName

The "transformCodeName" property specifies the name of an existing code package with a "codeType" of "getRecordsTransform".

When this property is present in a "getRecords..." transform, the server passes the query results to the code package as an array of objects. The code transforms the records and returns a valid JSON value. The server places the value in the "data" property of the response to the "getRecords..." action.

 Optional with default of "". string The string must contain the name of an existing code package with a "codeType" of "getRecordsTransform"

transformName

(deprecated) The "transformName" property specifies the name of a transform process you have created. Replaced by the "transformSteps" property.

 Optional with default of "" string 1 to 64 bytes

transformNameFilter

The "transformNameFilter" property specifies which assigned transform the response will be filtered by. If no integration tables are assigned to the transform, the action returns no tables. If omitted or set to null, the "listIntegrationTables" action will not filter by transform name.

 Optional with default of "" string 1 to 64 bytes

transformStepMethod

 The "transformStepMethod" property 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. For more details, see "transformStepMethod". Required - No default value string enum

"javascript"

"jsonToDifferentTableFields"

"jsonToTableFields"

"tableFieldsToJson"

transformStepName

The "transformStepName" property assigns a name to each transform step.

 Optional with default of "" string 1 to 64 bytes

transformSteps

 The "transformSteps" property specifies an array of transform objects. Required - No default value array of objects

0 or more objects containing 1 or more of the following properties:

"codeName"

"databaseName"

"ownerName"

"mapOfPropertiesToFields"

"targetDatabaseName"
"targetOwnerName"

"targetTableName"

"transformStepMethod"

"transformStepName"

"transformStepService"

transformStepService

The "transformStepService" property 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.

 

 Optional with default of "" string 1 to 64 bytes

triggers

The "triggers" property specifies a list of events on a table that create data change events.

 Optional with default of [ "insert", "update", "delete" ] array of enum strings

"delete"

"insert"

"update"

type

The "type" property specifies the field's data type. See Data types for the limits, valid values, and whether "length" and "scale" are required.

 

Request example

"fields": [
  {
    "name": "j",
    "type": "number"
  }
]
 Required - No default value string

"json"

"bit"

"tinyint"

"smallint"

"integer"

"bigint"

"real"

"float"

"number"

"money"

"date"

"time"

"timestamp"

"char"

"varchar"

"lvarchar"

"binary"

"varbinary"

"lvarbinary"

unique

The "unique" property causes the "createIndex" action to create a unique index, which requires the columns in the index to have a unique value for each record in the table, when set to true. 

"params": {
  "unique": true
}
 Optional with default of false Boolean

true

false

unsetHealthMeasures

The "unsetHealthMeasures" property specifies whether or not to include sessions without health measures in the response.

 Optional with default of true Boolean

true

false

uri

 The "uri" property specifies the identifier name of the Rest resource. Required - No default value string 1 to 1024 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


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

Required - No default value

 

Optional with default of the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

usernameFilter

The "usernameFilter" property contains usernames that filter the returned list of sessions by the accounts associated with those usernames.

 Optional with default of [] array 1 to 64 bytes

usernames

 The "usernames" property specifies the names of the accounts that the action will target. Optional with default of [] array 0 or more usernames, each between 1 and 64 bytes.

userProperties

The "userProperties" property specifies an array of key-value objects used to describe a user. A key-value object contains a "key" property and a "value" property with string values. You can assign multiple key-value pairs to an MQTT 5 message; the server includes them in the messages it delivers to subscribers. The server may process specific key-value pairs as instructions that modify its behavior.

"userProperties": [
  {
    "key": "some key",
    "value": "some value"
  }
]
 Optional with default of null array 0 or more key/value pairs

validateMqttPayload

The "validateMqttPayload" property specifies whether the broker will validate the payload of each MQTT message.

  • When true, the MQTT broker validates the payload of each MQTT message to verify that it matches the type specified by the "mqttPayloadType" property.
    • If a payload fails validation, the message is delivered without change to all subscribers. The broker also sets the error field to true and adds an error object to the log field (see the error object example). Users, applications, and JavaScript transform steps can read the values of the error and log fields to know when incoming content is invalid.
  • When false, the MQTT broker does not validate the payload. This increases message throughput because validation increases the time it takes to process each message. Without validation, the broker cannot update the error and log fields to indicate when content is invalid. Lastly, invalid content can cause problems for subscribers and JavaScript transforms that expect valid content.

 

Example error object describing an invalid MQTT payload

[
  {
    "errorCode": 12046,
    "errorMessage": "Payload is not a valid JSON.",
    "errorSource": "MQTT payload format"
  }
]
 Optional with default of the "defaultValidateMqttPayload" value in the services.json file, which is true by default. Boolean

true

false

value

The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records.

 

In Key-Value actions, the required "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

variantFormat

 The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request. For more details, see "variantFormat". Optional with default of "json" string

"json"

"binary"

"string"

"variantObject"

The "verifyLinks" property causes the action to verify that the specified labels, records, and tables exist when set to true. 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.

 Optional with default of true Boolean

true

false

waitToBeLoaded

The "waitToBeLoaded" property causes the "createIndex" action to not return until the index is created when set to true. 

  • Waiting for a large index to be created may cause an API timeout.
  • The default is to return immediately and create the index in the background.
"params": {
  "waitToBeLoaded": true
}
 Optional with default of true Boolean

true

false

willContentType

The "willContentType" property specifies the content type of the last will message.

 Optional with default of "" string

IanaMediaType

CustomType

willCorrelationData

The "willCorrelationData" property specifies a JSON value that can be used to set will request-response messages.

 Optional with default of "" JSON 0 to 65,500 bytes

willDelaySeconds

The "willDelaySeconds" property specifies the number of seconds the server will wait before sending the last will message.

 Optional with default of 60 integer  

willExpirySeconds

The "willExpirySeconds" property specifies the number of seconds before the last will message expires.

 Optional with default of 60 integer  

willPayload

The "willPayload" property contains the payload of the last will message. You can set it to any JSON value, including binary values embedded in a JSON string or array.

 Required - No default value JSON  

willPayloadFormatIndicator

The "willPayloadFormatIndicator" property specifies the payload format for the last will message.

 Optional with default of "none" ENUM

"none"

"utf8"

willQoS

The property "willQoS" is reserved. The server sets it to 2.

 Optional with default of 2 integer  

willResponseTopic

The "willResponseTopic" property specifies the topic for the last will message response.

 Optional with default of "" string  

willRetain

The "willRetain" property tells the FairCom server to send the will message to new subscribers as the first message they receive when subscribing to a topic when set to true.

 Optional with default of false Boolean

true

false

willTopic

The "willTopic" property contains 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.

 Optional with default of "" UTF-8 string  

willUserProperties

The "willUserProperties" property assigns key-value pairs to the last will messages.

 Optional with default of [] array  

 

 
 

 

 

 

Response examples

Success

{
    "result": {},
    "requestId": "00000003",
    "errorCode": 0,
    "errorMessage": "",
    "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response properties

Response properties

Universal response properties list

Property Description Type Limits (inclusive)

_bookmark_

The "_bookmark_" property designates a universal record identifier (aka bookmark). You can always use a bookmark to identify a record, even when the table lacks a primary key. 

 

Returned when the request property "includeBookmarks" is true. 

 string 0 to 2048 bytes

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 specifies an array of ciphers that the server will accept for communications with clients. 

  • 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:
      • ["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • @STRENGTH at the end of the list will 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 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".

 string The filepath to the folder where FairCom's apps are located.

applications

The "applications" property 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 building and adding your own app servers in 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 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 "autoValue" property indicates when and how the server automatically sets the field value. See autoValue for more details.  string

"none"

"incrementOnInsert"

"timestampOnInser"

"timestampOnUpdate"

"timestampOnUpdateAndInsert"

"changeid"

 

Some actions only:

“bookmark”

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 indicates the average number of messages the specified topic publishes per hour. integer The average number of messages published per hour

averageMessagesPerMinute

 The "averageMessagesPerMinute" property indicates the average number of messages the specified topic publishes per minute. integer The average number of messages published per minute

binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. See binaryFormat for more details.  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 contains a list of "brokerConnectionName" strings. Each string is the name of a table. 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 indicates the unique broker hostname or TCP/IP address of the specified broker connection.

 string The unique broker host name or TCP/IP address of the specified broker connection.

brokerPort

The "brokerPort" property defines the TCP/IP port.

 integer A number between 1 and 65535

brokerUserName

The "brokerUsername" property is the login name to the external broker. 

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

 VARCHAR(500) string The login name to the external broker.

caCertificateFilename

The "caCertificateFilename" property specifies the name and optional path of the CA certificate file (such as "ca.pem"). 

  • When included, allows 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 authority's certificate file.
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
 string No limits

caseInsensitive 

The "caseInsensitive" property determines if case comparisons for index key values accounts for case. When false, the server stores index key values in mixed case for comparisons.

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

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

true

false

certificateFilename

The "certificateFilename" property 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.

 string 1 to 64 bytes

clientCertificateEnabled

 The "clientCertificateEnabled" property enables client certificate authentication when set to true. The target FairCom DB or RTG server must be configured to accept client certificates. boolean

true

false

clientCertificateFilename

The "clientCertificateFilename" property specifies the name of the client certificate file. 

 string The file name of a client certificate.

clientPrivateKeyFilename

The "clientPrivateKeyFilename" property specifies the name of the client private key file. 

 string The file name of a client certificate private key file.

clientName

 The “Clientname” property 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 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

 The “collectStats” property identifies whether usage statistics are being collected and stored. boolean

true

false

compression

 The “compression” property identifies whether the index is compressed. string

"on"

"off"

"auto"

conditionalExpression

 The “conditionalExpression” property 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. 

  • 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 identifies the connector in the "tagProvenance" objects returned from the "alterTag" and "describeTags" actions when the "includeTagProvenance" property is true. 

  • 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 unique identifier returned by the server.

  • The "getRecordsFromCursor" action uses it to quickly and efficiently retrieve paginated records.
  • 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 specifies the database that contains the tables. 

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

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

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

 “dataChangeStreams” lists the data change streams that match the request filters 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 (case-insensitive) defines the format of the "data" property. The default for "dataFormat" can be changed during a "createSession" action by assigning a different value to the "dataFormat" property in "defaultResponseOptions".

  • "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. 

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

 The "binaryFormat" property determines the format of binary values embedded in JSON strings. For more details, see defaultBinaryFormat.  string One of the following: "base64", "hex", or "byteArray".

defaultDatabaseName

The "defaultDatabaseName" property specifies which database name to use when the "databaseName" property is omitted. Its value is case-insensitive.

 string 1 to 64 bytes

defaultDebug

The "defaultDebug" property defines the default value of the "debug" property for all requests in a session. 

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 "defaultValue" property specifies the field's default value. string 0 to 65,500 bytes

defaultVariantFormat

The "defaultVariantFormat" property sets the default value for the "variantFormat" property when a JSON Action request omits 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.

 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.

 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.

 string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

defaultValue

 “defaultValue” specifies the default value of a field. string 0 to 65,500 bytes

deferindexing

 “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 due to the changes being included 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 describes the tags that were deleted. array of objects

zero or more objects containing the following properties:

"id"

"tagName"

deprecated

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

 Boolean

true

false

null

description

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

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

 

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

 

 string 1 to 65,500 bytes

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 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 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 assigns an integer from -32768 to 32767 to a label. 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 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. 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,
    "primaryKey": 0, 
    "autoValue": "none"
  }
]
 array

"autoTimestamp"

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

"primaryKey"

"autoValue"

 

updateRecords and deleteRecords only: 

“bookmark”

fixedOutput

 “fixedOutput” includes all properties in a data change event when true. Boolean

true

false

group

The "group" property 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.

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 whether the group name exists in the list of groups returned by the "listLabelGroups" action. 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 "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 "hostnames" property specifies zero or more hostnames assigned to the device. Each item in the array should be a different hostname. 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 of strings zero or more hostname strings of 1 to 64 bytes

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 specifies the number of seconds a session with no activity will remain open.

A value of 0 keeps a session open indefinitely.

 integer 0 to 2147483647

idleCursorTimeoutSeconds

The "idleCursorTimeoutSeconds" property 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. 

  • 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

 "immutableKeys" indicates whether a key's value 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 specifies the source table fields in the data change event or all fields when empty.

 array of strings 0 or more strings

includeExistingRecordsFilter

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

 Boolean

true

false

includeMetadata

The "includeMetadata" property adds user-defined properties to each data change event.

 array of metadata objects 
[
  {
    "propertyPath": "myPath",
    "propertyValue": "myValue"
  }
]

includePrimaryKey

The "includePrimaryKey" property 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

 “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"

“isPrimaryIndex”

inputConnectors

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

 

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

 array of objects

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

"connectorName"

"connectorId"

"lastCollectedTimestamp"

inputName

 The "inputName" property specifies the unique name of an input. string 1 to 64 bytes

integrationServices

The "integrationServices" property describes and controls FairCom's integration services. 

  • 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

isPrimaryIndex

The “isPrimaryIndex” property returns whether or not the index being acted upon is the primary key index of its table. 

 

 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. For more details, see jsonActionApiDefaults.  object see jsonActionApiDefaults

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. string 1 to 128 bytes

keys

 The "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 "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 can assign 1 or more labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

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

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

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

 

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

 

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

 

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

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

1 or more label objects

 

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

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 describes and controls FairCom's listeners. 

  • 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 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 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 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" 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 "location" property specifies the item's location. A thing may have one location. 

 

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

 “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 "manufacturer" property specifies the manufacturer of the thing. A thing may have one manufacturer. Many things can share the same manufacturer. 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.

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. If this property is 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 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 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 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 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. 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"model" property specifies a thing's model. A thing may have one model. Many things can share the same model number. 

 

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 specifies the variant type format of the "source_payload" field. For more details, see mqttPayloadType.  string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

name

The "name" property is the name of a label or field. 

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. 

  • It may be set to one of two values:
    • "newMessages" (default)
    • "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.

  • 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. 
  • 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

 “nullable” identifies whether a field can contain a NULL value. Boolean

true

false

numberFormat

The "numberFormat" property (case-sensitive) defines the format of JSON numbers. 

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.
 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 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. 

  • "outputPayloadField" must be one of the following values: 
    • "source_payload" (default) allows
    • 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 identifies the user who owns an object (see Object owner).  string 0 to 64 bytes

partialKey

The "partialKey" property 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. 

  • 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 "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 defines a password that 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 specifications for requirements of this and all other system properties.

 string 0 to 256 bytes

permanentSession

The "permanentSession" property indicates if a session is permanent. 

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 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 "photo" property contains a photo of a thing. 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.

primaryIndexName

 The “primaryIndexName” property returns the name of the primary key index. If there is none, it returns “”. string 0 to 256 bytes

primaryKey

 When > 0, the "primaryKey" property identifies the ordinal position of the field within the table's primary key. integer 0 to 32

primaryKeys

“primaryKeys” 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 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" specifies the name and optional path of a server key file.

    "tls": {
      "allowedCipherSuites": "",
      "certificateAuthoritiesFilename": "",
      "certificateFilename": "",
      "privateKeyFilename": ""
    },
 string No limits

problemCode

The "problemCode" property specifies a unique code number that identifies the type of problem.

 integer A unique code number

problemData

The "problemData" property 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 contains a message describing the problem.

 string A message detailing the problem

problems

 The "problems" property 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 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 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

Contains properties that define the data values of a "propertyPath". 

The data values specified in the "propertyValue" object can be strings or objects.

  • "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 provides a short description of the specified server's purpose.

 

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

 

This API uses the Label API to manage purposes.

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

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. 

  • 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 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 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.

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. 

Possible 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 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. It applies when a client publishes to the broker and when the broker publishes to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. 

  • 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.
  • 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 "returnTagsBy" property is an enumerated string with the following values: "tagName" and “id".It is used by the "listTags" action to determine whether tags are returned by ID or by name. string enum

"id"

"tagName"

returnThingsBy

 The "returnThingsBy" property is an enumerated string with the following values: "name" and "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 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 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

reverseCompare

The "reverseCompare" property specifies whether the bytes in an index key field are compared starting from the beginning to the end of the key.

When true, bytes in an index key field are compared starting from the end to the beginning of the key. This speeds comparisons when the unique parts of the bytes are at the end of keys.

"fields": [
  {
    "reverseCompare": true
  }
]
 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. 

 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 specifies the unique name of the account that owns an object. 

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

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

 “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.

 object

Allen-Bradley "params"

Modbus "params"

OPC UA "settings"

Siemens S7 "params."

sortDescending

The "sortDescending" property sorts the returned sessions in descending order based on the last time the sessions connected or disconnected, the sessions' "clientName" properties, or the sessions' IP addresses.

"fields": [
  {
    "sortDescending": true
  }
]
 Optional with default of false Boolean

sourceDatabaseName

The "sourceDatabaseName" property 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 contains the name of a field from an integration table. 

 string

"source_payload"

"t1"

"t2"

"t3"

"t4"

"t5"

"t6"

"t7"

"t8"

"t9"

sourceDataFilePath

The "sourceDataFilePath" property 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.  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 "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. 
  • 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 "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 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 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 specifies the login password of a FairCom DB or RTG server. string 1 to 128 bytes

sourcePayloadBinaryFormat

The "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".
  • 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 "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".
  • 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 "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.
  • 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 "sourcePayloadPath" property is the propertyPath of the tag's value in the source_payload field, such as "sourcePayloadPath": "temperature".

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


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

 string 1 to 2048 bytes

sourcePayloadTimeFormat

The "sourcePayloadTimeFormat" 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".
  • Use one of the following values (see "timeFormat"):
  • 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 "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".
  •  


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 specifies the ISAM TCP/IP port of a FairCom DB or RTG server. int16 1 to 65535

sourceServerName

 The "sourceServerName" property 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 contains 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 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 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 "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 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 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 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 specifies a partial match for a connection name. string 1 to 64 bytes

streamingConnections

The "streamingConnections" property lists the streaming connections that match the request filters 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 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 "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 "tableName" property is a string containing the name of a table.

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

 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 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 "tagDataType" property specifies the data type of the tag.  

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

tagName

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

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

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

 string 1 to 256 bytes

tagNames

 The "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.  string 1 to 256 bytes

thingName

 The "thingName" property specifies the unique name of a thing.   string 1 to 64 bytes

thingNames

 The "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. 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 "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. 

 

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 "testDatabaseName" property specifies the database for the test table used by this action to test 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 "testOwnerName" property specifies the owner account for the test table used to test 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 "testTableName" property specifies the name of the test table used to test 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. 

  • 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 allowed cipher suites, and whether the client certificate is required. 

 

"tls": { "serverCertificateFilename": "server.crt", "privateKeyFilename": "server.key", "caCertificateFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" "requireClientCertificate": "true"
}
 object

"allowedCipherSuites"

"caCertificateFilename"

"certificateFilename"

"privateKeyFilename"

topic

The "topic" property 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. 

  • 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 specifies the number of bytes the session allocates 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 optimizes to help prevent the server from performing expensive memory allocations.

 integer 0 or more bytes

transformPercentComplete

The "transformPercentComplete" property returns 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 describes and controls FairCom's transform services. 

"transformServices" [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": true
  }
],
 array of objects

"enabled"

"serviceLibrary"

"serviceName"

transformStatus

 The "transformStatus" property describes the state of the transform process. Example values include "running" and "done". string the status of the transform

transformStepMethod

The "transformStepMethod" property specifies the type of transform, such as the "javascript" transform method, which runs JavaScript to change the table's data, or the "jsonToTableFields" transform method, which extracts values from properties in a JSON field and stores them in other fields.

Note The "transformStepMethod" property replaces the deprecated "transformActionName" property.

The “transformStepMethod” value affects 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 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 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 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 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 specifies the path to the "serviceLibrary" file. 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 specifies 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 specifications for requirements of this and all other system properties.

In Key-Value actions, the "username" property is 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

 

 

 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 can be any JSON value that is associated with a label.

 

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 "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 verifies if 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

When true, “willRetain” 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 contains 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  
 
 

 

 

 

 

data conversion endpoint documentation

Was this article helpful?

Give feedback about this article

Related Articles