Response properties

Response properties

Universal response properties list

Property Description Type Contents

accounts

The "accounts" property returns each account that matches one of the usernames or partial usernames specified in the request. Each account is returned as an object, containing all the properties relevant to the account.

    "accounts": [
      {
        "username": "admin",
        "accountDescription": "",
        "lockoutAfterNFailedAttempts": 0,
        "maxDaysBeforePasswordMustChange": 0,
        "maxMinutesBeforeNextLogin": 0,
        "memoryLimit": 0,
        "memoryRule": "default",
        "roles": [
          {
            "roleName": "ADMIN"
          }
        ]
      }

 

 array of objects One object per matching account.

accounts

.roleNames

The "roleNames" property lists the roles given to the accounts specified by the "partialNames" property. This property can specify one or more roles, each between 1 and 64 bytes.

  "params": {
    "partialNames": [
      "adm",
      "NewAccount"
    ]
  },

 

 array of strings An array of 1 or more strings between 1 and 64 bytes.

accounts

.username

The "username" property is a required string up to 64 bytes long. It is the name that uniquely identifies the account.

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

 string 1 to 64 bytes

affectedRows

 The "affectedRows" property specifies the number of records that were affected by the SQL statement. integer number of records affected by the statement.

allowedCipherSuites

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

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

applicationRoot

The "applicationRoot" property is a string that specifies the location of web applications relative to <faircom>/server/.

The default value of "./web/apps/" translates to the folder <faircom>/server/web/apps.

There is rarely a reason to change the "applicationRoot".

For information on how to add your own web applications, which can use any of FairCom's jsonAction APIs, contact FairCom.

 string The filepath to the folder where FairCom's apps are located.

applications

The "applications" property is an array of objects that describes and controls web applications that can run with the FairCom server. It defaults to an empty array which means no applications are configured to run.

FairCom and other custom web applications are single-page, browser-based applications served from folders in the default <faircom>/server/web/apps/ folder.

An app server is a backend service used by one or more web applications. It listens to HTTP and/or WebSocket requests and then returns results.

Contact FairCom for information on how to build and add your own app servers using C or C++.

The following "applications" properties should be considered for each web app:

  • "enabled"
  • "folderName"
  • "serviceLibrary"
  • "serviceName"
  • "uriPath"
 array of objects One object per application.

authToken

The "authToken" property signifies that the client is authenticated and authorized. It is required.

It is supplied by the server in response to the connect action.

Clients must include it in all subsequent requests to validate that they are authenticated and authorized. If the client does not supply the correct values, the server returns an unauthorized error.

 string 0 to 255 bytes

autoValue

The optional "autoValue" property indicates when and how the server automatically sets the field value.

Only one of these values is allowed per field.

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

Request

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

Response

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

"none"

"incrementOnInsert"

"timestampOnInser"

"timestampOnUpdate"

"timestampOnUpdateAndInsert"

"changeid"

averageMessagesPerDay

 The "averageMessagesPerDay" property describes how many messages the specified topic publishes per day on average. integer The average number of messages published per day

averageMessagesPerHour

 The "averageMessagesPerHour" property describes how many messages the specified topic publishes per hour on average. integer The average number of messages published per hour

averageMessagesPerMinute

 The "averageMessagesPerMinute" property describes how many messages the specified topic publishes per minute on average. integer The average number of messages published per minute

brokerConnectionNames

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

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

1 object for each broker connection matching the request containing some or all of the following properties:

"brokerHostname"

"brokerPort"

"brokerUserName"

"reconnectFrequencySeconds"

"isConnected"

"statusCode"

"statusMessage"

brokerHostname

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

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

brokerPort

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

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

brokerUserName

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

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

  • A zero-length username is invalid.
  • It is VARCHAR(500).
 string the login name to the external broker.

caCertificateFilename

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

  • You must include "caCertificateFilename" to allow clients to use X509 certificates to authenticate with the server.
  • The certificate authorities file contains the list of certificate authorities the server uses to validate X509 certificates that clients present as authentication credentials.
  • In order for an X509 certificate to be accepted by the server, the certificate must be signed by a certificate authority that is present in the certificate authorities certificate file.
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
 string No limits

certificateFilename

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

    "tls": {
      "allowedCipherSuites": "",
      "certificateAuthoritiesFilename": "",
      "certificateFilename": "",
      "privateKeyFilename": ""
    },
 string No limits

changedLabels

The "changedLabels" property lists an object for each label that has been updated with new values. Each object contains the "id", "group", "name", "value", "enum", "sequence", "deprecated", "description", and "metadata" properties and their new values for the label that was updated.

    "changedLabels": [
      {
        "id": 4,
        "group": "myLabelGroupName",
        "name": "myLabelName",
        "value": 99,
        "enum": 0,
        "sequence": 1.2,
        "deprecated": false,
        "description": "My label description.",
        "metadata": {}
      }
    ]
 array of objects An object for each changed label.

changeIdField

This property's value designates the name of the field used for change-tracking functionality if you are not using the "changeId" field for change tracking.

"createTable" automatically creates the "changeId" field to hold the change tracking number used for optimistic locking. Using the "changeId" field for optimistic locking is a best practice.

However, if you use the name "changeId" for another purpose, you can use the "changeIdField" property to designate a different field as the change tracking number field.

 

Request example

"params": {
  "changeIdField": "changetrackingid"
  }
 string 1 to 64 bytes

clientName

 uniquely identifies an MQ session. string  

clonedCodeId

The "clonedCodeId" indicates which copy the specified code package is out of all existing code package clones. If the specified code package is the original one, its value will be 0.

  "result": {
    "data": [
      {
        "codeId": 1,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 1,
        "clonedCodeId": 0
    ]
  },
 integer The cloned code ID.

codeServices

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

 array of objects

"serviceName"

"serviceLibrary"

"enabled"

codeVersion

The "codeVersion" property indicates the version of the specified code package.

  "result": {
    "data": [
      {
        "codeId": 1,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertTemperature",
        "codeVersion": 1,
        "clonedCodeId": 0
    ]
  },
 integer The version of the specified code package.

collectStats

 identifies whether usage statistics are being collected and stored. boolean

true

false

compression

 identifies whether the index is compressed. string

"on"

"off"

"auto"

conditionalExpression

 identifies an optional conditional expression that filters which records are included in the index. It is null when there is no conditional expression. string

null

or a string containing a conditional expression.

connectionStatus

The "connectionStatus" property is returned by the "describeMqSessions" action to indicate if and how a client is connected to an MQ session. It has the following values:

  • "disconnected" indicates no device or software is connected to the MQ session.
  • "connected" indicates a device or software has established a permanent connection to the MQ session.
  • "connectedTemporarily" indicates a device or software has established a temporary connection to the MQ session. When the device or software disconnects, the server removes the data associated with the MQ session.
 string

"disconnected"

"connected"

"connectedTemporarily"

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.

creationTime

 The "creationTime" property details the date and time when the specified topic was created. This property stores the creation date in an ISO 8601 timestamp. timestamp An ISO 8601 timestamp

cursorid

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

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

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

 string 0 to 255 bytes

data

The "data" property contains a response message. Its contents are defined by the action. It is an empty array when no results are available. The following is an example of the data property from a code package action.

  "result": {
    "data": [
      {
        "codeId": 6,
        "databaseName": "faircom",
        "ownerName": "admin",
        "codeName": "convertAndCategorizeTemperature",
        "codeVersion": 1,
        "clonedCodeId": 1,
        "codeStatus": "active",
        "codeLanguage": "javascript",
        "serviceName": "javascript",
        "codeType": "module",
        "description": "optional new description",
        "metadata": {},
        "createdBy": "ADMIN",
        "createdOn": "2025-08-25T21:48:38.109",
        "updatedBy": "ADMIN",
        "updatedOn": "2025-08-25T21:48:38.109",
        "comment": "Cloned from convertTemperature",
        "codeFormat": "utf8"
      },
    ]
 array of objects The action determines its contents.

databaseConnectionString

 The "databaseConnectionString" property specifies the connection string for the database that holds the persistence table. string No limits

databaseName

The "databaseName" property is an optional string that specifies the database that contains the tables. It defaults to the database name supplied at login.

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

  • A zero-length "databaseName" is invalid.
  • Its length limit is from 0 to 64 bytes.
  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.
  • If no default database is specified during "createSession", "databaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.
"params": {
  "databaseName": "mainDatabase"
  }
 string 1 to 64 bytes

databaseUserName

 The "databaseUserName" property specifies the user name of the account logged into the database that holds the persistence table. string 0 to 64 bytes

dataFormat

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

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

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

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

"autoDetect"

"arrays"

"objects"

defaultApi

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

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

string enum

"admin"

"hub"

"mq"

"db"

defaultBinaryFormat

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

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

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

 

Example requests

 

Create a "binary_test" table

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

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

 

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

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

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

 

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

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

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

 

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

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

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

 

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

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

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

 

Responses

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

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

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

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

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

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

 

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

defaultDatabaseName

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

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

defaultDebug

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

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

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

"none"

"max"

defaultOwnerName

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

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

defaultValue

 The optional "defaultValue" property identifies the default value of the field. string 0 to 65,500 bytes

defaultVariantFormat

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

 string

"json"

"binary"

"string"

"variantObject"

defaultResponseOptions

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

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

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

Example

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

"binaryFormat"

"dataFormat"

"numberFormat"

binaryFormat

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

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

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

 

Example requests

 
Create a "binary_test" table

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

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

 

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

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

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

 

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

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

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

 

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

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

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

 

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

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

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

 

Response examples

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

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

 

Retrieve a record with "binaryFormat" as hexadecimal

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

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

 

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

 

Retrieve a record with "binaryFormat" as base64

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

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

 

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

defaultResponseOptions

.numberFormat

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

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

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

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

 

Example request

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

"number"

"string"

defaultResponseOptions

.stringFormat

The optional "stringFormat" property in "responseOptions" changes how "char", "varchar", "lvarchar", and "variant" string field values are returned.

This property applies to all "getRecords..." actions, except for "getRecordsUsingSql" because SQL controls the format of strings it returns.

 string

"json"

"hex"

defaultResponseOptions

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

defaultRetentionPeriod

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

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

defaultRetentionPolicy

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

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

"doNotPersist"

"neverPurge"

"autoPurge"

defaultRetentionUnit

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

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

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

defaultValue

 specifies the default value of a field. string 0 to 65,500 bytes

deferindexing

 identifies whether deferred indexing is enabled. A deferred index builds and updates asynchronously. This speeds up inserts, updates, and deletes, with a slight delay from including the changes in the index. boolean

true

false

deletedLabels

The "deletedLabels" property lists an object for each label that has been deleted. Each object contains the "id", "group", "name", "value", "enum", "sequence", "deprecated", "description", and "metadata" properties and their values for the label that was deleted.

    "deletedLabels": [
      {
        "id": 4,
        "group": "myLabelGroupName",
        "name": "myLabelName",
        "value": 99,
        "enum": 0,
        "sequence": 1.2,
        "deprecated": false,
        "description": "My label description.",
        "metadata": {}
      }
    ]
 array of objects An object for each deleted label. 

deprecated

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

 Boolean

true

false

null

description

The "description" property optionally provides additional information about a label. You can use it as internal or external documentation about the meaning, purpose, and usage of a label.

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

 

 string 1 to 65,500 bytes

elapsedMilliseconds

 The "elapsedMilliseconds" property specifies the number of milliseconds it took for the server to execute the SQL statement. integer The number of seconds it took to execute the statement.

enabled

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

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

true

false

enablePermanentJsonApiSessions

The "enablePermanentJsonApiSessions" property enables or disables permanent sessions. When set to false, permanent sessions cannot be created.

 Boolean

true

false

enum

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

 

 smallint -32768 to 32767

errorCode

 The "errorCode" property indicates an error when set to a non-zero integer or success when 0. integer -2147483648 to 2147483647

errorMessage

 The "errorMessage" property displays a human-readable error message. string 0 to 256 bytes

fields

The "fields" property is an array of objects. It is required when creating a table. Each object in the array defines a field by specifying its properties.

 

"fields": [
  {
    "autoValue": "none",
    "name": "name",
    "type": "varchar",
    "length": 50,
    "scale": null,
    "defaultValue": null,
    "nullable": false
  }
]
 array

"autoValue"

"primaryKey"
"name"
"type"
"length"
"scale"
"defaultValue"
"nullable"

group

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

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

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

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

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

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

 

 string 1 to 64 bytes

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.

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 a label. 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

idleConnectionTimeoutSeconds

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

A value of 0 keeps a session open indefinitely.

 integer 0 to 2147483647

idleCursorTimeoutSeconds

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

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

ids

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

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

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

 array 0 or more ids

immutableKeys

 identifies whether the key's values can be changed. boolean

true

false

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"

integrationServices

The "integrationServices" property is an array of objects that describes and controls FairCom's integration services. It defaults to an empty array.

  • An integration service is a connector that uses a protocol to collect information from devices and/or deliver information to devices — for example, FairCom Edge includes connectors that collect data from Modbus and OPC UA.
  • For information on how to build and add your own connectors using C or C++, contact FairCom.
  • Do not change the settings of the object properties unless disabling an unused connector.
 array of objects

"enabled"

"schemaName"

"serviceLibrary"

"serviceName"

isConnected

 The "isConnected" property indicates whether the specified broker connection is active. Boolean

true

false

jsonActionApiDefaults

The default settings for the FairCom jsonAction APIs and browser-based applications are specified in the services.json file in the "jsonActionApiDefaults" property.

Note Use the Google Chrome browser for FairCom browser-based tools. Other browsers may cause unexpected behavior.

 

Default settings for jsonAction APIs

"jsonActionApiDefaults": {
    "defaultApi": "db",
    "defaultBinaryFormat": "hex",
    "defaultVariantFormat": "json",
    "defaultDatabaseName": "faircom",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions": 
    {
      "binaryFormat": "hex",
      "variantFormat": "json",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy":"autoPurge",
    "defaultRetentionPeriod":"4",
    "defaultRetentionUnit":"week"
  }

 

The property names and values in "jsonActionApiDefaults" are identical to those in the "params" property of "createSession", "alterSession", and "describeSessions". Each FairCom product ships with different default settings that make sense for that product — for example, in FairCom DB, the "defaultAPI" property is set to "db", in FairCom MQ it is set to "mq", and in FairCom Edge it is set to "hub".

You can change the values of the properties in services.json, and all jsonAction APIs and browser-based user interfaces will use these properties as their default. If any of the properties in "jsonActionApiDefaults" are omitted from services.json, the property values may vary depending on the JSON action performed.

Note FairCom's core configuration file, ctsrvr.cfg, contains a SQL_DATABASE setting. You can set SQL_DATABASE to the name of a database and when the FairCom server starts, it creates a database with that name if it does not already exist. 

By default, ctsrvr.cfg sets SQL_DATABASE to "ctreeSQL". If you change SQL_DATABASE to use another database name, it is a good practice to put the same name in the "defaultDatabaseName" property in services.json. This makes your newly created database the default database in all of FairCom's jsonActionAPIs and browser-based applications.

 

Keeping SQL_DATABASE and "jsonActionApiDefaults" in sync

ctsrvr.cfg 

SQL_DATABASE my_new_database

services.json 

"": {
    "defaultApi": "db",
    "defaultBinaryFormat": "hex",
    "defaultDatabaseName": "my_new_database",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions": 
    {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy":"autoPurge",
    "defaultRetentionPeriod":"4",
    "defaultRetentionUnit":"week"
  }
 object

"defaultApi"

"defaultBinaryFormat"

"defaultDatabaseName"

"defaultDebug"

"defaultOwnerName"

"defaultResponseOptions"

"defaultRetentionPeriod"

"defaultRetentionPolicy"

"defaultRetentionUnit"

"defaultVariantFormat"

"enablePermanentJsonApiSessions"

"idleConnectionTimeoutSeconds"

"idleCursorTimeoutSeconds"

"maxJsonApiSessions"

"maxJsonApiSessionsPerIpAddress"

"maxJsonApiSessionsPerUsername"

labels

The "labels" property is a required array of label objects. It can assign many labels to the same record. Each label may belong to any group. Each specified label must have already been created using the "createLabel" action so that it exists in the label table.

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

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

length

 Identifies the length of the field. integer 1 to 65500 

listeners

The "listeners" property is an array of objects that describes and controls FairCom's listeners. It defaults to an empty array.

  • A listener is a service that listens on a specified TCP/IP port for a specified protocol.
  • FairCom servers provide listeners for the protocols:
    • "http"
    • "https"
    • "mqtt"
    • "mqtts"
    • "mqttws"
    • "mqttwss"
  • Each protocol is hardwired to a specific set of backend services:
    • The HTTP and HTTPS protocols are hardwired to support the jsonAction APIs and web applications. 
    • The MQTT and MQTTS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over TCP/IP.
    • The MQTTWS and MQTTWSS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over WebSocket.
  • For information on how to build and add your own listeners using C or C++, contact FairCom.
  • Do not change the object property settings unless disabling an unused listener.
  • Each protocol can listen with TLS authentication for secure communications.
 array of objects

"enabled"

"description"

"port"

"protocol"

"serviceLibrary"

"serviceName"

"tls"

maxConnectionsPerIpAddress

The "maxConnectionsPerIpAddress" property is the number of TCP/IP connections the app server will accept from a single TCP/IP address.

This feature is implemented at the FairCom App Server level to prevent the app server from being overwhelmed by a DoS attack. It protects against simultaneous DoS attacks across multiple protocols: HTTP, HTTPS, MQTT, MQTTS, WS, and WSS.

The default is 25 connections.

A value of 0 disables this protection.

This property can be added to the top level of the services.json file and/or to each listener object in the "listeners" array. At the top level, the property applies to all listeners. Within a listener, it applies only to that listener.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

 

{
  "maxConnectionsPerIpAddress": 5,
    "listeners": [
    {
      "serviceName": "https8443",
      "description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
      "port": 8443,
      "protocol": "https",
      "enabled": true,
      "maxConnectionsPerIpAddress": 5,
      "tls": {
        "certificateFilename": "./web/fccert.pem"
      }
    }
  ]
}
 integer 1 to 2147483647

maxDeliveryRatePerSecond

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

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

maxJsonApiSessions

The "maxJsonApiSessions" property is the total number of JSON API sessions the app server will accept. This setting ensures the server does not consume so many resources that it becomes unstable.

The default value is the maximum number of JSON API connections allowed by the license.

A value of 0 disables this protection and allows JSON API sessions up to the maximum number of connections allowed by the license file.

This property is added to the "jsonActionApiDefaults" object.

 integer 1 to 2147483647

maxJsonApiSessionsPerIpAddress

The "maxJsonApiSessionsPerIpAddress" property is the number of JSON API sessions the app server will accept from the same client IP Address.

The default value is 50.

The maximum possible number of connections is determined by the license file.

A value of 0 disables this protection and allows JSON API sessions with the same IP Address up to the maximum number of connections allowed by the license file.

This property is added to the "jsonActionApiDefaults" object.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

 integer 1 to 2147483647

maxJsonApiSessionsPerUsername

The "maxJsonApiSessionsPerUsername" property is the number of JSON API sessions the app server will accept with the same username. Because of this, an application may use a different account for each JSON API session.

The default value is 50.

The maximum possible number of connections is determined by the license file.

A value of 0 disables this protection and allows unlimited sessions with the same username up to the maximum number of connections allowed by the license file.

If your application uses one account for all JSON API sessions, this feature will need to be disabled.

This property is added to the "jsonActionApiDefaults" object. See the example below.

 

"jsonActionApiDefaults":
{
  "maxJsonApiSessions": 500,
  "maxJsonApiSessionsPerIpAddress": 20,
  "maxJsonApiSessionsPerUsername": 20,
    "defaultApi": "hub",
  "defaultBinaryFormat": "hex",
  "defaultDatabaseName": "faircom",
  "defaultDebug": "max",
  "defaultOwnerName": "admin",
  "defaultResponseOptions":
  {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "idleConnectionTimeoutSeconds": 3600,
  "idleCursorTimeoutSeconds": 600,
  "defaultRetentionPolicy": "autoPurge",
  "defaultRetentionUnit": "week",
  "defaultRetentionPeriod": 4
}
 integer 1 to 2147483647

messageCount

 The "messageCount" property defines the total number of messages published by the topic. BigInteger 0 to 9223372036854775807

metadata

The "metadata" field optionally allows a customer to add a JSON value to the label. It is typically a JSON object, but may be any JSON value. It defaults to null. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

mqttPayloadType

The "mqttPayloadType" property is an optional string that specifies the expected data type of the MQTT payload. When omitted or set to null, it defaults to "binary". When the server receives an MQTT message, it always takes the binary value from the MQTT payload and stores it in the source_payload field. The source_payload field is a variant, which means it stores the type of data it contains. If there are no errors in validating the MQTT payload to match the type specified in "mqttPayloadType", the server assigns the value of "mqttPayloadType" as the variant field's type. 

Depending on the values of the "mqttPayloadType" and "validateMqttPayload" properties, the server may validate the MQTT payload to ensure it matches the type. The default value for the "validateMqttPayload" property is true. The server may also convert the MQTT payload into another form before storing it. If the MQTT payload does not match the type or cannot be converted, the server stores the payload in the source_payload field, sets its variant type to "binary", and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field. 

  • This property is a hint to the server about the format and type of the MQTT message payload.
  • This property does not cause server to validate the MQTT payload to see if it matches the type you set. The server stores the payload as is without validation. For example, setting the type to "json", it does not stop the server from receiving and storing a non-JSON value or invalid JSON document in the source payload.
  • The FairCom Edge Explorer application may use the value of this property to determine the default way to display a topic's payload.
  • The transform engine may use the value of this property to help it transform the source payload.

FairCom's MQTT server does the following when a topic receives an MQTT message and "mqttPayloadType" is set to one of the following values:

  • "binary" - The server stores the MQTT payload in the source_payload field with no validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".
  • "json" - The server stores the MQTT payload in the source_payload field.
    • If "validateMqttPayload" is true, it validates the MQTT payload as JSON.
    • If successful, it assigns the "json" type to the source_payload field.
      If unsuccessful, the server assigns a "binary" type to the source_payload field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.
      If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "json" type to the source_payload field. The publisher must send MQTT messages containing valid JSON, or database queries may return errors.
  • "utf8" - The server stores the MQTT payload in the source_payload field.
    • If "validateMqttPayload" is true, it validates the MQTT payload as a UTF-8 string.
    • If successful, it assigns the "utf8" type to the source_payload field.
      If unsuccessful, the server assigns a "binary" type to the field and sets the error field to 1 to indicate there is an error. It also adds an error entry to the JSON array in the log field.
      If "validateMqttPayload" is false, it does not validate the MQTT payload and assigns the "utf8" type to the source_payload field. The publisher must send MQTT messages containing valid UTF-8, or database queries may return errors.
  • "variantObject" - The server validates the payload as a variant object.
    • If successful, the server extracts the value from the variant object’s "value" property and assigns it to the value of the source_payload field. It also assigns the variant object’s type to the type of the source_payload field.
      If unsuccessful, the server writes the MQTT payload to the source_payload field, assigns a "binary" type to the field, and sets the error field to 1, to indicate that it also adds an error entry to the JSON array in the log field.
    • The server ignores the value of "validateMqttPayload". The server always validates "variantObject".
  • "siemensUdt" - The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".
  • "jpeg" - The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".
  • "xml" - The server stores the MQTT payload in the source_payload field without validation or conversion and assigns the "binary" type to the field. It ignores the value of "validateMqttPayload".
 string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

name

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

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

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

 

 string 1 to 64 bytes

newSubscriberDeliveryMode

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

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

"newMessages"

"storedMessages"

newSubscriberMaxDeliveredMessages

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

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

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

 integer -1 to 2147483647

nullable

 Identifies whether a field can contain a NULL value. Boolean

true

false

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"

outputPayloadField

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

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

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

 string "source_payload" or a user-defined field

ownerName

The "ownerName" property is an optional string from 1 to 64 bytes that identifies the user who owns an object (see Object owner). If it is omitted or set to "" or null, the server uses the default owner name supplied during the "createSession" action or uses the account's "username" as the owner name.

"params": {
  "ownerName": "SuperUser"
}
 string 0 to 64 bytes

password

The "password" property is a required string from 0 to 256 bytes. "password" authenticates an account.

  • The "password" property is required by the "createSession" action for authentication.
  • It is possible, but not recommended, for a password policy to allow a zero-length string.

Note See System limits for requirements of this and all other system properties.

 string 0 to 256 bytes

permanentSession

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

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

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

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

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

true

false

persistence

 The "persistence" property is an object that defines the parameters of the persistence table. object

"databaseConnectionString"

"databaseName"

"databaseUserName"

"maxDeliveryRatePerSecond"

"mqttPayloadType"

"newSubscriberDeliveryMode"

"newSubscriberMaxDeliveredMessages"

"outputPayloadField"

"ownerName"

"retentionPeriod"

"retentionPolicy"

"retentionUnit"

"retrySeconds"

"tableName"

"tableReplicationReady"

"threads"

"topic"

“validateMqttPayload”

port

The "port" property is an integer that specifies the port number.

 integer an integer port number

primaryKey

 When > 0, the "primaryKey" property identifies the ordinal position of the field within the table's primary key. integer 0 to 32

primaryKeys

This optional property identifies a table's primary key.

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

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

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

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

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

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

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

 

Example

"fields": [
  {
    "name": "a",
    "type": "tinyint",
    "primaryKey": 1
  },
  {
    "name": "b",
    "type": "smallint",
    "primaryKey": 2
  },
  {
    "name": "c",
    "type": "integer",
    "primaryKey": 3
  }
]
 array of arrays an array of arrays

primaryKeyFields

This optional property specifies the fields of the table’s primary key when multiple fields are combined to form the primary key.

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

The order of fields in this property is the order of fields in the primary key index. The "fields" property contains the name and type of each field that is specified in the "primaryKeyFields" array. 

A primary key with multiple fields has an index named "pk". If you specify just one field, the index is named "<fieldname>_pk".

If only one field is used as the primary key, the "primaryKey" property defines the primary key.

Note The "primaryKeyFields" and "primaryKey" properties cannot be used together.

 

Example

"primaryKeyFields": [
  "a",
  "b",
  "c"
],
"fields": [
  {
    "name": "a",
    "type": "tinyint"
  },
  {
    "name": "b",
    "type": "smallint"
  },
  {
    "name": "c",
    "type": "integer"
  }
]
 array an array

privateKeyFilename

The "privateKeyFilename" is an optional string that specifies the name and optional path of a server key file.

    "tls": {
      "allowedCipherSuites": "",
      "certificateAuthoritiesFilename": "",
      "certificateFilename": "",
      "privateKeyFilename": ""
    },
 string No limits

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

reactions

 The "reactions" property contains the data returned by a SQL SELECT statement. array of objects

"affectedRows"

"elapsedMilliseconds"

"errorCode"

"errorMessage"

"outParams"

"rows"

"startTimestamp"

"sql"

reconnectFrequencySeconds

The "reconnectFrequencySeconds" property is the number of seconds that the broker waits between attempts to reconnect to an external broker. This property is optional. If omitted, it defaults to 15 seconds.

  • If it is set to 0, the broker does not attempt to reconnect when it loses a connection or fails to connect.
  • FairCom's servers attempt to connect to an external broker when it is configured as a subscriber to topics on an external broker or when it is configured to forward messages to an external broker.
    • To stop the reconnect process, send the "configureBrokerConnection" message with the command property set to "disconnect".
  • To restart the reconnect process, send the "configureBrokerConnection" message with the command property set to "reconnect".
 int32 the number of seconds the broker will wait between attempts to reconnect to an external broker.

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

retentionPeriod

The "retentionPeriod" property specifies how many units of data to retain. It must be an integer value from 1 to 100. It refers to the unit of time specified by the "retentionUnit" property — for example, if "retentionPeriod" is 14 and "retentionUnit" is "day", then message data is retained for 14 days. This property is optional.

  • Periodically, the system increments the age of each table partition.
    • "Minute" units are incremented at the zero second of each minute, whether the table partition was created 1 second before or 59 seconds before.
    • "Day" units are incremented at midnight GMT, not midnight of the local UTC time zone. A table partition becomes one day old at midnight GMT, whether it was created one second before or 23 hours and 59 seconds before.
    • "Week" units are incremented at midnight GMT on the last day of each week, even if the table partition was created one second before. The last day of the week is Saturday GMT.
    • "Month" units are incremented at midnight GMT on the last day of each month.
    • "Year" units are incremented at midnight GMT on Dec 31.
  • "retentionPeriod" implicitly calculates an upper bound on how many partitions are able to accumulate on your hard drive. However, partitions are not deleted just because this calculated number of partitions is reached. The system also does not restrict the deletion of all partitions.
  • If the FairCom database is shut down for a month, when the database is started up again, all partitions that are retained for less than one month are immediately deleted.
  • If someone purposely or accidentally sets the date to a future date, all partitions immediately become older, and auto-deletion ensues accordingly.

When partitions are auto-purged, some data are maintained "forever" in a global index. Auto-purge does not prevent these files from growing without bounds and filling up your hard drive.

If not specified, the default found in the services.json file is used. Initially, it is 4 (weeks).

Automatically purging data is important to ensure that retained data does not consume all storage and shut down the computer. The default value of 4 weeks allows FairCom's servers to store 1 TB of messages when 200 topics send one 2K message per second.

Note 

  • If the value is not an integer from 1 to 100, FairCom's servers set it to the default value.
  • Smaller numbers improve SQL performance.
  • Each time the "retentionPeriod" cycles, FairCom's servers automatically and efficiently delete expired data.
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
  • FairCom's servers only use the "retentionPeriod" property when the "retentionPolicy" is "autoPurge".
  • The "retentionPeriod" can be changed to retain fewer or more messages. Changing it does not necessarily destroy existing data, but data may expire more quickly or be retained longer.
  • The "retentionPeriod" and "retentionUnit" properties control data granularity as well as the retention time. In other words, "retentionPeriod" defines how many sets of data are stored, and "retentionUnit" defines how often data is purged.
    • For example, if "rententionPeriod" is set to 14 , the server stores 14 sets of data. At the beginning of the 15th cycle, the server automatically purges the oldest set of data. If "retentionUnit" is set to day, then data will be purged daily. If set to "week", then data will be purged weekly.
  • The current calendar date affects purging.
    • FairCom's servers automatically purge all retained data that has expired. This is noticeable when FairCom's servers come online after having been offline for a long time. When a server comes back online, it automatically purges all expired data.
    • For example, if a FairCom server is offline for four weeks when it comes online, it will completely purge all retained data that has a retention time of less than 4 weeks.
 integer 1 to 100

retentionPolicy

The "retentionPolicy" property controls how messages are persisted. This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "autoPurge".

retentionPolicy values:
  • "autoPurge"
    • This is the default. It is automatically applied when a new topic is created. It is preferred because it allows FairCom's servers to automatically remove messages that are older than the retention time. This helps ensure message data does not consume all storage space. It also minimizes storage costs and speeds up data access. The server partitions a table into multiple files so it can efficiently delete expired files.
  • "neverPurge"
    • This stores messages on disk and never removes them. This is useful when you need the entire history of the message stream. If message velocity is high, this can consume all storage space and cause an outage. The server creates a non-partitioned table, which is slightly faster than a partitioned table because it stores all records in one file.
 string enum

"autoPurge"

"neverPurge"

retentionUnit

Each time this unit cycles, FairCom purges expired messages. For example, if you want a week's worth of messages to be purged once a week, set "retentionUnit" to "week". This property is optional.

If not specified, the default found in the services.json file is used. Initially, it is "week". 

  • This property is used in concert with "retentionPeriod" to determine retention time.
  • "retentionUnit" values:
    • "minute"
    • "hour"
    • "day"
    • "week"
    • "month"
    • "year"
    • "forever"

Note 

  • For best performance, set the "retentionUnit" to a value that keeps "retentionPeriod" between 5 and 30. 
  • When you set "retentionUnit" property to "forever" the server will not purge messages. This setting is the same as setting "retentionPolicy" to "neverPurge".
  • The "retentionUnit" and "retentionPeriod" properties are used only when the "retentionPolicy" is set to "autoPurge".
 string enum

"minute"

"hour"

"day"

"week"

"month"

"year"

retrySeconds

The "retrySeconds" property is the number of seconds that FairCom's MQTT broker will wait for the next expected packet from a client during a QoS 1 or QoS 2 PUBLISH packet exchange/PUBLISH handshake with an MQTT client. The default value is 5. It applies when a client is publishing to the broker and when the broker is publishing to a client. This property does not apply to QoS 0 PUBLISH operations because QoS 0 PUBLISH operations are not answered. "retrySeconds" is optional.

  • If the "retrySeconds" time expires, FairCom's broker will disconnect the MQTT client with MQTT error code 7.  MQTT 5 clients will also receive a Reason Code.  An error message will be logged to <faircom>/data/CTSTATUS.FCS explaining why the disconnect happened. For example: 
    • MQTT connection for client ID [myMqttClient7] has been disconnected due to inactivity timeout. retrySeconds is set to [25] seconds for topic [my/test/topic12].: 14226
    • When the MQTT client reconnects, FairCom's MQTT broker will attempt to resume the PUBLISH handshake by resending the unanswered packet to the client, hoping that the client will reply with the next step of the handshake.
  • The minimum value is 1 and the maximum value is 65535.
  • If "retrySeconds" is omitted or its range is exceeded, FairCom's broker uses the default value.
  • Note that this parameter is not related to MQTT Keep Alive or when PINGREQ packets should be sent by the client.
 integer 1 to 65535

returnedRecordCount

The "returnedRecordCount" is a 32-bit integer set by the server in response to the "getRecordsFromCursor" method.

  • It makes it easy to know how many records were returned from the last call to "getRecordsFromCursor".
  • An application can use "returnedRecordCount" in conjunction with "requestedRecordCount" to determine if fewer records were returned than requested, which occurs when the cursor reaches the end of the recordset.
 integer

0 to 2147483647

requestMaxThreads

The "requestMaxThreads" property specifies the maximum number of threads allowed in the request.

 integer 1 to 2147483647

rows

 The "rows" property specifies the rows returned by a stored procedure of a SELECT statement and metadata about the results. object The rows returned by a stored procedure.

scale

 If the type is "number" or "money", the "scale" property identifies the number of places to the right of the decimal point,. integer 0 to 32

schemaName

The "schemaName" property is an optional string from 1 to 64 bytes that specifies the unique name of the account that owns an object. The default value is the "username" of the logged-in account.

Things to know:
  • About "schemaName":
    • If the "schemaName" property is omitted, set to "", or null, the server uses the default schema name supplied at login (if any) or uses the user’s username as the schema name.
    • For legacy support, "schemaName" can be "", which means a table has no schema.
  • About how schemas work:
    • If there is no table with the specified schema name, but there is a table that does not belong to any schema, it belongs to all schemas and that table will match. A table can belong to one schema or all schemas, but not more than one schema.
    • The fully qualified name of an object includes "databaseName", "schemaName", and the object's name, such as "tableName".
    • Queries and scripts are often written without specifying "databaseName" and/or "schemaName". This allows queries and scripts to work properly when run in different databases or in different schemas.
    • The default database name is supplied by the "defaultDatabaseName" property, and the default schema name is supplied by the "defaultSchemaName" property.
 string 1 to 64 bytes

sequence

The "sequence" property optionally assigns an order to the labels in a group. You can use a floating point or integer number. You may embed the number in a JSON string. It defines the order of labels in a group. It is a floating point number to make it easy to change label order without renumbering all labels in a group. For example, to move a label in between two other labels, you can assign a fractional number to the label that is in between the sequence numbers of two other labels.

 float Any floating point or integer number.

serviceLibrary

The "serviceLibrary" property is a string that specifies the filename of a dynamic library that provides the API used by the web application.

Library files are located in the <faircom>/server/web/ folder.

The full path includes the "serviceLibrary" value — for example, the Monitor app has a "serviceLibrary" name of ctmonitor.dll, and its full path in the file system is <faircom>/server/web/ctmonitor.dll.

 string The file name for the service library.

serviceName

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

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

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

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

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

 string A service name between 1 and 64 bytes.

serverVersion

The "serverVersion" property indicates which version of the FairCom server the request was made to.

  "result": {
    "sessionStartTimestamp": "2025-08-28T15:44:56",
    "sessionLastAccessedTimestamp": "2025-08-28T18:07:07",
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4,
    "serverVersion": "FairCom EDGE Server - V4.2.4.109(Build-250819)"
  },
 string The name of the version of the FairCom server to which the request was made.

sessionLastAccessedTimestamp

The "sessionLastAccessedTimestamp" property indicates the date/time when the session was last accessed.

"result": {
  "sessionStartTimestamp": "2025-08-27T20:26:25",
  "sessionLastAccessedTimestamp": "2025-08-27T20:56:25"
  },
 timestamp An ISO 8601 timestamp

sessionPresent

Boolean that specifies whether the broker will use a previously stored session state, including the client's previous descriptions. 

 Boolean

true

false

sessions

The "sessions" property is an array of session objects where each session object minimally describes a session.

 array of objects

"authToken"

"defaultApi"

"defaultBinaryFormat"

"defaultDatabaseName"

"defaultDebug"

"defaultOwnerName"

"defaultResponseOptions"

"defaultRetentionPeriod"

"defaultRetentionPolicy"

"defaultRetentionUnit"

"defaultVariantFormat"

"description"

"hostIpAddresses"

"hostname"

"hostServerNamePort"

"hostSQLPort"

"hostUuid"

"idleConnectionTimeoutSeconds"

"idleCursorTimeoutSeconds"

"permanentSession"

"serverVersion"

"sessionLastAccessedTimestamp"

"sessionStartTimestamp"

"transformBufferInitialBytes"

"username"

sessionStartTimestamp

The "sessionStartTimestamp" property indicates the date/time when the session was first initialized.

"result": {
  "sessionStartTimestamp": "2025-08-27T20:26:25",
  "sessionLastAccessedTimestamp": "2025-08-27T20:56:25"
  },
 timestamp An ISO 8601 timestamp

sessionType

 specifies which type of session the requested client is currently running. string

"mqApi"

"mqtt"

"both"

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"

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

sourcePayloadFormat

 deprecated version of "mqttPayloadType". Please use "mqttPayloadType". string

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

subscribedTopics

 The "subscribedTopics" property lists the topics that the specified topic is subscribed to. array No limits

subscriberCount

 specifies the number of subscribers integer Number of subscribers

tableName

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

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

"params": {
  "tableName": "ctreeTable"
}
 string 1 to 64 bytes

tableReplicationReady

 The "tableReplicationReady" property enables the transaction log on the persistence table. Transaction logs must be enabled before a table can be replicated. Boolean

true

false

threads

The "threads" property is the number of threads assigned to a topic to write published messages to disk. This property is optional. The default value is 1.

  • The default of 1 is enough to handle typical workloads.
  • For heavy workloads, you may increase the number of threads to 2 or 3.
 integer

1

2

3

tls

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the cipher suites that are allowed, and whether the client certificate is required. This property is optional. It defaults to an empty object. 

 

"tls": { "serverCertificateFilename": "server.crt", "privateKeyFilename": "server.key", "caCertificateFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" "requireClientCertificate": "true"
}
 object

"allowedCipherSuites"

"caCertificateFilename"

"certificateFilename"

"privateKeyFilename"

topic

The "topic" property is an optional string that specifies the MQTT topic on the external broker to which messages will be forwarded.

 string A topic name between 1 and 65,500 bytes

totalRecordCount

The "totalRecordCount" property contains the total available number of records that can be returned from a query.

  • The "totalRecordCount" is set to -1, when the server does not know the total record count.
  • A very fast way to get the total number of records in a table is to call the "getRecordsByTable" method without applying a "tableFilter". This immediately returns the count without reading and counting records.
  • For most methods, the server does not calculate "totalRecordCount" because calculating it requires walking all records in the query, which may take a significant amount of time.
  • When the result is returned as a cursor, "totalRecordCount" is the total number of records that the cursor can traverse.
    • This does not apply to cursor responses.
  • When the result returns records directly, "totalRecordCount" is the total number of records that can be retrieved – not necessarily the number of records returned.
 integer

-1 to 99999999999999999999999999999999

transactionId

The "transactionId" property identifies a server-generated ID that represents a point in the progress of a transaction.

 string 0 to 255 bytes

transactionSavePointId

The "transactionSavepointId" is a string that the server generates and returns in a "createTransactionSavepoint" action. The generated ID represents a point in a transaction's progress. In requests, it defaults to an empty string.

  • A transaction savepoint represents the current point in the transaction process.
  • A client can roll back a transaction to any savepoint by calling the "rollbackTransaction" action with the desired "transactionSavepointId" property.
  • A client can commit a transaction to any savepoint by calling the "commitTransaction" action with the desired "transactionSavepointId" property.
  • A zero-length string returned in a response means the "transactionSavepointId" provided in the request is invalid.
  • Do not assume that the "transactionSavepointId" is a number in a string.
 string 0 to 255 bytes

transformBufferInitialBytes

The "transformBufferInitialBytes" property is optional and defaults to 0. It is a positive integer that specifies the number of bytes for the session to allocate initially for its transform buffer. Omit this property or set it to 0 when you do not plan on using the "transformCodeName" property to transform the JSON returned from the "getRecords..." actions. If you plan on transforming the JSON, you can set the "transformBufferInitialBytes" property to the number of bytes that you anticipate the server will need to store the results of each transform. If the server needs more memory, it automatically increases the buffer size; thus, this property is an optimization that helps prevent the server from doing expensive memory allocations.

 integer 0 or more bytes

transformServices

The "transformServices" property is an optional array of objects that describes and controls FairCom's transform services. It defaults to the services connected when the server last started up.

"transformServices" [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": true
  }
],
 array of objects

"enabled"

"serviceLibrary"

"serviceName"

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"

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.

uriPath

The "uriPath" property is optional. It is a string that indicates the path where the "serviceLibrary" file is stored. If specified, this value is appended to the default <faircom>/server/web/ folder path.

 string The file path for the service library.

username

The "username" property is a required string from 1 to 64 bytes. It is the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

 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 is an optional JSON value that is associated with a label. It can be any JSON value. It defaults to null. 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 JSON 0 to 65,500 bytes
The "verifyLinks" property is an optional Boolean property. When omitted or null, it defaults to true. When true, the action verifies that the specified labels, records, and tables exist. If your application has already validated that the labels, records, and tables exist, it can set "verifyLinks" to false, which provides a performance boost because the action does not need to look up this information. Boolean

true

false

willPayload

The "willPayload" property is required when a will message is present. It contains the payload of the last will message. You can set it to any JSON value, including binary values embedded in a JSON string or array.

 JSON  

willQoS

The property "willQoS" is reserved. The server sets it to 2.

 integer  

willRetain

The "willRetain" property is optional. It defaults to false. When true, it tells the FairCom server to send the will message to new subscribers as the first message they receive when subscribing to a topic.

 Boolean

true

false

willTopic

 The "willTopic" property is optional. It is a UTF-8 string containing the topic that the FairCom server will use to publish the will message. If you set it to an empty string, "", null, or omit it, the FairCom server will not add the will message to the connection. UTF-8 string  
 
 

 

 

behavior reaction

Was this article helpful?

Give feedback about this article

Related Articles