Tutorial: Trigger a workflow from a rule
An equipment class rule triggers a BPMN workflow whenever a data source publishes a value that meets a specified threshold.
Imagine a scenario when an oven must be preheated every time a new order number is published to an MQTT edge device.
You could automate this workflow with a rule that listens to messages published and evaluates a condition.
If the condition evaluates to true
, the rule triggers a BPMN workflow to preheat the oven.
--- title: Rules trigger workflows from data-source changes --- flowchart LR A(Property changed?) -->|yes| B{"rule evaluates to true?"} B -->|no| C(do nothing) B -->|"yes (optional: pass variables)"| D(Run BPMN workflow)
The broad procedure to create a rule is as follows:
- In the Rhize UI or through GraphQL, create models for the data source and its associated unit of measure, equipment, and equipment class.
- In the Rhize UI, write a BPMN workflow that is triggered when this data source changes and executes some business logic.
- In the equipment class, create a rule that triggers the workflow.
The following sections describe how to do these steps in more detail.
Prerequisites
Before you start, ensure you have the following:
- Access your Rhize customer environment
- The Agent configured to listen for your data-source ID
Set up: configure equipment and workflows
The setup involves modeling the objects associated with the rule.
- Data source
- Data source topic
- Unit of measure
- BPMN
- Equipment class with bound properties
Once you have these, you can create a rule and associate it with an actual equipment item.
Create a data source
- From the main menu, navigate to Master Data > Data Sources.
- Create a new data source. The label (ID) must match the one specified in the configuration file for the
libre-agent
microservice. - From the General tab, add a draft data source version.
- Select
MQTT
as the data-source protocol. - Optionally, enter a connection string, such as
mqtt://<REMOTE_HOST>:1883
, that matches the one specified in the configuration file for thelibre-agent
microservice. - Save the data source version to create it.

Create a data source topic
- Navigate to the Topics tab.
- Add a new property (that is, a topic).
- Select
STRING
for the property data type (this assumes an order number is a string such asOrder1
). - Select your preferred deduplication key. The default option,
Message Value
, is most appropriate for this scenario. - For label, enter the exact topic name as it appears in the data source. Use a slash to access nested topics. For this example, all new order numbers are published to
Oven/OrderNumber
. - Confirm by clicking the green tick icon.
- Navigate to the General tab and change the version state to active.

Create a unit of measure
- From the Main Menu, navigate to Master Data > Units of Measure.
- Add a new unit of measure.
- Enter
Order Number
for the unit name. - Select
STRING
for the data type.

Creating a BPMN workflow
A rule must trigger a BPMN workflow. Before setting up a rule, create its workflow. For this example, this 3-node BPMN is enough:
- Navigate to Workflows > Process List.
- Import the BPMN.
- Save it.
- Set the version as active.

The BPMN has a Libre Jsonata Transform
task that contains an expression "Preheating oven for order number " & $.orderNumber"
.
The rule engine triggers this BPMN with a payload that includes the order number value, as follows:
{
"orderNumber": "Order1"
}
Create an equipment class with bound properties
Equipment class and version
- Navigate to Master Data > Equipment Class.
- Create a new equipment class from the sidebar. The label might be
Pizza Line
, for example. - From the General tab, Create a new Draft version.

Equipment class property
- From the properties tab, create a new property.
- For type, select
BOUND
. - For name, enter
orderNumber
. - For UoM, select the unit of measure created earlier (
Order Number
). - Confirm by clicking the green tick icon.

