Skip to content

Toro Cloud Dev Center

Waiting for external events

A Event Based Workflow has the capability to pause its execution when it needs to. This is useful when your workflow might need to wait for a response before continuing to another state. To do this, you can mark a state as waiting. A waiting state is required to have at least one transition. When a waiting state is executed, the service is immediately paused. It can be resumed by sending an event to the Event Based Workflow. We call this type of event an external event.

An external event contains the following properties:

  • event - tells the waiting state what transition to invoke.
  • inputs - values to set to the waiting state's inputs.
  • tags - allows selective sending of events to resume multiple Event Based Workflows.

$fluxEvent becomes a state input when setting a state to waiting. This is because a waiting state is transitioned based on the value of event which is then mapped to $fluxEvent. When the external event is accepted, the waiting state's action is executed.

Unlike regular states, inputs of a waiting state are injected from an external event. These are validated as well. If any validation error occurs, the Event Based Workflow will ignore the event and will continue waiting. This is a fail-fast feature and prevents a Event Based Workflow from accidentally resuming its execution due to invalid inputs.

To demonstrate waiting states, create a Event Based Workflow containing a three states, one of which transitions to two other states similar to the following:

Before waiting state

Notice that the starting state has a validation error. This is because $fluxEvent is not set. Let's see what happens when we set this state to waiting. To mark a state as waiting, right click the state and click Toggle Waiting. You will know that a state is waiting when it has a hand icon on it.

Setting waiting state

Setting waiting state

Notice that the validation error for waiting state is now gone. If you examine the state on the Mapper view, $fluxEvent is now an input property instead of an output. A waiting state requires an external event to resume its execution. Execution will pause until it receives an external event. $fluxEvent's value will be based on the external event sent.

Sending an external event

Sending an external event to a Event Based Workflow can be done via the Event Based Workflow REST API or the IDE. Below, we'll demonstrate how to do this. But first, you must run the service.

To a single Event Based Workflow

In order to resume a specific Event Based Workflow, you need to know its ID. It can be retrieved from the response after running the Event Based Workflow. Fortunately, Martini provides a dialog that sends external events which is useful for development purposes.

To access this dialog, right click on any blank space in the Event Based Workflow canvas. From the appearing context menu, click Send Event Based Workflow Event. You can also access this option by right clicking an instance in the Navigator view.

Sending external event

Right click on a transition to send an event

A quick way to send external event is to right click a transition and click Send Event Based Workflow Event. This will populate the properties of the external event as well as the inputs from the waiting state.

Sending external event

To multiple Event Based Workflows

You can also send an external event to multiple Event Based Workflows with the use of tags. Any service will accept the event if it satisfies all these conditions:

  1. It is currently waiting.
  2. It is tagged with at least one of the specified tags.
  3. Its current state has a transition of the event.
  4. No validation error occurred when inputs of the external event are injected.

If any of these conditions are not met, the event will be ignored.