Software AG Products 10.7 | Administering Integration Server | Configuring Integration Server for MQTT Messaging | Creating an MQTT Connection Alias
 
Creating an MQTT Connection Alias
An MQTT connection alias contains the configuration information that Integration Server needs to establish a connection to an MQTT server. Integration Server uses an MQTT connection alias when publishing an MQTT message. An MQTT trigger uses an MQTT connection alias to retrieve messages from the topics to which it subscribes on the MQTT server. Each Integration Server can have multiple MQTT connection aliases.
If the MQTT connection alias establishes a connection to a secure port on an MQTT server, you need to do the following before completing configuration of the alias.
*Create a truststore that contains the trusted certificates for the Certificate Authority (CA) to use for communication with the MQTT server. Then create a truststore alias for the truststore.
A truststore is required for one-way SSL as well as two-way (mutual) SSL.
*If the port on the MQTT server is configured for two-way SSL, do the following:
*Create a keystore that contains the client certificates Integration Server provides to connect with the MQTT server.
*Create a keystore alias for the keystore, making sure to specify a key alias for the private key and associated certificate used for connecting to the MQTT server securely.
*When configuring an MQTT connection alias to a secure Universal Messaging port, you must specify a truststore and possibly a keystore alias and key alias.
*If the Universal Messaging port does not have the Enable Client Cert Validation option selected, you must specify a truststore alias.
*If the Universal Messaging port has the Enable Client Cert Validation option selected, you must specify a truststore alias, keystore alias, and key alias.
For more information about establishing secure connections with Integration Server via SSL, see Configuring Integration Server for Secure Communications. For information about creating truststore and keystore aliases, see Using Keystores and Truststores with Integration Server.
Use the following procedure to create an MQTT connection alias.
*To create an MQTT connection alias
1. Open the Integration Server Administrator if it is not already open.
2. Go to Settings > Messaging.
3. Under MQTT Configuration, click MQTT Settings.
4. Click Create MQTT Connection Alias.
5. Under General Settings, specify values for the fields in the following table:
Field
Description
Connection Alias Name
Unique name for the MQTT connection alias. Each MQTT connection alias contains the configuration information needed for Integration Server to establish a connection to the MQTT server.
Description
Description for the MQTT connection alias.
Package
Name of the package that you want to associate with the MQTT connection alias. Integration Server saves the connection alias configuration in this package. When you assign an MQTT connection alias to a package, Integration Server enables and disables the alias in conjunction with the package. If you disable the package, Integration Server disables the MQTT connection alias automatically. A package retains its MQTT connection alias when the package is published to other servers. If a subscriber installs the package, the MQTT connection alias is created automatically on the subscriber's Integration Server. If you do not have a package to assign to the MQTT connection alias, leave the Package setting at WmRoot (the server's core package). This makes the MQTT connection alias available whenever Integration Server is running
6. Under Connection Protocol Settings, specify values for the fields in the following table
Field
Description
Host
URL containing the protocol, domain, and port of the MQTT server.
If the MQTT connection alias needs to be configured to use SSL to connect to the MQTT server, the URL must begin with: ssl://
Connection Client ID
Client identifier for the connections associated with this MQTT connection alias. Integration Server generates a connection client identifier automatically, but you can supply your own
Use Clean Session for Subscriptions
Whether connections created for MQTT triggers using this MQTT connection alias establish a persistent session on the MQTT server. Do one of the following:
*Select the Use Clean Session for Subscriptions check box to remove any previous subscriptions established by an MQTT trigger that uses this MQTT connection alias. When the session ends, the MQTT server will remove any subscriptions created by the MQTT trigger.
*Clear the Use Clean Session for Subscriptions check box to persist subscriptions across sessions. Any new subscriptions created by an MQTT trigger during a session will be added to the existing subscriptions for the trigger. Additionally, the subscriptions remain after the trigger disconnects. Messages sent while the trigger is disconnected will be kept if the Quality of Service (QoS) is 1 or 2. The trigger will retrieve missed messages when it reconnects.
Connection Timeout (seconds)
Maximum number of seconds that Integration Server waits for a network connection to the MQTT server to be established. A value of 0 disables the timeout, which means that Integration Server waits for a failed or successful network connection attempt. The default is 30 seconds.
Keep Alive (seconds)
The maximum number of seconds that can elapse between messages being sent to or received from the MQTT server using a connection created for this MQTT connection alias. The keep alive functionality in MQTT ensures that the connection between the MQTT client (IS) and the MQTT server is open. A value of 0 disables keep alive. The default is 60 seconds.
7. Under Last-Will Settings, enter the information you want Integration Server to provide in the event of an ungraceful disconnection from the MQTT server.
Field
Description
Enable Last-Will
Whether the MQTT server sends a will message on behalf of Integration Server if Integration Server disconnects abruptly from the MQTT server. A will message allows other MQTT clients to handle an abrupt disconnection. Select Enable Last-Will Message if you want the MQTT server to send a specific message to a particular topic when Integration Server disconnect abruptly from the MQTT server. Do one of the following:
*Select the Enable Last-Will check box to send a will message if Integration Server disconnects ungracefully.
*Clear the Enable Last-Will check box if Integration Server will not send a will message upon ungraceful disconnection.
Last-Will QoS
The Quality of Service for the will message. Select one of the following:
*At most once (0)
*At least once (1)
*Exactly once (2)
Last-Will Retained
Whether the MQTT server retains the last will message. Do one of the following:
*Select the Last-Will Message Retained check box to instruct the MQTT server to retain the last will message.
*Clear the Last-Will Message Retained check box if the MQTT server will not retain the last will message.
Last-Will Topic
The topic to which to publish the last will message. All subscribers to this topic will receive the last will message. The topic does not need to exist at the time you create the MQTT connection alias. If it does not exist the first time Integration Server uses the MQTT connection alias to establish connection, the MQTT server creates the topic.
Last-Will Message Payload
The contents of the last will message.
On Connect Message Payload
The message to send upon successful connection to the MQTT server. This is the payload of the connect message and is sent to the same topic as the Last-Will Message Topic.
On Disconnect Message Payload
The message to send upon disconnecting from the MQTT server. This is the payload of the disconnect message and is sent to the same topic as the Last-Will Message Topic.
8. Under Security Settings, if basic authentication is required to connect to the MQTT server, provide the user name and password Integration Server uses to establish a connection.
Field
Description
User Name
User name for the Integration Server to provide for client authentication
Password
Password for the user name.
9. Under Security Settings, if SSL is required to connect to the MQTT server, select Yes for Use SSL and provide the following truststore and/or keystore information:
Field
Description
Truststore Alias
The alias for the truststore that contains the Certificate Authority (CA) certificate for the MQTT server. You must select a truststore alias when Use SSL is set to Yes.
Keystore Alias
The alias for the keystore that contains the client certificate that Integration Server sends to the MQTT server during the mutual (two-way) SSL handshake. You need to select a keystore alias only when the port on the MQTT server is configured to use mutual (two-way) SSL.
Key Alias
The alias of the Integration Server private key and associated certificate that Integration Server sends to the MQTT server during the mutual (two-way) SSL handshake. The key alias must be in the keystore specified in Keystore Alias. You must specify a Key Alias if you specify a Keystore Alias.
10. Click Save Changes.
11. Enable the MQTT connection alias.