FairCom — 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.

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

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

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"

verifyLinks

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