alterMqSession

Alter session settings without disrupting the client

The "alterMqSession" property modifies an existing MQTT or MQ API session identified by the required "clientName" property. If a client with the same "clientName" is connected, it does not disconnect that session. This allows an administrator to alter session settings without disrupting a connected client.

Important You can alter the session of any client including those connected through MQTT and those connected through this MQ API. This works because the properties of MQTT and MQ API sessions are the same.

  1. You can set the session's properties, such as MQTT's Will Message and User Properties, which is a convenient way to centrally manage settings for all sessions.
  2. You can set "temporarySession" to true to make a session temporary. The server cleans the session after the client disconnects. A clean session resets the session state and clears its subscriptions.
  3. It returns information about a client connection and the session's capabilities. 
  4. You can set "sessionStatus" to "hidden", "banned", "inactive", or "normal" to hide its visibility in API results and dashboard views, ban a client from connecting, mark a client as inactive, or restore a client to normal status. If omitted, the session status does not change.

To subscribe to and unsubscribe from topics, use the "subscribeToMq" action.

Note When you set the "binaryFormat" property to "utf8" or "json", the server automatically assigns the "willPayloadFormatIndicator" property to utf8 to indicate that the payload contains UTF-8 encoded characters, such as JSON.

 

Request example

Maximal

