"createMqApiSession"(JSON Action)

The "cleanSession" property is a synonym for "temporarySession" (see temporarySession). It exists for name compatibility with MQTT. Use "temporarysession" because its name is more intuitive.

This property is an optional Boolean property. It defaults to false when omitted or set to null. When true, the MQ engine resets the current session, and when the client disconnects, the engine removes the session's settings, subscriptions, and message position. Because you normally want the engine to remember your message position between sessions, you rarely set "cleanSession" to true.

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.

The "keepAliveSeconds" property is an optional integer that specifies how often (in seconds) the broker expects a message to be sent. The server will retain a temporary session as long as the client performs an MQ Message action within the keep alive timeout period, which is "keepAliveSeconds" x 1.5. Once there is no activity, the server starts the session expiry timer to remove the temporary session. If there is no session activity within the number of seconds specified in the "sessionExpiryInternal" property, the server removes the session.

The optional "label" property assigns a label to an object. The "label" object contains "group" and "name" properties that uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a valid group and name for a label.

A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as "listTopics" and "listMqSessions" to find objects with a specific label.

The "label" property is mutually exclusive from the "labelId" property.

Example

"label": {
 "group": "group name",
 "name": "label name"
}

The optional "group" property is a child of the "label" property. It defaults to "", which is a valid group name.

A label's "group" and "name" properties work together to uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a unique and valid natural identifier for a label.

The "labelId" property is another way to uniquely identify a label.

Example

"label": {
  "group": "group name",
  "name": "label name"
}

The optional "name" property is a child of the "label" property. It defaults to "", which is a valid label name.

A label's "group" and "name" properties work together to uniquely identify a label. If you omit the "group" and "name" properties, they default to the empty string, "", which is a unique and valid natural identifier for a label.

The "labelId" property is another way to uniquely identify a label.

Example

"label": {
  "group": "group name",
  "name": "label name"
}

The optional "labelId" property assigns a label to an object. The "labelId" property uniquely identifies a label.

A label is a tag that you can add to some objects, such as an MQTT topic or session. You can use list actions such as "listTopics" and "listMqSessions" to find objects with a specific label.

The "labelId" property is mutually exclusive with the "label" property.

Example

"labelId": 423

The "maxHealthyBacklogRatePerMinute" property sets the maximum number of backlog messages per minute for a healthy session. A backlog message is one the server has not yet published to subscribers. The backlog of a topic grows when the incoming message rate exceeds the outgoing. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.

A connected session is healthy when its message backlog rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthyBacklogRatePerMinute" property and the "sessionHealth" property to report the health of a session.

The "maxHealthySendRatePerMinute" property sets the maximum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no upper bound.

A connected session is healthy when its message send rate does not exceed the maximum. The "describeMqSessions" action returns the "maxHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.

The "maxHealthySubscribedTopicFiltersCount" property sets the maximum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no upper bound.

A connected session is healthy when it has subscribed to at most the maximum number of topic filters. The "describeMqSessions" action returns the "maxHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.

A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "maxHealthySubscribedTopicFiltersCount" property does not limit the number of topics.

The "maximumPacketSize" property is an optional integer that specifies the maximum size of a single packet that the session can receive.

The "minHealthySendRatePerMinute" property sets the minimum number of messages per minute for a healthy session. You can set it to any positive integer or whole number, such as 10 or 0.1. The default value is 0, which sets no lower bound.

A connected session is healthy when its message send rate exceeds the minimum. The "describeMqSessions" action returns the "minHealthySendRatePerMinute" property and the "sessionHealth" property to report the health of a session.

The "minHealthySubscribedTopicFiltersCount" property sets the minimum number of topic filters for a healthy session. You can set it to any positive integer, such as 10. The default value is 0, which sets no lower bound.

A connected session is healthy when it has subscribed to at least the minimum number of topic filters. The "describeMqSessions" action returns the "minHealthySubscribedTopicFiltersCount" property and the "sessionHealth" property to report the health of a session.

A topic filter may include MQTT wildcard characters, which allows one topic filter to subscribe to many topics. The "minHealthySubscribedTopicFiltersCount" property does not limit the number of topics the wildcards match - rather, it establishes a lower bound on the number of subscribed topic filters an MQ Session is allowed to have.

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 "requestProblemInformation" property is an optional Boolean that specifies whether or not to include problem Information in the response.

The "requestResponseInformation" property is an optional Boolean that specifies whether or not to include response information in the response.

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 "sessionHealth" property is included in the response to the "describeMqSessions" action. It is an enumerated string with the following values: "healthy", "unhealthy", and "offline":

The server excludes a metric from the calculation when it is set to the default value of 0.

The session health properties include: 

The "sessionStatus" property specifies the status of an MQTT or MQ API session as "normal", "hidden", "banned", or "inactive" to hide its visibility in API results and the dashboard views, ban a client from connecting, or mark a client as inactive. A banned session prevents clients from using the session to publish and subscribe to messages. When "sessionStatus" is omitted, it defaults to "normal".

The "temporarySession" property is an optional Boolean property that defaults to false when omitted or set to null. It is used in the "createMqApiSession" and "alterMqSession" actions to make a session temporary or permanent. When set to true, the session is temporary; otherwise, it is permanent.

When true, the MQ engine resets the current session, and when the client disconnects, the engine removes the session's settings, subscriptions, and message position. Because you normally want the engine to remember your message position between sessions, you rarely set "temporarySession" to true.

Use the "temporarySession" property to control session permanency rather than the "cleanSession" property because its name is more intuitive. The server returns an error if you include both and set them to opposite values.

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

The "userProperties" property is optional in the "publishMessagesToMq" action and defaults to null. When present, it is an array of key-value objects. A key-value object contains a "key" property and a "value" property with string values. You can assign multiple key-value pairs to an MQTT 5 message; the server includes them in the messages it delivers to subscribers. The server may process specific key-value pairs as instructions that modify its behavior.

"userProperties": [
  {
    "key": "some key",
    "value": "some value"
  }
]

The "willContentType" property is an optional string that specifies the content type of the last will message.

The "willCorrelationData" property is an optional JSON value that can be used to set will request-response messages.

The "willDelaySeconds" property is an optional integer that specifies the number of seconds the server will wait before sending the last will message.

The "willExpirySeconds" property is an optional integer that specifies the number of seconds before the last will message expires.

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 "willPayloadFormatIndicator" property is an optional enumerated value that specifies the payload format for the last will message.

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

The "willResponseTopic" property is an optional string that specifies the topic for the last will message response.

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.

The "willUserProperties" property is an optional array that assigns key-value pairs to the last will messages.

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 "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 "sessionType" property specifies which type of session the requested client is currently running. This property can return "mqApi", "mqtt", or "both".

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

  "result": {
    "sessionPresent": false
  },

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