diff --git a/ctk/features/set.feature b/ctk/features/set.feature index c0772f88..c5fd4395 100644 --- a/ctk/features/set.feature +++ b/ctk/features/set.feature @@ -3,7 +3,7 @@ Feature: Set Task I want to ensure that set tasks can be executed within the workflow So that my implementation conforms to the expected behavior - # Tests emit tasks + # Tests set tasks Scenario: Set Task Given a workflow with definition: """yaml diff --git a/dsl-reference.md b/dsl-reference.md index c4ce431a..d36fded5 100644 --- a/dsl-reference.md +++ b/dsl-reference.md @@ -25,8 +25,8 @@ + [Shell](#shell-process) + [Script](#script-process) + [Workflow](#workflow-process) - - [Switch](#switch) - [Set](#set) + - [Switch](#switch) - [Try](#try) - [Wait](#wait) + [Flow Directive](#flow-directive) @@ -42,6 +42,7 @@ - [Standard Error Types](#standard-error-types) + [Event Consumption Strategy](#event-consumption-strategy) + [Event Filter](#event-filter) + + [Event Properties](#event-properties) + [Retry](#retry) + [Input](#input) + [Output](#output) @@ -230,9 +231,9 @@ The Serverless Workflow DSL defines a list of [tasks](#task) that **must be** su - [Call](#call), used to call services and/or functions. - [Do](#do), used to define one or more subtasks to perform in sequence. - [Fork](#fork), used to define one or more subtasks to perform concurrently. -- [Emit](#emit), used to emit [events](#event). +- [Emit](#emit), used to emit [events](#event-properties). - [For](#for), used to iterate over a collection of items, and conditionally perform a task for each of them. -- [Listen](#listen), used to listen for an [event](#event) or more. +- [Listen](#listen), used to listen for an [event](#event-properties) or more. - [Raise](#raise), used to raise an [error](#error) and potentially fault the [workflow](#workflow). - [Run](#run), used to run a [container](#container-process), a [script](#script-process) , a [shell](#shell-process) command or even another [workflow](#workflow-process). - [Switch](#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions @@ -369,7 +370,7 @@ The [HTTP Call](#http-call) enables workflows to interact with external services | Name | Type | Required | Description| |:--|:---:|:---:|:---| | method | `string` | `yes` | The HTTP request method. | -| endpoint | [`endpoint`](#endpoint) | `yes` | An URI or an object that describes the HTTP endpoint to call. | +| endpoint | `string`\|[`endpoint`](#endpoint) | `yes` | An URI or an object that describes the HTTP endpoint to call. | | headers | `map` | `no` | A name/value mapping of the HTTP headers to use, if any. | | body | `any` | `no` | The HTTP request body, if any. | | query | `map[string, any]` | `no` | A name/value mapping of the query parameters to use, if any. | @@ -496,7 +497,7 @@ Allows workflows to publish events to event brokers or messaging systems, facili | Name | Type | Required | Description | |:--|:---:|:---:|:---| -| emit.event | [`event`](#event) | `yes` | Defines the event to emit. | +| emit.event | [`eventProperties`](#event-properties) | `yes` | Defines the event to emit. | ##### Examples @@ -510,15 +511,16 @@ do: - emitEvent: emit: event: - source: https://petstore.com - type: com.petstore.order.placed.v1 - data: - client: - firstName: Cruella - lastName: de Vil - items: - - breed: dalmatian - quantity: 101 + with: + source: https://petstore.com + type: com.petstore.order.placed.v1 + data: + client: + firstName: Cruella + lastName: de Vil + items: + - breed: dalmatian + quantity: 101 ``` #### For @@ -530,9 +532,9 @@ Allows workflows to iterate over a collection of items, executing a defined set | Name | Type | Required | Description| |:--|:---:|:---:|:---| | for.each | `string` | `no` | The name of the variable used to store the current item being enumerated.
Defaults to `item`. | -| for.in | `string` | `yes` | A [runtime expression](./dsl.md/#runtime-expressions) used to get the collection to enumerate. | +| for.in | `string` | `yes` | A [runtime expression](dsl.md#runtime-expressions) used to get the collection to enumerate. | | for.at | `string` | `no` | The name of the variable used to store the index of the current item being enumerated.
Defaults to `index`. | -| while | `string` | `no` | A [runtime expression](./dsl.md/#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. | +| while | `string` | `no` | A [runtime expression](dsl.md#runtime-expressions) that represents the condition, if any, that must be met for the iteration to continue. | | do | [`task`](#task) | `yes` | The task to perform for each item in the collection. | ##### Examples @@ -965,7 +967,7 @@ do: ##### Switch Case -Defines a switch case, encompassing of a condition for matching and an associated action to execute upon a match. +Defines a switch case, encompassing a condition for matching and an associated action to execute upon a match. | Name | Type | Required | Description | |:--|:---:|:---:|:---| @@ -1390,6 +1392,28 @@ Represents the configuration of an event consumption strategy. | any | [`eventFilter[]`](#event-filter) | `no` | Configures the workflow to wait for any of the defined events before resuming execution.
*Required if `all` and `one` have not been set.* | | one | [`eventFilter`](#event-filter) | `no` | Configures the workflow to wait for the defined event before resuming execution.
*Required if `all` and `any` have not been set.* | +### Event Properties + +An event object typically includes details such as the event type, source, timestamp, and unique identifier along with any relevant data payload. The [Cloud Events specification](https://cloudevents.io/), favored by Serverless Workflow, standardizes this structure to ensure interoperability across different systems and services. + +#### Properties + +| Property | Type | Required | Description | +|----------|:----:|:--------:|-------------| +| id | `string` | `no` | Identifies the event. `source` + `id` is unique for each distinct event.
*Required when emitting an event using `emit.event.with`.* | +| source | `string` | `no` | An URI formatted string, or [runtime expression](dsl.md#runtime-expressions), that identifies the context in which an event happened. `source` + `id` is unique for each distinct event.
*Required when emitting an event using `emit.event.with`.* | +| type | `string` | `no` | Describes the type of event related to the originating occurrence.
*Required when emitting an event using `emit.event.with`.* | +| time | `string` | `no` | A string, or [runtime expression](dsl.md#runtime-expressions), representing the timestamp of when the occurrence happened. | +| subject | `string` | `no` | Describes the subject of the event in the context of the event producer. | +| datacontenttype | `string` | `no` | Content type of `data` value. If omitted, it implies the `data` is a JSON value conforming to the "application/json" media type. | +| dataschema | `string` | `no` | An URI formatted string, or [runtime expression](dsl.md#runtime-expressions), that identifies the schema that `data` adheres to. | +| data | `object` | `no` | The event payload. | + +*Additional properties can be supplied, see the Cloud Events specification [documentation](https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#extension-context-attributes) for more info.* + +*When used in an [`eventFilter`](#event-filter), at least one property must be supplied.* + + ### Event Filter An event filter is a mechanism used to selectively process or handle events based on predefined criteria, such as event type, source, or specific attributes. @@ -1398,7 +1422,7 @@ An event filter is a mechanism used to selectively process or handle events base | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| -| with | `object` | `yes` | A name/value mapping of the attributes filtered events must define. Supports both regular expressions and runtime expressions. | +| with | [`eventProperties`](#event-properties) | `yes` | A name/value mapping of the attributes filtered events must define. Supports both regular expressions and runtime expressions. | | correlate | [`map[string, correlation]`](#correlation) | `no` | A name/definition mapping of the correlations to attempt when filtering events. | ### Correlation @@ -1474,7 +1498,7 @@ When set, runtimes must validate input data against the defined schema, unless d | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| | schema | [`schema`](#schema) | `no` | The [`schema`](#schema) used to describe and validate input data.
*Even though the schema is not required, it is strongly encouraged to document it, whenever feasible.* | -| from | `string`
`object` | `no` | A [runtime expression](#runtime-expressions), if any, used to filter and/or mutate the workflow/task input. | +| from | `string`
`object` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter and/or mutate the workflow/task input. | #### Examples @@ -1503,7 +1527,7 @@ When set, runtimes must validate output data against the defined schema, unless | Property | Type | Required | Description | |----------|:----:|:--------:|-------------| | schema | [`schema`](#schema) | `no` | The [`schema`](#schema) used to describe and validate output data.
*Even though the schema is not required, it is strongly encouraged to document it, whenever feasible.* | -| as | `string`
`object` | `no` | A [runtime expression](#runtime-expressions), if any, used to filter and/or mutate the workflow/task output. | +| as | `string`
`object` | `no` | A [runtime expression](dsl.md#runtime-expressions), if any, used to filter and/or mutate the workflow/task output. | #### Examples @@ -1637,6 +1661,17 @@ minutes: 15 seconds: 30 ``` +### Endpoint + +Describes an enpoint. + +#### Properties + +| Property | Type | Required | Description | +|----------|:----:|:--------:|-------------| +| uri | `string` | `yes` | The endpoint's URI. | +| authentication | `[authentication](#authentication)` | `no` | The authentication policy to use. | + ### HTTP Response Describes an HTTP response. diff --git a/dsl.md b/dsl.md index c1ed3588..3339d767 100644 --- a/dsl.md +++ b/dsl.md @@ -81,7 +81,7 @@ Workflows in the Serverless Workflow DSL can exist in several phases, each indic Additionally, the flow of execution within a workflow can be controlled using [directives*](dsl-reference.md#flow-directive), which provide instructions to the workflow engine on how to manage and handle specific aspects of workflow execution. -**To learn more about flow directives and how they can be utilized to control the execution and behavior of workflows, please refer to [Flow Directives](dsl-reference.md#flow-directive).* +\**To learn more about flow directives and how they can be utilized to control the execution and behavior of workflows, please refer to [Flow Directives](dsl-reference.md#flow-directive).* #### Components @@ -102,14 +102,14 @@ The Serverless Workflow DSL defines several default [task](dsl-reference.md#task - [Call](dsl-reference.md#call), used to call services and/or functions. - [Do](dsl-reference.md#do), used to define one or more subtasks to perform in sequence. -- [Fork](dsl-reference.md#fork), used to define one or more two subtasks to perform in parallel. - [Emit](dsl-reference.md#emit), used to emit [events](dsl-reference.md#event). - [For](dsl-reference.md#for), used to iterate over a collection of items, and conditionally perform a task for each of them. +- [Fork](dsl-reference.md#fork), used to define one or more two subtasks to perform in parallel. - [Listen](dsl-reference.md#listen), used to listen for an [event](dsl-reference.md#event) or more. - [Raise](dsl-reference.md#raise), used to raise an [error](dsl-reference.md#error) and potentially fault the [workflow](dsl-reference.md#workflow). - [Run](dsl-reference.md#run), used to run a [container](dsl-reference.md#container-process), a [script](dsl-reference.md#script-process), a [shell](dsl-reference.md#shell-process) command or even another [workflow](dsl-reference.md#workflow-process). -- [Switch](dsl-reference.md#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions - [Set](dsl-reference.md#set), used to dynamically set or update the [workflow](dsl-reference.md#workflow)'s data during the its execution. +- [Switch](dsl-reference.md#switch), used to dynamically select and execute one of multiple alternative paths based on specified conditions - [Try](dsl-reference.md#try), used to attempt executing a specified [task](dsl-reference.md#task), and to handle any resulting [errors](dsl-reference.md#error) gracefully, allowing the [workflow](dsl-reference.md#workflow) to continue without interruption. - [Wait](dsl-reference.md#wait), used to pause or wait for a specified duration before proceeding to the next task. @@ -138,7 +138,7 @@ A workflow begins with the first task defined. Once the task has been executed, different things can happen: -- `continue`: the task ran to completion, and the next task, if any, should be executed. The task to run next is implictly the next in declaration order, or explicitly defined by the `then` property of the executed task. If the executed task is the last task, then the workflow's execution gracefully ends. +- `continue`: the task ran to completion, and the next task, if any, should be executed. The task to run next is implicitly the next in declaration order, or explicitly defined by the `then` property of the executed task. If the executed task is the last task, then the workflow's execution gracefully ends. - `fault`: the task raised an uncaught error, which abruptly halts the workflow's execution and makes it transition to `faulted` [status phase](#status-phases). - `end`: the task explicitly and gracefully ends the workflow's execution. diff --git a/schema/workflow.yaml b/schema/workflow.yaml index 3c0e34ff..9783dc2b 100644 --- a/schema/workflow.yaml +++ b/schema/workflow.yaml @@ -1,3 +1,4 @@ + $id: https://serverlessworkflow.io/schemas/1.0.0-alpha1/workflow.yaml $schema: https://json-schema.org/draft/2020-12/schema description: Serverless Workflow DSL - Workflow Schema @@ -369,37 +370,9 @@ $defs: event: type: object properties: - id: - type: string - description: The event's unique identifier - source: - description: Identifies the context in which an event happened - oneOf: - - title: LiteralSource - type: string - format: uri-template - - $ref: '#/$defs/runtimeExpression' - type: - type: string - description: This attribute contains a value describing the type of event related to the originating occurrence. - time: - oneOf: - - title: LiteralTime - type: string - format: date-time - - $ref: '#/$defs/runtimeExpression' - subject: - type: string - datacontenttype: - type: string - description: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format. - dataschema: - oneOf: - - title: LiteralDataSchema - type: string - format: uri-template - - $ref: '#/$defs/runtimeExpression' - required: [ source, type ] + with: + $ref: '#/$defs/eventProperties' + required: [ source, type ] additionalProperties: true required: [ event ] forTask: @@ -852,6 +825,40 @@ $defs: $ref: '#/$defs/referenceableAuthenticationPolicy' description: The authentication policy to use. required: [ uri ] + eventProperties: + type: object + properties: + id: + type: string + description: The event's unique identifier + source: + description: Identifies the context in which an event happened + oneOf: + - title: LiteralSource + type: string + format: uri-template + - $ref: '#/$defs/runtimeExpression' + type: + type: string + description: This attribute contains a value describing the type of event related to the originating occurrence. + time: + oneOf: + - title: LiteralTime + type: string + format: date-time + - $ref: '#/$defs/runtimeExpression' + subject: + type: string + datacontenttype: + type: string + description: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format. + dataschema: + oneOf: + - title: LiteralDataSchema + type: string + format: uri-template + - $ref: '#/$defs/runtimeExpression' + additionalProperties: true eventConsumptionStrategy: type: object unevaluatedProperties: false @@ -884,28 +891,8 @@ $defs: properties: with: title: WithEvent - type: object + $ref: '#/$defs/eventProperties' minProperties: 1 - properties: - id: - type: string - description: The event's unique identifier - source: - type: string - description: Identifies the context in which an event happened - type: - type: string - description: This attribute contains a value describing the type of event related to the originating occurrence. - time: - type: string - subject: - type: string - datacontenttype: - type: string - description: Content type of data value. This attribute enables data to carry any type of content, whereby format and encoding might differ from that of the chosen event format. - dataschema: - type: string - additionalProperties: true description: An event filter is a mechanism used to selectively process or handle events based on predefined criteria, such as event type, source, or specific attributes. correlate: type: object