{
  "api": "mq",
  "action": "alterMqSession",
  "cleanSession": false,
  "params":
  {

    "clientName": "a unique client identifier for MQTT or MQ API",
    "temporarySession": false,
    "sessionStatus": "normal | hidden | banned | inactive",

    "keepAliveSeconds": 60,

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

    "mqttPayloadType": "utf8",

    "sessionExpiryInterval": 60,
    "receiveMaximum": 1024,
    "maximumPacketSize": 1024,
    "topicAliasMaximum": 0,
    "requestProblemInformation": true,
    "requestResponseInformation": false,

    "willTopic": "some/Topic/Name/",
    "willQoS": 2,
    "willPayload": "This message is sent when client disconnects.",
    "willRetain": true,
    "willContentType": "IanaMediaType or a CustomType",
    "willCorrelationData": "any JSON value up to 65500 bytes",
    "willPayloadFormatIndicator": "none | utf8",
    "willExpirySeconds": 60,
    "willDelaySeconds": 60,
    "willResponseTopic": "topic/name/for/subscriber/to/respond/to",
    "willUserProperties": [
      {
        "key": "some key",
        "value": "some value"
      }
    ],

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

    "minHealthySendRatePerMinute": 10,
    "maxHealthySendRatePerMinute": 1000,
    "maxHealthyBacklogRatePerMinute": 10,
    "minHealthySubscribedTopicFiltersCount": 10,
    "maxHealthySubscribedTopicFiltersCount": 1000,

    "metadata": {}
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response example

Maximal

{
  "authToken": "BAz72agLF4M1s8acj6kyO5fNt9QhhxnbbPT33fGPZ1Eu1DEpknYcNXGBZkQ3NBM0",
  "result": {
    "clientName": "client1",
    "sessionStatus": "normal",
    "username": "ADMIN",
    "ipaddress": "127.0.0.1",
    "port": 64283,
    "mqttProtocol": "3.1.1",
    "keepAliveSeconds": 60,
    "connectionStatus": "connected",
    "connectionDateTime": "2025-09-17T16:24:41",
    "defaultBinaryFormat": "hex",
    "defaultVariantFormat": "json",
    "defaultResponseOptions": {
      "binaryFormat": "hex",
      "variantFormat": "json",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "sessionType": "mqApi",
    "willTopic": "some/Topic/Name/",
    "willQoS": 2,
    "willPayload": "This message is sent when client disconnects.",
    "willRetain": true,
    "metadata": {}
  },
  "requestId": "00000003",
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

clientName

 The "clientName" property specifies the unique name that identifies the client to the FairCom MQ engine. Optional with default of "" string 0 to 65,550 bytes

keepAliveSeconds

The "keepAliveSeconds" property 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.

 Optional with default of 0 integer No limit

label

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

 Optional with default of null object 
"label": {
  "group": "group name",
  "name": "label name"
}

label

.group

The "group" property groups labels into a lookup list or tag set. It is a namespace for a set of labels that identifies their purpose. You can use the "listLabelGroups" action to return the list groups. You can use the "listLabels" action to return labels in one or more groups. 

The "group" and "name" properties work together to uniquely identify each label. They are its natural key. 

When you assign a group name to a label, the server automatically checks if the group name exists in the list of groups that the "listLabelGroups" action returns. If the group name does not exist, the server adds the group name to the list. When you rename a group assigned to a label, the server automatically adds a new group name to the list and removes the previous group name if no other label uses it.

Tip If your application creates many groups, you can use a delimiter character, such as the forward slash / in your group names to create a group hierarchy. Include the delimiter after each part of the hierarchy and at the end of the group name. In the "listLabels" action, you can use the "partialGroupFilter" filter to return subsets of groups in the hierarchy. For example, you if have groups named "product/size/", "product/weight/", "product/ranking/", "person/gender/", and "person/ranking/", you can set the "partialGroupFilter" to "product/" to return the product groups.

 Optional with default of "" string 1 to 64 bytes of UTF-8 encoded characters

label

.name

The "name" property is the name of a label or field. 

The "group" and "name" properties combined uniquely identify each label. The "createLabel" and "alterLabel" actions return an error if the "group" and "name" properties do not create a unique label name.

The "id" property also uniquely identifies each label, so you can rename a label's group and name without breaking "id" references to the label.

 

 Required - No default value string 1 to 64 bytes

maxHealthyBacklogRatePerMinute

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.

 Optional with default of 0 integer Any positive integer

maxHealthySendRatePerMinute

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.

 Optional with default of 0 integer Any positive integer

maxHealthySubscribedTopicFiltersCount

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.

 Optional with default of 0 integer Any positive integer

maximumPacketSize

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

 Optional with default of 1024 integer  

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

minHealthySendRatePerMinute

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.

 Optional with default of 0 integer Any positive number

minHealthySubscribedTopicFiltersCount

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.

 Optional with default of 0 integer Any positive number

mqttPayloadType

The "mqttPayloadType" property specifies the variant type format of the "source_payload" field. For more details, see mqttPayloadType. 

 Optional with default of "binary" string enum

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

"variantObject"

receiveMaximum

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

 Optional with default of 1024 integer 1 to 65535

requestProblemInformation

The "requestProblemInformation" property specifies whether or not to include problem Information in the response.

 Optional with default of true Boolean

true

false

requestResponseInformation

The "requestResponseInformation" property specifies whether or not to include response information in the response.

 Optional with default of false Boolean

true

false

sessionExpiryInterval

The "sessionExpiryInterval" property specifies the number of seconds that a temporary session can be inactive before the server deactivates it. 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. 

  • Set "sessionExpiryInterval" to 0 to expire a temporary session when the JSON action session closes.
  • Set "sessionExpiryInterval" to a value between 0 and 4294967296 to expire the session when it has been inactive for the specified number of seconds.
  • Set "sessionExpiryInterval" to 4294967296 to never expire the session.

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

  • If "temporarySession" is true, the server defaults "sessionExpiryInterval" to 0 so that a temporary session expires by default when the JSON session expires.
  • If "temporarySession" is false, the server sets "sessionExpiryInterval" to 4294967296.
 If "temporarySession" is true, "sessionExpiryInterval" defaults to 0 to ensure the temporary session expires when the JSON session does. If "temporarySession" is false, it defaults to 4294967296 because a permanent session never expires. integer 0 to 4294967296

sessionStatus

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

  • "normal" resets a client to its default normal state. The client is not hidden in API results and dashboard views and may connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to unhide, unban, and activate a client.
  • "hidden" hides a client from most API results and dashboard views while allowing the client to connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to hide administrative client connections.
  • "banned" prevents a client from connecting in the future while preserving all information about the client. Use it to prevent unwanted clients from connecting again using the session's "clientName" to publish and subscribe to messages.
  • "inactive" marks a client session as inactive while allowing the client to connect, publish, and subscribe to messages. The server does not remove an "inactive" session's data so that historical message data sent and received by the client can continue to be associated with the deleted client. If a client connects to an inactive session, the server changes the session to "normal".
    • Use the "deleteMqSession" action to permanently delete the session which removes all session information. The server can no longer associate sent and received messages with the client. The client can reconnect in the future to establish a new session, but this will create a new session. It is common to permanently delete temporary client connections created during testing and troubleshooting.
 Optional with default of "normal" string enum

"normal"

"hide"

"ban"

temporarySession

The "temporarySession" property makes 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.

 Optional with default of false Boolean

true

false

topicAliasMaximum

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

 Optional with default of 0 integer 0 to 65535

userProperties

The "userProperties" property specifies an array of key-value objects used to describe a user. 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"
  }
]
 Optional with default of null array 0 or more key/value pairs

userProperties

.key

 The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value.

Optional with default of "".

 

Required in the Key-Value API 

 string 1 to 128 bytes

userProperties

.value

The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records.

 

In Key-Value actions, the required "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

willContentType

The "willContentType" property specifies the content type of the last will message.

 Optional with default of "" string

IanaMediaType

CustomType

willCorrelationData

The "willCorrelationData" property specifies a JSON value that can be used to set will request-response messages.

 Optional with default of "" JSON 0 to 65,500 bytes

willDelaySeconds

The "willDelaySeconds" property specifies the number of seconds the server will wait before sending the last will message.

 Optional with default of 60 integer  

willExpirySeconds

The "willExpirySeconds" property specifies the number of seconds before the last will message expires.

 Optional with default of 60 integer  

willPayload

The "willPayload" property 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.

 Required - No default value JSON  

willPayloadFormatIndicator

The "willPayloadFormatIndicator" property specifies the payload format for the last will message.

 Optional with default of "none" ENUM

"none"

"utf8"

willQoS

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

 Optional with default of 2 integer  

willResponseTopic

The "willResponseTopic" property specifies the topic for the last will message response.

 Optional with default of "" string  

willRetain

The "willRetain" property tells the FairCom server to send the will message to new subscribers as the first message they receive when subscribing to a topic when set to true.

 Optional with default of false Boolean

true

false

willTopic

The "willTopic" property contains 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.

 Optional with default of "" UTF-8 string  

willUserProperties

The "willUserProperties" property assigns key-value pairs to the last will messages.

 Optional with default of [] array

"key"

"value"

willUserProperties

.key

 The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value.

Optional with default of "".

 

Required in the Key-Value API 

 string 1 to 128 bytes

willUserProperties

.value

The "value" property is used by the server to compare the value assigned to "value" to the appropriate field data in records.

 

In Key-Value actions, the required "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 Required - No default value string

"string"

"integer"

"number"

"boolean"

"null"

 

Response properties ("result")

Property Description Type Limits (inclusive)

clientName

 The "Clientname" property uniquely identifies an MQ session. string  

connectionDateTime

 The "connectionDateTime" property indicates when the connection was made. timestamp An ISO 8601 timestamp

connectionStatus

 The "connectionStatus" property specifies if and how a client is connected to an MQ session. string enum "disconnected"
"connected"
"connectedTemporarily"

defaultBinaryFormat

 Defines the default value of "binaryFormat".  string One of the following: "base64", "hex", or "byteArray".

defaultResponseOptions

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.

JSON NAV allows you to choose how your program detects errors. By default, all error properties are included in each response – unless you override this behavior as shown in the example.

The example omits the error object in all responses which makes it easier for statically typed languages, such as C, C++, Java, C#, and VB, because they prefer properties to always be present. To help these languages, the "errorCode", "errorMessage", and "errorData" properties are always present whether there is an error or not.

Example

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

"binaryFormat"

"dataFormat"

"numberFormat"

defaultResponseOptions

.binaryFormat

 The "binaryFormat" property designates the format of binary values embedded in JSON strings. For more details, see "binaryFormat".  string One of the following: "base64", "hex", or "byteArray".

defaultResponseOptions

.dataFormat

The "dataFormat" property 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".

There are three different (but similar) versions of the "dataFormat" property:

Two of those versions occur in a request, and another occurs in a response. They all indicate how data is formatted.

  • "dataFormat" in the request in "responseOptions" determines how the "data" property in the response is formatted.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
  • "dataFormat" in the request in the "params" object notifies the server how the "sourceData" property is formatted in the request. This version is rarely used because of the default "autoDetect" behavior.
    • Possible values include:
      • "arrays"
        • This causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
      • "autoDetect"
        • This is the default, and the server automatically detects the format of the data in the "sourceData" property.
  • "dataFormat" in the response shows the client how the server formatted the "data" property.
    • Possible values include:
      • "arrays"
        • This is the default and causes the server to return results as an array of arrays, which is the most efficient.
      • "objects"
        • This returns results as an array of objects. This is less efficient but is simpler to generate, read, and troubleshoot.
 string

"default"

"arrays"

"objects"

defaultResponseOptions

.numberFormat

The "numberFormat" property defines the format of JSON numbers. For more details, see "numberFormat". 

 string

"number"

"string"

defaultResponseOptions

.variantFormat

 The "variantFormat" property tells the server how to interpret the variant data included in a JSON Action request. For more details, see "variantFormat". string

"json"

"binary"

"string"

"variantObject"

defaultVariantFormat

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

 string

"json"

"binary"

"string"

"variantObject"

ipaddress

 The "ipAddress" property specifies the PLC/Equipment IPV4 Address. string A valid IP address

keepAliveSeconds

The "keepAliveSeconds" property 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.

 integer No limit

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

mqttProtocol

 The "mqttProtocol" property specifies the version of MQTT protocol to use in your session. string enum

"3.1.1"

"5.0"

port

The "port" property is an integer that specifies the port number.

 integer an integer port number

sessionStatus

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

  • "normal" resets a client to its default normal state. The client is not hidden in API results and dashboard views and may connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to unhide, unban, and activate a client.
  • "hidden" hides a client from most API results and dashboard views while allowing the client to connect, publish, and subscribe to messages. The engine preserves all information about the client. Use it to hide administrative client connections.
  • "banned" prevents a client from connecting in the future while preserving all information about the client. Use it to prevent unwanted clients from connecting again using the session's "clientName" to publish and subscribe to messages.
  • "inactive" marks a client session as inactive while allowing the client to connect, publish, and subscribe to messages. The server does not remove an "inactive" session's data so that historical message data sent and received by the client can continue to be associated with the deleted client. If a client connects to an inactive session, the server changes the session to "normal".
    • Use the "deleteMqSession" action to permanently delete the session which removes all session information. The server can no longer associate sent and received messages with the client. The client can reconnect in the future to establish a new session, but this will create a new session. It is common to permanently delete temporary client connections created during testing and troubleshooting.
 string enum

"normal"

"hide"

"ban"

sessionType

 "sessionType" specifies which type of session the requested client is currently running. string

"mqApi"

"mqtt"

"both"

username

The "username" property specifies the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System specifications for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

 

 1 to 64 bytes

willPayload

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.

 JSON  

willQoS

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

 integer  

willRetain

When true, "willRetain" tells the FairCom server to send the will message to new subscribers as the first message they receive when subscribing to a topic.

 Boolean

true

false

willTopic

 The "willTopic" property contains 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. UTF-8 string  

 

Was this article helpful?

Give feedback about this article

Related Articles