Skip to content

Commit

Permalink
[Fix #742] Ricardos comments
Browse files Browse the repository at this point in the history 
Signed-off-by: Francisco Javier Tirado Sarti <ftirados@redhat.com>
  • Loading branch information
@fjtirado
fjtirado committed Feb 22, 2024
1 parent 3c9316b commit 77c77b2
Showing 1 changed file with 40 additions and 51 deletions.
91 changes: 40 additions & 51 deletions specification.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -643,8 +643,8 @@ a workflow with a single event state and show how data filters can be combined.

```json
{
"id": "GreetCustomersWorkflow",
"name": "Greet Customers when they arrive",
"name": "GreetCustomersWorkflow",
"description": "Greet Customers when they arrive",
"version": "1.0.0",
"specVersion": "0.8",
"start": "WaitForCustomerToArrive",
Expand Down Expand Up @@ -1910,16 +1910,16 @@ we can use this expression in the workflow "version" parameter:

```json
{
"id": "MySampleWorkflow",
"name": "Sample Workflow",
"name": "MySampleWorkflow",
"description": "Sample Workflow",
"version": "${ .inputVersion }",
"specVersion": "0.8"
}
```

which would set the workflow version to "1.0.0".
Note that the workflow "id" property value is not allowed to use an expression. The workflow
definition "id" must be a constant value.
Note that the workflow "name" property value is not allowed to use an expression. The workflow
definition "name" must be a constant value.

### Workflow Definition Structure

Expand Down Expand Up @@ -1962,10 +1962,9 @@ definition "id" must be a constant value.

```json
{
"id": "sampleWorkflow",
"name": "sampleWorkflow",
"version": "1.0.0",
"specVersion": "0.8",
"name": "Sample Workflow",
"description": "Sample Workflow",
"start": "MyStartingState",
"states": [],
Expand All @@ -1980,10 +1979,9 @@ definition "id" must be a constant value.
<td valign="top">

```yaml
id: sampleWorkflow
name: sampleWorkflow
version: '1.0.0'
specVersion: '0.8'
name: Sample Workflow
description: Sample Workflow
start: MyStartingState
states: []
Expand All @@ -2006,18 +2004,13 @@ Following figure describes the main workflow definition blocks.
<img src="media/spec/workflowdefinitionblocks.png" height="300px" alt="Serverless Workflow Definitions Blocks"/>
</p>

The `id` property defines the unique, domain-specific workflow identifier, for example "orders", "payment", etc.

The `key` property defines the unique, domain-specific workflow identifier.
It can be used when the `id` property is auto-generated by a content-management system for example.
In these cases, you can specify the `key` property to be the domain-specific identifier of the workflow definition.
The `id` and `key` properties are mutually exclusive, meaning you cannot define both.
The required `name` property defines the unique workflow definition identifier, for example "orders", "payment", etc.

The `name` property is the workflow logical name.
The optional `key` property is an expression that evaluates to a domain related, unique running workflow instance identifier, for example "orders-1", "orders-2"...

The `description` property can be used to give further information about the workflow.
The `description` property might be used to give further information about the workflow.

The `version` property can be used to provide a specific workflow version. It must use the [semantic versioning](https://semver.org/) format.
The `version` property can be used to provide a specific workflow version. It must use the [semantic versioning](https://semver.org/) format.If not specified, "latest" is assumed.

The `annotations` property defines a list of helpful terms describing the workflows intended purpose, subject areas, or other important qualities,
for example "machine learning", "monitoring", "networking", etc
Expand Down Expand Up @@ -2168,10 +2161,9 @@ Here is an example of using external resource for function definitions:

```json
{
"id": "sampleWorkflow",
"name": "sampleWorkflow",
"version": "1.0.0",
"specVersion": "0.8",
"name": "Sample Workflow",
"description": "Sample Workflow",
"start": "MyStartingState",
"functions": "http://myhost:8080/functiondefs.json",
Expand Down Expand Up @@ -2205,10 +2197,9 @@ Here is an example of using external resource for event definitions:

```json
{
"id": "sampleWorkflow",
"name": "sampleWorkflow",
"version": "1.0.0",
"specVersion": "0.8",
"name": "Sample Workflow",
"description": "Sample Workflow",
"start": "MyStartingState",
"events": "http://myhost:8080/eventsdefs.json",
Expand Down Expand Up @@ -3149,7 +3140,6 @@ and our workflow is defined as:

```json
{
"id": "sendConfirmWorkflow",
"name": "SendConfirmationForCompletedOrders",
"version": "1.0.0",
"specVersion": "0.8",
Expand Down Expand Up @@ -3186,7 +3176,6 @@ and our workflow is defined as:
<td valign="top">

```yaml
id: sendConfirmWorkflow
name: SendConfirmationForCompletedOrders
version: '1.0.0'
specVersion: '0.8'
Expand Down Expand Up @@ -4031,9 +4020,9 @@ multiple other workflow definitions.
<img src="media/spec/subflowstateref.png" height="350px" alt="Referencing reusable workflow via SubFlow actions"/>
</p>

Reusable workflows are referenced by their `id` property via the SubFlow action `workflowId` parameter.
Reusable workflows are referenced by their `name` property via the SubFlow action `workflowId` parameter.

For the simple case, `subFlowRef` can be a string containing the `id` of the sub-workflow to invoke.
For the simple case, `subFlowRef` can be a string containing the `name` of the sub-workflow to invoke.
If you want to specify other parameters then a [subFlowRef](#SubFlowRef-Definition) should be provided instead.

Each referenced workflow receives the SubFlow actions data as workflow data input.
Expand Down Expand Up @@ -4200,19 +4189,19 @@ should not fail workflow execution.

`SubFlowRef` definition can have two types, namely `string` or `object`.

If `string` type, it defines the unique id of the sub-workflow to be invoked.
This short-hand definition can be used if sub-workflow lookup is done only by its `id`
If `string` type, it defines the unique name of the sub-workflow to be invoked.
This short-hand definition can be used if sub-workflow lookup is done only by its `name`
property and not its `version` property.

```json
"subFlowRef": "mySubFlowId"
"subFlowRef": "mySubFlowName"
```

If you need to define the `version` properties, you can use its `object` type:

| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| workflowId | Sub-workflow unique id | string | yes |
| workflowId | Sub-workflow unique name | string | yes |
| version | Sub-workflow version | string | no |
| invoke | Specifies if the subflow should be invoked `sync` or `async`. Default is `sync` | enum | no |
| onParentComplete | If `invoke` is `async`, specifies if subflow execution should `terminate` or `continue` when parent workflow completes. Default is `terminate` | enum | no |
Expand Down Expand Up @@ -4249,8 +4238,8 @@ version: '2.0.0'

</details>

The `workflowId` property define the unique ID of the sub-workflow to be invoked.
Usually, the workflow id should not be the same id of the workflow where the action is defined. Otherwise, it may occur undesired recurring calls to the same workflow.
The `workflowId` property define the unique name of the sub-workflow to be invoked.
The workflow id should not be the same name of the workflow where the action is defined. Otherwise, it may occur undesired recurring calls to the same workflow.

The `version` property defined the unique version of the sub-workflow to be invoked.
If this property is defined, runtimes should match both the `id` and the `version` properties
Expand Down Expand Up @@ -4707,7 +4696,7 @@ actions:

Each branch receives the same copy of the Parallel state's data input.

A branch can define actions that need to be executed. For the [`SubFlowRef`](#SubFlowRef-Definition) action, the workflow id should not be the same id of the workflow where the branch is defined. Otherwise, it may occur undesired recurring calls to the same workflow.
A branch can define actions that need to be executed. For the [`SubFlowRef`](#SubFlowRef-Definition) action, the workflow name should not be the same name of the workflow where the branch is defined. Otherwise, it may occur undesired recurring calls to the same workflow.


The `timeouts` property can be used to set branch specific timeout settings. Parallel state branches can set the
Expand Down Expand Up @@ -4993,7 +4982,7 @@ If the end definition is of type `object`, it has the following structure:
| 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 |
| [continueAs](#continuing-as-a-new-execution) | Defines that current workflow execution should stop, and execution should continue as a new workflow instance of the provided id | string or object | no |
| [continueAs](#continuing-as-a-new-execution) | Defines that current workflow execution should stop, and execution should continue as a new workflow instance of the provided name | string or object | no |

<details><summary><strong>Click to view example definition</strong></summary>
<p>
Expand Down Expand Up @@ -5058,7 +5047,7 @@ The [continueAs](#Continuing-as-a-new-Execution) property defines that the curre
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)
before the workflow execution is stopped, and continued as a new workflow instance with the defined workflow id.
before the workflow execution is stopped, and continued as a new workflow instance with the defined workflow name.

##### ProducedEvent Definition

Expand Down Expand Up @@ -5152,10 +5141,10 @@ Let's take a look at an example of additional properties:

```json
{
"id": "myworkflow",
"name": "myworkflow",
"version": "1.0.0",
"specVersion": "0.8",
"name": "My Test Workflow",
"description": "My Test Workflow",
"start": "My First State",
"loglevel": "Info",
"environment": "Production",
Expand All @@ -5170,10 +5159,10 @@ Note the same can be also specified using workflow metadata, which is the prefer

```json
{
"id": "myworkflow",
"name": "myworkflow",
"version": "1.0.0",
"specVersion": "0.8",
"name": "Py Test Workflow",
"description": "Py Test Workflow",
"start": "My First State",
"metadata": {
"loglevel": "Info",
Expand Down Expand Up @@ -5599,7 +5588,7 @@ To give an example, let's say that in our workflow definition we define the time

```json
{
"id": "testWorkflow",
"name": "testWorkflow",
...
"timeouts": {
...
Expand Down Expand Up @@ -6109,23 +6098,23 @@ likely to be forced to stop before reaching its completion. This can result in u
mission-critical workflows.

For those cases, the Serverless Workflow DSL provides a way to explicitly define stopping the current workflow
instance execution, and starting a new one (for the same workflow id or a different one).
instance execution, and starting a new one (for the same workflow name or a different one).
This can be done via the [end definitions](#end-definition) `continueAs` property.

The end definitions `continueAs` can be either of type `string` or `object`.
If string type, it contains the unique workflow id of the workflow that the execution should continue as, for example:
If string type, it contains the unique workflow name of the workflow that the execution should continue as, for example:


```json
{
"end": {
"continueAs": "myworkflowid"
"continueAs": "myworkflowname"
}
}
```

Defining this should stop the current workflow execution, and continue execution as a new workflow instance of the
workflow which defines the workflow id of "myworkflowid". The state data where this is define should
workflow which defines the workflow name of "myworkflowbane". The state data where this is define should
become the workflow data input of the workflow that is continuing the current workflow execution.

Note that any defined `produceEvents` and `compensate` definitions should be honored before `continueAs` is applied.
Expand All @@ -6134,7 +6123,7 @@ If `object` type, the `continueAs` property has the following properties:

| Parameter | Description | Type | Required |
| --- | --- | --- | --- |
| workflowId | Unique id of the workflow to continue execution as. | string | yes |
| workflowId | Unique name of the workflow to continue execution as. | string | yes |
| version | Version of the workflow to continue execution as. | string | no |
| data | If string type, a workflow expression which selects parts of the states data output to become the workflow data input of continued execution. If object type, a custom object to become the workflow data input of the continued execution. | string or object | no |
| [`workflowExecTimeout`](#Workflow-Timeouts) | Workflow execution timeout to be used by the workflow continuing execution. Overwrites any specific settings set by that workflow. | string or object | no |
Expand All @@ -6149,7 +6138,7 @@ in workflow states [Action](#Action-Definition) definitions.

Just like "parent" workflows, sub-workflow can also be long-running, and can run into the same type of runtime/serverless platform
limitations as previously discussed. As such they can also use `continueAs` to stop their current execution and continue it as
a new one of the same or different workflow id.
a new one of the same or different workflow name.

Note that when a sub-workflow is invoked it can produce a result that is then merged into the parent workflow state data.
This may bring up a question as to what happens when a sub-workflow calls `continueAs` in terms of what is returned as
Expand Down Expand Up @@ -6315,8 +6304,8 @@ Here is an example of metadata attached to the core workflow definition:

```json
{
"id": "processSalesOrders",
"name": "Process Sales Orders",
"name": "processSalesOrders",
"description": "Process Sales Orders",
"version": "1.0.0",
"specVersion": "0.8",
"start": "MyStartingState",
Expand Down Expand Up @@ -6351,8 +6340,8 @@ Implementations may use this keyword to give access to any relevant information
```json
{
"id": "processSalesOrders",
"name": "Process Sales Orders",
"name": "processSalesOrders",
"description": "Process Sales Orders",
"version": "1.0.0",
"specVersion": "0.8",
"start": "my-starting-state",
Expand Down

0 comments on commit 77c77b2

Please sign in to comment.