Intrexx Industrial - MQTT in Intrexx

1. Import certificate

Connections to the Test MQTT Broker are only available when encrypted. In the first step, please import the self-signed certificate from the server into the portal properties. In the "Certificate store" dialog, select the option "Download from internet address". Enter the server "message-broker.unitedplanet.com" and the port 8883 there for MQTT.

2. Read messages

The topic "guest/sampleMachine/machineState", which logs the status of a machine, is on the Test MQTT Broker. Here, we will demonstrate how you can read messages from this topic and write them to an Intrexx application.

2.1. Create application

Create a new application based on the template "Basic application".



Switch to the edit page. Delete all of the existing elements except the buttons. Then create the following new edit fields with the "Text" control type:


Switch to the "All Entries" and add the new fields as table columns. The "Creation date" data field can be added for sorting. The existing column "Title" can be removed. Save and publish the application.

2.2. Create process

Create a new process.



Remove all process elements, which may already be in the process. Then create a Generic event source. In the configuration select the class
"de.uplanet.lucy.server.mqtt.workflow.eventsource.MQTTWorkflowEventSource".
Add the following properties: When a generic MQTT event source is configured and the process is published, a connection to the Message Broker is established immediately.



Select the generic event source and open the "Details" dialog by pressing F4. There, copy the GUID of the event source to the clipboard.



Then create a Generic event handler. In the configuration select the class
"de.uplanet.lucy.server.mqtt.workflow.eventhandler.MQTTWorkflowEventHandler".
Add the property "MQTTSourceGuid". Add the copied GUID of the event source as the value. This connects the generic event handler to the generic event source, meaning it will listen out for events provided by this source.



Now create a Groovy action and connect it to the generic event handler. Insert the following script there:
import de.uplanet.util.ISODateTimeUtil
import groovy.json.JsonSlurper

def bytes = g_event.message.payload
def strMsg = new String(bytes, "UTF-8")

def l_jsonSlurper = new JsonSlurper()
def l_parsedJSON = l_jsonSlurper.parseText(strMsg)

g_sharedState.deviceOperationalStatus = l_parsedJSON.device.operationalStatus
g_sharedState.messagesTitle = l_parsedJSON.messages[0].title
In this script, the values of the machine status (deviceOperationalStatus) and the message titles (messagesTitle) are requested and assigned to the sharedState.



Create a Data group action and connect it to the Groovy action. Select the action "Add record".



Select the data group in the application created in this example as the Target data group.



On the Field assignment tab, add the user-defined system values "deviceOperationalStatus" and "messagesTitle", whose values are transmitted to the sharedState in the preceding Groovy action, and select the "Processing context" type. Assign the system values to the corresponding target fields from the application. Save the process.

2.3. The application in the browser




If you open the application in the browser, you will now see the protocol of the machine status, if and when changes have been made on the Test MQTT Broker. Every time a change is made on the Broker, a new data record with the current data will be created in the application by the process.

3. Write and administrate messages

3.1. Create application

Create a new application based on the template "Basic application".



Switch to the edit page. Create a new edit field with the title "Read" and the "Text" control type.



Switch to the "All Entries" and add the new field as a table column. The "Creation date" data field can be added for sorting. Save and publish the application.

3.2. Create process

3.2.1. First process chain: Write messages

Create a new process with a data group event handler.



In the properties of the event handler, select the application created in the previous step.



In the next step, select the data group and the record event "Change".



Create a Groovy action and connect it to the data group event handler. Insert the following Groovy script there:
def myVal = g_record["78A3E6FCB1CB525C159079D97DADA7BAE21F0CC4"].value /* datafield Title <string> */
g_sharedState.msgOut = '{"name":"' + myVal + '"}'
Replace the GUID "78A3E6FCB1CB525C159079D97DADA7BAE21F0CC4" with the GUID of the "Title" data field from your application. You can ascertain this GUID in the editor in the Application structure area and insert it directly. In this script, a reference to the Title data field from the application created earlier is made. In the second line, the current value of the data field is written to the sharedState.



Create a Generic action and connect it to the Groovy action. In the properties, select the class
"de.uplanet.lucy.server.mqtt.workflow.action.MQTTMessageProducerWorkflowAction"
and define the following properties: With this part of the process, the value of the "Title" data field is written to the topic "guest/[your topic name]" when you change one of the application's data records in the browser.

