diff --git a/dsl-reference.md b/dsl-reference.md index b10f3b3f..830d5ff6 100644 --- a/dsl-reference.md +++ b/dsl-reference.md @@ -30,6 +30,27 @@ - [Try](#try) - [Wait](#wait) + [Flow Directive](#flow-directive) + + [Lifecycle Events](#lifecycle-events) + - [Workflow Lifecycle Events](#workflow-lifecycle-events) + + [Workflow Started](#workflow-started-event) + + [Workflow Suspended](#workflow-suspended-event) + + [Workflow Resumed](#workflow-resumed-event) + + [Workflow Correlation Started](#workflow-correlation-started-event) + + [Workflow Correlation Completed](#workflow-correlation-completed-event) + + [Workflow Cancelled](#workflow-cancelled-event) + + [Workflow Faulted](#workflow-faulted-event) + + [Workflow Completed](#workflow-completed-event) + + [Workflow Status Changed](#workflow-status-changed-event) + - [Task Lifecycle Events](#task-lifecycle-events) + + [Task Created](#task-created-event) + + [Task Started](#task-started-event) + + [Task Suspended](#task-suspended-event) + + [Task Resumed](#task-resumed-event) + + [Task Retried](#task-retried-event) + + [Task Cancelled](#task-cancelled-event) + + [Task Faulted](#task-faulted-event) + + [Task Completed](#task-completed-event) + + [Task Status Changed](#task-status-changed-event) + [External Resource](#external-resource) + [Authentication](#authentication) - [Basic](#basic-authentication) @@ -60,6 +81,7 @@ + [AsyncAPI Server](#asyncapi-server) + [AsyncAPI Outbound Message](#asyncapi-outbound-message) + [AsyncAPI Subscription](#asyncapi-subscription) + + [Workflow Definition Reference](#workflow-definition-reference) + [Subscription Iterator](#subscription-iterator) ## Abstract @@ -306,7 +328,7 @@ The [AsyncAPI Call](#asyncapi-call) enables workflows to interact with external ###### Properties | Name | Type | Required | Description | -|:-------|:------:|:----------:|:--------------| +|:-----|:----:|:--------:|:------------| | document | [`externalResource`](#external-resource) | `yes` | The AsyncAPI document that defines the [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call. | | channel | `string` | `yes` | The name of the channel on which to perform the operation. The operation to perform is defined by declaring either `message`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `publish` operation will be executed, or `subscription`, in which case the [channel](https://v2.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject)'s `subscribe` operation will be executed.
*Used only in case the referenced document uses AsyncAPI `v2.6.0`.* | | operation | `string` | `yes` | A reference to the AsyncAPI [operation](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationObject) to call.
*Used only in case the referenced document uses AsyncAPI `v3.0.0`.* | @@ -1136,6 +1158,389 @@ Flow Directives are commands within a workflow that dictate its progression. | `"end"` | Provides a graceful conclusion to the workflow execution, signaling its completion explicitly. | | `string` | Continues the workflow at the task with the specified name | +### Lifecycle Events + +Lifecycle events are [cloud events](https://github.com/cloudevents/spec) used to notify users and external services about key state changes in workflows and tasks. + +#### Workflow Lifecycle Events + +##### Workflow Started Event + +The data carried by the cloud event that notifies that a workflow has started. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has started. | +| definition | [`workflowDefinitionReference`](#workflow-definition-reference) | `yes` | An object that describes the definition of the workflow that has started. | +| startedAt | `dateTime` | `yes` | The date and time at which the workflow has started. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +definition: + name: orderPetWorkflow + namespace: samples + version: '1.0.0' +startedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Workflow Suspended Event + +The data carried by the cloud event that notifies that the execution of a workflow has been suspended. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has been suspended. | +| suspendedAt | `dateTime` | `yes` | The date and time at which the workflow has been suspended. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +suspendedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Workflow Resumed Event + +The data carried by the cloud event that notifies that notifies that a workflow has been resumed. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has been resumed. | +| resumedAt | `dateTime` | `yes` | The date and time at which the workflow has been resumed. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +resumedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Workflow Correlation Started Event + +The data carried by the cloud event that notifies that a workflow has started correlating events. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has started correlating events. | +| startedAt | `dateTime` | `yes` | The date and time at which the workflow has started correlating events. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +startedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Workflow Correlation Completed Event + +The data carried by the cloud event that notifies that a workflow has completed correlating events. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has completed correlating events. | +| completedAt | `dateTime` | `yes` | The date and time at which the workflow has completed correlating events. | +| correlationKeys | `map` | `no` | A key/value mapping, if any, of the resolved correlation keys. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +completedAt: '2024-07-26T16:59:57-05:00' +correlationKeys: + petId: xt84hj202q14s + orderId: '0a7f8581-acb9-4133-a378-0460c98ea60c' +``` + +##### Workflow Cancelled Event + +The data carried by the cloud event that notifies that a workflow has been cancelled. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has been cancelled. | +| cancelledAt | `dateTime` | `yes` | The date and time at which the workflow has been cancelled. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +cancelledAt: '2024-07-26T16:59:57-05:00' +``` + +##### Workflow Faulted Event + +The data carried by the cloud event that notifies that a workflow has faulted. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow that has faulted. | +| faultedAt | `dateTime` | `yes` | The date and time at which the workflow has faulted. | +| error | [`error`](#error) | `yes` | The error that has cause the workflow to fault. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +faultedAt: '2024-07-26T16:59:57-05:00' +error: + type: https://serverlessworkflow.io/spec/1.0.0/errors/communication + title: Service Not Available + status: 503 +``` + +##### Workflow Completed Event + +The data carried by the cloud event that notifies that a workflow ran to completion. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow ran to completion. | +| completedAt | `dateTime` | `yes` | The date and time at which the workflow ran to completion. | +| output | `map` | `no` | The workflow's output, if any. | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +completedAt: '2024-07-26T16:59:57-05:00' +output: + orderId: '0a7f8581-acb9-4133-a378-0460c98ea60c' + petId: xt84hj202q14s + status: placed +``` + +##### Workflow Status Changed Event + +The data carried by the cloud event that notifies that the status phase of a workflow has changed. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| name | `string` | `yes` | The qualified name of the workflow which's status phase has changed. | +| updatedAt | `dateTime` | `yes` | The date and time at which the workflow's status phase has changed. | +| status | `string` | The workflow's current [status phase](https://github.com/serverlessworkflow/specification/blob/main/dsl.md#status-phases). | + +###### Examples + +```yaml +name: orderPetWorkflow-ix7iryakiem8j.samples +updatedAt: '2024-07-26T16:59:57-05:00' +status: completed +``` + +#### Task Lifecycle Events + +##### Task Created Event + +The data carried by the cloud event that notifies that a task has been created. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that has been created belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that has been created. | +| createdAt | `dateTime` | `yes` | The date and time at which the task has been created. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +createdAt: '2024-07-26T16:59:57-05:00' +``` + +##### Task Started Event + +The data carried by the cloud event that notifies that a task has started. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that has started belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that has started. | +| startedAt | `dateTime` | `yes` | The date and time at which the task has started. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +startedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Task Suspended Event + +The data carried by the cloud event that notifies that the execution of a task has been suspended. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that has been suspended belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that has been suspended. | +| suspendedAt | `dateTime` | `yes` | The date and time at which the task has been suspended. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +suspendedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Task Resumed Event + +The data carried by the cloud event that notifies that notifies that a task has been resumed. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that has been resumed belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that has been resumed. | +| resumedAt | `dateTime` | `yes` | The date and time at which the task has been resumed. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +resumedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Task Retried Event + +The data carried by the cloud event that notifies that notifies that a task is being retried. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that is being retried belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that is being retried. | +| retriedAt | `dateTime` | `yes` | The date and time at which the task has been retried. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +retriedAt: '2024-07-26T16:59:57-05:00' +``` + +##### Task Cancelled Event + +The data carried by the cloud event that notifies that a task has been cancelled. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that has been cancelled belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that has been cancelled. | +| cancelledAt | `dateTime` | `yes` | The date and time at which the task has been cancelled. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +cancelledAt: '2024-07-26T16:59:57-05:00' +``` + +##### Task Faulted Event + +The data carried by the cloud event that notifies that a task has been faulted. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that has faulted belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that has faulted. | +| faultedAt | `dateTime` | `yes` | The date and time at which the task has faulted. | +| error | [`error`](#error) | `yes` | The error that has cause the task to fault. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +faultedAt: '2024-07-26T16:59:57-05:00' +error: + type: https://serverlessworkflow.io/spec/1.0.0/errors/communication + title: Service Not Available + status: 503 +``` + +##### Task Completed Event + +The data carried by the cloud event that notifies that a task ran to completion. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task that ran to completion belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task that ran to completion. | +| completedAt | `dateTime` | `yes` | The date and time at which the task ran to completion. | +| output | `map` | `no` | The task's output, if any. | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +completedAt: '2024-07-26T16:59:57-05:00' +output: + orderId: '0a7f8581-acb9-4133-a378-0460c98ea60c' + petId: xt84hj202q14s + status: placed +``` + +##### Task Status Changed Event + +The data carried by the cloud event that notifies that the status phase of a task has changed. + +###### Properties + +| Name | Type | Required | Description| +|:--|:---:|:---:|:---| +| workflow | `string` | `yes` | The qualified name of the workflow the task which's status phase has changed belongs to. | +| task | `uri` | `yes` | A JSON Pointer that references the task which's status phase has changed. | +| updatedAt | `dateTime` | `yes` | The date and time at which the task's status phase has changed. | +| status | `string` | The task's current [status phase](https://github.com/serverlessworkflow/specification/blob/main/dsl.md#status-phases). | + +###### Examples + +```yaml +workflow: orderPetWorkflow-ix7iryakiem8j.samples +task: '/do/1/initialize' +updatedAt: '2024-07-26T16:59:57-05:00' +status: completed +``` + > [!WARNING] > Flow directives may only redirect to tasks declared within their own scope. In other words, they cannot target tasks at a different depth. @@ -2020,7 +2425,7 @@ Configures the target server of an AsyncAPI operation. #### Properties | Name | Type | Required | Description | -|:-------|:------:|:----------:|:--------------| +|:-----|:----:|:--------:|:------------| | name | `string` | `yes` | The name of the [server](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverObject) to call the specified AsyncAPI operation on. | | variables | `object` | `no` | The target [server's variables](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serverVariableObject), if any. | @@ -2058,7 +2463,7 @@ Configures an AsyncAPI message to publish. #### Properties | Name | Type | Required | Description | -|:-------|:------:|:----------:|:--------------| +|:-----|:----:|:--------:|:------------| | payload | `object` | `no` | The message's payload, if any. | | headers | `object` | `no` | The message's headers, if any. | @@ -2236,4 +2641,24 @@ do: type: io.serverlessworkflow.samples.asyncapi.message.consumed.v1 data: message: '${ $message }' +``` + +### Workflow Definition Reference + +References a workflow definition. + +#### Properties + +| Name | Type | Required | Description | +|:-----|:----:|:--------:|:------------| +| name | `string` | `yes` | The name of the referenced workflow definition. | +| namespace | `string` | `yes` | The namespace of the referenced workflow definition. | +| version | `string` | `yes` | The semantic version of the referenced workflow definition. | + +#### Examples + +```yaml +name: greet +namespace: samples +version: '0.1.0-rc2' ``` \ No newline at end of file diff --git a/dsl.md b/dsl.md index e0009475..465fdb68 100644 --- a/dsl.md +++ b/dsl.md @@ -9,6 +9,9 @@ - [Concepts](#concepts) + [Workflow](#workflow) - [Status Phases](#status-phases) + - [Lifecycle Events](#lifecycle-events) + + [Workflow Lifecycle Events](#workflow-lifecycle-events) + + [Task Lifecycle Events](#task-lifecycle-events) - [Components](#components) + [Task](#task) - [Scheduling](#scheduling) @@ -91,21 +94,56 @@ Additionally, workflows may optionally accept inputs and produce outputs, allowi #### Status Phases -Workflows in the Serverless Workflow DSL can exist in several phases, each indicating the current state of the workflow execution. These phases include: +Both workflows and tasks in the Serverless Workflow DSL can exist in several phases, each indicating the current state of the workflow/task execution. These phases include: | Phase | Description | | --- | --- | -| `pending` | The workflow has been initiated and is pending execution. | -| `running` | The workflow is currently in progress. | -| `waiting` | The workflow execution has been paused or halted temporarily and is waiting for something to happen. | -| `cancelled` | The workflow execution has been terminated before completion. | -| `faulted` | The workflow execution has encountered an error. | -| `completed` | The workflow execution has successfully finished all tasks. | +| `pending` | The workflow/task has been initiated and is pending execution. | +| `running` | The workflow/task is currently in progress. | +| `waiting` | The workflow/task execution is temporarily paused, awaiting either inbound event(s) or a specified time interval as defined by a [`wait`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#wait) task. | +| `suspended` | The workflow/task execution has been manually paused by a user and will remain halted until explicitly resumed. | +| `cancelled` | The workflow/task execution has been terminated before completion. | +| `faulted` | The workflow/task execution has encountered an error. | +| `completed` | The workflow/task ran to completion. | 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).* +#### Lifecycle Events + +Lifecycle [cloud events](https://github.com/cloudevents/spec) standardize notifications for key state changes in workflows and tasks—such as start, suspend, resume, cancel, fault, complete, and status change. These events carry consistent information like IDs, status transitions, timestamps, and relevant metadata, enabling users to reliably respond to updates, enhancing interoperability and simplifying integration across different implementations. + +Runtimes are expected to publish these events upon state changes. While using the [HTTP protocol binding](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md) with [structured content mode](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/bindings/http-protocol-binding.md#32-structured-content-mode) is recommended, other transports adhering to the [CloudEvents](https://github.com/cloudevents/spec) specification may be used. + +##### Workflow Lifecycle Events + +| Type | Data | Description | +|:----:|:----:|:------------| +| 
`io.serverlessworkflow.workflow.started.v1`
| [`workflowStartedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-started-event) | Notifies about the start of a workflow. | +| 
`io.serverlessworkflow.workflow.suspended.v1`
| [`workflowSupsendedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-suspended-event) | Notifies about suspending a workflow execution. | +| 
`io.serverlessworkflow.workflow.resumed.v1`
| [`workflowResumedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-resumed-event) | Notifies about resuming a workflow execution. | +| 
`io.serverlessworkflow.workflow.correlation-started.v1`
| [`workflowCorrelationStartedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-correlation-started-event) | Notifies about a workflow starting to correlate events. | +| 
`io.serverlessworkflow.workflow.correlation-completed.v1`
| [`workflowCorrelationCompletedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-correlation-completed-event) | Notifies about a workflow completing an event correlation. | +| 
`io.serverlessworkflow.workflow.cancelled.v1`
| [`workflowCancelledEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-cancelled-event) | Notifies about the cancellation of a workflow execution. | +| 
`io.serverlessworkflow.workflow.faulted.v1`
| [`workflowFaultedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-faulted-event) | Notifies about a workflow being faulted. | +| 
`io.serverlessworkflow.workflow.completed.v1`
| [`workflowCompletedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-completed-event) | Notifies about the completion of a workflow execution. | +| 
`io.serverlessworkflow.workflow.status-changed.v1`
| [`workflowStatusChangedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#workflow-status-changed-event) | Notifies about the change of a workflow's status phase. | + +##### Task Lifecycle Events + +| Type | Data | Description | +|:----:|:----:|:------------| +| 
`io.serverlessworkflow.task.created.v1`
| [`taskCreatedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-created-event) | Notifies about the creation of a task. | +| 
`io.serverlessworkflow.task.started.v1`
| [`taskStartedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-started-event) | Notifies about the start of a task. | +| 
`io.serverlessworkflow.task.suspended.v1`
| [`taskSuspendedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-suspended-event) | Notifies about suspending a task's execution. | +| 
`io.serverlessworkflow.task.resumed.v1`
| [`taskResumedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-resumed-event) | Notifies about resuming a task's execution. | +| 
`io.serverlessworkflow.task.retried.v1`
| [`taskRetriedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-retried-event) | Notifies about retrying a task's execution. | +| 
`io.serverlessworkflow.task.cancelled.v1`
| [`taskCancelledEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-cancelled-event) | Notifies about the cancellation of a task's execution. | +| 
`io.serverlessworkflow.task.faulted.v1`
| [`taskFaultedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-faulted-event) | Notifies about a task being faulted. | +| 
`io.serverlessworkflow.task.completed.v1`
| [`taskCompletedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-completed-event) | Notifies about the completion of a task's execution. | +| 
`io.serverlessworkflow.task.status-changed.v1`
| [`taskStatusChangedEvent`](https://github.com/serverlessworkflow/specification/blob/main/dsl-reference.md#task-status-changed-event) | Notifies about the change of a task's status phase. | + #### Components Serverless Workflow DSL allows for defining reusable components that can be referenced across the workflow. These include: