From cfd3aaa3a099bb8ed571834b94457345b0736c93 Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Fri, 3 Jun 2022 12:10:20 -0300 Subject: [PATCH 01/14] Fixed links Signed-off-by: Helber Belmiro --- specification.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/specification.md b/specification.md index 159ef389..834f682b 100644 --- a/specification.md +++ b/specification.md @@ -3698,18 +3698,18 @@ This is visualized in the diagram below: ##### Action Definition -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| name | Unique Action name | string | no | -| [functionRef](#FunctionRef-Definition) | References a reusable function definition | object | yes if `eventRef` & `subFlowRef` are not defined | -| [eventRef](#EventRef-Definition) | References a `produce` and `consume` reusable event definitions | object | yes if `functionRef` & `subFlowRef` are not defined | -| [subFlowRef](#SubFlowRef-Definition) | References a workflow to be invoked | object or string | yes if `eventRef` & `functionRef` are not defined | -| [retryRef](#retry-definition) | References a defined workflow retry definition. If not defined uses the default runtime retry definition | string | no | -| nonRetryableErrors | List of references to defined [workflow errors](#Defining Errors) for which the action should not be retried. Used only when `autoRetries` is set to `true` | array | no | -| retryableErrors | List of references to defined [workflow errors](#Defining Errors) for which the action should be retried. Used only when `autoRetries` is set to `false` | array | no | -| [actionDataFilter](#Action-data-filters) | Action data filter definition | object | no | -| sleep | Defines time periods workflow execution should sleep before / after function execution | object | no | -| [condition](#Workflow-Expressions) | Expression, if defined, must evaluate to true for this action to be performed. If false, action is disregarded | boolean | no | +| Parameter | Description | Type | Required | +|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------| +| name | Unique Action name | string | no | +| [functionRef](#FunctionRef-Definition) | References a reusable function definition | object | yes if `eventRef` & `subFlowRef` are not defined | +| [eventRef](#EventRef-Definition) | References a `produce` and `consume` reusable event definitions | object | yes if `functionRef` & `subFlowRef` are not defined | +| [subFlowRef](#SubFlowRef-Definition) | References a workflow to be invoked | object or string | yes if `eventRef` & `functionRef` are not defined | +| [retryRef](#retry-definition) | References a defined workflow retry definition. If not defined uses the default runtime retry definition | string | no | +| nonRetryableErrors | List of references to defined [workflow errors](#Defining-Errors) for which the action should not be retried. Used only when `autoRetries` is set to `true` | array | no | +| retryableErrors | List of references to defined [workflow errors](#Defining-Errors) for which the action should be retried. Used only when `autoRetries` is set to `false` | array | no | +| [actionDataFilter](#Action-data-filters) | Action data filter definition | object | no | +| sleep | Defines time periods workflow execution should sleep before / after function execution | object | no | +| [condition](#Workflow-Expressions) | Expression, if defined, must evaluate to true for this action to be performed. If false, action is disregarded | boolean | no |
Click to view example definition

