. If type is `expression`, defines the workflow expression. | string | no |
+| type | Defines the function type. Is either `rest`, `rpc` or `expression`. Default is `rest` | enum | no |
+| [metadata](#Workflow-Metadata) | Metadata information. Can be used to define custom function information | object | no |
Click to view example definition
@@ -1294,149 +1581,67 @@ the state should transition to the next state or can end the workflow execution
JSON |
YAML |
-
-|
-
-```json
-{
- "eventRefs": ["HighBodyTemperature"],
- "actions": [{
- "functionRef": {
- "refName": "sendTylenolOrder",
- "arguments": {
- "patientid": "${ .patientId }"
- }
- }
- }]
-}
-```
-
- |
-
-
-```yaml
-eventRefs:
-- HighBodyTemperature
-actions:
-- functionRef:
- refName: sendTylenolOrder
- arguments:
- patientid: "${ .patientId }"
-```
-
- |
-
-
-
-
+|
+
+```json
+{
+ "name": "HelloWorldFunction",
+ "operation": "https://hellworldservice.api.com/api.json#helloWorld"
}
```
-Depending on the value of the Event states `exclusive` property, this definition can mean two different things:
-
-1. If `exclusive` is set to "true", the consumption of **either** the `HighBodyTemperature` or `HighBloodPressure` events will trigger action execution.
-
-2. If `exclusive` is set to "false", the consumption of **both** the `HighBodyTemperature` and `HighBloodPressure` events will trigger action execution.
+ |
+
-This is visualized in the diagram below:
+```yaml
+name: HelloWorldFunction
+operation: https://hellworldservice.api.com/api.json#helloWorld
+```
-
-
-
+ |
+
+
-#### Event State: Timeout
+
-The event state timeout period is described in the ISO 8601 data and time format.
-You can specify for example "PT15M" to represent 15 minutes or "P2DT3H4M" to represent 2 days, 3 hours and 4 minutes.
-Timeout values should always be represented as durations and not as time/repeating intervals.
+The `name` property defines an unique name of the function definition.
-The timeout property needs to be described in detail as it depends on whether or not the Event state is a workflow starting
-state or not.
+The `type` property defines the function type. Its value can be either `rest` or `expression`. Default value is `rest`.
-If the Event state is a workflow starting state, incoming events may trigger workflow instances. In this case,
-if the `exclusive` property is set to true, the timeout property should be ignored.
+Depending on the function `type`, the `operation` property can be:
+* If `type` is `rest`, a combination of the function/service OpenAPI definition document URI and the particular service operation that needs to be invoked, separated by a '#'.
+ For example `https://petstore.swagger.io/v2/swagger.json#getPetById`.
+* If `type` is `rpc`, a combination of the gRPC proto document URI and the particular service name and service method name that needs to be invoked, separated by a '#'.
+For example `file://myuserservice.proto#UserService#ListUsers`.
+* If `type` is `expression`, defines the expression syntax. Take a look at the [workflow expressions section](#Workflow-Expressions) for more information on this.
-If the `exclusive` property is set to false, in this case, the defined timeout represents the time
-between arrival of specified events. To give an example, consider the following:
+The [`metadata`](#Workflow-Metadata) property allows users to define custom information to function definitions.
+This allows you for example to define functions that describe of a command executions on a Docker image:
-```json
-{
-"states": [
-{
- "name": "ExampleEventState",
- "type": "event",
- "exclusive": false,
- "timeout": "PT2M",
- "onEvents": [
- {
- "eventRefs": [
- "ExampleEvent1",
- "ExampleEvent2"
- ],
- "actions": [
- ...
- ]
- }
- ],
- "end": {
- "terminate": true
- }
-}
-]
-}
+```yaml
+functions:
+- name: whalesayimage
+ metadata:
+ image: docker/whalesay
+ command: cowsay
```
-The first timeout would start once any of the referenced events are consumed. If the second event does not occur within
-the defined timeout, no workflow instance should be created.
+Note that using metadata for cases such as above heavily reduces the portability of your workflow markup.
-If the event state is not a workflow starting state, the `timeout` property is relative to the time when the
-state becomes active. If the defined event conditions (regardless of the value of the exclusive property)
-are not satisfied within the defined timeout period, the event state should transition to the next state or end the workflow
-instance in case it is an end state without performing any actions.
+Function definitions themselves do not define data input parameters. Parameters can be
+defined via the `parameters` property in [function definitions](#FunctionRef-Definition) inside [actions](#Action-Definition).
-#### Action Definition
+#### Event Definition
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
-| name | Unique action name | string | no |
-| [functionRef](#FunctionRef-Definition) | References a reusable function definition | object | yes if `eventRef` is not used |
-| [eventRef](#EventRef-Definition) | References a `trigger` and `result` reusable event definitions | object | yes if `functionRef` is not used |
-| timeout | Time period to wait for function execution to complete or the resultEventRef to be consumed (ISO 8601 format). For example: "PT15M" (15 minutes), or "P2DT3H4M" (2 days, 3 hours and 4 minutes)| string | no |
-| [actionDataFilter](#action-data-filter) | Action data filter definition | object | no |
+| name | Unique event name | string | yes |
+| source | CloudEvent source | string | yes if kind is set to "consumed", otherwise no |
+| type | CloudEvent type | string | yes |
+| kind | Defines the event is either `consumed` or `produced` by the workflow. Default is `consumed` | enum | no |
+| [correlation](#Correlation-Definition) | Define event correlation rules for this event. Only used for consumed events | array | no |
+| [metadata](#Workflow-Metadata) | Metadata information | object | no |
Click to view example definition
@@ -1450,15 +1655,16 @@ instance in case it is an end state without performing any actions.
```json
-{
- "name": "Finalize Application Action",
- "functionRef": {
- "refName": "finalizeApplicationFunction",
- "arguments": {
- "applicantid": "${ .applicantId }"
- }
- },
- "timeout": "PT15M"
+{
+ "name": "ApplicantInfo",
+ "type": "org.application.info",
+ "source": "applicationssource",
+ "kind": "consumed",
+ "correlation": [
+ {
+ "contextAttributeName": "applicantId"
+ }
+ ]
}
```
@@ -1466,12 +1672,12 @@ instance in case it is an end state without performing any actions.
|
```yaml
-name: Finalize Application Action
-functionRef:
- refName: finalizeApplicationFunction
- arguments:
- applicantid: "${ .applicantId }"
-timeout: PT15M
+name: ApplicantInfo
+type: org.application.info
+source: applicationssource
+kind: consumed
+correlation:
+- contextAttributeName: applicantId
```
|
@@ -1480,99 +1686,171 @@ timeout: PT15M
Click to view example definition
-
+We can then define a correlation rule, through which all consumed events with the "hospitalMonitorSystem", and the "com.hospital.patient.heartRateMonitor"
+type that have the **same** value of the `patientId` property to be correlated to the created workflow instance:
+
+```json
+{
+"events": [
+ {
+ "name": "HeartRateReadingEvent",
+ "source": "hospitalMonitorSystem",
+ "type": "com.hospital.patient.heartRateMonitor",
+ "kind": "consumed",
+ "correlation": [
+ {
+ "contextAttributeName": "patientId"
+ }
+ ]
+ }
+]
+}
+```
+
+If a workflow instance is created (e.g., via Event state) by consuming a "HeartRateReadingEvent" event, all other consumed events
+from the defined source and with the defined type that have the same "patientId" as the event that triggered the workflow instance
+should then also be associated with the same instance.
+
+You can also correlate multiple events together. In the following example, we assume that the workflow consumes two different event types,
+and we want to make sure that both are correlated, as in the above example, with the same "patientId":
-
-
- | JSON |
- YAML |
-
-
-|
```json
{
- "refName": "finalizeApplicationFunction",
- "arguments": {
- "applicantid": "${ .applicantId }"
+"events": [
+ {
+ "name": "HeartRateReadingEvent",
+ "source": "hospitalMonitorSystem",
+ "type": "com.hospital.patient.heartRateMonitor",
+ "kind": "consumed",
+ "correlation": [
+ {
+ "contextAttributeName": "patientId"
}
+ ]
+ },
+ {
+ "name": "BloodPressureReadingEvent",
+ "source": "hospitalMonitorSystem",
+ "type": "com.hospital.patient.bloodPressureMonitor",
+ "kind": "consumed",
+ "correlation": [
+ {
+ "contextAttributeName": "patientId"
+ }
+ ]
+ }
+]
}
```
- |
-
-
-```yaml
-refName: finalizeApplicationFunction
-arguments:
- applicantid: "${ .applicantId }"
-```
-
- |
-
-
-
-Click to view example definition
@@ -1586,12 +1864,16 @@ Values of the `arguments` property can be either static values, or an expression
```json
-{
- "eventRef": {
- "triggerEventRef": "MakeVetAppointment",
- "data": "${ .patientInfo }",
- "resultEventRef": "VetAppointmentInfo"
- }
+{
+ "correlation": [
+ {
+ "contextAttributeName": "patientId"
+ },
+ {
+ "contextAttributeName": "department",
+ "contextAttributeValue" : "UrgentCare"
+ }
+ ]
}
```
@@ -1599,10 +1881,10 @@ Values of the `arguments` property can be either static values, or an expression
|
```yaml
-eventRef:
- triggerEventRef: MakeVetAppointment
- data: "${ .patientInfo }"
- resultEventRef: VetAppointmentInfo
+correlation:
+- contextAttributeName: patientId
+- contextAttributeName: department
+ contextAttributeValue: UrgentCare
```
|
@@ -1611,22 +1893,45 @@ eventRef:
Click to view example definition
@@ -1641,8 +1946,46 @@ to the trigger/produced event.
```json
{
- "error": "Item not in inventory",
- "transition": "IssueRefundToCustomer"
+"name": "MonitorVitals",
+"type": "event",
+"exclusive": true,
+"onEvents": [{
+ "eventRefs": ["HighBodyTemperature"],
+ "actions": [{
+ "functionRef": {
+ "refName": "sendTylenolOrder",
+ "arguments": {
+ "patientid": "${ .patientId }"
+ }
+ }
+ }]
+ },
+ {
+ "eventRefs": ["HighBloodPressure"],
+ "actions": [{
+ "functionRef": {
+ "refName": "callNurse",
+ "arguments": {
+ "patientid": "${ .patientId }"
+ }
+ }
+ }]
+ },
+ {
+ "eventRefs": ["HighRespirationRate"],
+ "actions": [{
+ "functionRef": {
+ "refName": "callPulmonologist",
+ "arguments": {
+ "patientid": "${ .patientId }"
+ }
+ }
+ }]
+ }
+],
+"end": {
+ "terminate": true
+}
}
```
@@ -1650,8 +1993,33 @@ to the trigger/produced event.
```yaml
-error: Item not in inventory
-transition: IssueRefundToCustomer
+name: MonitorVitals
+type: event
+exclusive: true
+onEvents:
+- eventRefs:
+ - HighBodyTemperature
+ actions:
+ - functionRef:
+ refName: sendTylenolOrder
+ arguments:
+ patientid: "${ .patientId }"
+- eventRefs:
+ - HighBloodPressure
+ actions:
+ - functionRef:
+ refName: callNurse
+ arguments:
+ patientid: "${ .patientId }"
+- eventRefs:
+ - HighRespirationRate
+ actions:
+ - functionRef:
+ refName: callPulmonologist
+ arguments:
+ patientid: "${ .patientId }"
+end:
+ terminate: true
```
|
@@ -1660,35 +2028,44 @@ transition: IssueRefundToCustomer
+
+
-The `retryRef` property is used to define the retry strategy to be used for this particular error.
+If the Event state in this case is a workflow starting state, the occurrence of *any* of the defined events would start a new workflow instance.
-For more information, see the [Workflow Error Handling](#Workflow-Error-Handling) sections.
+
+
+
-#### Retry Definition
+If the Event state in this case is a workflow starting state, the occurrence of *all* defined events would start a new
+ workflow instance.
+
+In order to consider only events that are related to each other, we need to set the `correlation` property in the workflow
+ [events definitions](#Event-Definition). This allows us to set up event correlation rules against the events
+ extension context attributes.
-| Parameter | Description | Type | Required |
-| --- | --- | --- | --- |
-| name | Unique retry strategy name | string | yes |
-| delay | Time delay between retry attempts (ISO 8601 duration format) | string | no |
-| maxAttempts | Maximum number of retry attempts. Value of 0 means no retries are performed | string or number | no |
-| maxDelay | Maximum amount of delay between retry attempts (ISO 8601 duration format) | string | no |
-| increment | Static duration which will be added to the delay between successive retries (ISO 8601 duration format) | string | no |
-| multiplier | Float value by which the delay is multiplied before each attempt. For example: "1.2" meaning that each successive delay is 20% longer than the previous delay. For example, if delay is 'PT10S', then the delay between the first and second attempts will be 10 seconds, and the delay before the third attempt will be 12 seconds. | float or string | no |
-| jitter | If float type, maximum amount of random time added or subtracted from the delay between each retry relative to total delay (between 0.0 and 1.0). If string type, absolute maximum amount of random time added or subtracted from the delay between each retry (ISO 8601 duration format) | float or string | no |
+If the Event state is not a workflow starting state, the `timeout` property can be used to define the time duration from the
+invocation of the event state. If the defined event, or events have not been received during this time,
+the state should transition to the next state or can end the workflow execution (if it is an end state).
+
+#### Event State: onEvents Definition
+
+| Parameter | Description | Type | Required |
+| --- | --- | --- | --- |
+| eventRefs | References one or more unique event names in the defined workflow [events](#Event-Definition) | array | yes |
+| actionMode | Specifies how actions are to be performed (in sequence of parallel). Default is "sequential" | string | no |
+| [actions](#Action-Definition) | Actions to be performed | array | no |
+| [eventDataFilter](#Event-data-filters) | Event data filter definition | object | no |
Click to view example definition
@@ -1703,10 +2080,15 @@ For more information, see the [Workflow Error Handling](#Workflow-Error-Handling
```json
{
- "name": "TimeoutRetryStrat",
- "delay": "PT2M",
- "maxAttempts": 3,
- "jitter": "PT0.001S"
+ "eventRefs": ["HighBodyTemperature"],
+ "actions": [{
+ "functionRef": {
+ "refName": "sendTylenolOrder",
+ "arguments": {
+ "patientid": "${ .patientId }"
+ }
+ }
+ }]
}
```
@@ -1714,10 +2096,13 @@ For more information, see the [Workflow Error Handling](#Workflow-Error-Handling
```yaml
-name: TimeoutRetryStrat
-delay: PT2M
-maxAttempts: 3
-jitter: PT0.001S
+eventRefs:
+- HighBodyTemperature
+actions:
+- functionRef:
+ refName: sendTylenolOrder
+ arguments:
+ patientid: "${ .patientId }"
```
|
@@ -1726,103 +2111,190 @@ jitter: PT0.001S
+
+
+
+#### Event State: Timeout
+
+The event state timeout period is described in the ISO 8601 data and time format.
+You can specify for example "PT15M" to represent 15 minutes or "P2DT3H4M" to represent 2 days, 3 hours and 4 minutes.
+Timeout values should always be represented as durations and not as time/repeating intervals.
+
+The timeout property needs to be described in detail as it depends on whether or not the Event state is a workflow starting
+state or not.
+
+If the Event state is a workflow starting state, incoming events may trigger workflow instances. In this case,
+if the `exclusive` property is set to true, the timeout property should be ignored.
+
+If the `exclusive` property is set to false, in this case, the defined timeout represents the time
+between arrival of specified events. To give an example, consider the following:
```json
{
- "name": "Timeout Errors Strategy",
- "delay": "PT10S",
- "multiplier": 2,
- "maxAttempts": 4
+"states": [
+{
+ "name": "ExampleEventState",
+ "type": "event",
+ "exclusive": false,
+ "timeout": "PT2M",
+ "onEvents": [
+ {
+ "eventRefs": [
+ "ExampleEvent1",
+ "ExampleEvent2"
+ ],
+ "actions": [
+ ...
+ ]
+ }
+ ],
+ "end": {
+ "terminate": true
+ }
+}
+]
}
```
-which means that we will retry up to 4 times after waiting with increasing delay between attempts;
-in this example 10, 20, 40, and 80 seconds between retries.
-The `maxAttempts` property determines the maximum number of retry attempts allowed and is a positive integer value.
+The first timeout would start once any of the referenced events are consumed. If the second event does not occur within
+the defined timeout, no workflow instance should be created.
-The `jitter` property is important to prevent certain scenarios where clients
-are retrying in sync, possibly causing or contributing to a transient failure
-precisely because they're retrying at the same time. Adding a typically small,
-bounded random amount of time to the period between retries serves the purpose
-of attempting to prevent these retries from happening simultaneously, possibly
-reducing total time to complete requests and overall congestion. How this value
-is used in the exponential backoff algorithm is left up to implementations.
+If the event state is not a workflow starting state, the `timeout` property is relative to the time when the
+state becomes active. If the defined event conditions (regardless of the value of the exclusive property)
+are not satisfied within the defined timeout period, the event state should transition to the next state or end the workflow
+instance in case it is an end state without performing any actions.
-`jitter` may be specified as a percentage relative to the total delay.
-For example, if `interval` is 2 seconds, `multiplier` is 2 seconds, and we're at
-the third attempt, there will be a delay of 6 seconds. If we set `jitter` to
-0.3, then a random amount of time between 0 and 1.8 (`totalDelay * jitter == 6 * 0.3`)
-will be added or subtracted from the delay.
+#### Action Definition
-Alternatively, `jitter` may be defined as an absolute value specified as an ISO
-8601 duration. This way, the maximum amount of random time added is fixed and
-will not increase as new attempts are made.
+| Parameter | Description | Type | Required |
+| --- | --- | --- | --- |
+| name | Unique action name | string | no |
+| [functionRef](#FunctionRef-Definition) | References a reusable function definition | object | yes if `eventRef` is not used |
+| [eventRef](#EventRef-Definition) | References a `trigger` and `result` reusable event definitions | object | yes if `functionRef` is not used |
+| timeout | Time period to wait for function execution to complete or the resultEventRef to be consumed (ISO 8601 format). For example: "PT15M" (15 minutes), or "P2DT3H4M" (2 days, 3 hours and 4 minutes)| string | no |
+| [actionDataFilter](#Action-data-filters) | Action data filter definition | object | no |
-The `maxDelay` property determines the maximum amount of delay that is desired between retry attempts, and is applied
-after `increment`, `multiplier`, and `jitter`.
+Click to view example definition
+
-To explain this better, let's say we have the following retry definition:
+
+
+ | JSON |
+ YAML |
+
+
+|
```json
{
- "name": "Timeout Errors Strategy",
- "delay": "PT10S",
- "maxDelay": "PT100S",
- "multiplier": 4,
- "jitter": "PT1S",
- "maxAttempts": 4
+ "name": "Finalize Application Action",
+ "functionRef": {
+ "refName": "finalizeApplicationFunction",
+ "arguments": {
+ "applicantid": "${ .applicantId }"
+ }
+ },
+ "timeout": "PT15M"
}
```
-which means that we will retry up to 4 times after waiting with increasing delay between attempts;
-in this example we might observe the following series of delays:
-* 11s (min(`maxDelay`, (`delay` +/- rand(`jitter`)) => min(100, 10 + 1))
-* 43s (min(`maxDelay`, (11s * `multiplier`) +/- rand(`jitter`)) => min(100, (11 * 4) - 1))
-* 100s (min(`maxDelay`, (43s * `multiplier`) +/- rand(`jitter`)) => min(100, (43 * 4) + 0))
-* 100s (min(`maxDelay`, (100s * `multiplier`) +/- rand(`jitter`)) => min(100, (100 * 4) - 1))
-For more information, refer to the [Workflow Error Handling](#Workflow-Error-Handling) sections.
+ |
+
-#### Transition Definition
+```yaml
+name: Finalize Application Action
+functionRef:
+ refName: finalizeApplicationFunction
+ arguments:
+ applicantid: "${ .applicantId }"
+timeout: PT15M
+```
-`Transition` definition can have two types, either `string` or `object`.
-If `string`, it defines the name of the state to transition to.
-This can be used as a short-cut definition when you don't need to define any other parameters, for example:
+ |
+
+
+
+Click to view example definition
@@ -1837,11 +2309,10 @@ it with its `object` type which has the following properties:
```json
{
- "produceEvents": [{
- "eventRef": "produceResultEvent",
- "data": "${ .result.data }"
- }],
- "nextState": "EvalResultState"
+ "refName": "finalizeApplicationFunction",
+ "arguments": {
+ "applicantid": "${ .applicantId }"
+ }
}
```
@@ -1849,10 +2320,9 @@ it with its `object` type which has the following properties:
```yaml
-produceEvents:
-- eventRef: produceResultEvent
- data: "${ .result.data }"
-nextState: EvalResultState
+refName: finalizeApplicationFunction
+arguments:
+ applicantid: "${ .applicantId }"
```
|
@@ -1861,29 +2331,29 @@ nextState: EvalResultState
Click to view example definition
@@ -1898,20 +2368,11 @@ Transitions allow you to move from one state (control-logic block) to another. F
```json
{
- "name": "RejectApplication",
- "type": "operation",
- "actionMode": "sequential",
- "actions": [
- {
- "functionRef": {
- "refName": "sendRejectionEmailFunction",
- "arguments": {
- "customer": "${ .customer }"
- }
- }
- }
- ],
- "end": true
+ "eventRef": {
+ "triggerEventRef": "MakeVetAppointment",
+ "data": "${ .patientInfo }",
+ "resultEventRef": "VetAppointmentInfo"
+ }
}
```
@@ -1919,15 +2380,10 @@ Transitions allow you to move from one state (control-logic block) to another. F
```yaml
-name: RejectApplication
-type: operation
-actionMode: sequential
-actions:
-- functionRef:
- refName: sendRejectionEmailFunction
- arguments:
- customer: "${ .customer }"
-end: true
+eventRef:
+ triggerEventRef: MakeVetAppointment
+ data: "${ .patientInfo }"
+ resultEventRef: VetAppointmentInfo
```
|
@@ -1936,24 +2392,22 @@ end: true
Click to view example definition
@@ -1967,23 +2421,9 @@ Once all actions have been performed, a transition to another state can occur.
```json
-{
- "name":"CheckVisaStatus",
- "type":"switch",
- "eventConditions": [
- {
- "eventRef": "visaApprovedEvent",
- "transition": "HandleApprovedVisa"
- },
- {
- "eventRef": "visaRejectedEvent",
- "transition": "HandleRejectedVisa"
- }
- ],
- "eventTimeout": "PT1H",
- "default": {
- "transition": "HandleNoVisaDecision"
- }
+{
+ "error": "Item not in inventory",
+ "transition": "IssueRefundToCustomer"
}
```
@@ -1991,16 +2431,8 @@ Once all actions have been performed, a transition to another state can occur.
|
```yaml
-name: CheckVisaStatus
-type: switch
-eventConditions:
-- eventRef: visaApprovedEvent
- transition: HandleApprovedVisa
-- eventRef: visaRejectedEvent
- transition: HandleRejectedVisa
-eventTimeout: PT1H
-default:
- transition: HandleNoVisaDecision
+error: Item not in inventory
+transition: IssueRefundToCustomer
```
|
@@ -2009,35 +2441,35 @@ default:
Click to view example definition
@@ -2052,9 +2484,10 @@ If events defined in event-based conditions do not arrive before the states `eve
```json
{
- "name": "Eighteen or older",
- "condition": "${ .applicant | .age >= 18 }",
- "transition": "StartApplication"
+ "name": "TimeoutRetryStrat",
+ "delay": "PT2M",
+ "maxAttempts": 3,
+ "jitter": "PT0.001S"
}
```
@@ -2062,9 +2495,10 @@ If events defined in event-based conditions do not arrive before the states `eve
```yaml
-name: Eighteen or older
-condition: "${ .applicant | .age >= 18 }"
-transition: StartApplication
+name: TimeoutRetryStrat
+delay: PT2M
+maxAttempts: 3
+jitter: PT0.001S
```
|
@@ -2073,81 +2507,103 @@ transition: StartApplication
Click to view example definition
-
+The `multiplier` property specifies the value by which the interval time is increased for each of the retry attempts.
+To explain this better, let's say we have the following retry definition:
-
-
- | JSON |
- YAML |
-
-
-|
+```json
+{
+ "name": "Timeout Errors Strategy",
+ "delay": "PT10S",
+ "multiplier": 2,
+ "maxAttempts": 4
+}
+```
+which means that we will retry up to 4 times after waiting with increasing delay between attempts;
+in this example 10, 20, 40, and 80 seconds between retries.
+
+The `maxAttempts` property determines the maximum number of retry attempts allowed and is a positive integer value.
+
+The `jitter` property is important to prevent certain scenarios where clients
+are retrying in sync, possibly causing or contributing to a transient failure
+precisely because they're retrying at the same time. Adding a typically small,
+bounded random amount of time to the period between retries serves the purpose
+of attempting to prevent these retries from happening simultaneously, possibly
+reducing total time to complete requests and overall congestion. How this value
+is used in the exponential backoff algorithm is left up to implementations.
+
+`jitter` may be specified as a percentage relative to the total delay.
+For example, if `interval` is 2 seconds, `multiplier` is 2 seconds, and we're at
+the third attempt, there will be a delay of 6 seconds. If we set `jitter` to
+0.3, then a random amount of time between 0 and 1.8 (`totalDelay * jitter == 6 * 0.3`)
+will be added or subtracted from the delay.
+
+Alternatively, `jitter` may be defined as an absolute value specified as an ISO
+8601 duration. This way, the maximum amount of random time added is fixed and
+will not increase as new attempts are made.
+
+The `maxDelay` property determines the maximum amount of delay that is desired between retry attempts, and is applied
+after `increment`, `multiplier`, and `jitter`.
+
+To explain this better, let's say we have the following retry definition:
```json
{
- "name": "Visa approved",
- "eventRef": "visaApprovedEvent",
- "transition": "HandleApprovedVisa"
+ "name": "Timeout Errors Strategy",
+ "delay": "PT10S",
+ "maxDelay": "PT100S",
+ "multiplier": 4,
+ "jitter": "PT1S",
+ "maxAttempts": 4
}
```
+which means that we will retry up to 4 times after waiting with increasing delay between attempts;
+in this example we might observe the following series of delays:
+* 11s (min(`maxDelay`, (`delay` +/- rand(`jitter`)) => min(100, 10 + 1))
+* 43s (min(`maxDelay`, (11s * `multiplier`) +/- rand(`jitter`)) => min(100, (11 * 4) - 1))
+* 100s (min(`maxDelay`, (43s * `multiplier`) +/- rand(`jitter`)) => min(100, (43 * 4) + 0))
+* 100s (min(`maxDelay`, (100s * `multiplier`) +/- rand(`jitter`)) => min(100, (100 * 4) - 1))
- |
-
-
-```yaml
-name: Visa approved
-eventRef: visaApprovedEvent
-transition: HandleApprovedVisa
-```
-
- |
-
-
-
-Click to view example definition
@@ -2162,10 +2618,11 @@ The `eventDataFilter` property can be used to filter event when it is received.
```json
{
- "name": "WaitForCompletion",
- "type": "delay",
- "timeDelay": "PT5S",
- "transition": "GetJobStatus"
+ "produceEvents": [{
+ "eventRef": "produceResultEvent",
+ "data": "${ .result.data }"
+ }],
+ "nextState": "EvalResultState"
}
```
@@ -2173,10 +2630,10 @@ The `eventDataFilter` property can be used to filter event when it is received.
```yaml
-name: WaitForCompletion
-type: delay
-timeDelay: PT5S
-transition: GetJobStatus
+produceEvents:
+- eventRef: produceResultEvent
+ data: "${ .result.data }"
+nextState: EvalResultState
```
|
@@ -2185,25 +2642,29 @@ transition: GetJobStatus
Click to view example definition
@@ -2217,124 +2678,21 @@ Delay state waits for a certain amount of time before transitioning to a next st
```json
- {
- "name":"ParallelExec",
- "type":"parallel",
- "completionType": "and",
- "branches": [
+{
+ "name": "RejectApplication",
+ "type": "operation",
+ "actionMode": "sequential",
+ "actions": [
{
- "name": "Branch1",
- "actions": [
- {
- "functionRef": {
- "refName": "functionNameOne",
- "arguments": {
- "order": "${ .someParam }"
- }
+ "functionRef": {
+ "refName": "sendRejectionEmailFunction",
+ "arguments": {
+ "customer": "${ .customer }"
}
}
- ]
- },
- {
- "name": "Branch2",
- "actions": [
- {
- "functionRef": {
- "refName": "functionNameTwo",
- "arguments": {
- "order": "${ .someParam }"
- }
- }
- }
- ]
}
- ],
- "end": true
-}
-```
-
- |
-
-
-```yaml
-name: ParallelExec
-type: parallel
-completionType: and
-branches:
-- name: Branch1
- actions:
- - functionRef:
- refName: functionNameOne
- arguments:
- order: "${ .someParam }"
-- name: Branch2
- actions:
- - functionRef:
- refName: functionNameTwo
- arguments:
- order: "${ .someParam }"
-end: true
-```
-
- |
-
-
-
-Click to view example definition
-
-
-
-
- | JSON |
- YAML |
-
-
-|
-
-```json
-{
- "name": "Branch1",
- "actions": [
- {
- "functionRef": {
- "refName": "functionNameOne",
- "arguments": {
- "order": "${ .someParam }"
- }
- }
- },
- {
- "functionRef": {
- "refName": "functionNameTwo",
- "arguments": {
- "order": "${ .someParamTwo }"
- }
- }
- }
- ]
+ ],
+ "end": true
}
```
@@ -2342,68 +2700,41 @@ Exceptions may occur during execution of branches of the Parallel state, this is
|
```yaml
-name: Branch1
-actions:
-- functionRef:
- refName: functionNameOne
- arguments:
- order: "${ .someParam }"
-- functionRef:
- refName: functionNameTwo
- arguments:
- order: "${ .someParamTwo }"
-```
-
- |
-
-
-
-Click to view example definition
@@ -2417,11 +2748,23 @@ For more information, see the [Workflow Error Handling](#Workflow-Error-Handling
```json
-{
- "name": "HandleApprovedVisa",
- "type": "subflow",
- "workflowId": "handleApprovedVisaWorkflowID",
- "end": true
+{
+ "name":"CheckVisaStatus",
+ "type":"switch",
+ "eventConditions": [
+ {
+ "eventRef": "visaApprovedEvent",
+ "transition": "HandleApprovedVisa"
+ },
+ {
+ "eventRef": "visaRejectedEvent",
+ "transition": "HandleRejectedVisa"
+ }
+ ],
+ "eventTimeout": "PT1H",
+ "default": {
+ "transition": "HandleNoVisaDecision"
+ }
}
```
@@ -2429,10 +2772,16 @@ For more information, see the [Workflow Error Handling](#Workflow-Error-Handling
|
```yaml
-name: HandleApprovedVisa
-type: subflow
-workflowId: handleApprovedVisaWorkflowID
-end: true
+name: CheckVisaStatus
+type: switch
+eventConditions:
+- eventRef: visaApprovedEvent
+ transition: HandleApprovedVisa
+- eventRef: visaRejectedEvent
+ transition: HandleRejectedVisa
+eventTimeout: PT1H
+default:
+ transition: HandleNoVisaDecision
```
|
@@ -2441,52 +2790,35 @@ end: true
-
-
-
-Reusable workflow are referenced by their `id` property via the SubFlow states`workflowId` parameter.
-
-Each referenced workflow receives the SubFlow states data as workflow data input.
+Switch states can be viewed as workflow gateways: they can direct transitions of a workflow based on certain conditions.
+There are two types of conditions for switch states:
+* [Data-based conditions](#switch-state-dataconditions)
+* [Event-based conditions](#switch-state-eventconditions)
-The `waitForCompletion` property defines if the SubFlow state should wait until the referenced reusable workflow
-has completed its execution. If it's set to "true" (default value), SubFlow state execution must wait until the referenced workflow has completed its execution.
-In this case the workflow data output of the referenced workflow can and should be merged with the SubFlow states state data.
-If it's set to "false" the parent workflow can continue its execution while the referenced sub-workflow
-is being executed. For this case, the referenced (child) workflow data output cannot be merged with the SubFlow states
-state data (as by the time its completion the parent workflow execution has already continued).
+These are exclusive, meaning that a switch state can define one or the other condition type, but not both.
-The `repeat` property defines the SubFlow states repeated execution (looping) behavior. This allows you to specify that
-the sub-workflow should be executed multiple times repeatedly.
-If the `repeat` property is defined, the `waitForCompletion` should be assumed have the value of `true`.
-If the workflow explicitly triggers [compensation](#Workflow-Compensation) and the SubFlow state
-was executed and defines its compensation state, it should be compensated once, no matter how many times
-its was executed as defined by the `repeat` property.
-After each execution of the SubFlow state, if `repeat` is defined, the SubFlow state data at the end of the
-one execution should become the state data of the next execution.
+At times multiple defined conditions can be evaluated to `true` by runtime implementations.
+Conditions defined first take precedence over conditions defined later. This is backed by the fact that arrays/sequences
+are ordered in both JSON and YAML. For example, let's say there are two `true` conditions: A and B, defined in that order.
+Because A was defined first, its transition will be executed, not B's.
-For more information about the `repeat` property see the [Repeat Definition](#Repeat-Definition) section.
+In case of data-based conditions definition, switch state controls workflow transitions based on the states data.
+If no defined conditions can be matched, the state transitions is taken based on the `default` property.
+This property can be either a `transition` to another workflow state, or an `end` definition meaning a workflow end.
-Referenced sub-workflows must declare their own [function](#Function-Definition) and [event](#Event-Definition) definitions.
+For event-based conditions, a switch state acts as a workflow wait state. It halts workflow execution
+until one of the referenced events arrive, then making a transition depending on that event definition.
+If events defined in event-based conditions do not arrive before the states `eventTimeout` property expires,
+ state transitions are based on the defined `default` property.
-#### Inject State
+#### Switch State: Data Conditions
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
-| id | Unique state id | string | no |
-| name | State name | string | yes |
-| type | State type | string | yes |
-| data | JSON object which can be set as state's data input and can be manipulated via filter | object | yes |
-| [stateDataFilter](#state-data-filter) | State data filter | object | no |
-| [transition](#Transitions) | Next transition of the workflow after subflow has completed | object | yes (if end is set to false) |
-| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no |
-| [compensatedBy](#Workflow-Compensation) | Unique name of a workflow state which is responsible for compensation of this state | String | no |
-| [usedForCompensation](#Workflow-Compensation) | If true, this state is used to compensate another state. Default is "false" | boolean | no |
+| name | Data condition name | string | no |
+| [condition](#Workflow-Expressions) | Workflow expression evaluated against state data. Must evaluate to true or false | string | yes |
+| [transition](#Transitions) or [end](#End-Definition) | Defines what to do if condition is true. Transition to another state, or end workflow | object | yes |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
-| [end](#End-Definition) | If this state and end state | object | no |
Click to view example definition
@@ -2500,13 +2832,10 @@ Referenced sub-workflows must declare their own [function](#Function-Definition)
```json
-{
- "name":"Hello",
- "type":"inject",
- "data": {
- "result": "Hello"
- },
- "transition": "World"
+{
+ "name": "Eighteen or older",
+ "condition": "${ .applicant | .age >= 18 }",
+ "transition": "StartApplication"
}
```
@@ -2514,11 +2843,9 @@ Referenced sub-workflows must declare their own [function](#Function-Definition)
|
```yaml
-name: Hello
-type: inject
-data:
- result: Hello
-transition: World
+name: Eighteen or older
+condition: "${ .applicant | .age >= 18 }"
+transition: StartApplication
```
|
@@ -2527,15 +2854,26 @@ transition: World
Click to view example definition
+
@@ -2545,59 +2883,111 @@ as data output to the transition state:
|
- ```json
- {
- "name":"SimpleInjectState",
- "type":"inject",
- "data": {
- "person": {
- "fname": "John",
- "lname": "Doe",
- "address": "1234 SomeStreet",
- "age": 40
- }
- },
- "transition": "GreetPersonState"
- }
- ```
+```json
+{
+ "name": "Visa approved",
+ "eventRef": "visaApprovedEvent",
+ "transition": "HandleApprovedVisa"
+}
+```
|
```yaml
- name: SimpleInjectState
- type: inject
- data:
- person:
- fname: John
- lname: Doe
- address: 1234 SomeStreet
- age: 40
- transition: GreetPersonState
+name: Visa approved
+eventRef: visaApprovedEvent
+transition: HandleApprovedVisa
```
|
-The data output of the "SimpleInjectState" which then is passed as input to the transition state would be:
+Click to view example definition
+
+
+
+
+ | JSON |
+ YAML |
+
+
+|
```json
{
- "person": {
- "fname": "John",
- "lname": "Doe",
- "address": "1234 SomeStreet",
- "age": 40
- }
+ "name": "WaitForCompletion",
+ "type": "delay",
+ "timeDelay": "PT5S",
+ "transition": "GetJobStatus"
}
+```
+
+ |
+
+```yaml
+name: WaitForCompletion
+type: delay
+timeDelay: PT5S
+transition: GetJobStatus
```
-If the inject state already receives a data input from the previous transition state, the inject data should be merged
-with its data input.
+ |
+
+
-You can also use the filter property to filter the state data after data is injected. Let's say we have:
+Click to view example definition
+
@@ -2608,116 +2998,91 @@ You can also use the filter property to filter the state data after data is inje
|
```json
- {
- "name":"SimpleInjectState",
- "type":"inject",
- "data": {
- "people": [
- {
- "fname": "John",
- "lname": "Doe",
- "address": "1234 SomeStreet",
- "age": 40
- },
- {
- "fname": "Marry",
- "lname": "Allice",
- "address": "1234 SomeStreet",
- "age": 25
- },
- {
- "fname": "Kelly",
- "lname": "Mill",
- "address": "1234 SomeStreet",
- "age": 30
- }
+ {
+ "name":"ParallelExec",
+ "type":"parallel",
+ "completionType": "and",
+ "branches": [
+ {
+ "name": "Branch1",
+ "actions": [
+ {
+ "functionRef": {
+ "refName": "functionNameOne",
+ "arguments": {
+ "order": "${ .someParam }"
+ }
+ }
+ }
]
- },
- "stateDataFilter": {
- "dataOutputPath": "${ {people: [.people[] | select(.age < 40)]} }"
- },
- "transition": "GreetPersonState"
- }
+ },
+ {
+ "name": "Branch2",
+ "actions": [
+ {
+ "functionRef": {
+ "refName": "functionNameTwo",
+ "arguments": {
+ "order": "${ .someParam }"
+ }
+ }
+ }
+ ]
+ }
+ ],
+ "end": true
+}
```
|
```yaml
- name: SimpleInjectState
- type: inject
- data:
- people:
- - fname: John
- lname: Doe
- address: 1234 SomeStreet
- age: 40
- - fname: Marry
- lname: Allice
- address: 1234 SomeStreet
- age: 25
- - fname: Kelly
- lname: Mill
- address: 1234 SomeStreet
- age: 30
- stateDataFilter:
- dataOutputPath: "${ {people: [.people[] | select(.age < 40)]} }"
- transition: GreetPersonState
+name: ParallelExec
+type: parallel
+completionType: and
+branches:
+- name: Branch1
+ actions:
+ - functionRef:
+ refName: functionNameOne
+ arguments:
+ order: "${ .someParam }"
+- name: Branch2
+ actions:
+ - functionRef:
+ refName: functionNameTwo
+ arguments:
+ order: "${ .someParam }"
+end: true
```
|
-In which case the states data output would include only people whose age is less than 40:
-
-```json
-{
- "people": [
- {
- "fname": "Marry",
- "lname": "Allice",
- "address": "1234 SomeStreet",
- "age": 25
- },
- {
- "fname": "Kelly",
- "lname": "Mill",
- "address": "1234 SomeStreet",
- "age": 30
- }
- ]
-}
-```
+Click to view example definition
@@ -2732,21 +3097,25 @@ This allows you to test if your workflow behaves properly for cases when there a
```json
{
- "name": "ProvisionOrdersState",
- "type": "foreach",
- "inputCollection": "${ .orders }",
- "iterationParam": "singleorder",
- "outputCollection": "${ .provisionresults }",
- "actions": [
- {
- "functionRef": {
- "refName": "provisionOrderFunction",
- "arguments": {
- "order": "${ .singleorder }"
- }
- }
- }
- ]
+ "name": "Branch1",
+ "actions": [
+ {
+ "functionRef": {
+ "refName": "functionNameOne",
+ "arguments": {
+ "order": "${ .someParam }"
+ }
+ }
+ },
+ {
+ "functionRef": {
+ "refName": "functionNameTwo",
+ "arguments": {
+ "order": "${ .someParamTwo }"
+ }
+ }
+ }
+ ]
}
```
@@ -2754,16 +3123,16 @@ This allows you to test if your workflow behaves properly for cases when there a
```yaml
-name: ProvisionOrdersState
-type: foreach
-inputCollection: "${ .orders }"
-iterationParam: "singleorder"
-outputCollection: "${ .provisionresults }"
+name: Branch1
actions:
- functionRef:
- refName: provisionOrderFunction
+ refName: functionNameOne
arguments:
- order: "${ .singleorder }"
+ order: "${ .someParam }"
+- functionRef:
+ refName: functionNameTwo
+ arguments:
+ order: "${ .someParamTwo }"
```
|
@@ -2772,58 +3141,53 @@ actions:
Click to view example definition
+
@@ -2835,35 +3199,10 @@ and our workflow is defined as:
```json
{
- "id": "sendConfirmWorkflow",
- "name": "SendConfirmationForCompletedOrders",
- "version": "1.0",
- "start": "SendConfirmState",
- "functions": [
- {
- "name": "sendConfirmationFunction",
- "operation": "file://confirmationapi.json#sendOrderConfirmation"
- }
- ],
- "states": [
- {
- "name":"SendConfirmState",
- "type":"foreach",
- "inputCollection": "${ [.orders[] | select(.completed == true)] }",
- "iterationParam": "completedorder",
- "outputCollection": "${ .confirmationresults }",
- "actions":[
- {
- "functionRef": {
- "refName": "sendConfirmationFunction",
- "arguments": {
- "orderNumber": "${ .completedorder.orderNumber }",
- "email": "${ .completedorder.email }"
- }
- }
- }],
- "end": true
- }]
+ "name": "HandleApprovedVisa",
+ "type": "subflow",
+ "workflowId": "handleApprovedVisaWorkflowID",
+ "end": true
}
```
@@ -2871,82 +3210,64 @@ and our workflow is defined as:
|
```yaml
-id: sendConfirmWorkflow
-name: SendConfirmationForCompletedOrders
-version: '1.0'
-start: SendConfirmState
-functions:
-- name: sendConfirmationFunction
- operation: file://confirmationapi.json#sendOrderConfirmation
-states:
-- name: SendConfirmState
- type: foreach
- inputCollection: "${ [.orders[] | select(.completed == true)] }"
- iterationParam: completedorder
- outputCollection: "${ .confirmationresults }"
- actions:
- - functionRef:
- refName: sendConfirmationFunction
- arguments:
- orderNumber: "${ .completedorder.orderNumber }"
- email: "${ .completedorder.email }"
- end: true
+name: HandleApprovedVisa
+type: subflow
+workflowId: handleApprovedVisaWorkflowID
+end: true
```
|
-The workflow data input containing order information is passed to the `SendConfirmState` foreach state.
-The foreach state defines an `inputCollection` property which selects all orders that have the `completed` property set to `true`.
+
+
+
-```json
-{
- "completedorder": {
- "orderNumber": "1234",
- "completed": true,
- "email": "firstBuyer@buyer.com"
- }
-}
-```
+Reusable workflow are referenced by their `id` property via the SubFlow states`workflowId` parameter.
-and the second:
+Each referenced workflow receives the SubFlow states data as workflow data input.
-```json
-{
- "completedorder": {
- "orderNumber": "5678",
- "completed": true,
- "email": "secondBuyer@buyer.com"
- }
-}
-```
+The `waitForCompletion` property defines if the SubFlow state should wait until the referenced reusable workflow
+has completed its execution. If it's set to "true" (default value), SubFlow state execution must wait until the referenced workflow has completed its execution.
+In this case the workflow data output of the referenced workflow can and should be merged with the SubFlow states state data.
+If it's set to "false" the parent workflow can continue its execution while the referenced sub-workflow
+is being executed. For this case, the referenced (child) workflow data output cannot be merged with the SubFlow states
+state data (as by the time its completion the parent workflow execution has already continued).
-The results of each parallel action execution are stored as elements in the state data array defined by the `outputCollection` property.
+The `repeat` property defines the SubFlow states repeated execution (looping) behavior. This allows you to specify that
+the sub-workflow should be executed multiple times repeatedly.
+If the `repeat` property is defined, the `waitForCompletion` should be assumed have the value of `true`.
+If the workflow explicitly triggers [compensation](#Workflow-Compensation) and the SubFlow state
+was executed and defines its compensation state, it should be compensated once, no matter how many times
+its was executed as defined by the `repeat` property.
+After each execution of the SubFlow state, if `repeat` is defined, the SubFlow state data at the end of the
+one execution should become the state data of the next execution.
-#### Callback State
+For more information about the `repeat` property see the [Repeat Definition](#Repeat-Definition) section.
+
+Referenced sub-workflows must declare their own [function](#Function-Definition) and [event](#Event-Definition) definitions.
+
+#### Inject State
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| id | Unique state id | string | no |
| name | State name | string | yes |
| type | State type | string | yes |
-| [action](#Action-Definition) | Defines the action to be executed | object | yes |
-| eventRef | References an unique callback event name in the defined workflow [events](#Event-Definition) | string | yes |
-| [timeout](#eventstate-timeout) | Time period to wait from when action is executed until the callback event is received (ISO 8601 format). For example: "PT15M" (wait 15 minutes), or "P2DT3H4M" (wait 2 days, 3 hours and 4 minutes)| string | yes |
-| [eventDataFilter](#event-data-filter) | Callback event data filter definition | object | no |
-| [stateDataFilter](#state-data-filter) | State data filter definition | object | no |
+| data | JSON object which can be set as state's data input and can be manipulated via filter | object | yes |
+| [stateDataFilter](#state-data-filters) | State data filter | object | no |
+| [transition](#Transitions) | Next transition of the workflow after subflow has completed | object | yes (if end is set to false) |
| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no |
-| [transition](#Transitions) | Next transition of the workflow after callback event has been received | object | yes |
-| [end](#End-Definition) | Is this state an end state | object | no |
-| [compensatedBy](#Workflow-Compensation) | Uniaue name of a workflow state which is responsible for compensation of this state | String | no |
+| [compensatedBy](#Workflow-Compensation) | Unique name of a workflow state which is responsible for compensation of this state | String | no |
| [usedForCompensation](#Workflow-Compensation) | If true, this state is used to compensate another state. Default is "false" | boolean | no |
| [metadata](#Workflow-Metadata) | Metadata information| object | no |
+| [end](#End-Definition) | If this state and end state | object | no |
Click to view example definition
@@ -2960,20 +3281,13 @@ The results of each parallel action execution are stored as elements in the stat
```json
-{
- "name": "CheckCredit",
- "type": "callback",
- "action": {
- "functionRef": {
- "refName": "callCreditCheckMicroservice",
- "arguments": {
- "customer": "${ .customer }"
- }
- }
- },
- "eventRef": "CreditCheckCompletedEvent",
- "timeout": "PT15M",
- "transition": "EvaluateDecision"
+{
+ "name":"Hello",
+ "type":"inject",
+ "data": {
+ "result": "Hello"
+ },
+ "transition": "World"
}
```
@@ -2981,16 +3295,11 @@ The results of each parallel action execution are stored as elements in the stat
|
```yaml
-name: CheckCredit
-type: callback
-action:
- functionRef:
- refName: callCreditCheckMicroservice
- arguments:
- customer: "${ .customer }"
-eventRef: CreditCheckCompletedEvent
-timeout: PT15M
-transition: EvaluateDecision
+name: Hello
+type: inject
+data:
+ result: Hello
+transition: World
```
|
@@ -2999,40 +3308,77 @@ transition: EvaluateDecision
+
+ | JSON |
+ YAML |
+
+
+|
+
+ ```json
+ {
+ "name":"SimpleInjectState",
+ "type":"inject",
+ "data": {
+ "person": {
+ "fname": "John",
+ "lname": "Doe",
+ "address": "1234 SomeStreet",
+ "age": 40
+ }
+ },
+ "transition": "GreetPersonState"
+ }
+ ```
+
+ |
+
+
+```yaml
+ name: SimpleInjectState
+ type: inject
+ data:
+ person:
+ fname: John
+ lname: Doe
+ address: 1234 SomeStreet
+ age: 40
+ transition: GreetPersonState
+```
-The callback event payload is merged with the Callback state data and can be filtered via the "eventDataFilter" definition.
+ |
+
+
-The Callback state `timeout` property defines a time period from the action execution until the callback event should be received.
+The data output of the "SimpleInjectState" which then is passed as input to the transition state would be:
-If the defined callback event has not been received during this time period, the state should transition to the next state or end workflow execution if it is an end state.
+```json
+{
+ "person": {
+ "fname": "John",
+ "lname": "Doe",
+ "address": "1234 SomeStreet",
+ "age": 40
+ }
+}
-#### Repeat Definition
+```
-| Parameter | Description | Type | Required |
-| --- | --- | --- | --- |
-| [expression](#Workflow-Expressions) | Workflow expression evaluated against state data. SubFlow will repeat execution as long as this expression is true or until the max property count is reached | string | no |
-| checkBefore | If set to `true` (default value) the expression is evaluated before each repeat execution, if set to false the expression is evaluated after each repeat execution | boolean | no |
-| max | Sets the maximum amount of repeat executions | integer | no |
-| continueOnError | If set to `true` repeats executions in a case unhandled errors propagate from the sub-workflow to this state | boolean | no |
-| stopOnEvents | List referencing defined consumed workflow events. SubFlow will repeat execution until one of the defined events is consumed, or until the max property count is reached | array | no |
+If the inject state already receives a data input from the previous transition state, the inject data should be merged
+with its data input.
-Click to view example definition
-
+You can also use the filter property to filter the state data after data is injected. Let's say we have:
@@ -3043,71 +3389,116 @@ If the defined callback event has not been received during this time period, the
|
```json
-{
- "max": 10,
- "continueOnError": true
-}
+ {
+ "name":"SimpleInjectState",
+ "type":"inject",
+ "data": {
+ "people": [
+ {
+ "fname": "John",
+ "lname": "Doe",
+ "address": "1234 SomeStreet",
+ "age": 40
+ },
+ {
+ "fname": "Marry",
+ "lname": "Allice",
+ "address": "1234 SomeStreet",
+ "age": 25
+ },
+ {
+ "fname": "Kelly",
+ "lname": "Mill",
+ "address": "1234 SomeStreet",
+ "age": 30
+ }
+ ]
+ },
+ "stateDataFilter": {
+ "output": "${ {people: [.people[] | select(.age < 40)]} }"
+ },
+ "transition": "GreetPersonState"
+ }
```
|
```yaml
-max: 10
-continueOnError: true
+ name: SimpleInjectState
+ type: inject
+ data:
+ people:
+ - fname: John
+ lname: Doe
+ address: 1234 SomeStreet
+ age: 40
+ - fname: Marry
+ lname: Allice
+ address: 1234 SomeStreet
+ age: 25
+ - fname: Kelly
+ lname: Mill
+ address: 1234 SomeStreet
+ age: 30
+ stateDataFilter:
+ output: "${ {people: [.people[] | select(.age < 40)]} }"
+ transition: GreetPersonState
```
|
-Click to view example definition
@@ -3122,8 +3513,21 @@ If the start definition is of type `object`, it has the following structure:
```json
{
- "stateName": "MyStartingstate",
- "schedule": "2020-03-20T09:00:00Z/2020-03-20T15:00:00Z"
+ "name": "ProvisionOrdersState",
+ "type": "foreach",
+ "inputCollection": "${ .orders }",
+ "iterationParam": "singleorder",
+ "outputCollection": "${ .provisionresults }",
+ "actions": [
+ {
+ "functionRef": {
+ "refName": "provisionOrderFunction",
+ "arguments": {
+ "order": "${ .singleorder }"
+ }
+ }
+ }
+ ]
}
```
@@ -3131,8 +3535,16 @@ If the start definition is of type `object`, it has the following structure:
```yaml
-stateName: MyStartingstate
-schedule: 2020-03-20T09:00:00Z/2020-03-20T15:00:00Z
+name: ProvisionOrdersState
+type: foreach
+inputCollection: "${ .orders }"
+iterationParam: "singleorder"
+outputCollection: "${ .provisionresults }"
+actions:
+- functionRef:
+ refName: provisionOrderFunction
+ arguments:
+ order: "${ .singleorder }"
```
|
@@ -3141,66 +3553,58 @@ schedule: 2020-03-20T09:00:00Z/2020-03-20T15:00:00Z
Click to view example definition
-
+and our workflow is defined as:
@@ -3212,7 +3616,35 @@ it with its `object` type which has the following properties:
```json
{
- "cron": "0 0/15 * * * ?"
+ "id": "sendConfirmWorkflow",
+ "name": "SendConfirmationForCompletedOrders",
+ "version": "1.0",
+ "start": "SendConfirmState",
+ "functions": [
+ {
+ "name": "sendConfirmationFunction",
+ "operation": "file://confirmationapi.json#sendOrderConfirmation"
+ }
+ ],
+ "states": [
+ {
+ "name":"SendConfirmState",
+ "type":"foreach",
+ "inputCollection": "${ [.orders[] | select(.completed == true)] }",
+ "iterationParam": "completedorder",
+ "outputCollection": "${ .confirmationresults }",
+ "actions":[
+ {
+ "functionRef": {
+ "refName": "sendConfirmationFunction",
+ "arguments": {
+ "orderNumber": "${ .completedorder.orderNumber }",
+ "email": "${ .completedorder.email }"
+ }
+ }
+ }],
+ "end": true
+ }]
}
```
@@ -3220,53 +3652,82 @@ it with its `object` type which has the following properties:
|
```yaml
-cron: 0 0/15 * * * ?
+id: sendConfirmWorkflow
+name: SendConfirmationForCompletedOrders
+version: '1.0'
+start: SendConfirmState
+functions:
+- name: sendConfirmationFunction
+ operation: file://confirmationapi.json#sendOrderConfirmation
+states:
+- name: SendConfirmState
+ type: foreach
+ inputCollection: "${ [.orders[] | select(.completed == true)] }"
+ iterationParam: completedorder
+ outputCollection: "${ .confirmationresults }"
+ actions:
+ - functionRef:
+ refName: sendConfirmationFunction
+ arguments:
+ orderNumber: "${ .completedorder.orderNumber }"
+ email: "${ .completedorder.email }"
+ end: true
```
|
-Click to view example definition
@@ -3281,8 +3742,19 @@ it with its `object` type which has the following properties:
```json
{
- "expression": "0 15,30,45 * ? * *",
- "validUntil": "2021-11-05T08:15:30-05:00"
+ "name": "CheckCredit",
+ "type": "callback",
+ "action": {
+ "functionRef": {
+ "refName": "callCreditCheckMicroservice",
+ "arguments": {
+ "customer": "${ .customer }"
+ }
+ }
+ },
+ "eventRef": "CreditCheckCompletedEvent",
+ "timeout": "PT15M",
+ "transition": "EvaluateDecision"
}
```
@@ -3290,8 +3762,16 @@ it with its `object` type which has the following properties:
```yaml
-expression: 0 15,30,45 * ? * *
-validUntil: '2021-11-05T08:15:30-05:00'
+name: CheckCredit
+type: callback
+action:
+ functionRef:
+ refName: callCreditCheckMicroservice
+ arguments:
+ customer: "${ .customer }"
+eventRef: CreditCheckCompletedEvent
+timeout: PT15M
+transition: EvaluateDecision
```
|
@@ -3300,43 +3780,37 @@ validUntil: '2021-11-05T08:15:30-05:00'
Click to view example definition
@@ -3351,11 +3825,8 @@ If the end definition is of type `object`, it has the following structure:
```json
{
- "terminate": true,
- "produceEvents": [{
- "eventRef": "provisioningCompleteEvent",
- "data": "${ .provisionedOrders }"
- }]
+ "max": 10,
+ "continueOnError": true
}
```
@@ -3363,11 +3834,8 @@ If the end definition is of type `object`, it has the following structure:
```yaml
-terminate: true
-produceEvents:
-- eventRef: provisioningCompleteEvent
- data: "${ .provisionedOrders }"
-
+max: 10
+continueOnError: true
```
|
@@ -3376,32 +3844,51 @@ produceEvents:
Click to view example definition
@@ -3416,22 +3903,17 @@ is reached.
```json
{
- "eventRef": "provisioningCompleteEvent",
- "data": "${ .provisionedOrders }",
- "contextAttributes": [{
- "buyerId": "${ .buyerId }"
- }]
- }
+ "stateName": "MyStartingstate",
+ "schedule": "2020-03-20T09:00:00Z/2020-03-20T15:00:00Z"
+}
```
```yaml
-eventRef: provisioningCompleteEvent
-data: "${ .provisionedOrders }"
-contextAttributes:
-- buyerId: "${ .buyerId }"
+stateName: MyStartingstate
+schedule: 2020-03-20T09:00:00Z/2020-03-20T15:00:00Z
```
|
@@ -3440,127 +3922,65 @@ contextAttributes:
-
-
-
-#### Event Data
-
-[Event states](#Event-State) wait for arrival of defined CloudEvents, and when consumed perform a number of defined actions.
-CloudEvents can contain data which is needed to make further orchestration decisions. Data from consumed CloudEvents
-can be merged with the data of the Event state, so it can be used inside defined actions
-or be passed as data output to transition states.
-
-
-
-
-
-Similarly for Callback states, the callback event data is merged with the data of the Callback state.
-
-Merging of this data case be controlled via [data filters](#State-Data-Filtering).
-
-#### Action Data
-
-[Event](#Event-State), [Callback](#Callback-State), and [Operation](#Operation-State) states can execute [actions](#Action-Definition).
-Actions can invoke different services (functions). Functions can return results that may be needed to make
-further orchestration decisions. Function results can be merged with the state data.
-
-
-
-
-
-Merging of this data case be controlled via [data filters](#State-Data-Filtering).
-
-#### Information Passing Between States
-
-States in a workflow can receive data (data input) as well as produce a data result (data output). The states data input is
-typically the previous states data output.
-When a state completes its tasks, its data output is passed to the data input of the state it transitions to.
-
-There are two of rules to consider here:
-
-- If the state is the workflow starting state, its data input is the [workflow data input](#Workflow-data-input).
-- If the state is an end state ([`end`](#End-Definition) property is defined), its data output is the [workflow data output](#Workflow-data-output).
-
-
-
-
-
-#### State Data Filtering
-
-Data filters allow you to select and extract specific data that is useful and needed during workflow execution.
-Filters use [workflow expressions](#Workflow-Expressions) for extracting portions of state's data
-input and output, actions data and results, event data, as well as error data.
-
-There are several types of data filters:
-
-- [State Data Filter](#state-data-filter)
-- [Action Data Filter](#action-data-filter)
-- [Event Data Filter](#event-data-filter)
-
-All states can define state data filters. States which can consume events can define event data filters, and states
-that can perform actions can define action data filters for each of the actions they perform.
-
-#### State data filtering - State Data Filter
+If you need to define the `cron` or the `timezone` parameters in your `schedule` definition, you can define
+it with its `object` type which has the following properties:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
-| dataInputPath | Workflow expression to filter the states data input | string | no |
-| dataOutputPath | Workflow expression that filters the states data output | string | no |
+| interval | Time interval (must be repeating interval) described with ISO 8601 format. Declares when workflow instances will be automatically created. | string | yes if `cron` not defined |
+| [cron](#Cron-Definition) | Cron expression defining when workflow instances should be created (automatically) | object | yes if `interval` not defined |
+| timezone | Timezone name used to evaluate the interval & cron-expression. If the interval specifies a date-time w/ timezone then proper timezone conversion will be applied. (default: UTC). | string | no |
Click to view example definition
@@ -3575,8 +3995,7 @@ that can perform actions can define action data filters for each of the actions
```json
{
- "dataInputPath": "${ .orders }",
- "dataOutputPath": "${ .provisionedOrders }"
+ "cron": "0 0/15 * * * ?"
}
```
@@ -3584,8 +4003,7 @@ that can perform actions can define action data filters for each of the actions
```yaml
-dataInputPath: "${ .orders }"
-dataOutputPath: "${ .provisionedOrders }"
+cron: 0 0/15 * * * ?
```
|
@@ -3594,96 +4012,116 @@ dataOutputPath: "${ .provisionedOrders }"
Click to view example definition
+
+
+
+
+ | JSON |
+ YAML |
+
+
+|
```json
{
- "stateDataFilter": {
- "dataInputPath": "${ {fruits: .fruits} }"
- }
+ "expression": "0 15,30,45 * ? * *",
+ "validUntil": "2021-11-05T08:15:30-05:00"
}
```
-The state data output then would include only the fruits data:
+ |
+
-```json
-{
- "fruits": [ "apple", "orange", "pear"]
-}
+```yaml
+expression: 0 15,30,45 * ? * *
+validUntil: '2021-11-05T08:15:30-05:00'
```
-
-
-
+ |
+
+
-For our second example let's say that we are interested in only vegetable that are "veggie like".
-Here we have two ways of filtering our data, depending on if actions within our state need access to all vegetables, or
-only the ones that are "veggie like".
+
-
-
+#### End Definition
-The second way would be to directly filter only the "veggie like" vegetables with just the data input path:
+Can be either `boolean` or `object` type. If type boolean, must be set to `true`, for example:
-```json
-{
- "stateDataFilter": {
- "dataInputPath": "${ {vegetables: .vegetables[] | select(.veggieLike == true)} }"
- }
-}
+```json
+"end": true
```
+In this case it's assumed that the `terminate` property has its default value of `false`, and the `produceEvents` and
+`compensate` properties are not defined.
-#### State data filtering - Action Data Filter
+If the end definition is of type `object`, it has the following structure:
| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
-| dataInputPath | Workflow expression that filters states data that can be used by the state action | string | no |
-| dataResultsPath | Workflow expression that filters the actions data result, to be added to or merged with the states data | string | no |
+| terminate | If true, terminates workflow instance execution | boolean | no |
+| produceEvents | Array of [producedEvent](#ProducedEvent-Definition) definitions. Defines events that should be produced. | array | no |
+| [compensate](#Workflow-Compensation) | If set to `true`, triggers workflow compensation before workflow execution completes. Default is `false` | boolean | no |
Click to view example definition
@@ -3698,8 +4136,11 @@ The second way would be to directly filter only the "veggie like" vegetables wit
```json
{
- "dataInputPath": "${ .language }",
- "dataResultsPath": "${ .payload.greeting }"
+ "terminate": true,
+ "produceEvents": [{
+ "eventRef": "provisioningCompleteEvent",
+ "data": "${ .provisionedOrders }"
+ }]
}
```
@@ -3707,8 +4148,11 @@ The second way would be to directly filter only the "veggie like" vegetables wit
```yaml
-dataInputPath: "${ .language } "
-dataResultsPath: "${ .payload.greeting }"
+terminate: true
+produceEvents:
+- eventRef: provisioningCompleteEvent
+ data: "${ .provisionedOrders }"
+
```
|
@@ -3717,50 +4161,32 @@ dataResultsPath: "${ .payload.greeting }"
Click to view example definition
@@ -3775,15 +4201,22 @@ with the state data.
```json
{
- "dataOutputPath": "${ .data.results }"
-}
+ "eventRef": "provisioningCompleteEvent",
+ "data": "${ .provisionedOrders }",
+ "contextAttributes": [{
+ "buyerId": "${ .buyerId }"
+ }]
+ }
```
```yaml
-dataOutputPath: "${ .data.results }"
+eventRef: provisioningCompleteEvent
+data: "${ .provisionedOrders }"
+contextAttributes:
+- buyerId: "${ .buyerId }"
```
|
@@ -3792,213 +4225,46 @@ dataOutputPath: "${ .data.results }"
-
-
-
-#### State data filtering - Using multiple filters
-
-As [Event states](#Event-State) can take advantage of all defined data filters, it is probably the best way to
-show how we can combine them all to filter state data.
-
-Let's say we have a workflow which consumes events defining a customer arrival (to your store for example),
-and then lets us know how to greet this customer in different languages. We could model this workflow as follows:
-
-```json
-{
- "id": "GreetCustomersWorkflow",
- "name": "Greet Customers when they arrive",
- "version": "1.0",
- "start": "WaitForCustomerToArrive",
- "events": [{
- "name": "CustomerArrivesEvent",
- "type": "customer-arrival-type",
- "source": "customer-arrival-event-source"
- }],
- "functions": [{
- "name": "greetingFunction",
- "operation": "http://my.api.org/myapi.json#greeting"
- }],
- "states":[
- {
- "name": "WaitForCustomerToArrive",
- "type": "event",
- "onEvents": [{
- "eventRefs": ["CustomerArrivesEvent"],
- "eventDataFilter": {
- "dataInputPath": "${ .customer }"
- },
- "actions":[
- {
- "functionRef": {
- "refName": "greetingFunction",
- "arguments": {
- "greeting": "${ .languageGreetings.spanish } ",
- "customerName": "${ .customer.name } "
- }
- },
- "actionDataFilter": {
- "dataResultsPath": "${ .finalCustomerGreeting }"
- }
- }
- ]
- }],
- "stateDataFilter": {
- "dataInputPath": "${ .hello } ",
- "dataOutputPath": "${ .finalCustomerGreeting }"
- },
- "end": true
- }
- ]
-}
-```
-
-The example workflow contains an event state which consumes CloudEvents of type "customer-arrival-type", and then
-calls the "greetingFunction" function passing in the greeting in Spanish and the name of the customer to greet.
-
-The workflow data input when starting workflow execution is assumed to include greetings in different languages:
-
-```json
-{
- "hello": {
- "english": "Hello",
- "spanish": "Hola",
- "german": "Hallo",
- "russian": "Здравствуйте"
- },
- "goodbye": {
- "english": "Goodbye",
- "spanish": "Adiós",
- "german": "Auf Wiedersehen",
- "russian": "Прощай"
- }
-}
-```
-
-We also assume for this example that the CloudEvent that our event state is set to consume (has the "customer-arrival-type" type) include the data:
-
-```json
-{
- "data": {
- "customer": {
- "name": "John Michaels",
- "address": "111 Some Street, SomeCity, SomeCountry",
- "age": 40
- }
- }
-}
-```
-
-Here is a sample diagram showing our workflow, each numbered step on this diagram shows a certain defined point during
-workflow execution at which data filters are invoked and correspond to the numbered items below.
-
-
-
-
-
-**(1) Workflow execution starts**: Workflow data is passed to our "WaitForCustomerToArrive" event state as data input.
-Workflow transitions to its starting state, namely the "WaitForCustomerToArrive" event state.
-
-The event state **stateDataFilter** is invoked to filter this data input. Its "dataInputPath" is evaluated and filters
- only the "hello" greetings in different languages. At this point our event state data contains:
-
-```json
-{
- "hello": {
- "english": "Hello",
- "spanish": "Hola",
- "german": "Hallo",
- "russian": "Здравствуйте"
- }
-}
-```
-
-**(2) CloudEvent of type "customer-arrival-type" is consumed**: First the "eventDataFilter" is triggered. Its "dataInputPath"
-expression selects the "customer" object from the events data and places it into the state data.
-
-At this point our event state data contains:
-
-```json
-{
- "hello": {
- "english": "Hello",
- "spanish": "Hola",
- "german": "Hallo",
- "russian": "Здравствуйте"
- },
- "customer": {
- "name": "John Michaels",
- "address": "111 Some Street, SomeCity, SomeCountry",
- "age": 40
- }
-}
-```
-
-**(3) Event state performs its actions**:
-Before the first action is executed, its actionDataFilter is invoked. Its "dataInputPath" expression selects
-the entire state data as the data available to functions that should be executed. Its "dataResultsPath" expression
-specifies that results of all functions executed in this action should be placed back to the state data as part
-of a new "finalCustomerGreeting" object.
-
-The action then calls the "greetingFunction" function passing in as parameters the Spanish greeting and the name of the customer that arrived.
-
-We assume that for this example "greetingFunction" returns:
+Defines the event (CloudEvent format) to be produced when workflow execution completes or during a workflow [transitions](#Transitions).
+The `eventRef` property must match the name of
+one of the defined `produced` events in the [events](#Event-Definition) definition.
-```json
-{
- "finalCustomerGreeting": "Hola John Michaels!"
-}
-```
+The `data` property can have two types, object or string. If of string type, it is an expression that can select parts of state data
+to be used as the event payload. If of object type, you can define a custom object to be the event payload.
-which then becomes the result of the action.
+The `contextAttributes` property allows you to add one or more [extension context attributes](https://github.com/cloudevents/spec/blob/master/spec.md#extension-context-attributes)
+to the generated event.
-**(4) Event State Completes Workflow Execution**: The results of action executions as defined in the actionDataFilter are placed into the
-states data under the "finalCustomerGreeting" object. So at this point our event state data contains:
+Being able to produce events when workflow execution completes or during state transition
+allows for event-based orchestration communication.
+For example, completion of an orchestration workflow can notify other orchestration workflows to decide if they need to act upon
+the produced event, or notify monitoring services of the current state of workflow execution, etc.
+It can be used to create very dynamic orchestration scenarios.
-```json
-{
- "hello": {
- "english": "Hello",
- "spanish": "Hola",
- "german": "Hallo",
- "russian": "Здравствуйте"
- },
- "customer": {
- "name": "John Michaels",
- "address": "111 Some Street, SomeCity, SomeCountry",
- "age": 40
- },
- "finalCustomerGreeting": "Hola John Michaels!"
-}
-```
+#### Transitions
-Since our event state has performed all actions it is ready to either transition to the next state or end workflow execution if it is an end state.
-Before this happens though, the "stateDataFilter" is again invoked to filter this states data, specifically the "dataOutputPath" expression
-selects only the "finalCustomerGreeting" object to make it the data output of the state.
+Serverless workflow states can have one or more incoming and outgoing transitions (from/to other states).
+Each state can define a `transition` definition that is used to determine which
+state to transition to next.
-Because our event state is also an end state, its data output becomes the final [workflow data output](#Workflow-data-output). Namely:
+Implementers can choose to use the states `name` property
+for determining the transition; however, we realize that in most cases this is not an
+optimal solution that can lead to ambiguity. This is why each state also include an "id"
+property. Implementers can choose their own id generation strategy to populate the `id` property
+for each of the states and use it as the unique state identifier that is to be used as the "nextState" value.
-```json
-{
- "finalCustomerGreeting": "Hola John Michaels!"
-}
-```
+So the options for next state transitions are:
-Note that in case of multiple actions with each containing an "actionDataFilter", you must be careful for their results
-not to overwrite each other after actions complete and their results are added to the state data.
-Also note that in case of parallel execution of actions, the results of only those that complete before the state
-transitions to the next one or ends workflow execution (end state) can be considered to be added to the state data.
+- Use the state name property
+- Use the state id property
+- Use a combination of name and id properties
-#### Workflow data output
+Events can be produced during state transitions. The `produceEvents` property of the `transition` definitions allows you
+to reference one or more defined `produced` events in the workflow [events definitions](#Event-Definition).
+For each of the produced events you can select what parts of state data to be the event payload.
-Once a workflow instance reaches an end state (where the `end` property is defined) and the workflow finishes its execution
-the data output of that result state becomes the workflow data output. This output can be logged or indexed depending on the
-implementation details.
+Transitions can trigger compensation via their `compensate` property. See the [Workflow Compensation](#Workflow-Compensation)
+section for more information.
### Workflow Error Handling
@@ -4596,4 +4862,4 @@ You can find a list of other languages, technologies and specifications related
## License
Serverless Workflow specification operates under the
-[Apache License version 2.0](LICENSE).
+[Apache License version 2.0](LICENSE).
\ No newline at end of file
+
-