Create a rule
Add a rule to an existing equipment class
- From the Rules tab of an equipment class version, create a new rule.
- Enter
Run BPMN on Order Number
for the name and confirm. - Select
rules_example_bpmn
for the workflow specification. - Add
orderNumber
as a trigger property. - Add a trigger expression that evaluates to true or false.
true
.
It’s common to compare the new value with the previous.In this case, we can compare the new order number to the previous by adding OrderNumber.current.value != OrderNumber.previous.value
.
Note that the root of the object path must match the ID of the equipment class property we set up earlier and all evaluations are case-sensitive.
The entire information that becomes available to the rule engine looks like this:
{
orderNumber: {
current: {
bindingType: "BOUND",
description: "bound prop",
equipmentClassProperty: {
id: "EQCLASS1.10.orderNumber",
iid: "0x2a78",
label: "orderNumber"
},
equipmentVersion: {
equipment: {
id: "EQ1",
iid: "0x1b",
label: "EQ1"
},
id: "EQ1",
iid: "0x22",
version: "2"
},
id: "EQCLASS1.10.orderNumber",
label: "orderNumber",
messageKey: "ns=3;i=1003.1695170450000000000",
propertyType: "DefaultType",
serverPicoseconds: 0,
serverTimestamp: "2023-09-20T00:40:50.028Z",
sourcePicoseconds: 0,
sourceTimestamp: "2023-09-20T00:40:50Z",
value: "Order2",
valueUnitOfMeasure: {
dataType: "FLOAT",
id: "FLOAT",
iid: "0x28"
}
},
previous: {
bindingType: "BOUND",
description: "bound prop",
equipmentClassProperty: {
id: "EQCLASS1.10.orderNumber",
iid: "0x2a78",
label: "orderNumber"
},
equipmentVersion: {
equipment: {
id: "EQ1",
iid: "0x1b",
label: "EQ1"
},
id: "EQ1",
iid: "0x22",
version: "2"
},
id: "EQCLASS1.10.orderNumber",
label: "orderNumber",
messageKey: "ns=3;i=1003.1695170440000000000",
propertyType: "DefaultType",
serverPicoseconds: 0,
serverTimestamp: "2023-09-20T00:40:40.003Z",
sourcePicoseconds: 0,
sourceTimestamp: "2023-09-20T00:40:40Z",
value: "Order1",
valueUnitOfMeasure: {
dataType: "FLOAT",
id: "FLOAT",
iid: "0x28"
}
}
}
}
`OrderNumber.current.value != OrderNumber.previous.value`
True
<button class=“hextra-code-copy-btn hx-group/copybtn hx-transition-all active:hx-opacity-50 hx-bg-primary-700/5 hx-border hx-border-black/5 hx-text-gray-600 hover:hx-text-gray-900 hx-rounded-md hx-p-1.5 dark:hx-bg-primary-300/10 dark:hx-border-white/10 dark:hx-text-gray-400 dark:hover:hx-text-gray-50” title=“Copy code”
<div class="copy-icon group-[.copied]/copybtn:hx-hidden hx-pointer-events-none hx-h-4 hx-w-4"></div>
<div class="success-icon hx-hidden group-[.copied]/copybtn:hx-block hx-pointer-events-none hx-h-4 hx-w-4"></div>
The expression evaluates to false
, because the current
and previous
values differ.
Optionally, pass information to the BPMN by adding a payload message. The message is an object with multiple keys.
- Enter
orderNumber
for the field name. - Enter
orderNumber.current.value
for the JSON expression. - Confirm by clicking the green tick icon.
- Create.
- From the General tab, change the equipment class version state to active.

Associate an equipment with a bound property
The final steps to setting up a rule are to:
- Create a new equipment version.
- Link it to a data source.
- Set up bound properties.
Create an equipment and version
- From the Main Menu, navigate to Master Data > Equipment.
- Select a piece of equipment. If none, create one called
Line 1
. - From the General tab, Create.
- Link the version to the equipment class you created earlier (
Pizza Line
). - Save the version to create it.

Link a data source
- From the Data Sources tab, link the equipment version to the data source you created in the previous section.

Set up the bound property
- From the Properties tab, find a property that you want this equipment to inherit and select the binding icon.
- If you chose the property
orderNumber
, add the topicOven/OrderNumber
you added previously.

Test the binding and the rule
Send a message to test that the value of the property orderNumber
of the equipment Line 1
is bound to the topic Oven/OrderNumber
.
Test using an MQTT client
For example, using MQTT Explorer:
- Open MQTT Explorer and connect to the broker.
The microservice Libre Agent (libre-agent
) should immediately publish a message to indicate the data source topic Oven/OrderNumber
has been set up successfully.

- Publish the string
Order1
to the topicOven/OrderNumber
.

If the message has been received,
a new topic, Oven
, appears with its subtopic OrderNumber
.
If there is an equipment property bound to this topic,
a topic called MQTT/<DATA_SOURCE_NAME>/ValueChanged
also appears.
In addition, the published value should show in the column Expression
of the equipment property orderNumber
.

Core
will show up containing a subtopic called RuleTriggered
to indicate that the rule has indeed been triggered.
Confirm in execution in Tempo
To confirm the intended BPMN was executed, navigate to Grafana (Tempo) and look for a trace containing the expected BPMN ID.

Video example
- 🎥 Trigger BPMN. This video provides an example of creating a rule based on values for an OPC UA server in a baking process.