describeDataChangeStreams

View information about specified data change streams

The "describeDataChangeStreams" action describes data change streams that you specify by ID. You typically list data streams and then describe the streams for which you want more information.

 

Request examples

Minimal

This example describes the data change stream with the unique identifier of 2.

{
  "action": "describeDataChangeStreams",
  "params": {
    "ids": [2],
    "includeMetrics": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Maximal

This example returns all information about each affected data change stream.

{
  "api": "admin",
  "action": "deleteDataChangeStream",
  "result": {
    "description": "existing & new CA records from db1 ctreesql_admin_custmast",
    
    "dataChangeStreamStatus": "starting",
    "dataChangeStreamFirstStartTimestamp": "2025-06-07T12:23:19.275",
    "dataChangeStreamLastStartTimestamp": "2025-06-07T12:23:19.275",
    "dataChangeStreamLastPausedTimestamp": null,
    
    "streamingConnectionName": "db1",
    "streamingConnection": {
      "sourceServerName": "FAIRCOMS",
      "sourceHostname": "10.70.13.112",
      "sourcePort": 5597,
      "sourceUsername": "ADMIN",
      "sourcePassword": "ADMIN",
      "maxSecondsBeforeConnectingToNextServer": 15,
      "tls": {
        "enabled": true,
        "caCertificateFilename": "ca.crt",
        "allowedCipherSuites": "",
        "clientCertificateEnabled": true,
        "clientCertificateFilename": "admin_client.crt",
        "clientPrivateKeyFilename": "admin_client.key"
      },
      "metadata": {
      }
    },
    
    "topic": "custmast",
    
    "localTableName": "custmast",
    "localOwnerName": "admin",
    "localDatabaseName": "faircom",
    "localDataFilePath": "",
    
    "sourceTableName": "custmast",
    "sourceOwnerName": "admin",
    "sourceDatabaseName": "ctreeSQL",
    "sourceDataFilePath": "",
    
    "includeExistingRecordsFilter": true,
    "recordFilter": "!stricmp(cm_custstat,\"CA\")",
    "includedFields": [
      "cm_custnumb",
      "cm_custzipc",
      "cm_custcity"
    ],
    "triggers": [
      "insert",
      "update",
      "delete"
    ],
    
    "recordFormat": "fields",
    
    "tagChanges": "forEachField",
    "includePrimaryKey": "forPrimaryKeyFields",
    "includeMetadata": [
    ],
    "revealAfterValueOnFilteredDelete": false,
    "revealBeforeValueOnFilteredInsert": false,
    "fixedOutput": false
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

ids

The "ids" property specifies 0 or more ids. Each identifier in the array uniquely specifies a table row, indicating which records the action affects. It is required if the "primaryKeys" property is "null" or not specified.

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

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

Optional with default of "null".

Required when "primaryKeys" is omitted

array 0 or more ids

includeMetrics

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

 

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

Optional with default of false Boolean

true

false

 

Response properties ("result")

Property Description Type Limits (inclusive)

 dataChangeStreamFirstStartTimestamp

The "dataChangeStreamFirstStartTimestamp" property specifies the UTC date and time in ISO-8601 format when the stream first started.

 

string timestamp "2025-06-07T12:23:19.275"

dataChangeStreamLastPausedTimestamp

The "dataChangeStreamLastPausedTimestamp" property specifies the UTC date and time in ISO-8601 format when the stream last paused.

 

string timestamp "2025-06-07T12:23:19.275"

dataChangeStreamLastStartTimestamp

The "dataChangeStreamLastStartTimestamp" property specifies the UTC date and time in ISO-8601 format when the stream last restarted.

 

string timestamp "2025-06-07T12:23:19.275"

dataChangeStreamStatus

The "dataChangeStreamStatus" property specifies the status of the data change stream. It may specify any of the following states: string enum

"failed"

"initializing"

"jumpstarting"

"paused"

"pausing"

"running"

"scheduled"

description

The "description" property provides additional information about an object, such as a label or thing. You can use it as internal or external documentation of a label's meaning, purpose, and usage.

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

 

In the Thing API, It defaults to "unknown" and is a string from 1 to 512 bytes. You cannot use it for lookups and filtering.

 

string 1 to 65,500 bytes

fixedOutput

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

true

false

includedFields

The "includedFields" property specifies the source table fields in the data change event or all fields when empty.

array of strings 0 or more strings

includeExistingRecordsFilter

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

Boolean

true

false

includeMetadata

The "includeMetadata" property adds user-defined properties to each data change event.

array of metadata objects
[
  {
    "propertyPath": "myPath",
    "propertyValue": "myValue"
  }
]

includePrimaryKey

The "includePrimaryKey" property specifies when to add the "pk" property to the data change event's "fields" object to indicate the field's position in the primary key.

string

"forEachField"

"forPrimaryKeyFields"

"never"

localDatabaseName

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

string 1 to 64 bytes

localDataFilePath

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

string No limits

localOwnerName

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

string 1 to 64 bytes

localTableName

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

string 1 to 64 bytes

recordFilter

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

string 1 to 65,000 bytes

recordFormat

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

string

"fields"

"buffer"

revealAfterValueOnFilteredDelete

The "revealAfterValueOnFilteredDelete" property includes the "afterValue" property in the notification message when true. When "recordFilter" filters out a record based on field values, an update causes a deleted change event to occur when its field values no longer match the filter. The "afterValue" property, when present, reveals the new field values and leaks information.

Boolean

true

false

revealBeforeValueOnFilteredInsert

The "revealBeforeValueOnFilteredInsert" property includes the "beforeValue" property in the notification message when true. When "recordFilter" filters out a record based on field values, an update causes an insert change event when previous field values did not match the filter but now match it. The "beforeValue" property, when present, reveals the old field values and leaks information.

Boolean

true

false

sourceDatabaseName

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

string 1 to 64 bytes

sourceDataFilePath

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

string No limits

sourceOwnerName

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

string 1 to 64 bytes

sourceTableName

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

string 1 to 64 bytes

streamingConnection

The "streamingConnection" property is an object that contains the current values of the streaming connection object that connects FairCom MQ to the source FairCom DB or RTG server.

object
"streamingConnection": {
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "maxSecondsBeforeConnectingToNextServer": 15,
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  },
  "metadata": {}
}

streamingConnection

.maxSecondsBeforeConnectingToNextServer

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

streamingConnection

.metadata

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

JSON 0 to 65,500 bytes

streamingConnection

.sourceHostname

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

streamingConnection

.sourcePassword

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

streamingConnection

.sourcePort

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

streamingConnection

.sourceServerName

The "sourceServerName" property specifies the server name of a FairCom DB or RTG server. It is the name specified by the SERVER_NAME keyword defined in the target server's configuration file, ctsrvr.cfg. The server name used by most FairCom DB and RTG servers is "FAIRCOMS". This property is required if the "sourceHostname" is not defined. string 1 to 255 bytes

streamingConnection

.sourceUsername

The "sourceUsername" property specifies the name of a FairCom DB or RTG server. string 1 to 64 bytes

streamingConnection

.tls

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the allowed cipher suites, and whether the client certificate is required. 

 

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

"allowedCipherSuites"

"caCertificateFilename"

"certificateFilename"

"privateKeyFilename"

streamingConnection

tls

.allowedCipherSuites

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

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

streamingConnection

tls

.caCertificateFilename

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

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

streamingConnection

tls

.clientCertificateEnabled

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

true

false

streamingConnection

tls

.clientCertificateFilename

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

string No limits

streamingConnection

tls

.clientPrivateKeyFilename

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

string No limits

streamingConnection

tls

.enabled

The "enabled" property determines whether or not the specified feature is enabled. The example below enables the TLS feature.

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

true

false

streamingConnectionName

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

tagChanges

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

string

"forEachField"

"forPrimaryKeyFields"

"never"

topic

The "topic" property specifies the MQTT topic on the external broker to which messages will be forwarded.

string A topic name between 1 and 65,500 bytes

triggers

The "triggers" property specifies a list of events on a table that create data change events. array of enum strings

"delete"

"insert"

"update"