"describeMqSessions" (JSON Action)

The "clientNames" property is an optional array containing 0 or more "clientName" strings. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.

Connection authorization is done using an account name with a password or a client certificate.

The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.

The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics. 

The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the FairCom server disconnects the other client and vice-versa.

Set the "includeOtherFields" property to true to include additional fields that are not the built-in integration table fields, transform fields, or MQTT fields. Otherwise, omit the property or set it to false or null.

Set the "includePublishedTopics" property to true for the response to include the "publishedTopics" property, which contains all topics a client's session has published since the session was created. To omit the list of published topics, omit this property or set it to false or null.

The "includeStats" property indicates whether or not the "stats" property will be returned in the response.

Set the "includeSubscribedTopics" property to true for the response to include the "subscribedTopics" property, which contains the topics a client's session is currently subscribed to. To omit the list of subscribed topics, omit this property or set it to false or null.

The "mqttProtocol" property is an optional enumerated string that specifies the version of MQTT protocol to use in your session. This property currently accepts the following values:

The "receiveMaximum" property is an optional integer that specifies the maximum number of QoS 1 and QoS 2 publish messages that the MQTT client is willing to process concurrently.

The "sessionExpiryInterval" property specifies the number of seconds that a temporary session can be inactive before the server deactivates it. This property defaults to 0 when "temporarySession" is true and to 4294967296 when "temporarySession" is false. When a temporary session expires, the server removes its subscriptions and message delivery queue. 

The "sessionExpiryInterval" property has no effect on a permanent session because it does not expire. 

The "temporarySession" property sets the value of the "sessionExpiryInterval" property.

The "topicAliasMaximum" property is an optional integer that specifies the maximum number of topic aliases that the MQTT client can support.

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:

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

Example response

{
  "result": {
    "dataFormat": "objects"
  }
}

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

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.

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

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

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

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

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

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

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

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

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

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

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

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "ewogICJrZXkiOiAidmFsdWUiCn0=",
  "valueEncoding": ["base64"],
  "type": "binary"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "123.45",
  "valueEncoding": ["string"],
  "type": "number"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": 123.45,
  "type": "number"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": true,
  "type": "boolean"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": "A JSON string with embedded \" double quote.",
  "type": "string"
}

{
  "schema": "jsonaction.org/schemas/variantObject",
  "value": [1,"2",{"key": "value"}],
  "type": "json"
}

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.

Example request

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

The "publishedTopics" property returns a list of the topics the client has published since the session was first created.

The "stats" property for describeMqSessions may contain the following information:

The "sessionType" property specifies which type of session the requested client is currently running. This property can return "mqApi", "mqtt", or "both".

The "stats" property for describeMqSessions may contain the following information:

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

The "variantFormat" property is an optional enumerated string that specifies the format in which variant fields are returned. It may have one of the following values: "variant", "base64", "hex", or "utf8":

The "variantFormat" property converts the variant value into the form an application needs.

{
  "data": [
    {
      "myField": {
        "schema": "jsonaction.org/schemas/variantObject",
        "value": "R0lGODlhAQABAIAAAAAAAP///yH5BAUAAAEALAAAAAABAAEAAAICRAEAOw==",
        "valueEncoding": [ "base64" ],
        "type": "gif",
        "storageEncoding": ["7z"]
      }
    }
  ]
}

{
  "data": [
    {
      "myField": {
        "schema": "jsonaction.org/schemas/variantObject",
        "value": { "myProperty": "myValue" },
        "valueEncoding": [ "json" ], 
        "type": "json",
        "storageEncoding": ["7z"]
      }
    }
  ]
}

{
  "data": [
    {
      "myField": {
        "schema": "jsonaction.org/schemas/variantObject",
        "value": "UTF-8 encoded string",
        "valueEncoding": [ "utf8" ],
        "type": "string",
        "storageEncoding": ["7z"]
      }
    }
  ]
}

{
  "data": [
    {
      "myField": "47494638396101000100800000000000ffffff21f90405000001002c00000000010001000002024401003b"
    }
  ]
}

{
  "data": [
    {
      "myField": "7b20226d7950726f7065727479223a20226d7956616c756522207d"
    }
  ]
}

{
  "data": [
    {
      "myField": "5554462d3820656e636f64656420737472696e67"
    }
  ]
}

{
  "data": [
    {
      "myField": "R0lGODlhAQABAIAAAAAAAP///yH5BAUAAAEALAAAAAABAAEAAAICRAEAOw=="
    }
  ]
}

{
  "data": [
    {
      "myField": "eyAibXlQcm9wZXJ0eSI6ICJteVZhbHVlIiB9"
    }
  ]
}

{
  "data": [
    {
      "myField": "VVRGLTggZW5jb2RlZCBzdHJpbmc="
    }
  ]
}

{
  "data": [
    {
      "myField": "GIF89a    €     ÿÿÿ!ù      ,           D  ;"
    }
  ]
}

{
  "data": [
    {
      "myField": "{ \"myProperty\": \"myValue\" }"
    }
  ]
}

{
  "data": [
    {
      "myField": "UTF-8 encoded string"
    }
  ]
}

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.

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

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.

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.