Events in SonataFlow

This document describes event state in a workflow. You can use the event state to start a new workflow instance upon the reception of a designated CloudEvent or to pause the execution of an existing workflow instance until a designated CloudEvent is received.

Example of event match

An event state consists of one or more event definitions. Event definitions are combined to designate the CloudEvent types that the event state listens to.

In an event definition, the onEvents property is used to group the CloudEvent types that might trigger the same set of actions. The exclusive property in an event definition indicates how an event match is calculated. In case the value of exclusive property is false, then all CloudEvent types in the eventRefs array must be received for a match to occur. Otherwise, the reception of the referenced CloudEvent types is considered a match.

The following is an example of event definitions, consisting of two CloudEvent types including noisy and silent:

Example event definitions

"events": [
    {
      "name": "noisyEvent",
      "source": "",
      "type": "noisy",
      "dataOnly" : "false"
    },
    {
      "name": "silentEvent",
      "source": "",
      "type": "silent"
    }
  ]

To indicate that an event match occurs when both noisy and silent CloudEvent types are received and to execute different actions for both CloudEvent types, define an event state containing both event definitions in separate onEvent items and set exclusive property to false.

Example event state defintion with multiple onEvent items

  {
    "name": "waitForEvent",
    "type": "event",
    "onEvents": [
      {
        "eventRefs": [
          "noisyEvent"
         ],
         "actions": [
           {
             "functionRef": "letsGetLoud"
           }
         ]
      },
      {
        "eventRefs": [
           "silentEvent"
        ],
        "actions": [
          {
            "functionRef": "beQuiet"
          }
        ]
      }
    ]
    ,
    "exclusive": false
  }

To execute the same action when both event types are received, use only one onEvent item as shown in the following example:

Example event state definition with single onEvent item

  {
    "name": "waitForEvent",
    "type": "event",
    "onEvents": [
      {
        "eventRefs": [
          "noisyEvent",
          "silentEvent"
         ],
         "actions": [
           {
             "functionRef": "notCareAboutNoise"
           }
         ]
       }
    ]
    ,
    "exclusive": false
  }

If you want the same action to be executed when any of the event types is received, set the exclusive property to true as shown in the following example:

Example event state definition executing same action

  {
    "name": "waitForEvent",
    "type": "event",
    "onEvents": [
      {
        "eventRefs": [
          "noisyEvent",
          "silentEvent"
         ],
         "actions": [
           {
             "functionRef": "notCareAboutNoise"
           }
         ]
       }
    ]
    ,"exclusive": true
  }

You can also remove the exclusive property, as true is the default value.

To start a new workflow instance, set the start property to the event state name in the workflow header. The workflow instance starts when there is an event match. Using the previous example of event state definition, add the following code in the workflow header:

Start a workflow instance

"start":"waitForEvent"

An event state can also be used to pause an existing workflow instance. When the workflow execution reaches an event state, which is not starting, then the execution is paused until there is an event match for that workflow instance.

Similar to the callback state in a workflow, the workflow instance to be resumed is identified by kogitoprocrefid CloudEvent attribute or calculated according to the event correlation functionality. While callback state is used for fire&wait scenarios, event state covers wait&fire scenarios. For more information about the callback state, see Callback state 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!