3.2.2. Excursus: Context variables

Dynamic values from the current processing context can be used as well as static values for the property "data.contextVariableName" of the generic action. The following prefixes are supported: Click here for more information.

3.2.3. Second process chain: Read messages

To check whether writing messages on the Test MQTT Broker works correctly, a reading process chain can be created in addition. Follow the same steps as described in 3.2.2. Create process but with the following differences:
  1. The process chain is created in the current process. You don't need to create an additional process.
  2. In the generic event source, use the userName "extuser" instead of "guest". Add another property "password" with the value "haithabu".
  3. Use the topic name, which you defined in the generic action in the first process chain (guest/[any topic name]), for the property "topic".
  4. Insert following script in the Groovy action:
    import de.uplanet.util.ISODateTimeUtil
    import groovy.json.JsonSlurper
    
    def bytes = g_event.message.payload
    def strMsg = new String(bytes, "UTF-8")
    
    def l_jsonSlurper = new JsonSlurper()
    def l_parsedJSON = l_jsonSlurper.parseText(strMsg)
    
    g_sharedState.msg = l_parsedJSON.name
    
  5. On the "Field assignment" tab of the data group action, add the user-defined system value "msg" with "Processing context" as the type and assign this to the data field "Read" from the application created earlier.
  6. Save the process.
The entire process should now look something like this:

3.3. The application in the browser




On the edit page, enter a random title. This title can then be modified on the "All Entries" page by clicking on the magnifying glass symbol in the first column of the table. This change triggers the process that writes the change to the broker. The second process chain responds and writes the changed value in a new data record that you can then immediately see in the table on the "All Entries" page.

4. Classes

4.1. MQTTWorkflowEventSource

The class "MQTTWorkflowEventSource" makes messages from one or more MQTT topics available. Click here for more information about the class and the properties described below.

Property: serverUri

Mandatory. The connection URI for the MQTT server needs to be entered as the value (e.g. ssl://message-broker.unitedplanet.com:8883).

Property: topic

Mandatory. The MQTT topic that should be consumed needs to be entered as the value (e.g. guest/sampleMachine/machineState). Click here for more information.

Property: userName

Enter the username for logging in to the server as the value here.

Property: password

Enter the password for the user logging in to the server as the value here.

Property: clientId

Client identifier that identifies the MQTT client against the server. This property usually doesn't need to be defined as Intrexx automatically generates a unique client ID.

Property: randomizeClientId

If the value is true (default), a globally unique suffix will be added to the configured client ID.

Property: globalSharedState

globalSharedState (default: false) is a standard property for event sources or timers. This property defines whether a joint global sharedState should be used.

Property: impersonateUserGuid

impersonateUserGuid is a standard property for event sources or timers. Here, enter the GUID of the user, who should be used to perform this event source, as the value. If a user GUID is not provided, the processes are performed with the system account and administrative permissions.

Property: runWithLocalSystemPrivileges

runWithLocalSystemPrivileges (default: true) is a standard property for event sources or timers. It defines whether the process shoul be performed with administrative permissions.

Property: logVerbose

More detailed logging (default: false).

Property: reconnect

This property (default: true) controls whether the client (meaning this event source) should try to reconnect to the server if the connection is broken.

Property: sendBeforeStartEvent

Defines whether an event should be generated before the event source is initiated (default: false).

Property: sendAfterStopEvent

Defines whether an event should be generated after the event source is finished (default: false).

Property: startDelay

Is a standard property for many event sources or timers. Determines the latency in milliseconds before the event source is initiated (default: 0).

Property: onErrorRestartWaitTimeout

# Latency in milliseconds before restarting work after an error (default: 60 seconds = 60000 ms).

Property: stopWaitTimeout

Latency in milliseconds before closing the connection.

4.2. QOS

With this class, the MQTT Quality of Service is managed. Possible values: Click here for more information.

5. More information

  1. Intrexx Industrial
  2. MQTT in Intrexx
  3. Service bus
  4. Polling
  5. Increased perfomance by only refreshing specific elements on a page
  6. Complete Java Sample Code for a seamless integration in the Processes module (event source, event handler and action)
  7. Configuration of an MQTT Message Broker
  8. http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html