Skip to main content
Previous sectionNext section

Configuring and Using the MQTT Passthrough Business Service and Operation

This chapter describes the behavior of the built-in MQTT passthrough business service and the passthrough business operation.

Adding and Configuring the Passthrough Business Service

To add your business service to a production, use the Management Portal to do the following in an interoperability-enabled namespace

  1. If you are using a username/password authentication with the MQTT broker, you need to first define credentials with that information (Interoperability > Configure > Credentials in the Management Portal). If you are using SSL authentication, see “Using SSL/TLS with InterSystems IRIS” in the Security Administration Guide.

  2. Add an instance the EnsLib.MQTT.Service.Passthrough business service class to the production.

  3. Configure the business service so that it can receive input.

    • Set the TargetConfigNames property in Basic Settings. This property is common to many business services and specifies where the business services sends its messages. The target can be one or more business processes and business operations.

    • Optionally, set the CleanSession property. If CleanSession is checked, the broker will not preserve any information about the subscription from one connection to the next. If you want to receive any messages that were published while your connection was temporarily down, do not check CleanSession.

    • Set the ClientID property. This identifies your client to the broker. It must be ASCII-encoded and between 1 and 23 characters. If you disconnect and then reconnect to the broker, it will preserve your identity if the ClientID is the same and return any messages that were sent while you were disconnected (unless you check CleanSession). If you leave the ClientID field empty, the client assigns a unique ClientID. If you have multiple productions running the same business service, ensure that each has a different ClientID or the broker will treat them as a single client and only return a message to one of them.

    • Set the ConnectTimeout property. This sets the number of seconds that the business service will wait for an acknowledgement from the broker.

    • If you are using login credentials, set the CredentialsName property to the credentials name you defined in Step 1.

    • Set the KeepAlive property for the maximum number of seconds that should be between messages from the client to the broker.

    • Optionally, set the LWTTopic and LWTMessage properties. These set the Last Will and Testament message for the connection. If the broker detects that the connection has unexpectedly been lost, it will publish a message with the specified topic and message.

    • Set the QOS property, which sets the Quality of Service in the connection with the broker. A value of 0 tells the business service to not wait for an acknowledgement from the broker and a value of 1 says that the business service will wait for an acknowledgement that the broker has received the message.

    • Do not check the Retained property. It is only used for publishing messages not for subscribing to messages. Setting this property when publishing messages tells the broker to retain this message and return it to any new subscribers.

    • If you are using SSL security, set SSLConfigName to the name of the SSL configuration.

    • If you have set QOS to 1, set the Timeout property to the number of seconds that you want the business service to wait for an acknowledgment.

    • Set the Topic property to the topic that you want to subscribe to. The topic is typically a hierarchal string with levels of subtopics separated by a / (forward slash). On subscriptions, the topic can contain wildcards:

      • + (plus sign) — Matches any string at that level. For example “/temperatures/+/highest” would match the topics “temperatures/Paris/highest” and “temperatures/Bangkok/highest” but would not match “temperatures/Paris/highest/today”. The plus sign cannot be combined with other characters within the same level.

      • # (number sign) — Can only be the last level and matches any string at that level and any subtopics. For example “temperatures/Paris/#” would match all of the following topics: “temperatures/Paris/highest”, “temperatures/Paris/highest/today”, and “temperatures/Paris/lowest/record/thiscentury”.

    • If you want to trace the MQTT actions taken by the business service, check the Trace property and set the TraceLevel property. The MQTT trace messages are written to the production log for the business service. TraceLevel can have the following values:

      • 0 — MQTTCLIENTTRACEMAXIMUM, maximum level tracing.

      • 1 — MQTTCLIENTTRACEMEDIUM, medium level tracing.

      • 2 — MQTTCLIENTTRACEMINIMUM, minimum level tracing.

      • 3 — MQTTCLIENTTRACEPROTOCOL, trace protocol level.

      • 4 — MQTTCLIENTTRACEERROR, trace only errors.

      • 5 — MQTTCLIENTTRACESEVERE, trace only severe errors.

      • 6 — MQTTCLIENTTRACEFATAL, trace only fatal errors.

    • Set the Url property with the URL and port number of the broker. The scheme is either “tcp” or “ssl” followed by the domain name and port delimited by a “:”, for example, “tcp://MQTTBroker.example.com:1883”. Typically SSL enabled end points are configured with a port of 8883, but this is not mandatory.

  4. Enable the business service in the Basic Settings.

  5. Run the production.

