Timeouts in SonataFlow

The Serverless Workflow specification defines several timeouts configurations that you can use to configure maximum times for the workflow execution in different scenarios. For example, you can configure how long a workflow can wait for an event to arrive when it is in a given state, etc. Currently, SonataFlow supports only the workflow execution timeout and event timeouts.

Regardless of its application scope (workflow or state), the timeouts must be configured as an amount of time (a duration), which is considered to start when the referred scope becomes active. Timeouts use the ISO 8601 data and time standard to specify a duration of time and follow the format PnDTnHnMn.nS with days considered to be exactly 24 hours. For instance, PT15M configures 15 minutes, and P2DT3H4M defines 2 days, 3 hours and 4 minutes.

Workflow timeout

To configure the maximum amount of time a workflow can be running before being canceled, you can use the workflow timeout. This is configured in the header section of the workflow, by using the WorkflowExecTimeout definition. Only the duration property is currently implemented. Once canceled, the workflow is considered to be finished, and will not be accessible through a GET request anymore. So it behaves as if the interrupt was true by default.

For example, to cancel the workflow after an hour of execution, you must use the following configuration.

Example of workflow timeout
{
  "id": "workflow_timeouts",
  "version": "1.0",
  "name": "Workflow Timeouts",
  "description": "Simple workflow to show the workflowExecTimeout working",
  "start": "PrintStartMessage",
  "timeouts": {
    "workflowExecTimeout": "PT1H"
  } ...
}

Event timeout

When you define a state in a workflow, you can use the timeouts property to configure the maximum time to complete this state. When that time is overdue, the state is considered timed-out, and the engine continues the execution from this state. The execution flow depends on the state type, for instance, a transition to a next state might be executed. All the properties that you can use to configure state timeouts are described in the Serverless Workflow specification.

Event-based states can use the sub-property eventTimeout to configure the maximum time to wait for an event to arrive. This is the only property that is supported in current implementation.

Callback state timeout

The Callback state can be used when you need to execute an action, in general to call an external service, and wait for an asynchronous response in form of an event, the callback.

Once the response event is consumed, the workflow continues the execution, in general moving to the next state defined in the transition property. See more on Callback state in SonataFlow.

Since the Callback state halts the execution until the event is consumed, you can configure an eventTimeout for it, and in case the event does not arrive in the configured time duration, the workflow continues the execution moving to the next state defined in the transition, see the example.

Example of Callback state with timeout
{
 "name": "CallbackState",
 "type": "callback",
 "action": {
   "name": "callbackAction",
   "functionRef": {
     "refName": "callbackFunction",
     "arguments": {
       "input": "${\"callback-state-timeouts: \" + $WORKFLOW.instanceId + \" has executed the callbackFunction.\"}"
     }
   }
 },
 "eventRef": "callbackEvent",
 "transition": "CheckEventArrival",
 "onErrors": [
   {
     "errorRef": "callbackError",
     "transition": "FinalizeWithError"
   }
 ],
 "timeouts": {
   "eventTimeout": "PT30S"
 }
}

Switch state timeout

The Switch state can be used when you need to take an action depending on certain conditions, these conditions can be based on the workflow data, dataConditions, or on events, eventConditions.

When you use the eventConditions, the workflow execution waits to make a decision until any of the configured events arrives and matches a condition. In this situation, you can configure an event timeout, that controls the maximum time to wait for an event to match the conditions.

If this time expires, the workflow moves to the state defined in the defaultCondition property of the Switch state, as you can see in the example.

See more details about this state on the Serverless Workflow specification - Switch State.

Example of Switch state with timeout
{
    "name": "ChooseOnEvent",
    "type": "switch",
    "eventConditions": [
    {
        "eventRef": "visaApprovedEvent",
        "transition": "ApprovedVisa"
    },
    {
        "eventRef": "visaDeniedEvent",
        "transition": "DeniedVisa"
    }
    ],
        "defaultCondition": {
        "transition": "HandleNoVisaDecision"
    },
        "timeouts": {
        "eventTimeout": "PT5S"
    }
}

Event state timeout

The Event state is used to wait for one or more events to be received by the workflow, execute a set of actions, and then continue the execution. If the Event state is a starting state, a new workflow instance is created.

The Event state is not supported as a starting state if the exclusive flag is set to false, therefore timeout is not supported in this case.

The timeouts property is used for this state to configure the maximum time the workflow should wait for the configured events to arrive.

If this time is exceeded and the events are not received, the workflow moves to the state defined in the transition property or ends the workflow instance (in case of an end state), without performing any actions.

You can see this in the example.

For more information about Event state timeout, see Serverless Workflow specification - Event State.

Example of Event state with timeout
{
  "name": "WaitForEvent",
  "type": "event",
  "onEvents": [
    {
      "eventRefs": [
        "event1"
      ],
      "eventDataFilter": {
        "data": "${ \"The event1 was received.\" }",
        "toStateData": "${ .exitMessage }"
      },
      "actions": [
        {
          "name": "printAfterEvent1",
          "functionRef": {
            "refName": "systemOut",
            "arguments": {
              "message": "${\"event-state-timeouts: \" + $WORKFLOW.instanceId + \" executing actions for event1.\"}"
            }
          }
        }
      ]
    },
    {
      "eventRefs": [
        "event2"
      ],
      "eventDataFilter": {
        "data": "${ \"The event2 was received.\" }",
        "toStateData": "${ .exitMessage }"
      },
      "actions": [
        {
          "name": "printAfterEvent2",
          "functionRef": {
            "refName": "systemOut",
            "arguments": {
              "message": "${\"event-state-timeouts: \" + $WORKFLOW.instanceId + \" executing actions for event2.\"}"
            }
          }
        }
      ]
    }
  ],
  "timeouts": {
    "eventTimeout": "PT30S"
  },
  "transition": "PrintExitMessage"
}

Deploying a timed-based workflow

To deploy a workflow that uses timeouts, or any other timer-based action, it is necessary to have a job service running in your environment, which is an independent service responsible to control the workflows timers, see the job service for more information. The provisioning of this service depends on the work mode that you are using.

SonataFlow Operator Dev Profile

When you work with the SonataFlow Operator Dev Profile, the operator will automatically provide an execution environment that contains an embedded job service instance, as well as an instance of the data index service. And thus, there is no need for additional configurations.

In the timeouts showcase you can see the details of how to work with timeouts and the SonataFlow Operator Dev Profile.

Quarkus Workflow Project

When you work with a standalone Quarkus Workflow Project, you must:

  1. Configure the project to include the required addon for the workflows to connect with that service.

  2. Ensure that a jobs service instance is available in your environment.

In the job service guide you can see all the available add-ons and configuration alternatives for this case.

Timeouts showcase

To see the examples about how configure the timeouts, and execute them in different deployment scenarios, you can use the Timeouts showcase in SonataFlow

Additional resources

Found an issue?

If you find an issue or any misleading information, please feel free to report it here. We really appreciate it!