BMPN 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.

Message events subscribe or publish to the Rhize broker.
A message event

Timer events start according to some interval or date, or wait for some duration.

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 `Cycle`, to begin at recurring intervals. For example,`R5/2024-05-09T08:12:55/PT10S` starts on `2024-05-09` and executes every 10 seconds for 5 repetitions. If `<START_DATE>` is not set, Rhize uses `2023-01-01T00:00:00Z`. `Date`, to happen at a certain time, for example, `2024-05-09T08:12:55` Enter values in ISO 8601 format.
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.

Note Besides tasks, you can also use call activities, processes which call and invoke other processes.

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.

An empty service task — *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

Call activities have a task with an icon to expand

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.

Gateway with two branches — *Drawn as diamonds, gateways represent branches in a sequence flow.*

Exclusive gateway

exclusive gateways are marked by an “x” icon

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 that has a condition and a default — *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

Parallel gateways are marked by a “+” icon

Marked by a “+” icon, parallel gateways indicate a point where parallel tasks are run.

A parallel gateway that branches and rejoins — *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.

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.