Note:

When using SSL you must use an absolute path and not a relative path to the certificate file. See “Creating or Editing an SSL/TLS Configuration” in the Security Administration Guide for details on using SSL.

Adding and Configuring the Passthrough Business Operation

To add your business operation to a production, use the Management Portal to do the following in an interoperability-enabled namespace

  1. If you are using a username/password authentication with the MQTT broker, you need to first define Credentials with that information (Interoperability > Configure > Credentials in the Management Portal). If you are using SSL authentication, see “Using SSL/TLS with InterSystems IRIS” in the Security Administration Guide.

  2. Add an instance the EnsLib.MQTT.Operation.Passthrough business operation class to the production.

  3. Configure the business operation so that it can publish messages.

    • Optionally, set the CleanSession property. If the Clean Session property is checked, the broker will not preserve any information about the session from one connection to the next.

    • Set the ClientID property. This identifies your client to the broker. It must be ASCII-encoded and between 1 and 23 characters. If you disconnect and then reconnect to the broker, it will preserve your identity if the ClientID is the same. If you leave the ClientID field empty, the client assigns a unique client ID.

    • Set the ConnectTimeout property. This sets the number of seconds that the business service will wait for an acknowledgement from the broker.

    • If you are using login credentials, set the CredentialsName property to the credentials name you defined in Step 1.

    • Set the KeepAlive property for the maximum number of seconds that should be between messages from the client to the broker.

    • Optionally, set the LWTTopic and LWTMessage properties. These set the Last Will and Testament message for the connection. If the broker detects that the connection has unexpectedly been lost, it will publish a message with the specified topic and message.

    • Set the QOS property, which sets the Quality of Service in the connection with the broker. A value of 0 tells the business operation to not wait for an acknowledgement from the broker and a value of 1 says that the business operation will wait for an acknowledgement that the broker has received the message.

    • Check the Retained property if you are publishing the message to retain. Each subscription has only one retained message. It is the message that is sent to a first-time subscriber. Other messages are only sent to the subscribers if they are published after the subscription has started.

    • If you are using SSL security, set SSLConfigName to the name of the SSL configuration.

    • If you have set QOSto 1, set the Timeout property to the number of seconds that you want the business service to wait for an acknowledgment.

    • Set the Topic property, which specifies the default topic for publishing messages. The topic is typically a hierarchal string with levels of subtopics separated by a / (forward slash). The operation will use the topic specified in its input parameter. If the input parameter does not have a topic, it uses the default topic. When publishing messages, the topic should not contain any wildcards.

    • If you want to trace the MQTT actions taken by the business service and business operation select the Trace property and set the TraceLevel property. The MQTT trace messages are written to the production log. TraceLevel can have the following values:

      • 0 — MQTTCLIENTTRACEMAXIMUM, maximum level tracing.

      • 1 — MQTTCLIENTTRACEMEDIUM, medium level tracing.

      • 2 — MQTTCLIENTTRACEMINIMUM, minimum level tracing.

      • 3 — MQTTCLIENTTRACEPROTOCOL, trace protocol level.

      • 4 — MQTTCLIENTTRACEERROR, trace only errors.

      • 5 — MQTTCLIENTTRACESEVERE, trace only severe errors.

      • 6 — MQTTCLIENTTRACEFATAL, trace only fatal errors.

    • Set the Url property with the URL and port number of the broker. The scheme is either “tcp” or “ssl” followed by the domain name and port delimited by a “:”, for example, “tcp://MQTTBroker.example.com:1883”. Typically SSL enabled end points are configured with a port of 8883, but this is not mandatory.

  4. Enable the business operation in Basic Settings.

  5. Run the production.

Note:

When using SSL, you must use an absolute path and not a relative path to the certificate file. See “Creating or Editing an SSL/TLS Configuration” in the Security Administration Guide for details on using SSL.

MQTT Message Format

The passthrough business service sends an EnsLib.MQTT.Message message and the passthrough business operation receives an EnsLib.MQTT.Message message. The EnsLib.MQTT.Message class is an extension of the Ens.StringContainer class with an additional property, Topic. The MQTT topic is stored in the Topic property and the MQTT message is stored in the string container value.