"startDataChangeStream" (JSON Action)

{
  "api": "admin",
  "action": "startDataChangeStream",
  "params": {
    "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",
      "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": "",
    
    "includeExistingRecords": 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"
}

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.

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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": []
  },

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.

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.

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

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

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

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

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

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.

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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

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

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

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

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

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

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

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

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

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": []
  },

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.

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.

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