"alterMqSession"
(jsonAction)
Use the "alterMqSession"
action to 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.
Permanent sessions
A permanent session is ideal for the MQ API because you can do all message actions without worrying about your MQ session expiring.
You can be disconnected from the server for an extended time and call the
"getMessagesFromMqApiSession"
action to receive all the unexpired messages since you last called it.The server persists the state of a permanent session, including its settings, subscriptions, and subscription delivery queue.
Set the
"temporarySession"
property tofalse
(the default) to create a permanent session.When creating a permanent session, the server sets the
"cleanSession"
property tofalse
,"keepAliveSeconds"
to0
so it never times out, and"sessionExpiryInterval"
to4294967296
to retain a session when the client is disconnected.
Temporary sessions
A temporary session is ideal for doing temporary message actions, and you want the server to clean up the session state automatically after the session expires.
Set the
"temporarySession"
property totrue
to create a temporary session.When creating a temporary session, the server automatically sets the
"cleanSession"
property totrue
and sets the session expiry timer to the value of"sessionExpiryInterval"
.
The server retains 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"sessionExpiryInterval"
property, the server removes the session. You can use the"pingSession"
action to keep a temporary session alive.You should use the
"temporarySession"
property to control session permanency rather than the"cleanSession"
property because it has a more intuitive name. It is an error to include both and set them to opposite values.
This action is useful in the following ways:
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.
You can set
"temporarySession"
totrue
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.It returns information about a client connection and the session's capabilities.
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
{
"api": "mq",
"action": "alterMqSession",
"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"
}
],
"binaryFormat": "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"
}
],
"labelId": 423,
"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"
}
{
"requestId": "clientRequestId",
"result": {
"sessionPresent": false,
"clientName": "a unique MQ API client identifier",
"connectionStatus": "connected",
"sessionStatus": "normal",
"sessionExpiryInterval": 0,
"receiveMaximum": 65535,
"maximumQoS": 2,
"retainAvailable": true,
"maximumPacketSize": 268435460,
"topicAliasMaximum": 65535,
"reasonString": "",
"userProperties": [ {"key":"", "value":""} ],
"wildcardSubscriptionAvailable": true,
"subscriptionIdentifiersAvailable": true,
"sharedSubscriptionAvailable": true,
"brokerKeepAlive": 0,
"responseMessagePrefix": "uniqueTopicPrefixForResponseMessages/",
"brokerReference": "optional connection string to another broker",
"authenticationMethod": "",
"authenticationData": "encoded binary value for authentication",
"label": {
"id": 423,
"group": "mylabelGroupName",
"name": "mylabelName",
"value": 99,
"enum": 0,
"sequence": 1.2,
"deprecated": false,
"description": "My label description.",
"metadata": {}
},
"minHealthySendRatePerMinute": 10,
"maxHealthySendRatePerMinute": 1000,
"maxHealthyBacklogRatePerMinute": 10,
"minHealthySubscribedTopicFiltersCount": 10,
"maxHealthySubscribedTopicFiltersCount": 1000,
"metadata": {}
},
"errorCode": 0,
"errorMessage": "",
"debugInfo": {}
}
Use the "alterMqSession"
action to alter session settings without disrupting the client
"params"
property summariesProperty | Description | Default | Type | Limits (inclusive) | |||
---|---|---|---|---|---|---|---|
(optional) specifies how the |
| string | One of the following: | ||||
(optional) synonymous with |
| Boolean |
| ||||
(optional) specifies the unique name that identifies the client to the FairCom MQ engine |
| string | 0 to 65,550 bytes | ||||
(optional) specifies the number of seconds before the server removes the session |
| integer | |||||
(optional) specifies the maximum number of backlog messages per minute for a session to be considered healthy |
| integer | |||||
(optional) specifies the maximum number of messages per minute for a session to be considered healthy |
| integer | |||||
(optional) specifies the maximum number of topic filters for a session to be considered healthy |
| integer | |||||
(optional) specifies the maximum size of a single packet that the session can receive |
| integer | |||||
(optional) specifies the minimum number of messages per minute for a session to be considered healthy |
| integer | |||||
(optional) specifies the minimum number of topic filters for a session to be considered healthy |
| integer | |||||
(optional) specifies the version of MQTT protocol to use in your session |
| string | |||||
(optional) specifies the maximum number of packets the session can receive |
| integer | |||||
(optional) specifies whether or not to include problem information in the response |
| Boolean |
| ||||
(optional) specifies whether or not to include response information in the response |
| Boolean |
| ||||
(optional) specifies the number of seconds that a temporary session can be inactive before the server deactivates it |
| integer |
| ||||
specifies the status of the session's health | Required - No default value | enum |
| ||||
(optional) specifies the status of an MQTT or MQ API session |
| enum |
| ||||
(optional) specifies whether or not the session will be permanent or temporary |
| Boolean |
| ||||
(optional) specifies the maximum number of aliases a topic can have |
| integer | |||||
(optional) assigns key-value pairs to MQTT 5 messages |
| array | |||||
(optional) specifies the content type of the last will message |
| string |
| ||||
(optional) sets up request-response messages |
| JSON | 0 to 65,500 bytes | ||||
(optional) specifies the number of second the server will wait before sending the last will message |
| integer | |||||
(optional) specifies the number of seconds before the last will message expires |
| integer | |||||
contains the payload of the last will message | Required - No default value | JSON | |||||
(optional) specifies the payload format for the last will message |
| ENUM |
| ||||
(optional) specifies the quality of service the publisher used when publishing the will |
| integer | |||||
(optional) specifies the topic for the last will message response |
| string | |||||
(optional) tells the FairCom server to retain the will message for automatically sending to new subscribers as the first message they receive |
| Boolean |
| ||||
(optional) specifies the topic that the FairCom server will use to publish the will message |
| UTF-8 string | |||||
(optional) assigns key-vale pairs to the last will messages |
| array |
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 "clientName"
property is an optional string of up to 65,550 characters. 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 the number of seconds before the server removes a temporary MQ API session. The server retains 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 "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 "sessionHealthy"
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 "mqttProtocol"
property is an optional integer that specifies the version of MQTT protocol to use in your session.
The "receiveMaximum"
property is an optional integer that specifies the maximum number of packets the session can receive.
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. 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"
to0
to expire a temporary session when the JSON action session closes.Set
"sessionExpiryInterval"
to a value between0
and4294967296
to expire the session when it has been inactive for the specified number of seconds.Set
"sessionExpiryInterval"
to4294967296
to never expire the session.
The "temporarySession"
property sets the value of the "sessionExpiryInterval"
property.
If
"temporarySession"
istrue
, the server defaults"sessionExpiryInterval"
to0
so that a temporary session expires by default when the JSON session expires.If
"temporarySession"
isfalse
, the server sets"sessionExpiryInterval"
to4294967296
.
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"
:
"healthy"
indicates the session is healthy, which occurs when a client is:Connected
Sends the expected number of messages per minute (see
"minHealthySendRatePerMinute"
).Sends less than or equal to the maximum number of messages per minute (see
"maxHealthySendRatePerMinute"
).Does not exceed the maximum backlog of unprocessed subscribed messages (see
"maxHealthyBacklogRatePerMinute"
).Subscribes to at least the minimum expected number of topic filters ( see
"minHealthySubscribedTopicFiltersCount"
).Subscribes to no more than the maximum number of expected number of topic filters (see
"maxHealthySubscribedTopicFiltersCount"
).
"unhealthy"
indicates the session is unhealthy, which occurs when a client:Fails to send the expected number of messages per minute (see
"minHealthySendRatePerMinute"
).Sends more than the maximum number of messages per minute (see
"maxHealthySendRatePerMinute"
).Exceeds the maximum backlog of unprocessed subscribed messages (see
"maxHealthyBacklogRatePerMinute"
).Subscribes to less than the minimum number of expected number of topic filters ( see
"minHealthySubscribedTopicFiltersCount"
).Subscribes to more than the maximum number of expected number of topic filters (see
"maxHealthySubscribedTopicFiltersCount"
).
"offline"
indicates a session is not connected.
The server excludes a metric from the calculation when it is set to the default value of 0
.
The session health properties include:
"minHealthySendRatePerMinute"
"maxHealthySendRatePerMinute"
"maxHealthyBacklogRatePerMinute"
"minHealthySubscribedTopicFiltersCount"
"maxHealthySubscribedTopicFiltersCount"
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.
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 aliases a topic can have.
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.