BPMN elements
This document describes the parameters available to each BPMN element in the Rhize UI. These parameters control how users set conditions, transform data, access variables, call services, and so on.
Common parameters
Every BPMN workflow and every element that the workflow contains have the following parameters:
| Parameter | Description |
|---|---|
| ID | Mandatory unique ID. For guidance, follow the BPMN naming conventions. |
| Name | Optional human readable name. If empty, takes ID value. |
| Documentation | Optional freeform text for additional information |
| Extension properties | Optional metadata to add to workflow or node |
Events
Events are something that happen in the course of a process. In BPMN, events are drawn with circles. Events have a type and a dimension.
In event-driven models, events can happen in one of three dimensions:
- Start
- All processes begin with some trigger that starts an event. Start events are drawn with a single thin circle.
- Intermediate.
- Possible events between the start and end. Intermediate events might start from some trigger, or create some result. They are drawn with a double thin line.
- End
- All processes end with some result. End events are drawn with a single thick line.
Besides these dimensions, BPMN also classifies events by whether they catch a trigger or throw a result. All start events are catch events; that is, they react to some trigger. All end events are throw events; that is, they terminate with some output—even an error. Intermediate events may throw or catch.
Rhize supports various event types to categorize an event, as described in the following sections. As with Gateways and Activities, event types are marked by their icons. Throwing events are represented with icons that are filled in.
Start events
Start events are triggered by the CreateAndRunBPMN and CreateAndRunBPMNSync mutation operations.
The parameters for a start event are as follows:
| Parameter | Description |
|---|---|
| Outputs | Optional variables to add to the process variable context. JSON or JSONata. |
Message start events
Message events are triggered from a message published to the Rhize broker. The parameters for a message event are as follows:
| Parameter | Description |
|---|---|
| Message | The topic the message subscribes to on the Rhize Broker. The topic structure follows MQTT syntax. |
| Outputs | Optional variables to add to the process variable context. JSON or JSONata. |
Timer start events
Timer start events are triggered either at a specific date or recurring intervals. The parameters for a timer start event are as follows:
| Parameter | Description |
|---|---|
| Timer | One of
|
| Outputs | Optional variables to add to the process variable context. JSON or JSONata. |
Intermediate message events
Intermediate message events throw a message to the Rhize NATS broker. This may provide info for a subscribing third-party client, or initiate another BPMN workflow.
The parameters for an intermediate message event are as follows:
| Parameter | Description |
|---|---|
| Message | The topic the message publishes to on the Rhize Broker. The topic structure follows MQTT syntax |
| Inputs | Variables to send in the body. For messages to the Rhize broker, use the special variable BODY. Value can be JSON or JSONata. |
| Headers | Additional headers to send in the request |
| Outputs | JSON or JSONata. Optional variables to add to the process variable context. |
Intermediate timer events
An intermediate message pauses for some duration. The parameters for an intermediate timer event are as follows:
| Parameter | Description |
|---|---|
| Timer | A duration to pause. Enter values in ISO 8601 format. |
| Outputs | Optional variables to add to the process variable context. The assignment value can be JSON or JSONata. |
Service tasks
In BPMN, an activity is work performed within a business process.
On the Rhize platform, most activities are tasks, work that cannot be broken down into smaller levels of detail. Tasks are drawn with rectangles with rounded corners.
A service task uses some service. In Rhize workflows, service tasks include Calls to the GraphQL API (and REST APIs), data source reads and writes, and JSON manipulation. These service tasks come with templates.
As with Gateways and events, service task are marked by their icons.
Service tasks have a gear icon marker
To add a service task, select the change icon (“wrench”), then select Service Task. Use Templates to structure the service task call and response.
The service task templates are as follows
JSONata transform
Transform JSON data with a JSONata expression. For detailed examples, read The Rhize Guide to JSONata.
| Call parameters | Description |
|---|---|
| Input | Input data for the transform |
| Transform | The transform expression |
| Max Payload size | Number. If the response length exceeds this number of characters, Rhize throws an error. |
Besides the call parameters, the JSONata task has following additional fields:
| Parameter | Description |
|---|---|
| Input response | The name of the variable to add to the process variable context |
GraphQL Query
Run a GraphQL query
| Call parameters | Description |
|---|---|
| Query body | GraphQL query expression |
| Variables | JSON. Variables for the GraphQL query. |
| Connection Timeout | Number. Time in milliseconds to establish a connection. |
| Max Payload size | Number. If the response length exceeds this number of characters, Rhize throws an error. |
Besides the call parameters, the Query task has following additional fields:
| Parameter | Description |
|---|---|
| Input response | Optional JSONata expression to map to the process variable context. For GraphQL operations, use this only to map values. Rely on GQL filters to limit the payload. |
| Headers | Additional headers to send in the request |
GraphQL Mutation
Run a GraphQL mutation
| Call parameters | description |
|---|---|
| Mutation body | GraphQL Mutation expression |
| Variables | JSON. Variables for the GraphQL query. |
| Connection Timeout | Number. Time in milliseconds to establish a connection. |
| Max Payload size | Number. If the response length exceeds this number of characters, Rhize throws an error. |
Besides the call parameters, the mutation task has following additional fields:
| Parameter | Description |
|---|---|
| Input response | Optional JSONata expression to map to the process variable context. For mutations, use this only to map values. Use the mutation call to limit the payload. |
| Headers | Additional headers to send in the request |
Call REST API
HTTP call to a REST API service.
| Call parameters | Description |
|---|---|
| Method Type | One of GET, POST, PATCH, PUT, DELETE |
| Verification | Boolean. Whether verify the Certificate Authority provided in the TLS certificate. |
| URL | The target URL |
| URL Parameters | JSON. The key-value pairs to be used as query parameters in the URL |
| HTTP Headers | JSON. The key-value pairs to be used as request headers |
| Connection Timeout | Number. Time in milliseconds to establish a connection. |
| Max Payload size | Number. If the response length exceeds this number of characters, Rhize throws an error. |
Besides the call parameters, the REST task has following additional fields:
| Parameter | Description |
|---|---|
| Input response | Optional JSONata expression to map to the process variable context |
| Headers | Additional headers to send in the request |
JSON schema
Validate that a payload conforms to a configured JSON schema.
For example, you can validate that data.arr contains an array of numbers
and that userID contains a string of certain length.
| Call Parameters | Description |
|---|---|
| Schema | A JSON schema. You can also create one from a JSON file with a tool such as JSON to JSON schema |
| Variable | Optional. Key of specific variable to validate (default checks all variables in |
The Schema task has the following output that you can define as a variable:
| Response mapping | Description |
|---|---|
| Valid | The boolean output of the schema evaluation. True if schema is valid. |
| Validation error | A string that reports the validation errors if the schema is invalid. |
Read Datasource
Read values from topics of a datasource (for example, an OPC-UA server)
| Call parameters | Description |
|---|---|
| Data source | The ID of the datasource |
| Data | JSON or JSONata expression. Topics and values to write to |
| Max Payload size | Number. If the response length exceeds this number of characters, Rhize throws an error. |
Besides the call parameters, the data source task has following additional fields:
| Parameter | Description |
|---|---|
| Input response | The variable name to store the response in process variable context |
| Headers | Additional headers to send in the request |
Write Datasource
Write values to topics of a datasource.
| Call parameters | Description |
|---|---|
| Data source | The ID of the datasource |
| Data | JSON or JSONata expression. Topics and values to write to |
| Max Payload size | Number. If the response length exceeds this number of characters, Rhize throws an error. |
Besides the call parameters, the data source task has following additional fields:
| Parameter | Description |
|---|---|
| Input response | The variable name to store the response in process variable context |
| Headers | Additional headers to send in the request |
Call activities
A call activity invokes another workflow. In this flow, the process that contains the call is the parent, and the process that is called is the child.
Call activities have the following parameters:
| Parameters | Description |
|---|---|
| Called element | The ID of the called process |
The inputs have the following parameters:
| Parameters | Description |
|---|---|
| Local variable name | The name of the variable as it will be accessed in the child process (that is, the key name) |
| assignment value | The value to pass from the parent variable context |
The outputs have the following parameters:
| Parameters | Description |
|---|---|
| Local variable name | What to name the incoming data, as it will be accessed in the parent process (that is, the key name) |
| assignment value | The value to pass from the child variable context |
For a guide to reusing functions, read the Reuse workflows section in the “Create workflow” guide.
Gateways
Gateways control how sequence flows interact as they converge and diverge within a process. They represent mechanisms that either allow or disallow a passage.
BPMN notation represents gateways as diamonds with single thin lines, as is common in many diagrams with decision flows. Besides decisions, however, Rhize’s BPMN notation also includes parallel gateways.
As with Events and Activities, gateway types are marked by their icons.
Drawn as diamonds, gateways represent branches in a sequence flow.
Exclusive gateway
Marked by an “X” icon, an exclusive gateway represents a point in a process where only one path is followed. In some conversations, an exclusive gateway is also called an XOR.
If a gateway has multiple sequence flows, all flows except one must have a conditional JSONata expression that the engine can evaluate. To designate a default, leave one flow without an expression.
An exclusive gateway with a condition and default. Configure conditions as JSONata expressions
Exclusive gateways can only branch. That is, they cannot join multiple flows.
Parallel gateway
Marked by a “+” icon, parallel gateways indicate a point where parallel tasks are run.
Parallel gateways run jobs in parallel.
Parallel joins
You can join parallel tasks with another parallel gateway. This joins the variables from both branches to process variable context. Note that parallel joins have performance costs, so be mindful of using them, especially in large tasks. To learn more, read Tune BPMN performance.
Parallel joins join variable context, but have performance costs.
Variables and expressions
As data passes and transforms from one element to another, variables remain in the process variable context. You can access these variables through JSONata expressions.