Adding ContinueAs Example (#507)

* Adding ContinueAs Example

Signed-off-by: Tihomir Surdilovic <[email protected]>

* formatting

Signed-off-by: Tihomir Surdilovic <[email protected]>

* update to roadmap

Signed-off-by: Tihomir Surdilovic <[email protected]>

* Update examples/README.md

Co-authored-by: Ricardo Zanini <[email protected]>

* Update examples/README.md

Co-authored-by: Ricardo Zanini <[email protected]>

* Update specification.md

Co-authored-by: Ricardo Zanini <[email protected]>

Co-authored-by: Ricardo Zanini <[email protected]>

Author: tsurdilo

examples/README.md

@@ -28,6 +28,8 @@ Provides Serverless Workflow language examples
 - [Book Lending Workflow](#Book-Lending)
 - [Filling a glass of water (Expression functions)](#Filling-a-glass-of-water)
 - [Online Food Ordering](#Online-Food-Ordering)
+- [Online Food Ordering](#Online-Food-Ordering)
+- [Continuing as a new Execution](#Continuing-as-a-new-Execution)
 
 ### Hello World Example
 
@@ -4234,3 +4236,163 @@ For the example order event, the workflow output for a successful completion wou
   ]
 }
 ```
+
+### Continuing as a new Execution
+
+#### Description
+
+Some runtime implementations on which we run our workflows can have different quotas, such as maximum execution durations, maximum consumed events, etc. We can use the Serverless workflow "continueAs" functionality that can be used to stop the current workflow execution and start another one (of the same or a different type). This is very useful in cases where we have to ensure we don't reach the imposed quotas of single workflow execution.
+
+This example assumes that the runtime we are using has a quota set to a maximum of one thousand consumed events per single workflow execution. 
+Our sample workflow consumes a single customer event at a time and invokes the `emailCustomer` function. 
+Note that we do not set a workflow `workflowExecTimeout`, so we intend to have a long-running workflow. However, because of the runtime restriction, in this case, we would run into the event consume limit, and our workflow would have to terminate. We can fix this problem by using [`continueAs`](../specification.md#Continuing-as-a-new-Execution), which will allow us to make sure that we reach the given limit and then continue our workflow execution as a new run.
+
+We assume that our workflow input has the runtime-imposed quota:
+
+```json
+{
+  "quota": {
+   "maxConsumedEvents": 1000
+  }
+}
+```
+
+#### Workflow Diagram
+
+<p align="center">
+<img src="../media/examples/example-continueas.png" height="400px" alt="ContinueAs Example"/>
+</p>
+
+#### Workflow Definition
+
+<table>
+<tr>
+    <th>JSON</th>
+    <th>YAML</th>
+</tr>
+<tr>
+<td valign="top">
+
+```json
+{
+ "id":"notifycustomerworkflow",
+ "name":"Notify Customer",
+ "version":"1.0",
+ "specVersion":"0.7",
+ "start":"WaitForCustomerEvent",
+ "states":[
+  {
+   "name":"WaitForCustomerEvent",
+   "type":"event",
+   "onEvents":[
+    {
+     "eventRefs":[
+      "CustomerEvent"
+     ],
+     "eventDataFilter":{
+      "data":"${ .customerId }",
+      "toStateData":"${ .eventCustomerId }"
+     },
+     "actions":[
+      {
+       "functionRef":{
+        "refName":"NotifyCustomerFunction",
+        "arguments":{
+         "customerId":"${ .eventCustomerId }"
+        }
+       }
+      }
+     ]
+    }
+   ],
+   "stateDataFilter":{
+    "output":"${ .count = .count + 1 }"
+   },
+   "transition":"CheckEventQuota"
+  },
+  {
+   "name":"CheckEventQuota",
+   "type":"switch",
+   "dataConditions":[
+    {
+     "condition":"${ try(.customerCount) != null and .customerCount > .quota.maxConsumedEvents }",
+     "end":{
+      "continueAs": {
+       "workflowId": "notifycustomerworkflow",
+       "version": "1.0",
+       "data": "${ del(.customerCount) }"
+      }
+     }
+    }
+   ],
+   "defaultCondition":{
+    "transition":"WaitForCustomerEvent"
+   }
+  }
+ ],
+ "events":[
+  {
+   "name":"CustomerEvent",
+   "type":"org.events.customerEvent",
+   "source":"customerSource"
+  }
+ ],
+ "functions":[
+  {
+   "name":"NotifyCustomerFunction",
+   "operation":"http://myapis.org/customerapis.json#notifyCustomer"
+  }
+ ]
+}
+```
+
+</td>
+<td valign="top">
+
+```yaml
+id: notifycustomerworkflow
+name: Notify Customer
+version: '1.0'
+specVersion: '0.7'
+start: WaitForCustomerEvent
+states:
+ - name: WaitForCustomerEvent
+   type: event
+   onEvents:
+    - eventRefs:
+       - CustomerEvent
+      eventDataFilter:
+       data: "${ .customerId }"
+       toStateData: "${ .eventCustomerId }"
+      actions:
+       - functionRef:
+          refName: NotifyCustomerFunction
+          arguments:
+           customerId: "${ .eventCustomerId }"
+   stateDataFilter:
+    output: "${ .count = .count + 1 }"
+   transition: CheckEventQuota
+ - name: CheckEventQuota
+   type: switch
+   dataConditions:
+    - condition: "${ try(.customerCount) != null and .customerCount > .quota.maxConsumedEvents
+      }"
+      end:
+       continueAs:
+        workflowId: notifycustomerworkflow
+        version: '1.0'
+        data: "${ del(.customerCount) }"
+   defaultCondition:
+    transition: WaitForCustomerEvent
+events:
+ - name: CustomerEvent
+   type: org.events.customerEvent
+   source: customerSource
+functions:
+ - name: NotifyCustomerFunction
+   operation: http://myapis.org/customerapis.json#notifyCustomer
+```
+
+</td>
+</tr>
+</table>

media/examples/example-continueas.png

@@ -28,6 +28,7 @@ _Status description:_
 | ✔️| ForEach state "iterationParam" no longer a required property | [spec doc](https://github.com/serverlessworkflow/specification/blob/main/specification.md)  |
 | ✔️| Added "useData" for eventDataFilter, and "useResults" for actionDataFilter | [spec doc](https://github.com/serverlessworkflow/specification/blob/main/specification.md)  |
 | ✔️| Added "resultEventTimeout" for action eventref | [spec doc](https://github.com/serverlessworkflow/specification/blob/main/specification.md)  |
+| ✔️| Added example for "continueAs" | [examples doc](https://github.com/serverlessworkflow/specification/blob/main/examples/README.md)  |
 | ✏️️| Support for async action invocation |   |
 | ✏️️| Add "completedBy" functionality |   |
 | ✏️️| Define workflow context |   |

roadmap/README.md

@@ -2278,7 +2278,7 @@ the state should transition to the next state or can end the workflow execution
 
 The `timeouts` property can be used to define state specific timeout settings. Event states can define the
 `stateExecTimeout`, `actionExecTimeout`, and `eventTimeout` properties.
-For more information about Event state specific event timeout settings reference [this section](#Event Timeout Definition).
+For more information about Event state specific event timeout settings reference [this section](#Event-Timeout-Definition).
 For more information about workflow timeouts reference the [Workflow Timeouts](#Workflow-Timeouts) section.
 
 ##### Operation State
@@ -4769,7 +4769,7 @@ is reached.
 The [compensate](#Workflow-Compensation) property defines that workflow compensation should be performed before the workflow 
 execution is completed.
 
-The [continueAs](#Continuing as a new Execution) property defines that the current workflow instance should stop its execution,
+The [continueAs](#Continuing-as-a-new-Execution) property defines that the current workflow instance should stop its execution,
 and worklow execution should continue as a new instance of a new workflow.
 When defined, it should be assumed that `terminate` is `true`. If `continueAs` is defined, and `terminate` is explicitly
 set to false, runtimes should report this to users. Producing events, and compensation should still be performed (if defined)
@@ -5786,6 +5786,10 @@ End definitions can trigger compensations by specifying the `compensate` propert
 This means that before workflow finishes its execution workflow compensation must be performed. Note that
 in case when the end definition has its `produceEvents` property set, compensation must be performed before
 producing the specified events and ending workflow execution.
+In the case the end definition has a `continueAs` property defined, compensation must be performed before 
+workflow execution continues as a new workflow invocation.
+In the case where the end definition has both `produceEvents`, and `continueAs` compensation is performed first, 
+then the event should be produced, and then the workflow should continue its execution as a new workflow invocation.
 
 #### Compensation Execution Details