From 2d7405603fd2e3a637a45c8f43a0d300cbb9010c Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Fri, 3 Jun 2022 12:14:39 -0300 Subject: [PATCH 02/14] Fixed `invoke` parameter in EventRef Definition Signed-off-by: Helber Belmiro --- specification.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification.md b/specification.md index 834f682b..96772afc 100644 --- a/specification.md +++ b/specification.md @@ -3898,14 +3898,14 @@ onErrors definition. Note that errors raised during functions that are invoked a Allows defining invocation of a function via event. -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| [produceEventRef](#Event-Definition) | Reference to the unique name of a `produced` event definition | string | yes | -| [consumeEventRef](#Event-Definition) | Reference to the unique name of a `consumed` event definition | string | no | -| consumeEventTimeout | Maximum amount of time (ISO 8601 format) to wait for the consume event. If not defined it be set to the [actionExecutionTimeout](#Workflow-Timeout-Definition) | string | no | -| data | If string type, an expression which selects parts of the states data output to become the data (payload) of the event referenced by `produceEventRef`. If object type, a custom object to become the data (payload) of the event referenced by `produceEventRef`. | string or object | no | -| contextAttributes | Add additional event extension context attributes to the trigger/produced event | object | no | -| invoke | Specifies if the function should be invoked sync or async. Default is sync | string | no | +| Parameter | Description | Type | Required | +|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| +| [produceEventRef](#Event-Definition) | Reference to the unique name of a `produced` event definition | string | yes | +| [consumeEventRef](#Event-Definition) | Reference to the unique name of a `consumed` event definition | string | no | +| consumeEventTimeout | Maximum amount of time (ISO 8601 format) to wait for the consume event. If not defined it be set to the [actionExecutionTimeout](#Workflow-Timeout-Definition) | string | no | +| data | If string type, an expression which selects parts of the states data output to become the data (payload) of the event referenced by `produceEventRef`. If object type, a custom object to become the data (payload) of the event referenced by `produceEventRef`. | string or object | no | +| contextAttributes | Add additional event extension context attributes to the trigger/produced event | object | no | +| invoke | Specifies if the function should be invoked `sync` or `async`. Default is `sync` | enum | no |

Click to view example definition

From 2cfb85a823edf9fb3fe5d2cdc89a261179bc877b Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Fri, 3 Jun 2022 12:21:13 -0300 Subject: [PATCH 03/14] Fixed `onParentComplete` parameter in SubFlowRef Definition Signed-off-by: Helber Belmiro --- specification.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification.md b/specification.md index 96772afc..339f6cc0 100644 --- a/specification.md +++ b/specification.md @@ -3980,12 +3980,12 @@ property and not its `version` property. 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 | -| version | Sub-workflow version | string | no | -| invoke | Specifies if the subflow should be invoked sync or async. Default is sync | string | no | -| onParentComplete | If invoke is 'async', specifies how subflow execution should behave when parent workflow completes. Default is 'terminate' | string | no | +| Parameter | Description | Type | Required | +|------------------|------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------| +| workflowId | Sub-workflow unique id | 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 |

Click to view example definition

From 4f1619acda9450c32cf4ac9b75ffd3c7d03884cf Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Fri, 3 Jun 2022 13:47:14 -0300 Subject: [PATCH 04/14] Changed fields that expect "sequential" or "parallel" to enum Signed-off-by: Helber Belmiro --- specification.md | 76 ++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/specification.md b/specification.md index 339f6cc0..92cab94d 100644 --- a/specification.md +++ b/specification.md @@ -2275,20 +2275,20 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that ##### Operation State -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| name | Unique State name | string | yes | -| type | State type | string | yes | -| actionMode | Should actions be performed sequentially or in parallel | string | no | -| [actions](#Action-Definition) | Actions to be performed | array | yes | -| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | -| [stateDataFilter](#State-data-filters) | State data filter | object | no | -| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | -| [transition](#Transitions) | Next transition of the workflow after all the actions have been performed | object | yes (if end is not defined) | -| [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) | Is this state an end state | object | no | +| Parameter | Description | Type | Required | +|-----------------------------------------------|-------------------------------------------------------------------------------------|---------|-----------------------------| +| name | Unique State name | string | yes | +| type | State type | string | yes | +| actionMode | Should actions be performed sequentially or in parallel | enum | no | +| [actions](#Action-Definition) | Actions to be performed | array | yes | +| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | +| [stateDataFilter](#State-data-filters) | State data filter | object | no | +| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | +| [transition](#Transitions) | Next transition of the workflow after all the actions have been performed | object | yes (if end is not defined) | +| [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) | Is this state an end state | object | no |

Click to view example definition

@@ -2843,24 +2843,24 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that ##### ForEach State -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| name | Unique State name | string | yes | -| type | State type | string | yes | -| inputCollection | Workflow expression selecting an array element of the states data | string | yes | -| outputCollection | Workflow expression specifying an array element of the states data to add the results of each iteration | string | no | -| iterationParam | Name of the iteration parameter that can be referenced in actions/workflow. For each parallel iteration, this param should contain an unique element of the inputCollection array | string | no | -| batchSize | Specifies how many iterations may run in parallel at the same time. Used if `mode` property is set to `parallel` (default). If not specified, its value should be the size of the `inputCollection` | string or number | no | -| mode | Specifies how iterations are to be performed (sequentially or in parallel). Default is `parallel` | string | no | -| [actions](#Action-Definition) | Actions to be executed for each of the elements of inputCollection | array | yes | -| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | -| [stateDataFilter](#State-data-filters) | State data filter definition | object | no | -| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | -| [transition](#Transitions) | Next transition of the workflow after state has completed | object | yes if "end" is not defined | -| [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) | Is this state an end state | object | yes if "transition" is not defined | +| Parameter | Description | Type | Required | +|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|------------------------------------| +| name | Unique State name | string | yes | +| type | State type | string | yes | +| inputCollection | Workflow expression selecting an array element of the states data | string | yes | +| outputCollection | Workflow expression specifying an array element of the states data to add the results of each iteration | string | no | +| iterationParam | Name of the iteration parameter that can be referenced in actions/workflow. For each parallel iteration, this param should contain an unique element of the inputCollection array | string | no | +| batchSize | Specifies how many iterations may run in parallel at the same time. Used if `mode` property is set to `parallel` (default). If not specified, its value should be the size of the `inputCollection` | string or number | no | +| mode | Specifies how iterations are to be performed (sequentially or in parallel). Default is `parallel` | enum | no | +| [actions](#Action-Definition) | Actions to be executed for each of the elements of inputCollection | array | yes | +| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | +| [stateDataFilter](#State-data-filters) | State data filter definition | object | no | +| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | +| [transition](#Transitions) | Next transition of the workflow after state has completed | object | yes if "end" is not defined | +| [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) | Is this state an end state | object | yes if "transition" is not defined |

Click to view example definition

@@ -3596,12 +3596,12 @@ The `contextAttributeValue` property defines the value of the defined CloudEvent ##### 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 or in 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 | +| 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 or in parallel). Default is `sequential` | enum | 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

From bd0978c8685a27c601f906219efab5e233cc5278 Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Tue, 7 Jun 2022 14:20:35 -0300 Subject: [PATCH 05/14] Fixed functionref.invoke Signed-off-by: Helber Belmiro --- specification.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification.md b/specification.md index 92cab94d..43315ce6 100644 --- a/specification.md +++ b/specification.md @@ -3825,12 +3825,12 @@ Note that if used with `string` type, the invocation of the function is synchron If you need to define parameters in your `functionRef` definition, you can define it with its `object` type which has the following properties: -| Parameter | Description | Type | Required | -| --- | --- | --- | --- | -| refName | Name of the referenced [function](#Function-Definition) | string | yes | -| arguments | Arguments (inputs) to be passed to the referenced function | object | yes if function type is `graphql`, otherwise no | +| Parameter | Description | Type | Required | +|--------------|----------------------------------------------------------------------------------------------------------------------------------------------|--------|-------------------------------------------------| +| refName | Name of the referenced [function](#Function-Definition) | string | yes | +| arguments | Arguments (inputs) to be passed to the referenced function | object | yes if function type is `graphql`, otherwise no | | selectionSet | Used if function type is `graphql`. String containing a valid GraphQL [selection set](https://spec.graphql.org/June2018/#sec-Selection-Sets) | string | yes if function type is `graphql`, otherwise no | -| invoke | Specifies if the function should be invoked sync or async. Default is sync | string | no | +| invoke | Specifies if the function should be invoked `sync` or `async`. Default is `sync` | enum | no |

Click to view example definition

From c89135e07704c8b4f508620d0139fdc13612394f Mon Sep 17 00:00:00 2001 From: Helber Belmiro Date: Mon, 20 Jun 2022 15:54:08 -0300 Subject: [PATCH 06/14] Reverted table formatting Signed-off-by: Helber Belmiro --- specification.md | 138 +++++++++++++++++++++++------------------------ 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/specification.md b/specification.md index 43315ce6..189fd295 100644 --- a/specification.md +++ b/specification.md @@ -2275,20 +2275,20 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that ##### Operation State -| Parameter | Description | Type | Required | -|-----------------------------------------------|-------------------------------------------------------------------------------------|---------|-----------------------------| -| name | Unique State name | string | yes | -| type | State type | string | yes | -| actionMode | Should actions be performed sequentially or in parallel | enum | no | -| [actions](#Action-Definition) | Actions to be performed | array | yes | -| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | -| [stateDataFilter](#State-data-filters) | State data filter | object | no | -| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | -| [transition](#Transitions) | Next transition of the workflow after all the actions have been performed | object | yes (if end is not defined) | -| [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) | Is this state an end state | object | no | +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| name | Unique State name | string | yes | +| type | State type | string | yes | +| actionMode | Should actions be performed sequentially or in parallel | enum | no | +| [actions](#Action-Definition) | Actions to be performed | array | yes | +| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | +| [stateDataFilter](#State-data-filters) | State data filter | object | no | +| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | +| [transition](#Transitions) | Next transition of the workflow after all the actions have been performed | object | yes (if end is not defined) | +| [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) | Is this state an end state | object | no |

Click to view example definition

@@ -2843,24 +2843,24 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that ##### ForEach State -| Parameter | Description | Type | Required | -|-----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|------------------------------------| -| name | Unique State name | string | yes | -| type | State type | string | yes | -| inputCollection | Workflow expression selecting an array element of the states data | string | yes | -| outputCollection | Workflow expression specifying an array element of the states data to add the results of each iteration | string | no | -| iterationParam | Name of the iteration parameter that can be referenced in actions/workflow. For each parallel iteration, this param should contain an unique element of the inputCollection array | string | no | -| batchSize | Specifies how many iterations may run in parallel at the same time. Used if `mode` property is set to `parallel` (default). If not specified, its value should be the size of the `inputCollection` | string or number | no | -| mode | Specifies how iterations are to be performed (sequentially or in parallel). Default is `parallel` | enum | no | -| [actions](#Action-Definition) | Actions to be executed for each of the elements of inputCollection | array | yes | -| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | -| [stateDataFilter](#State-data-filters) | State data filter definition | object | no | -| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | -| [transition](#Transitions) | Next transition of the workflow after state has completed | object | yes if "end" is not defined | -| [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) | Is this state an end state | object | yes if "transition" is not defined | +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| name | Unique State name | string | yes | +| type | State type | string | yes | +| inputCollection | Workflow expression selecting an array element of the states data | string | yes | +| outputCollection | Workflow expression specifying an array element of the states data to add the results of each iteration | string | no | +| iterationParam | Name of the iteration parameter that can be referenced in actions/workflow. For each parallel iteration, this param should contain an unique element of the inputCollection array | string | no | +| batchSize | Specifies how many iterations may run in parallel at the same time. Used if `mode` property is set to `parallel` (default). If not specified, its value should be the size of the `inputCollection` | string or number | no | +| mode | Specifies how iterations are to be performed (sequentially or in parallel). Default is `parallel` | enum | no | +| [actions](#Action-Definition) | Actions to be executed for each of the elements of inputCollection | array | yes | +| [timeouts](#Workflow-Timeouts) | State specific timeout settings | object | no | +| [stateDataFilter](#State-data-filters) | State data filter definition | object | no | +| [onErrors](#Error-Definition) | States error handling and retries definitions | array | no | +| [transition](#Transitions) | Next transition of the workflow after state has completed | object | yes if "end" is not defined | +| [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) | Is this state an end state | object | yes if "transition" is not defined |

Click to view example definition

@@ -3596,12 +3596,12 @@ The `contextAttributeValue` property defines the value of the defined CloudEvent ##### 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 or in parallel). Default is `sequential` | enum | no | -| [actions](#Action-Definition) | Actions to be performed | array | no | -| [eventDataFilter](#Event-data-filters) | Event data filter definition | object | no | +| 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 or in parallel). Default is `sequential` | enum | 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

@@ -3698,18 +3698,18 @@ This is visualized in the diagram below: ##### Action Definition -| Parameter | Description | Type | Required | -|------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------| -| name | Unique Action name | string | no | -| [functionRef](#FunctionRef-Definition) | References a reusable function definition | object | yes if `eventRef` & `subFlowRef` are not defined | -| [eventRef](#EventRef-Definition) | References a `produce` and `consume` reusable event definitions | object | yes if `functionRef` & `subFlowRef` are not defined | -| [subFlowRef](#SubFlowRef-Definition) | References a workflow to be invoked | object or string | yes if `eventRef` & `functionRef` are not defined | -| [retryRef](#retry-definition) | References a defined workflow retry definition. If not defined uses the default runtime retry definition | string | no | -| nonRetryableErrors | List of references to defined [workflow errors](#Defining-Errors) for which the action should not be retried. Used only when `autoRetries` is set to `true` | array | no | -| retryableErrors | List of references to defined [workflow errors](#Defining-Errors) for which the action should be retried. Used only when `autoRetries` is set to `false` | array | no | -| [actionDataFilter](#Action-data-filters) | Action data filter definition | object | no | -| sleep | Defines time periods workflow execution should sleep before / after function execution | object | no | -| [condition](#Workflow-Expressions) | Expression, if defined, must evaluate to true for this action to be performed. If false, action is disregarded | boolean | no | +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| name | Unique Action name | string | no | +| [functionRef](#FunctionRef-Definition) | References a reusable function definition | object | yes if `eventRef` & `subFlowRef` are not defined | +| [eventRef](#EventRef-Definition) | References a `produce` and `consume` reusable event definitions | object | yes if `functionRef` & `subFlowRef` are not defined | +| [subFlowRef](#SubFlowRef-Definition) | References a workflow to be invoked | object or string | yes if `eventRef` & `functionRef` are not defined | +| [retryRef](#retry-definition) | References a defined workflow retry definition. If not defined uses the default runtime retry definition | string | no | +| nonRetryableErrors | List of references to defined [workflow errors](#Defining-Errors) for which the action should not be retried. Used only when `autoRetries` is set to `true` | array | no | +| retryableErrors | List of references to defined [workflow errors](#Defining-Errors) for which the action should be retried. Used only when `autoRetries` is set to `false` | array | no | +| [actionDataFilter](#Action-data-filters) | Action data filter definition | object | no | +| sleep | Defines time periods workflow execution should sleep before / after function execution | object | no | +| [condition](#Workflow-Expressions) | Expression, if defined, must evaluate to true for this action to be performed. If false, action is disregarded | boolean | no |

Click to view example definition

@@ -3825,12 +3825,12 @@ Note that if used with `string` type, the invocation of the function is synchron If you need to define parameters in your `functionRef` definition, you can define it with its `object` type which has the following properties: -| Parameter | Description | Type | Required | -|--------------|----------------------------------------------------------------------------------------------------------------------------------------------|--------|-------------------------------------------------| -| refName | Name of the referenced [function](#Function-Definition) | string | yes | -| arguments | Arguments (inputs) to be passed to the referenced function | object | yes if function type is `graphql`, otherwise no | +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| refName | Name of the referenced [function](#Function-Definition) | string | yes | +| arguments | Arguments (inputs) to be passed to the referenced function | object | yes if function type is `graphql`, otherwise no | | selectionSet | Used if function type is `graphql`. String containing a valid GraphQL [selection set](https://spec.graphql.org/June2018/#sec-Selection-Sets) | string | yes if function type is `graphql`, otherwise no | -| invoke | Specifies if the function should be invoked `sync` or `async`. Default is `sync` | enum | no | +| invoke | Specifies if the function should be invoked `sync` or `async`. Default is `sync` | enum | no |

Click to view example definition

@@ -3898,14 +3898,14 @@ onErrors definition. Note that errors raised during functions that are invoked a Allows defining invocation of a function via event. -| Parameter | Description | Type | Required | -|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------|----------| -| [produceEventRef](#Event-Definition) | Reference to the unique name of a `produced` event definition | string | yes | -| [consumeEventRef](#Event-Definition) | Reference to the unique name of a `consumed` event definition | string | no | -| consumeEventTimeout | Maximum amount of time (ISO 8601 format) to wait for the consume event. If not defined it be set to the [actionExecutionTimeout](#Workflow-Timeout-Definition) | string | no | -| data | If string type, an expression which selects parts of the states data output to become the data (payload) of the event referenced by `produceEventRef`. If object type, a custom object to become the data (payload) of the event referenced by `produceEventRef`. | string or object | no | -| contextAttributes | Add additional event extension context attributes to the trigger/produced event | object | no | -| invoke | Specifies if the function should be invoked `sync` or `async`. Default is `sync` | enum | no | +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| [produceEventRef](#Event-Definition) | Reference to the unique name of a `produced` event definition | string | yes | +| [consumeEventRef](#Event-Definition) | Reference to the unique name of a `consumed` event definition | string | no | +| consumeEventTimeout | Maximum amount of time (ISO 8601 format) to wait for the consume event. If not defined it be set to the [actionExecutionTimeout](#Workflow-Timeout-Definition) | string | no | +| data | If string type, an expression which selects parts of the states data output to become the data (payload) of the event referenced by `produceEventRef`. If object type, a custom object to become the data (payload) of the event referenced by `produceEventRef`. | string or object | no | +| contextAttributes | Add additional event extension context attributes to the trigger/produced event | object | no | +| invoke | Specifies if the function should be invoked sync or async. Default is sync | enum | no |

Click to view example definition

@@ -3980,12 +3980,12 @@ property and not its `version` property. 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 | -| 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 | +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| workflowId | Sub-workflow unique id | 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 |

Click to view example definition

From ce5e6367415e79d4f4d20cb865b3722a0f265875 Mon Sep 17 00:00:00 2001 From: radtriste Date: Tue, 17 May 2022 13:56:13 +0200 Subject: [PATCH 07/14] Correct WF definition for multiple data filters Signed-off-by: radtriste --- specification.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification.md b/specification.md index 189fd295..498f4312 100644 --- a/specification.md +++ b/specification.md @@ -660,12 +660,12 @@ a workflow with a single event state and show how data filters can be combined. "functionRef": { "refName": "greetingFunction", "arguments": { - "greeting": "${ .spanish } ", + "greeting": "${ .hello.spanish } ", "customerName": "${ .customerInfo.name } " } }, "actionDataFilter": { - "fromStateData": "${ .hello }", + "fromStateData": "${ { hello, customerInfo } }", "results": "${ .greetingMessageResult }", "toStateData": "${ .finalCustomerGreeting }" } @@ -767,7 +767,7 @@ At this point our state data contains: ```json { - "hello": { + "hello": { "english": "Hello", "spanish": "Hola", "german": "Hallo", @@ -790,7 +790,7 @@ At this point our state data contains: **(3) Event state performs its actions**: Before the first action is executed, its actionDataFilter is invoked. Its "fromStateData" expression filters the current state data to select from its data that should be available to action arguments. In this example -it selects the "hello" property from the current state data. +it selects the "hello" and "customerInfo" properties from the current state data. At this point the action is executed. We assume that for this example "greetingFunction" returns: @@ -899,7 +899,7 @@ After merging the state data should be: } ``` -Merging array types should be done by concatenating them into a larger array including unique elements of both arrays. +Merging array types should be done by concatenating them into a larger array including unique elements of both arrays. To give an example, merging: ```json From cac11677d53eb8860d0075a899f7621df708b497 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Mon, 20 Jun 2022 18:09:44 +0200 Subject: [PATCH 08/14] Added function resource and invocation authentication Signed-off-by: Charles d'Avernas --- schema/functions.json | 29 ++++++++++++++++++++--- specification.md | 55 +++++++++++++++++++++++++++++++++++++------ 2 files changed, 74 insertions(+), 10 deletions(-) diff --git a/schema/functions.json b/schema/functions.json index 08f3b345..a29bd2d7 100644 --- a/schema/functions.json +++ b/schema/functions.json @@ -54,9 +54,32 @@ "default": "rest" }, "authRef": { - "type": "string", - "description": "References an auth definition name to be used to access to resource defined in the operation parameter", - "minLength": 1 + "oneOf": [ + { + "type": "string", + "description": "References the auth definition to be used to invoke the operation", + "minLength": 1 + }, + { + "type": "object", + "description": "Configures both the auth definition used to retrieve the operation's resource and the auth definition used to invoke said operation", + "properties":{ + "resource":{ + "type": "string", + "description": "References an auth definition to be used to access the resource defined in the operation parameter", + "minLength": 1 + }, + "invocation":{ + "type": "string", + "description": "References an auth definition to be used to invoke the operation" + } + }, + "additionalProperties": false, + "required": [ + "resource" + ] + } + ] }, "metadata": { "$ref": "common.json#/definitions/metadata" diff --git a/specification.md b/specification.md index 498f4312..ad2aeafe 100644 --- a/specification.md +++ b/specification.md @@ -1986,8 +1986,7 @@ If we have the following function definition: ``` The `authRef` property is used to reference an authentication definition in -the `auth` property and should be applied to access the `https://secure.resources.com/myapi.json` -OpenApi definition file. +the `auth` property and should be applied when invoking the `helloWorld` function. An [AuthRef](#AuthRef-Definition) object can alternatively be used to configure the authentication definition to use when accessing the function's resource and/or when invoking the function. The `functions` property can be either an in-line [function](#Function-Definition) definition array, or an URI reference to a resource containing an array of [functions](#Function-Definition) definition. @@ -3248,7 +3247,7 @@ Depending on the function `type`, the `operation` property can be: Defining custom function types is possible, for more information on that refer to the [Defining custom function types](#defining-custom-function-types) section. The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). -It is used to provide authentication info to access the resource defined in the `operation` property. +It is used to provide authentication info to access the resource defined in the `operation` property and/or to invoke the function. 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: @@ -3266,6 +3265,50 @@ Note that using metadata for cases such as above heavily reduces the portability 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). +###### AuthRef Definition + +| Parameter | Description | Type | Required | +| --- | --- | --- | --- | +| resource | References an auth definition to be used to access the resource defined in the operation parameter | string | yes | +| invocation | References an auth definition to be used to invoke the operation | string | no | + +The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). +It can be a string, in which case the referenced [auth definition](#Auth-Definition) is used solely for the function's invocation, or an object, in which case it is possible to specify an [auth definition](#Auth-Definition) to use for the function's resource retrieval (as defined by the `operation` property) and another for its invocation. + +Example of a function definition configured to use an [auth definition](#Auth-Definition) called "My Basic Auth" upon invocation: + +```yaml +functions: +- name: SecuredFunctionInvocation + operation: https://test.com/swagger.json#HelloWorld + authRef: My Basic Auth +``` + +Example of a function definition configured to use an [auth definition](#Auth-Definition) called "My Basic Auth" to retrieve the resource defined by the `operation` property, and an [auth definition](#Auth-Definition) called "My OIDC Auth" upon invocation: + +```yaml +functions: +- name: SecuredFunctionInvocation + operation: https://test.com/swagger.json#HelloWorld + authRef: + resource: My Basic Auth + invocation: My OIDC Auth +``` + +Note that if multiple functions share the same `operation` value, and if one of them defines an [auth definition](#Auth-Definition) for resource access, then it should always be used to access said resource. +In other words, when retrieving the resource of the function "MySecuredFunction2" defined in the following example, the "My Api Key Auth" [auth definition](#Auth-Definition) should be used, because the "MySecuredFunction1" has defined it for resource access. +This is done to avoid unnecessary repetitions of [auth definition](#Auth-Definition) configuration when using the same resource for multiple defined functions. + +```yaml +functions: + - name: MySecuredFunction1 + operation: https://secure.resources.com/myapi.json#helloWorld + authRef: + resource: My ApiKey Auth + - name: MySecuredFunction2 + operation: https://secure.resources.com/myapi.json#holaMundo +``` + ##### Event Definition | Parameter | Description | Type | Required | @@ -3483,10 +3526,8 @@ If `false`, both Event payload and context attributes should be accessible. ##### Auth Definition -Auth definitions can be used to define authentication information that should be applied -to resources defined in the operation property of [function definitions](#Function-Definition). -It is not used as authentication information for the function invocation, but just to access -the resource containing the function invocation information. +Auth definitions can be used to define authentication information that should be applied to [function definitions](#Function-Definition). +It can be used for both the retrieval of the function's resource (as defined by the `operation` property) and for the function's invocation. | Parameter | Description | Type | Required | | --- | --- | --- | --- | From e4879424de0b36e314331ff64a7fee9a4916a818 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Tue, 21 Jun 2022 10:31:33 +0200 Subject: [PATCH 09/14] Minor fixes to the spec file Signed-off-by: Charles d'Avernas --- specification.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/specification.md b/specification.md index ad2aeafe..fd232dba 100644 --- a/specification.md +++ b/specification.md @@ -3272,8 +3272,11 @@ defined via the `parameters` property in [function definitions](#FunctionRef-Def | resource | References an auth definition to be used to access the resource defined in the operation parameter | string | yes | | invocation | References an auth definition to be used to invoke the operation | string | no | -The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). -It can be a string, in which case the referenced [auth definition](#Auth-Definition) is used solely for the function's invocation, or an object, in which case it is possible to specify an [auth definition](#Auth-Definition) to use for the function's resource retrieval (as defined by the `operation` property) and another for its invocation. +The `authRef` property references a name of a defined workflow [auth definition](#Auth-Definition). It can be a string or an object. + +If it's a string, the referenced [auth definition](#Auth-Definition) is used solely for the function's invocation. + +If it's an object, it is possible to specify an [auth definition](#Auth-Definition) to use for the function's resource retrieval (as defined by the `operation` property) and another for its invocation. Example of a function definition configured to use an [auth definition](#Auth-Definition) called "My Basic Auth" upon invocation: @@ -3295,7 +3298,7 @@ functions: invocation: My OIDC Auth ``` -Note that if multiple functions share the same `operation` value, and if one of them defines an [auth definition](#Auth-Definition) for resource access, then it should always be used to access said resource. +Note that if multiple functions share the same `operation` path (*which is the first component of the operation value, located before the first '#' character*), and if one of them defines an [auth definition](#Auth-Definition) for resource access, then it should always be used to access said resource. In other words, when retrieving the resource of the function "MySecuredFunction2" defined in the following example, the "My Api Key Auth" [auth definition](#Auth-Definition) should be used, because the "MySecuredFunction1" has defined it for resource access. This is done to avoid unnecessary repetitions of [auth definition](#Auth-Definition) configuration when using the same resource for multiple defined functions. From de0f2846c1498afb1f87f95d46afabf62d493463 Mon Sep 17 00:00:00 2001 From: Charles d'Avernas Date: Thu, 23 Jun 2022 10:31:26 +0200 Subject: [PATCH 10/14] Added a note on how to handle auth def declared for an OpenAPI function Signed-off-by: Charles d'Avernas --- specification.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification.md b/specification.md index fd232dba..754d2118 100644 --- a/specification.md +++ b/specification.md @@ -3312,6 +3312,8 @@ functions: operation: https://secure.resources.com/myapi.json#holaMundo ``` +It's worth noting that if an [auth definition](#Auth-Definition) has been defined for an OpenAPI function which's resource declare an authentication mechanism, the later should be used instead, thus ignoring entirely the [auth definition](#Auth-Definition). + ##### Event Definition | Parameter | Description | Type | Required | From 4c9961fb83dd8430934d150873e45c3d7b62db3d Mon Sep 17 00:00:00 2001 From: Tihomir Surdilovic Date: Sat, 25 Jun 2022 23:33:42 -0400 Subject: [PATCH 11/14] update meeting info (#645) Signed-off-by: Tihomir Surdilovic --- README.md | 36 ++++++------------------------------ 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 7a04e49d..53aee313 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,7 @@ Cloud Native Sandbox level project on July 14, 2020. - [Community](#Community) - [Communication](#Communication) - [Code of Conduct](#Code-of-Conduct) - - [Meetings](#Meetings) - - [Meeting Minutes](#Meeting-Minutes) + - [Weekly Meetings](#Weekly-Meetings) - [Repository Structure](#Repository-Structure) - [Support](#Support) @@ -121,40 +120,17 @@ religion, or nationality. See our full project Code of Conduct information [here](code-of-conduct.md). -### Meetings +### Weekly Meetings -* [CNCF public events calendar](https://www.cncf.io/calendar/) +The Serverless Workflow team meets weekly, every Monday at 11AM ET (USA Eastern Time). -The Serverless Workflow team meets weekly, every Wednesday at 11AM ET (USA Eastern Time). - -Join from PC, Mac, Linux, iOS or Android via [zoom](https://zoom.us/my/cncfserverlesswg?pwd=YjNqYzhOdjRRd01YWFkzS1lHbDZqUT09) - -Or iPhone one-tap : - - US: +16465588656,,3361029682# or +16699006833,,3361029682# - -Or Telephone: - - Dial: - US: +1 646 558 8656 (US Toll) or +1 669 900 6833 (US Toll) - or +1 855 880 1246 (Toll Free) or +1 877 369 0926 (Toll Free) - -Meeting ID: 336 102 9682 - -International numbers available: -https://zoom.us/zoomconference?m=QpOqQYfTzY_Gbj9_8jPtsplp1pnVUKDr - -NOTE: Please use \*6 to mute/un-mute your phone during the call. +To register for meetings please visit our [website](https://serverlessworkflow.io/) and click on the +"Register for Weekly Project Meetings" button. +You can register for individual meetings or for the entire series. World Time Zone Converter: http://www.thetimezoneconverter.com/?t=9:00%20am&tz=San%20Francisco& -### Meeting Minutes - -You can find meeting minutes [here](meetingminutes). -Note that unfortunately we have lost our Google doc which contained meeting info for our prior meetings. -We will move all meeting info to our github repo so that this never happens again. - ## Repository Structure Here is the outline of the repository to help navigate the specification From b342026a36db5118cb7b7a8dfa6b72afde9f8b27 Mon Sep 17 00:00:00 2001 From: Tihomir Surdilovic Date: Sun, 26 Jun 2022 00:06:22 -0400 Subject: [PATCH 12/14] update info (#646) Signed-off-by: Tihomir Surdilovic --- .github/CODEOWNERS | 2 +- MAINTAINERS.md | 1 - OWNERS | 1 - 3 files changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index d02b21b1..6c2a3e14 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -2,4 +2,4 @@ # the repo. Unless a later match takes precedence, # They will be requested for # review when someone opens a pull request. -* @tsurdilo @ricardozanini @manuelstein @cdavernas @antmendoza \ No newline at end of file +* @tsurdilo @ricardozanini @cdavernas @antmendoza \ No newline at end of file diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 6b6ca971..3069626e 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,6 +1,5 @@ # Serverless Workflow Org Maintainers -* [Manuel Stein](https://github.com/manuelstein) * [Tihomir Surdilovic](https://github.com/tsurdilo) * [Ricardo Zanini](https://github.com/ricardozanini) * [Charles d'Avernas](https://github.com/cdavernas) diff --git a/OWNERS b/OWNERS index ce5aec08..9e326158 100644 --- a/OWNERS +++ b/OWNERS @@ -1,7 +1,6 @@ # See the GOVERNANCE.md document for the definition of the roles and responsibilities maintainers: - tsurdilo - - manuelstein - ricardozanini - cdavernas - antmendoza From 9c5cb544ea0ea0077a3fdce8fb0c0b056e3b7e87 Mon Sep 17 00:00:00 2001 From: Ricardo Zanini Date: Mon, 8 Aug 2022 14:50:34 -0300 Subject: [PATCH 13/14] Old Approach of HTTP operation Signed-off-by: Ricardo Zanini --- roadmap/README.md | 2 +- schema/functions.json | 5 +- specification.md | 191 +++++++++++++++++++++++++++++++++++++++--- 3 files changed, 185 insertions(+), 13 deletions(-) diff --git a/roadmap/README.md b/roadmap/README.md index ba29fbd7..b27ed486 100644 --- a/roadmap/README.md +++ b/roadmap/README.md @@ -35,8 +35,8 @@ _Status description:_ | ✔️| Apply fixes to auth spec schema [workflow schema](https://github.com/serverlessworkflow/specification/tree/main/schema) | | ✔️| Update the `dataInputSchema` top-level property by supporting the assignment of a JSON schema object [workflow schema](https://github.com/serverlessworkflow/specification/tree/main/specification.md#workflow-definition-structure) | | ✔️| Add the new `WORKFLOW` reserved keyword to workflow expressions | +| ✔️| Add the new `http` function type [spec doc](https://github.com/serverlessworkflow/specification/tree/main/specification.md#using-functions-for-http-service-invocations) | | ✏️️| Add inline state defs in branches | | -| ✏️️| Update rest function definition | | | ✏️️| Add "completedBy" functionality | | | ✏️️| Define workflow context | | | ✏️️| Start work on TCK | | diff --git a/schema/functions.json b/schema/functions.json index a29bd2d7..97a7df19 100644 --- a/schema/functions.json +++ b/schema/functions.json @@ -36,14 +36,15 @@ }, "operation": { "type": "string", - "description": "If type is `rest`, #. If type is `asyncapi`, #. If type is `rpc`, ##. If type is `graphql`, ##. If type is `odata`, #. If type is `expression`, defines the workflow expression.", + "description": "If type is `rest`, #. If type is `asyncapi`, #. If type is `rpc`, ##. If type is `graphql`, ##. If type is `odata`, #. If type is `expression`, defines the workflow expression. If type is `http`, #", "minLength": 1 }, "type": { "type": "string", - "description": "Defines the function type. Is either `rest`, `asyncapi, `rpc`, `graphql`, `odata`, `expression`, or `custom`. Default is `rest`", + "description": "Defines the function type. Is either `rest`, `http`,`asyncapi, `rpc`, `graphql`, `odata`, `expression`, or `custom`. Default is `rest`", "enum": [ "rest", + "http", "asyncapi", "rpc", "graphql", diff --git a/specification.md b/specification.md index 754d2118..1313277e 100644 --- a/specification.md +++ b/specification.md @@ -23,9 +23,10 @@ + [Using multiple data filters](#using-multiple-data-filters) + [Data Merging](#data-merging) * [Workflow Functions](#workflow-functions) - + [Using Functions for RESTful Service Invocations](#using-functions-for-restful-service-invocations) + + [Using Functions for OpenAPI RESTFul Service Invocations](#using-functions-for-openapi-restful-service-invocations) + + [Using Functions for HTTP Service Invocations](#using-functions-for-http-service-invocations) + [Using Functions for Async API Service Invocations](#using-functions-for-async-api-service-invocations) - + [Using Functions for RPC Service Invocations](#using-functions-for-rpc-service-invocations) + + [Using Functions for gRPC Service Invocations](#using-functions-for-grpc-service-invocations) + [Using Functions for GraphQL Service Invocations](#using-functions-for-graphql-service-invocations) - [Invoking a GraphQL `Query`](#invoking-a-graphql-query) - [Invoking a GraphQL `Mutation`](#invoking-a-graphql-mutation) @@ -991,8 +992,9 @@ They can be referenced by their domain-specific names inside workflow [states](# Reference the following sections to learn more about workflow functions: -* [Using functions for RESTful service invocations](#Using-Functions-for-RESTful-Service-Invocations) -* [Using Functions for Async API Service Invocations](#Using-Functions-for-Async-API-Service-Invocations) +* [Using functions for OpenAPI RESTful service invocations](#using-functions-for-openapi-restful-service-invocations) ++ [Using functions for HTTP Service Invocations](#using-functions-for-http-service-invocations) +* [Using functions for Async API Service Invocations](#Using-Functions-for-Async-API-Service-Invocations) * [Using functions for gRPC service invocation](#Using-Functions-For-RPC-Service-Invocations) * [Using functions for GraphQL service invocation](#Using-Functions-For-GraphQL-Service-Invocations) * [Using Functions for OData Service Invocations](#Using-Functions-for-OData-Service-Invocations) @@ -1002,7 +1004,7 @@ Reference the following sections to learn more about workflow functions: We can define if functions are invoked sync or async. Reference the [functionRef](#FunctionRef-Definition) to learn more on how to do this. -#### Using Functions for RESTful Service Invocations +#### Using Functions for OpenAPI RESTful Service Invocations [Functions](#Function-Definition) can be used to describe services and their operations that need to be invoked during workflow execution. They can be referenced by states [action definitions](#Action-Definition) to clearly @@ -1059,6 +1061,162 @@ Note that the referenced function definition type in this case must be `rest` (d For more information about functions, reference the [Functions definitions](#Function-Definition) section. +#### Using functions for HTTP Service Invocations + +The specification supports describing HTTP invocations via a simplified interface in the [functions definition](#Function-Definition). + +Here is an example function definition for HTTP requests with method `GET` and request target corresponding with [URI Template](https://www.rfc-editor.org/rfc/rfc6570.html) `/users/{id}`: + +```json +{ + "functions":[ + { + "name":"queryUserById", + "operation":"GET#/users/{id}", + "type":"http" + } + ] +} +``` + +Note that the [Function Definition](#Function-Definition)'s `operation` property must have the following format: + +```text +# +``` + +* The HTTP method used by the HTTP invocation. Can be any [valid HTTP method](https://www.rfc-editor.org/rfc/rfc9110.html#name-method-definitions) such as `GET`, `POST`, `PUT`, etc. +* The endpoint **location path** or the service full URL. Runtimes implementations are **discouraged** to expect the full URL in this field since this is a matter of infrastructure configuration. + +The list below describes the HTTP function parameters in the `operation` attribute: + +* Path parameters must be enclosed with braces (`{}`) as defined by [URI Templates](https://www.rfc-editor.org/rfc/rfc6570.html). The parameter name can be later referenced by the workflow states. For example: `/user/{id}` +* [Query parameters](https://www.rfc-editor.org/rfc/rfc9110.html#section-4.2.2) must be enclosed with braces (`{}`) as defined by [URI Templates](https://www.rfc-editor.org/rfc/rfc6570.html). The parameter name can be later referenced by the workflow states. For example: `/user?status={status}`. + + +Additional HTTP header fields can be passed via the `metadata` function definition. For example: + +```json +{ + "functions":[ + { + "name":"queryUserById", + "operation":"GET#/users/{id}", + "type":"http", + "metadata":{ + "x-custom-header":"the-value" + } + } + ] +} +``` + +> Since the data manipulated in the Serverless Workflow specification is primarly JSON, runtimes are encouraged to support at least `Content-Type: application/json` header field for HTTP requests. + +Avoid passing sensitive information in headers such as authentication tokens. See the [auth definition](#auth-definition) for more information. + +HTTP request content doesn't need to be described in the function definition. **All the data within the state** should be passed to the HTTP request. See the [action data filter](#action-data-filters) if you need to limit the amount of data passed to a given action. + +The function can be referenced during workflow execution when the invocation of the HTTP service is desired. For example: + +```json +{ + "states":[ + { + "name":"QueryUserInfo", + "type":"operation", + "actions":[ + { + "functionRef":"queryUserById", + "arguments":{ + "id":"${ .user.id }" + } + } + ], + "end":true + } + ] +} +``` + +Example of the `POST` request sending the state data as part of the body: + +```json +{ + "functions":[ + { + "name":"createUser", + "operation":"POST#/users", + "type":"http" + } + ] +} +``` + +Then you can reference the `createUser` function and filter the input data to invoke it. + +Input data example: + +```json +{ + "order":{ + "id":"1234N", + "products":[ + { + "name":"Product 1" + } + ] + }, + "user":{ + "name":"John Doe", + "email":"john@doe.com" + } +} +``` + +Function invocation example: + +```json +{ + "states":[ + { + "name":"CreateNewUser", + "type":"operation", + "actions":[ + { + "functionRef":"createUser", + "actionDataFilter":{ + "fromStateData":"${ .user }", + "toStateData":"${ .user.id }" + } + } + ], + "end":true + } + ] +} +``` + +In this case, only the contents of the `user` attribute will be passed to the function. The user ID returned by the HTTP request body will then be added to the state data: + +```json +{ + "order":{ + "id":"1234N", + "products":[ + { + "name":"Product 1" + } + ] + }, + "user":{ + "id":"5678U", + "name":"John Doe", + "email":"john@doe.com" + } +} +``` + #### Using Functions for Async API Service Invocations [Functions](#Function-Definition) can be used to invoke PUBLISH and SUBSCRIBE operations on a message broker documented by the [Async API Specification](https://www.asyncapi.com/docs/specifications/v2.1.0). @@ -1148,7 +1306,7 @@ Our defined function definition can then we referenced in a workflow [action](#A } ``` -#### Using Functions for RPC Service Invocations +#### Using Functions for gRPC Service Invocations Similar to defining invocations of operations on RESTful services, you can also use the workflow [functions definitions](#Function-Definition) that follow the remote procedure call (RPC) protocol. @@ -1157,7 +1315,7 @@ a widely used RPC system. gRPC uses [Protocol Buffers](https://developers.google.com/protocol-buffers/docs/overview) to define messages, services, and the methods on those services that can be invoked. -Let's look at an example of invoking a service method using RPC. For this example let's say we have the following +Let's look at an example of invoking a service method using gRPC. For this example let's say we have the following gRPC protocol buffer definition in a myuserservice.proto file: ```text @@ -1409,7 +1567,7 @@ should follow the Serverless Workflow [OData Json schema](https://github.com/ser #### Using Functions for Expression Evaluation -In addition to defining RESTful, AsyncAPI, RPC, GraphQL and OData services and their operations, workflow [functions definitions](#Function-Definition) +In addition to defining RESTful, AsyncAPI, gRPC, GraphQL and OData services and their operations, workflow [functions definitions](#Function-Definition) can also be used to define expressions that should be evaluated during workflow execution. Defining expressions as part of function definitions has the benefit of being able to reference @@ -3189,11 +3347,24 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that | Parameter | Description | Type | Required | | --- | --- | --- | --- | | name | Unique function name | string | yes | -| operation | If type is `rest`, #. If type is `asyncapi`, #. If type is `rpc`, ##. If type is `graphql`, ##. If type is `odata`, #. If type is `expression`, defines the workflow expression. | string | yes | -| type | Defines the function type. Can be either `rest`, `asyncapi`, `rpc`, `graphql`, `odata`, `expression`, or [`custom`](#defining-custom-function-types). Default is `rest` | enum | no | +| operation | See the table "Function Operation description by type" below. | string | yes | +| type | Defines the function type. Can be either `rest`, `http`, `asyncapi`, `rpc`, `graphql`, `odata`, `expression`, or [`custom`](#defining-custom-function-types). Default is `rest` | enum | no | | authRef | References an [auth definition](#Auth-Definition) name to be used to access to resource defined in the operation parameter | string | no | | [metadata](#Workflow-Metadata) | Metadata information. Can be used to define custom function information | object | no | +Function Operation description by type: + +| Type | Operation Description | +| ---- | --------- | +| `rest` | # | +| `http` | # | +| `asyncapi` | # | +| `rpc` | ## | +| `graphql` | ## | +| `odata` | # | +| `expression` | defines the workflow expression | +| `custom` | see [Defining custom function types](#defining-custom-function-types) +

Click to view example definition

From 90b4cdb06bc0eaad7211551beebed11712dee34d Mon Sep 17 00:00:00 2001 From: Ricardo Zanini Date: Mon, 8 Aug 2022 15:54:19 -0300 Subject: [PATCH 14/14] Refactoring REST Operation to OpenAPI Path Item Signed-off-by: Ricardo Zanini --- schema/functions.json | 36 +++++++++---- specification.md | 122 ++++++++++++++++++++++-------------------- 2 files changed, 90 insertions(+), 68 deletions(-) diff --git a/schema/functions.json b/schema/functions.json index 97a7df19..4863c6fc 100644 --- a/schema/functions.json +++ b/schema/functions.json @@ -35,16 +35,15 @@ "minLength": 1 }, "operation": { - "type": "string", - "description": "If type is `rest`, #. If type is `asyncapi`, #. If type is `rpc`, ##. If type is `graphql`, ##. If type is `odata`, #. If type is `expression`, defines the workflow expression. If type is `http`, #", - "minLength": 1 + "type": "object", + "$ref": "#/definitions/operation" }, "type": { "type": "string", - "description": "Defines the function type. Is either `rest`, `http`,`asyncapi, `rpc`, `graphql`, `odata`, `expression`, or `custom`. Default is `rest`", + "description": "Defines the function type. Is either `rest`, `openapi`,`asyncapi, `rpc`, `graphql`, `odata`, `expression`, or `custom`. Default is `openapi`.", "enum": [ "rest", - "http", + "openapi", "asyncapi", "rpc", "graphql", @@ -52,7 +51,7 @@ "expression", "custom" ], - "default": "rest" + "default": "openapi" }, "authRef": { "oneOf": [ @@ -64,13 +63,13 @@ { "type": "object", "description": "Configures both the auth definition used to retrieve the operation's resource and the auth definition used to invoke said operation", - "properties":{ - "resource":{ + "properties": { + "resource": { "type": "string", "description": "References an auth definition to be used to access the resource defined in the operation parameter", "minLength": 1 }, - "invocation":{ + "invocation": { "type": "string", "description": "References an auth definition to be used to invoke the operation" } @@ -91,6 +90,25 @@ "name", "operation" ] + }, + "operation": { + "oneOf": [ + { + "type": "string", + "description": "If type is `openapi`, #. If type is `asyncapi`, #. If type is `rpc`, ##. If type is `graphql`, ##. If type is `odata`, #. If type is `expression`, defines the workflow expression.", + "minLength": 1 + }, + { + "type": "object", + "description": "OpenAPI Path Object definition", + "$comment": "https://spec.openapis.org/oas/v3.1.0#paths-object", + "patternProperties": { + "^/": { + "type": "object" + } + } + } + ] } } } \ No newline at end of file diff --git a/specification.md b/specification.md index 1313277e..badff29a 100644 --- a/specification.md +++ b/specification.md @@ -992,8 +992,8 @@ They can be referenced by their domain-specific names inside workflow [states](# Reference the following sections to learn more about workflow functions: -* [Using functions for OpenAPI RESTful service invocations](#using-functions-for-openapi-restful-service-invocations) -+ [Using functions for HTTP Service Invocations](#using-functions-for-http-service-invocations) +* [Using functions for OpenAPI Service invocations](#using-functions-for-openapi-service-invocations) ++ [Using functions for RESTful Service Invocations](#using-functions-for-rest-service-invocations) * [Using functions for Async API Service Invocations](#Using-Functions-for-Async-API-Service-Invocations) * [Using functions for gRPC service invocation](#Using-Functions-For-RPC-Service-Invocations) * [Using functions for GraphQL service invocation](#Using-Functions-For-GraphQL-Service-Invocations) @@ -1004,7 +1004,7 @@ Reference the following sections to learn more about workflow functions: We can define if functions are invoked sync or async. Reference the [functionRef](#FunctionRef-Definition) to learn more on how to do this. -#### Using Functions for OpenAPI RESTful Service Invocations +#### Using Functions for OpenAPI Service Invocations [Functions](#Function-Definition) can be used to describe services and their operations that need to be invoked during workflow execution. They can be referenced by states [action definitions](#Action-Definition) to clearly @@ -1057,67 +1057,41 @@ For example: } ``` -Note that the referenced function definition type in this case must be `rest` (default type). +Note that the referenced function definition type in this case must be `openapi` (default type). For more information about functions, reference the [Functions definitions](#Function-Definition) section. -#### Using functions for HTTP Service Invocations +#### Using functions for RESTful Service Invocations -The specification supports describing HTTP invocations via a simplified interface in the [functions definition](#Function-Definition). +The specification also supports describing REST invocations in the [functions definition](#Function-Definition) using [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object). -Here is an example function definition for HTTP requests with method `GET` and request target corresponding with [URI Template](https://www.rfc-editor.org/rfc/rfc6570.html) `/users/{id}`: +Here is an example function definition for REST requests with method `GET` and request target corresponding with [URI Template](https://www.rfc-editor.org/rfc/rfc6570.html) `/users/{id}`: ```json { "functions":[ { "name":"queryUserById", - "operation":"GET#/users/{id}", - "type":"http" - } - ] -} -``` - -Note that the [Function Definition](#Function-Definition)'s `operation` property must have the following format: - -```text -# -``` - -* The HTTP method used by the HTTP invocation. Can be any [valid HTTP method](https://www.rfc-editor.org/rfc/rfc9110.html#name-method-definitions) such as `GET`, `POST`, `PUT`, etc. -* The endpoint **location path** or the service full URL. Runtimes implementations are **discouraged** to expect the full URL in this field since this is a matter of infrastructure configuration. - -The list below describes the HTTP function parameters in the `operation` attribute: - -* Path parameters must be enclosed with braces (`{}`) as defined by [URI Templates](https://www.rfc-editor.org/rfc/rfc6570.html). The parameter name can be later referenced by the workflow states. For example: `/user/{id}` -* [Query parameters](https://www.rfc-editor.org/rfc/rfc9110.html#section-4.2.2) must be enclosed with braces (`{}`) as defined by [URI Templates](https://www.rfc-editor.org/rfc/rfc6570.html). The parameter name can be later referenced by the workflow states. For example: `/user?status={status}`. - - -Additional HTTP header fields can be passed via the `metadata` function definition. For example: - -```json -{ - "functions":[ - { - "name":"queryUserById", - "operation":"GET#/users/{id}", - "type":"http", - "metadata":{ - "x-custom-header":"the-value" - } + "operation": { + "/users": { + "get": { + "parameters": [{ + "name": "id", + "in": "path", + "required": true + }] + } + } + }, + "type":"rest" } ] } ``` -> Since the data manipulated in the Serverless Workflow specification is primarly JSON, runtimes are encouraged to support at least `Content-Type: application/json` header field for HTTP requests. - -Avoid passing sensitive information in headers such as authentication tokens. See the [auth definition](#auth-definition) for more information. +Note that the [Function Definition](#Function-Definition)'s `operation` property must follow the OpenAPI Paths Object specification definition. -HTTP request content doesn't need to be described in the function definition. **All the data within the state** should be passed to the HTTP request. See the [action data filter](#action-data-filters) if you need to limit the amount of data passed to a given action. - -The function can be referenced during workflow execution when the invocation of the HTTP service is desired. For example: +The function can be referenced during workflow execution when the invocation of the REST service is desired. For example: ```json { @@ -1145,17 +1119,43 @@ Example of the `POST` request sending the state data as part of the body: { "functions":[ { - "name":"createUser", - "operation":"POST#/users", - "type":"http" + "name": "createUser", + "operation": { + "/users": { + "post": { + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + } + }, + "required": ["name", "email"] + } + } + } + } + } + } + }, + "type": "rest" } ] } ``` -Then you can reference the `createUser` function and filter the input data to invoke it. +Note that the `requestBody` content schema is described inline rather than a reference to an external document. -Input data example: +You can reference the `createUser` function and filter the input data to invoke it, as shown in the example below: ```json { @@ -1197,7 +1197,7 @@ Function invocation example: } ``` -In this case, only the contents of the `user` attribute will be passed to the function. The user ID returned by the HTTP request body will then be added to the state data: +In this case, only the contents of the `user` attribute will be passed to the function. The user ID returned by the REST request body will then be added to the state data: ```json { @@ -1217,6 +1217,8 @@ In this case, only the contents of the `user` attribute will be passed to the fu } ``` +The specification does not support the [Security Requirement Object](https://spec.openapis.org/oas/v3.1.0#security-requirement-object). To define authentication for the REST operation, use the [Auth Definition](#Auth-Definition). If provided, this field is ignored. + #### Using Functions for Async API Service Invocations [Functions](#Function-Definition) can be used to invoke PUBLISH and SUBSCRIBE operations on a message broker documented by the [Async API Specification](https://www.asyncapi.com/docs/specifications/v2.1.0). @@ -3347,8 +3349,8 @@ Note that `transition` and `end` properties are mutually exclusive, meaning that | Parameter | Description | Type | Required | | --- | --- | --- | --- | | name | Unique function name | string | yes | -| operation | See the table "Function Operation description by type" below. | string | yes | -| type | Defines the function type. Can be either `rest`, `http`, `asyncapi`, `rpc`, `graphql`, `odata`, `expression`, or [`custom`](#defining-custom-function-types). Default is `rest` | enum | no | +| operation | See the table "Function Operation description by type" below. | string or object | yes | +| type | Defines the function type. Can be either `rest`, `openapi`, `asyncapi`, `rpc`, `graphql`, `odata`, `expression`, or [`custom`](#defining-custom-function-types). Default is `openapi` | enum | no | | authRef | References an [auth definition](#Auth-Definition) name to be used to access to resource defined in the operation parameter | string | no | | [metadata](#Workflow-Metadata) | Metadata information. Can be used to define custom function information | object | no | @@ -3356,8 +3358,8 @@ Function Operation description by type: | Type | Operation Description | | ---- | --------- | -| `rest` | # | -| `http` | # | +| `openapi` | # | +| `rest` | [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object) definition | | `asyncapi` | # | | `rpc` | ## | | `graphql` | ## | @@ -3399,12 +3401,14 @@ operation: https://hellworldservice.api.com/api.json#helloWorld The `name` property defines an unique name of the function definition. -The `type` property defines the function type. Its value can be either `rest` or `expression`. Default value is `rest`. +The `type` property defines the function type. Its value can be either `rest`, `openapi` or `expression`. Default value is `openapi`. 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 '#'. +* If `type` is `openapi`, 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 `rest`, an object definition of the [OpenAPI Paths Object](https://spec.openapis.org/oas/v3.1.0#paths-object). + For example, see [Using Functions for RESTful Service Invocations](#using-functions-for-rest-service-invocations). * If `type` is `asyncapi`, a combination of the AsyncApi definition document URI and the particular service operation that needs to be invoked, separated by a '#'. For example `file://streetlightsapi.yaml#onLightMeasured`. * 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 '#'.