"alterMqSession" (MQ API)

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

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