Trigger workflows

You also have multiple ways to start, or trigger, a BPMN workflow. The best choice of trigger depends on the context of the event and the system that initiates the workflow.

• API triggers come from a GraphQL call to the Rhize DB.
• Message triggers subscribe to a topic on the Rhize broker and run whenever an event is published to that topic.
• Rule triggers subscribe to the topics on a remote data source, such as an edge OPC-UA server or MQTT broker.
• Timer triggers start according to some schedule (once or repeating).

Start a workflow from an API

No matter the start event, all workflows can be triggered by an API call. However, if the workflow uses the default blank start event, you must trigger it through API call. For example, an API trigger may originate from a custom frontend application or a developer’s local machine.

The Rhize API has two mutations to start workflows. Both must specify the workflow ID as an argument in the request body. Each run for a workflow returns a unique ID that you can use for debugging.

Synchronous and asynchronous API triggers

To start BPMN workflows, Rhize has two API operations:

• createAndRunBPMNSync starts a workflow and waits for the process to complete or abort (synchronous).
• createAndRunBpmn starts a workflow and does not wait for the response (asynchronous).

Use the synchronous operation if you want to receive information about the result of the workflow in the call response. On the other hand, the asynchronous operation frees up the call system to do more work, no matter whether the workflow runs correctly.

Both operations have similar call syntax. For example, compare the syntax for these calls:

mutation sychronousCall{
  createAndRunBpmnSync(id: "API_demo_custom_response") {
    id
    jobState
    customResponse
  }
}

mutation asyncCall{
  createAndRunBpmn(id: "API_demo_custom_response") {
    id
    jobState
    customResponse
  }
}

The responses for these calls have two differences:

• For synchronous calls, the returned JobState should be a finished value (such as COMPLETED or ABORTED). Asynchronous calls likely return an in-progress status, such as RUNNING.
• Synchronous calls can request the dataJSON field to report the entire variable context at the final node.
• Only the synchronous call receives data in the customResponse. For details, refer to the next section.

customResponse

The customResponse is a special variable to return data in the response to clients that run createAndRunBPMNSync operations.

You can set the customResponse in any element that has an Output or Input response parameter. It can use any data from the process variable context, including variables added on the fly.

Functionally, only the last value of the customResponse is returned to the client that sent the response. However, you can use conditional branches and different end nodes to add error handling. For example, this workflow returns Workflow ran correctly if the call variables include the message CORRECT and an error message in all other cases.

Additional properties for workflow calls

API operations can also include parameters to add variables to the process variable context and to specify a workflow version.

To add variables, use the variables input argument. Note that the variables are accessible from their root object. For example, a workflow would access the following string value at $.input.message:

"variables": "{\"input\":{\"message\":\"CORRECT\"}}"
}

To specify a version, use the version property. For example, this input instructs Rhize to run version 3 of the API_demoCallToRemoteAPI workflow:

{
  "createAndRunBpmnSyncId": "API_demoCallToRemoteAPI",
  "version": "3"
}

If the version property is empty, Rhize runs the active version of the workflow (if an active version exists).

Start from a message

The message start event subscribes to a topic on the Rhize broker. Whenever a message is published to this topic, the workflow is triggered. The Rhize broker can receive messages published over MQTT, NATS, and OPC UA.

For example, this workflow subscribes to the topic material/stuff. Whenever a message is published to the topic, it evaluates whether the quantity is in the correct threshold. If the quantity is correct, it uses the mutation service task to add a material lot. If incorrect, it sends an alert back to the broker.

Note that, for a workflow to run from a message start event, the workflow must be enabled.

Rule-based triggers

Rule-based triggers subscribe to tag changes from a data source and trigger when the rule change condition is met. Typically, users choose this workflow trigger when they want to orchestrate processes originating from level-1 and level-2 systems.

To add a data source and create a rule based trigger, refer to Turn values into events.

Timer triggers

Timer triggers run according to a configured time or interval. For example, a timer trigger may start a workflow each day, or once at a certain time.

To use timer triggers, use the timer start event. As with message start events, the workflow must be enabled for it to run.