Skip to main content

"describeDataChangeStreams" (JSON Action)

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.

{
  "api": "admin",
  "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": {
      "logLevel": "development",
      "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"
}

"params"

Table 1. describeDataChangeStreams "params" property summaries

Property

Description

Default

Type

Limits (inclusive)

ids

specifies one or more unique data change stream identifiers.

Required - No default value

array of integers

The array may have any number of items.

Each integer in the array may be from 1 to 18446744073709551616.

includeMetrics

(optional) specifies if an action should include metrics in the results.

false

Boolean

false
true


"ids"

The "ids" property is a required array of integers that selects a data change stream by specifying one or more unique data change stream identifiers.

  "params": {
    "ids": [2]
  },

"includeMetrics"

The "includeMetrics" property is an optional Boolean that specifies if an action should include metrics in the results.

"result"

Table 2. describeDataChangeStreams "result" property summaries

Property

Description

Type

Contents

dataChangeStreamFirstStartTimestamp

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

string timestamp

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

dataChangeStreamLastPausedTimestamp

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

string timestamp

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

dataChangeStreamLastStartTimestamp

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

string timestamp

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

dataChangeStreamStatus

specifies the status of the data stream.

string enum

"failed"
"initializing"
"jumpstarting"
"paused"
"pausing"
"running"
"scheduled"

description

specifies a user-defined description of the data change stream. It is not a unique identifier: the "id" property returned by this action is the unique identifier.

string

1 to 512 bytes

fixedOutput

includes all properties in a data change event when true.

Boolean

false
true

includedFields

includes specified source table fields in the data change event or includes all fields when empty.

array of strings

0 or more strings

includeExistingRecordsFilter

includes streams that synchronize existing records if true.

Boolean

false
true

includeMetadata

adds user-defined properties to each data change event.

array of metadata objects

[
  {
    "propertyPath": "myPath",
    "propertyValue": "myValue"
  }
]

includePrimaryKey

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

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

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

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

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

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

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

string

"fields"
"buffer"

revealAfterValueOnFilteredDelete

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

false
true

revealBeforeValueOnFilteredInsert

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

false
true

sourceDatabaseName

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

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

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

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

contains the current values of the streaming connection object that connects FairCom MQ to the source FairCom DB or RTG server.

object

"streamingConnection": {
  "logLevel": "development",
  "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
.metadata

specifies metadata about the streaming connection.

object

0 or more key/value pairs

streamingConnection
.sourceHostname

specifies a unique host name or TCP/IP address of a FairCom DB or RTG server.

string

1 to 255 bytes

streamingConnection
.sourcePassword

specifies the login password of a FairCom DB or RTG server.

string

1 to 128 bytes

streamingConnection
.sourcePort

specifies the ISAM ICP/IP port of a FairCom DB or RTG server.

int16

1 to 65535

streamingConnection
.sourceServerName

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

string

1 to 255 bytes

streamingConnection
.sourceUsername

specifies the login name of a FairCom DB or RTG server.

string

1 to 64 bytes

streamingConnection
.tls

specifies Transport Layer Security settings for connecting to a FairCom DB or RTG server.

object

"allowedCipherSuite"
"caCertificateFilename"
"clientCertificateEnabled"
"clientCertificateFilename"
"clientPrivateKeyFilename"
"enabled"
streamingConnection
.tls
.allowedCipherSuites

limits the ciphers that FairCom MQ is willing to use when communicating with a FairCom DB or RTG server.

string

No limits

streamingConnection
.tls
.caCertificateFilename

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

string

No limits

streamingConnection
.tls
.clientCertificateEnabled

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

Boolean

false
true
streamingConnection
.tls
.clientCertificateFilename

specifies the file name, such as admin_client.crt, of a client certificate accepted by the target FairCom DB or RTG server.

string

No limits

streamingConnection
.tls
.clientPrivateKeyFilename

specifies the file name, such as admin_client.key, of a client certificate private key file accepted by the target FairCom DB or RTG server.

string

No limits

streamingConnection
.tls
.enabled

enables or disables tls.

Boolean

false
true

streamingConnectionName

specifies a unique, user-defined name for a streaming connection. This 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 bytes

tagChanges

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

specifies the MQTT topic name that FairCom MQ uses when publishing this stream's data change events. Use the "configureTopic" action to change this topic.

string

1 to 65,500 bytes

triggers

specifies a list of events on a table that create data change events.

array of enum strings

One or more of:

"delete"
"insert"
"update"


"dataChangeStreamFirstStartTimestamp"

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

"dataChangeStreamLastPausedTimestamp"

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

"dataChangeStreamLastStartTimestamp"

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

"dataChangeStreamStatus"

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

"failed"
"initializing"
"jumpstarting"
"paused"
"pausing"
"running"
"scheduled"

"description"

The "description" property specifies a user-defined description of the data change stream. It is not a unique identifier: the "id" property returned by this action is the unique identifier.

"fixedOutput"

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

"includedFields"

The "includedFields" property is an array of strings that includes specified source table fields in the data change event or all fields when empty.

"includeExistingRecordsFilter"

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

"includeMetadata"

The "includeMetadata" property is an array of metadata objects that adds user-defined properties to each data change event.

"includePrimaryKey"

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

"localDatabaseName"

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

"localDataFilePath"

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

"localOwnerName"

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

"localTableName"

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

"recordFilter"

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

"recordFormat"

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

"revealAfterValueOnFilteredDelete"

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

"revealBeforeValueOnFilteredInsert"

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

"sourceDatabaseName"

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

"sourceDataFilePath"

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

"sourceOwnerName"

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

"sourceTableName"

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

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

"metadata"

The "metadata" property is an optional JSON object. It exists primarily for the user interface to find integration information. By default, it is an empty JSON object.

  • It contains a flexible set of properties.

  • It typically contains tags and description properties.

Example

{
  "description": "",
  "tags": [""],
  "yourOwnProperties": "usage, purpose, notes, location, etc.",
}

"sourceHostname"

The "sourceHostname" property is a required string that specifies a unique host name or TCP/IP address of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourcePassword"

The "sourcePassword" property is an optional string that specifies the login password of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourcePort"

The "sourcePort" property is an optional integer that specifies the ISAM TCP/IP port of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourceServerName"

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

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

"sourceUsername"

The "sourceUsername" property is an optional string that specifies the name of a FairCom DB or RTG server.

    "sourceServers": [
      {
        "purpose": "Primary Server",
        "sourceServerName": "FAIRCOMS",
        "sourceHostname": "10.70.13.112",
        "sourcePort": 5597,
        "sourceUsername": "ADMIN",
        "sourcePassword": "ADMIN",
        
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
      }
    ]

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

Example

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

"allowedCipherSuites"

"caCertificateFilename"

"requireClientCertificate"

"allowedCipherSuites"

"caCertificateFilename"

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

"clientCertificateEnabled"

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

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

"clientCertificateFilename"

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

"clientPrivateKeyFilename"

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

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

"streamingConnectionName"

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

  "params": {
    "streamingConnectionName": "db1",
    "metadata": {},
    "maxSecondsBeforeConnectingToNextServer": 15,
    "streamParallelism": 4,
    "sourceServers": []
  },

"tagChanges"

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

"topic"

The "topic" property is a string that specifies the MQTT topic name that FairCom MQ uses when publishing this stream's data change events. Use the "configureTopic" action to change this topic.

"triggers"

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

JavaScript Object Notation (JSON) is a simple format for representing data. It requires very little markup and is flexible enough to represent the majority of data structures. It is self-describing, which makes it ideal for schemaless applications and search. It can optionally be paired with a schema to define an expected structure.