feat: Reusable Success and Failure Actions (#171)

* feat: adding support for share success and failure actions * Merging latest 'main' changes in to Action Object Extensions branch (#170) * chore: suggest multilevel parameters (#155) * chore: suggest multilevel parameters * Update versions/1.0.0.md Co-authored-by: Frank Kilcommins <[email protected]> * Update examples/1.0.0/ExtendedParametersExample.workflow.yaml Co-authored-by: Frank Kilcommins <[email protected]> * Update versions/1.0.0.md Co-authored-by: Frank Kilcommins <[email protected]> --------- Co-authored-by: Frank Kilcommins <[email protected]> * Remove references to WHATWG to avoid confusion (#145) * Remove references to WHATWG to avoid confusion * Correct relative reference wording * Section 4.2 not 4.1! * Simplify URI wording * Adjust Step Parameters desc to cater for Workflow parameters addition (#169) * feat: add `dependsOn` capability for workflow level (#164) * feat: add `dependsOn` capability for workflow level * chore: typo fix * chore: grammer fix * feat: Add Request Body Object (#162) * feat: Add Request Body Object * chore: fix typos in examples * Clarity on referencing Components Parameters (#149) * Clarity on referencing Components Parameters * Remove Reference Object to avoid clash with JSON Schema keyword. Replace with expression based referencing * chore: keep fixed field link names consistent * chore: Name component parameters as type Reusable Parameter Object * chore: adjust Workflow level parameters to use Reusable Parameter Objects --------- Co-authored-by: Dmytro Anansky <[email protected]> Co-authored-by: Nick Denny <[email protected]> * Add Reusable Object and referencing ability * chore: fix yaml example indentation * chore: fix JSON examples * chore: fix typo in `workflowStepActions` --------- Co-authored-by: Dmytro Anansky <[email protected]> Co-authored-by: Nick Denny <[email protected]>
OAI · Apr 3, 2024 · 5f25cc1 · 5f25cc1
1 parent aa47092
commit 5f25cc1
Showing 1 changed file with 75 additions and 10 deletions.
diff --git a/versions/1.0.0.md b/versions/1.0.0.md
@@ -59,10 +59,19 @@ The Workflows Specification can articulate these workflows in a human-readable a
         - [Components Object Example](#components-object-example)
       - [Reusable Parameter Object](#reusable-parameter-object)
         - [Fixed Fields](#fixed-fields-9)
-        - [Reusable Parameter Object Example](#reusable-parameter-object-example)      
-      - [Criterion Object](#criterion-object)
+        - [Reusable Parameter Object Example](#reusable-parameter-object-example) 
+      - [Reusable Object](#reusable-object)
         - [Fixed Fields](#fixed-fields-10)
-        - [Criterion Object Example](#criterion-object-example)          
+        - [Reusable Object Example](#reusable-object-example)                
+      - [Criterion Object](#criterion-object)
+        - [Fixed Fields](#fixed-fields-11)
+        - [Criterion Object Example](#criterion-object-example)
+      - [Request Body Object](#request-body-object)
+        - [Fixed Fields](#fixed-fields-12)
+        - [Request Body Object Example](#requestbody-object-example)
+      - [Payload Pointer Object](#payload-pointer-object)
+        - [Fixed Fields](#fixed-fields-13)
+        - [Payload Pointer Object Example](#payload-pointer-object-example)        
     - [Runtime Expressions](#runtime-expressions)
     - [Specification Extensions](#specification-extensions)
     - [Security Considerations](#security-considerations)
@@ -272,6 +281,8 @@ Field Name | Type | Description
 <a name="workflowInputs"></a>inputs | `JSON Schema` | A JSON Schema 2020-12 object representing the input parameters used by this workflow.
 <a name="dependsOn"></a>dependsOn | [`string`] | A list of workflows that MUST be completed before this workflow can be processed. The values provided MUST be a `workflowId`. If the workflow depended on is defined within the current Workflow Document, then specify the `workflowId` of the relevant local workflow. If the workflow is defined in a separate Workflows Document then the workflow MUST be defined in the `sourceDescriptions` and the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes.
 <a name="workflowSteps"></a>steps | [[Step Object](#step-object)] | **REQUIRED**. An ordered list of steps where each step represents a call to an API operation or to another workflow.
+<a name="workflowSuccessActions"></a>successActions | [[Success Action Object](#success-action-object) \| tbd] | A list of success actions that are applicable for all steps described under this workflow. These success actions can be overridden at the step level but cannot be removed there. The list MUST NOT include duplicate success actions.
+<a name="workflowFailureActions"></a>failureActions | [[Failure Action Object](#failure-action-object) \| tbd] | A list of failure actions that are applicable for all steps described under this workflow. These failure actions can be overridden at the step level but cannot be removed there. The list MUST NOT include duplicate failure actions.
 <a name="workflowOutputs"></a>outputs | Map[`string`, {expression}] |  A map between a friendly name and a dynamic output value. The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
 <a name="workflowParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Parameter Object](#reusable-parameter-object)] | A list of parameters that are applicable for all steps described under this workflow. These parameters can be overridden at the step level but cannot be removed there. Each parameter MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId` as specified within each step. If a Reusable Parameter Object is provided, it MUST link to parameters defined in the [components/parameters](#components-object) of the current Workflows document. The list MUST NOT include duplicate parameters.
 
@@ -327,11 +338,11 @@ Field Name | Type | Description
 <a name="stepOperationId"></a>operationId | `string` | The name of an existing, resolvable operation, as defined with a unique `operationId` and existing within one of the `sourceDescriptions`. The referenced operation will be invoked by this workflow step. If multiple (non `workflowsSpec` type) `sourceDescriptions` are defined, then the `operationId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<operationId>`) to avoid ambiguity or potential clashes. This field is mutually exclusive of the `operationPath` and `workflowId` fields respectively.
 <a name="stepOperationPath"></a>operationPath | `string` | A reference to a [Source](#source-description-object) combined with a [JSON Pointer](https://tools.ietf.org/html/rfc6901) to reference an operation. This field is mutually exclusive of the `operationId` and `workflowId` fields respectively. The operation being referenced MUST be described within one of the `sourceDescriptions` descriptions. A [runtime expression](#runtime-expressions) syntax MUST be used to identify the source description document. If the referenced operation has an `operationId` defined then the `operationId` SHOULD be preferred over the `operationPath`.
 <a name="stepWorkflowId"></a>workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows Description. If multiple `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes. The field is mutually exclusive of the `operationId` and `operationPath` fields respectively.
-<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Parameter Object](#reusable-parameter-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Parameter Object is provided, it MUST link to parameters defined in the [components/parameters](#components-object) of the current Workflows document. The list MUST NOT include duplicate parameters.
+<a name="stepParameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reusable Parameter Object](#reusable-parameter-object)] | A list of parameters that MUST be passed to an operation or workflow as referenced by `operationId`, `operationPath`, or `workflowId`. If a parameter is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Parameter Object is provided, it MUST link to a parameter defined in the [components/parameters](#components-object) of the current Workflows document. The list MUST NOT include duplicate parameters.
 <a name="stepRequestBody"></a>requestBody | [Request Body Object](#request-body-object) | The request body to pass to an operation as referenced by `operationId` or `operationPath`. The `requestBody` is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague (such as [GET](https://tools.ietf.org/html/rfc7231#section-4.3.1), [HEAD](https://tools.ietf.org/html/rfc7231#section-4.3.2) and [DELETE](https://tools.ietf.org/html/rfc7231#section-4.3.5)), `requestBody` is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
 <a name="stepSuccessCriteria"></a>successCriteria | [[Criterion Object](#criterion-object)] | A list of assertions to determine the success of the step. Each assertion is described using a [Criterion Object](#criterion-object). All assertions `MUST` be satisfied for the step to be deemed successful.
-<a name="stepOnSuccess"></a>onSuccess | [[Success Action Object](#success-action-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.
-<a name="stepOnFailure"></a>onFailure | [[Failure Action Object](#failure-action-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.
+<a name="stepOnSuccess"></a>onSuccess | [[Success Action Object](#success-action-object) \| [Reusable Object](#reusable-object)] | An array of success action objects that specify what to do upon step success. If omitted, the next sequential step shall be executed as the default behavior. If multiple success actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed.  If a success action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a success action defined in the [components](#components-object) of the current Workflows document. The list MUST NOT include duplicate success actions.
+<a name="stepOnFailure"></a>onFailure | [[Failure Action Object](#failure-action-object) \| [Reusable Object](#reusable-object)] | An array of failure action objects that specify what to do upon step failure. If omitted, the default behavior is to break and return. If multiple failure actions have similar `criteria`, the first sequential action matching the criteria SHALL be the action executed. If a failure action is already defined at the [Workflow](#workflow-object), the new definition will override it but can never remove it. If a Reusable Object is provided, it MUST link to a failure action defined in the [components](#components-object) of the current Workflows document. The list MUST NOT include duplicate failure actions.
 <a name="stepOutputs"></a>outputs | Map[`string`, {expression}] |  A map between a friendly name and a dynamic output value defined using a [runtime expression](#runtime-expressions). The name MUST use keys that match the regular expression: `^[a-zA-Z0-9\.\-_]+$`.
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
@@ -444,6 +455,7 @@ A single success action which describes an action to take upon success of a work
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
+<a name="successActionName"></a> name | `string` | **REQUIRED**. The name of the success action. Names are _case sensitive_.
 <a name="successActionType"></a> type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"` or `"goto"`.
 <a name="successWorkflowId"></a> workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows Description to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. If multiple `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes.  This field is mutually exclusive to `stepId`.
 <a name="successStepId"></a> stepId | `string` | The `stepId` to transfer to upon success of the step. This field is only relevant when the `type` field value is `"goto"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`.
@@ -456,6 +468,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten
 ##### Success Action Object Example
 
 ```yaml
+name: JoinWaitingList
 type: goto
 stepId: joinWaitingListStep
 criteria:
@@ -475,6 +488,7 @@ A single failure action which describes an action to take upon failure of a work
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
+<a name="failureActionName"></a> name | `string` | **REQUIRED**. The name of the failure action. Names are _case sensitive_.
 <a name="failureActionType"></a> type | `string` | **REQUIRED**. The type of action to take. Possible values are `"end"`, `"retry"`, or `"goto"`.
 <a name="failureWorkflowId"></a> workflowId | `string` | The [workflowId](#fixed-fields-2) referencing an existing workflow within the Workflows Description to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. If multiple `workflowsSpec` type `sourceDescriptions` are defined, then the `workflowId` MUST be specified using a [runtime expression](#runtime-expressions) (e.g., `$sourceDescriptions.<name>.<workflowId>`) to avoid ambiguity or potential clashes.  This field is mutually exclusive to `stepId`. When used with `"retry"`, context transfers back upon completion of the specified workflow.
 <a name="failureStepId"></a> stepId | `string` | The `stepId` to transfer to upon failure of the step. This field is only relevant when the `type` field value is `"goto"` or `"retry"`. The referenced `stepId` MUST be within the current workflow. This field is mutually exclusive to `workflowId`. When used with `"retry"`, context transfers back upon completion of the specified step.
@@ -488,6 +502,7 @@ This object MAY be extended with [Specification Extensions](#specification-exten
 ##### Failure Action Object Example
 
 ```yaml
+name: retryStep
 type: retry
 retryAfter: 1
 retryLimit: 5
@@ -508,6 +523,8 @@ Field Name | Type | Description
 ---|:---|---
 <a name="componentInputs"></a> inputs | Map[`string`, `JSON Schema`] | An object to hold reusable JSON Schema objects to be referenced from workflow inputs.
 <a name="componentParameters"></a>parameters | Map[`string`, [Parameter Object](#parameter-object)] | An object to hold reusable Parameter Objects
+<a name="componentSuccessActions"></a>successActions | Map[`string`, [Success Action Object](#success-action-object)] | An object to hold reusable Success Actions Objects.
+<a name="componentFailureActions"></a>failureActions | Map[`string`, [Failure Action Object](#failure-action-object)] | An object to hold reusable Failure Actions Objects.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -543,6 +560,16 @@ components:
         pageSize:
           type: integer
           format: int32
+  failureActions:
+    refreshToken:
+      name: refreshExpiredToken
+      type: retry
+      retryAfter: 1
+      retryLimit: 5
+      workflowId: refreshTokenWorkflowId
+      criteria:
+          # assertions to determine if this action should be executed
+          - condition: $statusCode == 401       
 ```
 
 ```json
@@ -568,21 +595,35 @@ components:
         }
       }
     }
+  },
+  "failureActions": {
+    "refreshToken": {
+      "name": "refreshExpiredToken",
+      "type": "retry",
+      "retryAfter": 1,
+      "retryLimit": 5,
+      "workflowId": "refreshTokenWorkflowId",
+      "criteria": [
+        {
+          "condition": "{$statusCode == 401}"
+        }
+      ]
+    }
   }
 }
 ```
 
 #### Reusable Parameter Object
 
-A simple object to allow reusable parameters from multiple steps in the Workflows Description.
+A simple object to allow reusable parameters from multiple steps or workflows in the Workflows Description.
 
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
 <a name="reusableParameterName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired parameter.
 <a name="reusableParameterValue"></a>value | `string` | A value by default MUST override that of the referenced parameter. 
 
-This object cannot be extended with additional properties and any properties added SHALL be ignored.
+This object cannot be extended with additional properties and any properties added MUST be ignored.
 
 ##### Reusable Parameter Object Example
 
@@ -593,11 +634,34 @@ This object cannot be extended with additional properties and any properties add
 
 ```json
   {
-    name: "{$components.parameters.page}",
+    "name": "{$components.parameters.page}",
     "value": 1
   }
 ```
 
+#### Reusable Object
+
+A simple object to allow referencing of objects contained within the [Components Object](#components-object) from locations within steps or workflows in the Workflows Description. This excludes parameters and inputs defined in the [components/parameters](#components-object). **Note** - parameters should be referenced using the [Reusable Parameter Object](#reusable-parameter-object) and inputs should use standard JSON Schema referencing using the `$ref` keyword.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="reusableObjectName"></a>name | `{expression}` | **REQUIRED**. A [runtime expression](#runtime-expressions) used to reference the desired object.
+
+This object cannot be extended with additional properties and any properties added MUST be ignored.
+
+##### Reusable Object Example
+
+```yaml
+  name: $components.successActions.notify
+```
+
+```json
+  {
+    "name": "{$components.successActions.notify}"
+  }
+```
+
 #### Criterion Object
 
 An object used to specify the context, conditions, and condition types that can be used to prove or satisfy assertions specified in [Step Object](#step-object) `successCriteria`, [Success Action Object](#success-action-object) `criteria`, and [Failure Action Object](#failure-action-object) `criteria`.
@@ -777,7 +841,7 @@ A runtime expression allows values to be defined based on information that will
 The runtime expression is defined by the following [ABNF](https://tools.ietf.org/html/rfc5234) syntax:
 
 ```abnf
-      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components.parameters." parameter-name)
+      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source / "$message." source / "$inputs." name / "$outputs." name / "$steps." name / "$workflows." name / "$sourceDescriptions." name / "$components." name / "$components.parameters." parameter-name)
       parameter-name = name ; Reuses 'name' rule for parameter names
       source = ( header-reference / query-reference / path-reference / body-reference )
       header-reference = "header." token
@@ -810,6 +874,7 @@ Response header        | `$response.header.Server` |  Single header values only
 workflow input        | `$inputs.username` or `$workflows.foo.inputs.username` |  Single input values only are available
 Step output value        | `$steps.someStep.pets` |  In situations where the output named property return payloads, references may be made to portions of the response body or the entire body.
 Workflow output value | `$outputs.bar` or `$workflows.foo.outputs.bar` |  Single input values only are available
+Components parameter | `$components.parameters.foo` | Accesses a foo parameter defined within the Components Object.
 
 Runtime expressions preserve the type of the referenced value.
 Expressions can be embedded into string values by surrounding the expression with `{}` curly braces.