Serverless Workflow DSL - Reference

Abstract

This document provides comprehensive definitions and detailed property tables for all the concepts discussed in the Serverless Workflow DSL. It serves as a reference guide, explaining the structure, components, and configurations available within the DSL. By exploring this document, users will gain a thorough understanding of how to define, configure, and manage workflows, including task definitions, flow directives, and state transitions. This foundational knowledge will enable users to effectively utilize the DSL for orchestrating serverless functions and automating processes.

Definitions

Workflow

A workflow serves as a blueprint outlining the series of tasks required to execute a specific business operation. It details the sequence in which tasks must be completed, guiding users through the process from start to finish, and helps streamline operations, ensure consistency, and optimize efficiency within an organization.

Properties

Name	Type	Required	Description
document	`document`	`yes`	Documents the defined workflow.
input	`input`	`no`	Configures the workflow's input.
use	`use`	`no`	Defines the workflow's reusable components, if any.
do	`map[string, task]`	`yes`	The task(s) that must be performed by the workflow.
timeout	`string` `timeout`	`no`	The configuration, if any, of the workflow's timeout. If a `string`, must be the name of a timeout defined in the workflow's reusable components.
output	`output`	`no`	Configures the workflow's output.
schedule	`schedule`	`no`	Configures the workflow's schedule, if any.
evaluate	`evaluate`	`no`	Configures runtime expression evaluation.

Document

Documents the workflow definition.

Name	Type	Required	Description
dsl	`string`	`yes`	The version of the DSL used to define the workflow.
namespace	`string`	`yes`	The workflow's namespace.
name	`string`	`yes`	The workflow's name.
version	`string`	`yes`	The workflow's semantic version
title	`string`	`no`	The workflow's title.
summary	`string`	`no`	The workflow's Markdown summary.
tags	`map[string, string]`	`no`	A key/value mapping of the workflow's tags, if any.
metadata	`map`	`no`	Additional information about the workflow.

Use

Defines the workflow's reusable components.

Name	Type	Required	Description
authentications	`map[string, authentication]`	`no`	A name/value mapping of the workflow's reusable authentication policies.
catalogs	`map[string, catalog]`	`no`	A name/value mapping of the workflow's reusable resource catalogs.
errors	`map[string, error]`	`no`	A name/value mapping of the workflow's reusable errors.
extensions	`map[string, extension]`	`no`	A list of the workflow's reusable extensions.
functions	`map[string, task]`	`no`	A name/value mapping of the workflow's reusable tasks.
retries	`map[string, retryPolicy]`	`no`	A name/value mapping of the workflow's reusable retry policies.
secrets	`string[]`	`no`	A list containing the workflow's secrets.
timeouts	`map[string, timeout]`	`no`	A name/value mapping of the workflow's reusable timeouts.

Schedule

Configures the schedule of a workflow.

Name	Type	Required	Description
every	`duration`	`no`	Specifies the duration of the interval at which the workflow should be executed. Unlike `after`, this option will run the workflow regardless of whether the previous run is still in progress. Required when no other property has been set.
cron	`string`	`no`	Specifies the schedule using a CRON expression, e.g., '0 0 * * ' for daily at midnight. Required when no other property has been set.*
after	`duration`	`no`	Specifies a delay duration that the workflow must wait before starting again after it completes. In other words, when this workflow completes, it should run again after the specified amount of time. Required when no other property has been set.
on	`eventConsumptionStrategy`	`no`	Specifies the events that trigger the workflow execution. Required when no other property has been set.

Evaluate

Configures a workflow's runtime expression evaluation.

Name	Type	Required	Description
language	`string`	`yes`	The language used for writting runtime expressions. Defaults to `jq`.
mode	`string`	`yes`	The runtime expression evaluation mode. Supported values are: - `strict`: requires all expressions to be enclosed within `${ }` for proper identification and evaluation. - `loose`: evaluates any value provided. If the evaluation fails, it results in a string with the expression as its content. Defaults to `strict`.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: order-pet
  version: '0.1.0'
  title: Order Pet - 1.0.0
  summary: >
    # Order Pet - 1.0.0
    ## Table of Contents
    - [Description](#description)
    - [Requirements](#requirements)
    ## Description
    A sample workflow used to process an hypothetic pet order using the [PetStore API](https://petstore.swagger.io/)
    ## Requirements
    ### Secrets
    - my-oauth2-secret
use:
  authentications:
    petStoreOAuth2:
      oauth2: 
        authority: https://petstore.swagger.io/.well-known/openid-configuration
        grant: client_credentials
        client:
          id: workflow-runtime
          secret: "**********"
        scopes: [ api ]
        audiences: [ runtime ]
  extensions:
    - externalLogging:
        extend: all
        before:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executing task '\($task.reference)'..." }
        after:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executed task '\($task.reference)'..." }
  functions:
    getAvailablePets:
      call: openapi
      with:
        document:
          endpoint: https://petstore.swagger.io/v2/swagger.json
        operationId: findByStatus
        parameters:
          status: available
  secrets:
    - my-oauth2-secret
do:
  - getAvailablePets:
      call: getAvailablePets
      output:
        as: "$input + { availablePets: [.[] | select(.category.name == \"dog\" and (.tags[] | .breed == $input.order.breed))] }"
  - submitMatchesByMail:
      call: http
      with:
        method: post
        endpoint:
          uri: https://fake.smtp.service.com/email/send
          authentication: 
            use: petStoreOAuth2
        body:
          from: noreply@fake.petstore.com
          to: ${ .order.client.email }
          subject: Candidates for Adoption
          body: >
            Hello ${ .order.client.preferredDisplayName }!

            Following your interest to adopt a dog, here is a list of candidates that you might be interested in:

            ${ .pets | map("-\(.name)") | join("\n") }

            Please do not hesistate to contact us at info@fake.petstore.com if your have questions.

            Hope to hear from you soon!

            ----------------------------------------------------------------------------------------------
            DO NOT REPLY
            ----------------------------------------------------------------------------------------------

Task

A task within a workflow represents a discrete unit of work that contributes to achieving the overall objectives defined by the workflow.

It encapsulates a specific action or set of actions that need to be executed in a predefined order to advance the workflow towards its completion.

Tasks are designed to be modular and focused, each serving a distinct purpose within the broader context of the workflow.

By breaking down the workflow into manageable tasks, organizations can effectively coordinate and track progress, enabling efficient collaboration and ensuring that work is completed in a structured and organized manner.

The Serverless Workflow DSL defines a list of tasks that must be supported by all runtimes:

Call, used to call services and/or functions.
Do, used to define one or more subtasks to perform in sequence.
Fork, used to define one or more subtasks to perform concurrently.
Emit, used to emit events.
For, used to iterate over a collection of items, and conditionally perform a task for each of them.
Listen, used to listen for an event or more.
Raise, used to raise an error and potentially fault the workflow.
Run, used to run a container, a script , a shell command or even another workflow.
Switch, used to dynamically select and execute one of multiple alternative paths based on specified conditions
Set, used to dynamically set the workflow's data during the its execution.
Try, used to attempt executing a specified task, and to handle any resulting errors gracefully, allowing the workflow to continue without interruption.
Wait, used to pause or wait for a specified duration before proceeding to the next task.

Properties

Name	Type	Required	Description
if	`string`	`no`	A `runtime expression`, if any, used to determine whether or not the task should be run. The task is considered skipped if not run, and the raw task input becomes the task's output. The expression is evaluated against the raw task input before any other expression of the task.
input	`input`	`no`	An object used to customize the task's input and to document its schema, if any.
output	`output`	`no`	An object used to customize the task's output and to document its schema, if any.
export	`export`	`no`	An object used to customize the content of the workflow context.
timeout	`string` `timeout`	`no`	The configuration of the task's timeout, if any. If a `string`, must be the name of a timeout defined in the workflow's reusable components.
then	`flowDirective`	`no`	The flow directive to execute next. If not set, defaults to `continue`.
metadata	`map`	`no`	Additional information about the task.

Call

Enables the execution of a specified function within a workflow, allowing seamless integration with custom business logic or external services.

Properties

Name	Type	Required	Description
call	`string`	`yes`	The name of the function to call.
with	`map`	`no`	A name/value mapping of the parameters to call the function with

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: call-example
  version: '0.1.0'
do:
  - getPet:
      call: http
      with:
        method: get
        endpoint: https://petstore.swagger.io/v2/pet/{petId}

Serverless Workflow defines several default functions that MUST be supported by all implementations and runtimes:

AsyncAPI
gRPC
HTTP
OpenAPI

AsyncAPI Call

The AsyncAPI Call enables workflows to interact with external services described by AsyncAPI.

Properties

Name	Type	Required	Description
document	`externalResource`	`yes`	The AsyncAPI document that defines the operation 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's `publish` operation will be executed, or `subscription`, in which case the channel'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 to call. Used only in case the referenced document uses AsyncAPI `v3.0.0`.
server	`asyncApiServer`	`no`	An object used to configure to the server to call the specified AsyncAPI operation on. If not set, default to the first server matching the operation's channel.
protocol	`string`	`no`	The protocol to use to select the target server. Ignored if `server` has been set. Supported values are: `amqp`, `amqp1`, `anypointmq`, `googlepubsub`, `http`, `ibmmq`, `jms`, `kafka`, `mercure`, `mqtt`, `mqtt5`, `nats`, `pulsar`, `redis`, `sns`, `solace`, `sqs`, `stomp` and `ws`
message	`asyncApiMessage`	`no`	An object used to configure the message to publish using the target operation. Required if `subscription` has not been set.
subscription	`asyncApiSubscription`	`no`	An object used to configure the subscription to messages consumed using the target operation. Required if `message` has not been set.
authentication	`string` `authentication`	`no`	The authentication policy, or the name of the authentication policy, to use when calling the AsyncAPI operation.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - publishGreetings:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: greet
        server:
          name: greetingsServer
          variables:
            environment:  dev
        message:
          payload:
            greetings: Hello, World!
          headers:
            foo: bar
            bar: baz
  - subscribeToChatInbox:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: chat-inbox
        protocol: http
        subscription:
          filter: ${ . == $workflow.input.chat.roomId } 
          consume:
            amount: 5
            for:
              seconds: 10

gRPC Call

The gRPC Call enables communication with external systems via the gRPC protocol, enabling efficient and reliable communication between distributed components.

Properties

Name	Type	Required	Description
proto	`externalResource`	`yes`	The proto resource that describes the GRPC service to call.
service.name	`string`	`yes`	The name of the GRPC service to call.
service.host	`string`	`yes`	The hostname of the GRPC service to call.
service.port	`integer`	`no`	The port number of the GRPC service to call.
service.authentication	`authentication`	`no`	The authentication policy, or the name of the authentication policy, to use when calling the GRPC service.
method	`string`	`yes`	The name of the GRPC service method to call.
arguments	`map`	`no`	A name/value mapping of the method call's arguments, if any.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: grpc-example
  version: '0.1.0'
do:
  - greet:
      call: grpc
      with:
        proto: 
          endpoint: file://app/greet.proto
        service:
          name: GreeterApi.Greeter
          host: localhost
          port: 5011
        method: SayHello
        arguments:
          name: ${ .user.preferredDisplayName }

HTTP Call

The HTTP Call enables workflows to interact with external services over HTTP.

Properties

Name	Type	Required	Description
method	`string`	`yes`	The HTTP request method.
endpoint	`string`\|`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.
output	`string`	`no`	The http call's output format. Supported values are: - `raw`, which output's the base-64 encoded http response content, if any. - `content`, which outputs the content of http response, possibly deserialized. - `response`, which outputs the http response. Defaults to `content`.
redirect	`boolean`	`no`	Specifies whether redirection status codes (`300–399`) should be treated as errors. If set to `false`, runtimes must raise an error for response status codes outside the `200–299` range. If set to `true`, they must raise an error for status codes outside the `200–399` range. Defaults to `false`.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: http-example
  version: '0.1.0'
do:
  - getPet:
      call: http
      with:
        method: get
        endpoint: https://petstore.swagger.io/v2/pet/{petId}

OpenAPI Call

The OpenAPI Call enables workflows to interact with external services described by OpenAPI.

Properties

Name	Type	Required	Description
document	`externalResource`	`yes`	The OpenAPI document that defines the operation to call.
operationId	`string`	`yes`	The id of the OpenAPI operation to call.
parameters	`map`	`no`	A name/value mapping of the parameters, if any, of the OpenAPI operation to call.
authentication	`authentication`	`no`	The authentication policy, or the name of the authentication policy, to use when calling the OpenAPI operation.
output	`string`	`no`	The OpenAPI call's output format. Supported values are: - `raw`, which output's the base-64 encoded http response content, if any. - `content`, which outputs the content of http response, possibly deserialized. - `response`, which outputs the http response. Defaults to `content`.
redirect	`boolean`	`no`	Specifies whether redirection status codes (`300–399`) should be treated as errors. If set to `false`, runtimes must raise an error for response status codes outside the `200–299` range. If set to `true`, they must raise an error for status codes outside the `200–399` range. Defaults to `false`.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: openapi-example
  version: '0.1.0'
do:
  - findPet:
      call: openapi
      with:
        document: 
          endpoint: https://petstore.swagger.io/v2/swagger.json
        operationId: findPetsByStatus
        parameters:
          status: available

Do

Serves as a fundamental building block within workflows, enabling the sequential execution of multiple subtasks. By defining a series of subtasks to perform in sequence, the Do task facilitates the efficient execution of complex operations, ensuring that each subtask is completed before the next one begins.

Properties

Name	Type	Required	Description
do	`map[string, task]`	`no`	The tasks to perform sequentially.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: do-example
  version: '0.1.0'
use:
  authentications:
    fake-booking-agency-oauth2:
      oauth2:
        authority: https://fake-booking-agency.com
        grant: client_credentials
        client:
          id: serverless-workflow-runtime
          secret: secret0123456789
do:
  - bookHotel:
      call: http
      with:
        method: post
        endpoint: 
          uri: https://fake-booking-agency.com/hotels/book
          authentication: 
            use: fake-booking-agency-oauth2
        body:
          name: Four Seasons
          city: Antwerp
          country: Belgium
  - bookFlight:
      call: http
      with:
        method: post
        endpoint: 
          uri: https://fake-booking-agency.com/flights/book
          authentication: 
            use: fake-booking-agency-oauth2
        body:
          departure:
            date: '01/01/26'
            time: '07:25:00'
            from:
              airport: BRU
              city: Zaventem
              country: Belgium
          arrival:
            date: '01/01/26'
            time: '11:12:00'
            to:
              airport: LIS
              city: Lisbon
              country: Portugal

Emit

Allows workflows to publish events to event brokers or messaging systems, facilitating communication and coordination between different components and services. With the Emit task, workflows can seamlessly integrate with event-driven architectures, enabling real-time processing, event-driven decision-making, and reactive behavior based on incoming events.

Properties

Name	Type	Required	Description
emit.event	`eventProperties`	`yes`	Defines the event to emit.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: emit-example
  version: '0.1.0'
do:
  - emitEvent:
      emit:
        event:
          with:
            source: https://petstore.com
            type: com.petstore.order.placed.v1
            data:
              client:
                firstName: Cruella
                lastName: de Vil
              items:
                - breed: dalmatian
                  quantity: 101

For

Allows workflows to iterate over a collection of items, executing a defined set of subtasks for each item in the collection. This task type is instrumental in handling scenarios such as batch processing, data transformation, and repetitive operations across datasets.

Properties

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 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 that represents the condition, if any, that must be met for the iteration to continue.
do	`map[string, task]`	`yes`	The task(s) to perform for each item in the collection.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: for-example
  version: '0.1.0'
do:
  - checkup:
      for:
        each: pet
        in: .pets
        at: index
      while: .vet != null
      do:
        - waitForCheckup:
            listen:
              to:
                one:
                  with:
                    type: com.fake.petclinic.pets.checkup.completed.v2
            output:
              as: '.pets + [{ "id": $pet.id }]'

Fork

Allows workflows to execute multiple subtasks concurrently, enabling parallel processing and improving the overall efficiency of the workflow. By defining a set of subtasks to perform concurrently, the Fork task facilitates the execution of complex operations in parallel, ensuring that multiple tasks can be executed simultaneously.

Properties

Name	Type	Required	Description
fork.branches	`map[string, task]`	`no`	The tasks to perform concurrently.
fork.compete	`boolean`	`no`	Indicates whether or not the concurrent `tasks` are racing against each other, with a single possible winner, which sets the composite task's output. If set to `false`, the task returns an array that includes the outputs from each branch, preserving the order in which the branches are declared. If to `true`, the task returns only the output of the winning branch. Defaults to `false`.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: fork-example
  version: '0.1.0'
do:
  - raiseAlarm:
      fork:
        compete: true
        branches:
          - callNurse:
              call: http
              with:
                method: put
                endpoint: https://fake-hospital.com/api/v3/alert/nurses
                body:
                  patientId: ${ .patient.fullName }
                  room: ${ .room.number }
          - callDoctor:
              call: http
              with:
                method: put
                endpoint: https://fake-hospital.com/api/v3/alert/doctor
                body:
                  patientId: ${ .patient.fullName }
                  room: ${ .room.number }

Listen

Provides a mechanism for workflows to await and react to external events, enabling event-driven behavior within workflow systems.

Properties

Name	Type	Required	Description
listen.to	`eventConsumptionStrategy`	`yes`	Configures the event(s) the workflow must listen to.
listen.read	`string`	`no`	Specifies how events are read during the listen operation. Supported values are: - `data`: Reads the event's data. - `envelope`: Reads the event's envelope, including its context attributes. - `raw`: Reads the event's raw data. Defaults to `data`.
foreach	`subscriptionIterator`	`no`	Configures the iterator, if any, for processing each consumed event.

Note

A listen task produces a sequentially ordered array of all the events it has consumed, and potentially transformed using foreach.output.as.

Note

When foreach is set, the configured operations for a events must complete before moving on to the next one. As a result, consumed events should be stored in a First-In-First-Out (FIFO) queue while awaiting iteration.

Warning

Events consumed by an until clause should not be included in the task's output. These events are used solely to determine when the until condition has been met, and they do not contribute to the result or data produced by the task itself

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: listen-example
  version: '0.1.0'
do:
  - callDoctor:
      listen:
        to:
          any:
          - with:
              type: com.fake-hospital.vitals.measurements.temperature
              data: ${ .temperature > 38 }
          - with:
              type: com.fake-hospital.vitals.measurements.bpm
              data: ${ .bpm < 60 or .bpm > 100 }

Raise

Intentionally triggers and propagates errors. By employing the "Raise" task, workflows can deliberately generate error conditions, allowing for explicit error handling and fault management strategies to be implemented.

Properties

Name	Type	Required	Description
raise.error	`string` `error`	`yes`	Defines the error to raise. If a `string`, must be the name of an error defined in the workflow's reusable components.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: raise-example
  version: '0.1.0'
do:
  - processTicket:
      switch:
        - highPriority:
            when: .ticket.priority == "high"
            then: escalateToManager
        - mediumPriority:
            when: .ticket.priority == "medium"
            then: assignToSpecialist
        - lowPriority:
            when: .ticket.priority == "low"
            then: resolveTicket
        - default:
            then: raiseUndefinedPriorityError
  - raiseUndefinedPriorityError:
      raise:
        error:
          type: https://fake.com/errors/tickets/undefined-priority
          status: 400
          instance: /raiseUndefinedPriorityError
          title: Undefined Priority
  - escalateToManager:
      call: http
      with:
        method: post
        endpoint: https://fake-ticketing-system.com/tickets/escalate
        body:
          ticketId: ${ .ticket.id }
  - assignToSpecialist:
      call: http
      with:
        method: post
        endpoint: https://fake-ticketing-system.com/tickets/assign
        body:
          ticketId: ${ .ticket.id }
  - resolveTicket:
      call: http
      with:
        method: post
        endpoint: https://fake-ticketing-system.com/tickets/resolve
        body:
          ticketId: ${ .ticket.id }

Run

Provides the capability to execute external containers, shell commands, scripts, or workflows.

Properties

Name	Type	Required	Description
run.container	`container`	`no`	The definition of the container to run. Required if `script`, `shell` and `workflow` have not been set.
run.script	`script`	`no`	The definition of the script to run. Required if `container`, `shell` and `workflow` have not been set.
run.shell	`shell`	`no`	The definition of the shell command to run. Required if `container`, `script` and `workflow` have not been set.
run.workflow	`workflow`	`no`	The definition of the workflow to run. Required if `container`, `script` and `shell` have not been set.
await	`boolean`	`no`	Determines whether or not the process to run should be awaited for. When set to `false`, the task cannot wait for the process to complete and thus cannot output the process’s result. In this case, it should simply output its transformed input. Defaults to `true`.
return	`string`	`no`	Configures the output of the process. Supported values are: - `stdout`: Outputs the content of the process STDOUT. - `stderr`: Outputs the content of the process STDERR. - `code`: Outputs the process's exit code. - `all`: Outputs the exit code, the STDOUT* content and the STDERR content, wrapped into a new processResult object.* - `none`: Does not output anything. Defaults to `stdout`.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: run-example
  version: '0.1.0'
do:
  - runContainer:
      run:
        container:
          image: fake-image

  - runScript:
      run:
        script:
          language: js
          code: >
            Some cool multiline script

  - runShell:
      run:
        shell:
          command: 'echo "Hello, ${ .user.name }"'

  - runWorkflow:
      run:
        workflow:
          namespace: another-one
          name: do-stuff
          version: '0.1.0'
          input: {}

Container Process

Enables the execution of external processes encapsulated within a containerized environment, allowing workflows to interact with and execute complex operations using containerized applications, scripts, or commands.

Properties

Name	Type	Required	Description
image	`string`	`yes`	The name of the container image to run
name	`string`	`no`	A runtime expression, if any, used to give specific name to the container.
command	`string`	`no`	The command, if any, to execute on the container
ports	`map`	`no`	The container's port mappings, if any
volumes	`map`	`no`	The container's volume mappings, if any
environment	`map`	`no`	A key/value mapping of the environment variables, if any, to use when running the configured process
lifetime	`containerLifetime`	`no`	An object used to configure the container's lifetime.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: run-container-example
  version: '0.1.0'
do:
  - runContainer:
      run:
        container:
          image: fake-image

Note

When a container process is executed, runtime implementations are recommended to follow a predictable naming convention for the container name. This can improve monitoring, logging, and container lifecycle management.

The Serverless Workflow specification recommends using the following convention: {workflow.name}-{uuid}.{workflow.namespace}-{task.name}

Script Process

Enables the execution of custom scripts or code within a workflow, empowering workflows to perform specialized logic, data processing, or integration tasks by executing user-defined scripts written in various programming languages.

Properties

Name	Type	Required	Description
language	`string`	`yes`	The language of the script to run. Supported values are: `js` and `python`.
code	`string`	`no`	The script's code. Required if `source` has not been set.
source	externalResource	`no`	The script's resource. Required if `code` has not been set.
arguments	`map`	`no`	A list of the arguments, if any, of the script to run
environment	`map`	`no`	A key/value mapping of the environment variables, if any, to use when running the configured script process

Warning

To ensure cross-compatibility, Serverless Workflow strictly limits the versions of supported scripting languages. These versions may evolve with future releases. If you wish to use a different version of a language, you may do so by utilizing the container process.

Supported languages

Language	Version
`JavaScript`	`ES2024`
`Python`	`3.13.x`

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: run-script-example
  version: '0.1.0'
do:
  - runScript:
      run:
        script:
          language: js
          arguments:
            greetings: Hello, world!
          code: >
            console.log(greetings)

Shell Process

Enables the execution of shell commands within a workflow, enabling workflows to interact with the underlying operating system and perform system-level operations, such as file manipulation, environment configuration, or system administration tasks.

Properties

Name	Type	Required	Description
command	`string`	`yes`	The shell command to run
arguments	`map`	`no`	A list of the arguments of the shell command to run
environment	`map`	`no`	A key/value mapping of the environment variables, if any, to use when running the configured process

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: run-shell-example
  version: '0.1.0'
do:
  - runShell:
      run:
        shell:
          command: 'echo "Hello, ${ .user.name }"'

Workflow Process

Enables the invocation and execution of nested workflows within a parent workflow, facilitating modularization, reusability, and abstraction of complex logic or business processes by encapsulating them into standalone workflow units.

Properties

Name	Type	Required	Description
name	`string`	`yes`	The name of the workflow to run
version	`string`	`yes`	The version of the workflow to run. Defaults to `latest`
input	`any`	`no`	The data, if any, to pass as input to the workflow to execute. The value should be validated against the target workflow's input schema, if specified

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: run-workflow-example
  version: '0.1.0'
do:
  - startWorkflow:
      run:
        workflow:
          namespace: another-one
          name: do-stuff
          version: '0.1.0'
          input:
            foo: bar

Set

A task used to set data.

Properties

Name	Type	Required	Description
set	`map` `string`	`yes`	The data to set. Can be an object or a direct runtime expression.

Examples

document:
  dsl: '1.0.0'
  namespace: default
  name: set-example
  version: '0.1.0'
do:
  - setShape:
      set:
        shape: circle
        size: ${ .configuration.size }
        fill: ${ .configuration.fill }
  - setColor:
      set: ${ .configuration.color }

Switch

Enables conditional branching within workflows, allowing them to dynamically select different paths based on specified conditions or criteria

Properties

Name	Type	Required	Description
switch	`case[]`	`yes`	A name/value map of the cases to switch on

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: switch-example
  version: '0.1.0'
do:
  - processOrder:
      switch:
        - case1:
            when: .orderType == "electronic"
            then: processElectronicOrder
        - case2:
            when: .orderType == "physical"
            then: processPhysicalOrder
        - default:
            then: handleUnknownOrderType
  - processElectronicOrder:
      do:
        - validatePayment:
            call: http
            with:
              method: post
              endpoint: https://fake-payment-service.com/validate
        - fulfillOrder:
            call: http
            with:
              method: post
              endpoint: https://fake-fulfillment-service.com/fulfill
      then: exit
  - processPhysicalOrder:
      do:
        - checkInventory:
            call: http
            with:
              method: get
              endpoint: https://fake-inventory-service.com/inventory
        - packItems:
            call: http
            with:
              method: post
              endpoint: https://fake-packaging-service.com/pack
        - scheduleShipping:
            call: http
            with:
              method: post
              endpoint: https://fake-shipping-service.com/schedule
      then: exit
  - handleUnknownOrderType:
      do:
        - logWarning:
            call: http
            with:
              method: post
              endpoint: https://fake-logging-service.com/warn
        - notifyAdmin:
            call: http
            with:
              method: post
              endpoint: https://fake-notification-service.com/notify

Switch Case

Defines a switch case, encompassing a condition for matching and an associated action to execute upon a match.

Name	Type	Required	Description
when	`string`	`no`	A runtime expression used to determine whether or not the case matches. If not set, the case will be matched by default if no other case match. Note that there can be only one default case, all others MUST* set a condition.*
then	`flowDirective`	`yes`	The flow directive to execute when the case matches.

Try

Serves as a mechanism within workflows to handle errors gracefully, potentially retrying failed tasks before proceeding with alternate ones.

Properties

Name	Type	Required	Description
try	`map[string, task]`	`yes`	The task(s) to perform.
catch	`catch`	`yes`	Configures the errors to catch and how to handle them.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: try-example
  version: '0.1.0'
do:
  - trySomething:
      try:
        - invalidHttpCall:
            call: http
            with:
              method: get
              endpoint: https://
      catch:
        errors:
          with:
            type: https://serverlessworkflow.io.io/dsl/errors/types/communication
            status: 503
        as: error
        retry:
          delay:
            seconds: 3
          backoff:
            exponential: {}
          limit:
            attempt:
              count: 5

Catch

Defines the configuration of a catch clause, which a concept used to catch errors.

Properties

Name	Type	Required	Description
errors	`errorFilter`	`no`	The definition of the errors to catch.
as	`string`	`no`	The name of the runtime expression variable to save the error as. Defaults to 'error'.
when	`string`	`no`	A runtime expression used to determine whether or not to catch the filtered error.
exceptWhen	`string`	`no`	A runtime expression used to determine whether or not to catch the filtered error.
retry	`string` `retryPolicy`	`no`	The `retry policy` to use, if any, when catching `errors`. If a `string`, must be the name of a retry policy defined in the workflow's reusable components.
do	`map[string, task]`	`no`	The definition of the task(s) to run when catching an error.

Wait

Allows workflows to pause or delay their execution for a specified period of time.

Properties

Name	Type	Required	Description
wait	`string` `duration`	`yes`	The amount of time to wait. If a `string`, must be a valid ISO 8601 duration expression.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: wait-example
  version: '0.1.0'
do:
  - waitAWhile:
      wait:
        seconds: 10

Flow Directive

Flow Directives are commands within a workflow that dictate its progression.

Directive	Description
`"continue"`	Instructs the workflow to proceed with the next task in line. This action may conclude the execution of a particular workflow or branch if there are not task defined after the continue one.
`"exit"`	Completes the current scope's execution, potentially terminating the entire workflow if the current task resides within the main `do` scope.
`"end"`	Provides a graceful conclusion to the workflow execution, signaling its completion explicitly.
`string`	Continues the workflow at the task with the specified name.

Warning

Flow directives may only redirect to tasks declared within their own scope. In other words, they cannot target tasks at a different depth.

Lifecycle Events

Lifecycle events are cloud events 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`	`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

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

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

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

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

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

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`	`yes`	The error that has cause the workflow to fault.

Examples

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

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.

Examples

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

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

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

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

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

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

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`	`yes`	The error that has cause the task to fault.

Examples

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

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.

Examples

workflow: orderPetWorkflow-ix7iryakiem8j.samples
task: '/do/1/initialize'
updatedAt: '2024-07-26T16:59:57-05:00'
status: completed

External Resource

Defines an external resource.

Properties

Property	Type	Required	Description
name	`string`	`no`	The name, if any, of the defined resource.
endpoint	`endpoint`	`yes`	The endpoint at which to get the defined resource.

Examples

name: sample-resource
endpoint:
  uri: https://fake.com/resource/0123
  authentication:
    basic:
      username: admin
      password: 1234

Authentication

Defines the mechanism used to authenticate users and workflows attempting to access a service or a resource.

Properties

Property	Type	Required	Description
use	`string`	`no`	The name of the top-level authentication definition to use. Cannot be used by authentication definitions defined at top level.
basic	`basicAuthentication`	`no`	The `basic` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
bearer	`bearerAuthentication`	`no`	The `bearer` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
certificate	`certificateAuthentication`	`no`	The `certificate` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
digest	`digestAuthentication`	`no`	The `digest` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
oauth2	`oauth2`	`no`	The `oauth2` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.
oidc	`oidc`	`no`	The `oidc` authentication scheme to use, if any. Required if no other property has been set, otherwise ignored.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: authentication-example
  version: '0.1.0'
use:
  secrets:
    - usernamePasswordSecret
  authentications:
    sampleBasicFromSecret:
      basic:
        use: usernamePasswordSecret
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            use: sampleBasicFromSecret

Basic Authentication

Defines the fundamentals of a 'basic' authentication.

Properties

Property	Type	Required	Description
username	`string`	`yes`	The username to use.
password	`string`	`yes`	The password to use.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: basic-authentication-example
  version: '0.1.0'
use:
  authentications:
    sampleBasic:
      basic:
        username: admin
        password: password123
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication: 
            use: sampleBasic

Bearer Authentication

Defines the fundamentals of a 'bearer' authentication

Properties

Property	Type	Required	Description
token	`string`	`yes`	The bearer token to use.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: bearer-authentication-example
  version: '0.1.0'
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            bearer:
              token: ${ .user.token }

Certificate Authentication

Digest Authentication

Defines the fundamentals of a 'digest' authentication.

Properties

Property	Type	Required	Description
username	`string`	`yes`	The username to use.
password	`string`	`yes`	The password to use.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: digest-authentication-example
  version: '0.1.0'
use:
  authentications:
    sampleDigest:
      digest:
        username: admin
        password: password123
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication: 
            use: sampleDigest

OAUTH2 Authentication

Defines the fundamentals of an 'oauth2' authentication.

Properties

Name	Type	Required	Description
authority	`uri-template`	`yes`	The URI that references the authority to use when making OAuth2 calls.
endpoints.token	`uri-template`	`no`	The relative path to the endpoint for OAuth2 token requests. Defaults to `/oauth2/token`.
endpoints.revocation	`uri-template`	`no`	The relative path to the endpoint used to invalidate tokens. Defaults to `/oauth2/revoke`.
endpoints.introspection	`uri-template`	`no`	The relative path to the endpoint used to validate and obtain information about a token, typically to check its validity and associated metadata. Defaults to `/oauth2/introspect`.
grant	`string`	`yes`	The grant type to use. Supported values are `authorization_code`, `client_credentials`, `password`, `refresh_token` and `urn:ietf:params:oauth:grant-type:token-exchange`.
client.id	`string`	`no`	The client id to use. Required if the `client.authentication` method has not been set to `none`.
client.secret	`string`	`no`	The client secret to use, if any.
client.assertion	`string`	`no`	A JWT containing a signed assertion with your application credentials. Required when `client.authentication` has been set to `private_key_jwt`.
client.authentication	`string`	`no`	The client authentication method to use. Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt` or `none`. Defaults to `client_secret_post`.
request.encoding	`string`	`no`	The encoding of the token request. Supported values are `application/x-www-form-urlencoded` and `application/json`. Defaults to application/x-www-form-urlencoded.
issuers	`uri-template[]`	`no`	A list that contains that contains valid issuers that will be used to check against the issuer of generated tokens.
scopes	`string[]`	`no`	The scopes, if any, to request the token for.
audiences	`string[]`	`no`	The audiences, if any, to request the token for.
username	`string`	`no`	The username to use. Used only if the grant type is `Password`.
password	`string`	`no`	The password to use. Used only if the grant type is `Password`.
subject	`oauth2Token`	`no`	The security token that represents the identity of the party on behalf of whom the request is being made.
actor	`oauth2Token`	`no`	The security token that represents the identity of the acting party.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: oauth2-authentication-example
  version: '0.1.0'
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            oauth2:
              authority: https://keycloak/realms/fake-authority
              endpoints:
                token: /oauth2/token
              grant: client_credentials
              client:
                id: workflow-runtime
                secret: "**********"
              scopes: [ api ]
              audiences: [ runtime ]

OAUTH2 Token

Represents the definition of an OAUTH2 token

Properties

Property	Type	Required	Description
token	`string`	`yes`	The security token to use to use.
type	`string`	`yes`	The type of security token to use.

OpenIdConnect Authentication

Defines the fundamentals of an 'oidc' authentication.

Properties

Name	Type	Required	Description
authority	`uri-template`	`yes`	The URI that references the authority to use when making OpenIdConnect calls.
grant	`string`	`yes`	The grant type to use. Supported values are `authorization_code`, `client_credentials`, `password`, `refresh_token` and `urn:ietf:params:oauth:grant-type:token-exchange`.
client.id	`string`	`no`	The client id to use. Required if the `client.authentication` method has not been set to `none`.
client.secret	`string`	`no`	The client secret to use, if any.
client.assertion	`string`	`no`	A JWT containing a signed assertion with your application credentials. Required when `client.authentication` has been set to `private_key_jwt`.
client.authentication	`string`	`no`	The client authentication method to use. Supported values are `client_secret_basic`, `client_secret_post`, `client_secret_jwt`, `private_key_jwt` or `none`. Defaults to `client_secret_post`.
request.encoding	`string`	`no`	The encoding of the token request. Supported values are `application/x-www-form-urlencoded` and `application/json`. Defaults to application/x-www-form-urlencoded.
issuers	`uri-template[]`	`no`	A list that contains that contains valid issuers that will be used to check against the issuer of generated tokens.
scopes	`string[]`	`no`	The scopes, if any, to request the token for.
audiences	`string[]`	`no`	The audiences, if any, to request the token for.
username	`string`	`no`	The username to use. Used only if the grant type is `Password`.
password	`string`	`no`	The password to use. Used only if the grant type is `Password`.
subject	`oauth2Token`	`no`	The security token that represents the identity of the party on behalf of whom the request is being made.
actor	`oauth2Token`	`no`	The security token that represents the identity of the acting party.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: oidc-authentication-example
  version: '0.1.0'
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: 
          uri: https://secured.fake.com/sample
          authentication:
            oidc:
              authority: https://keycloak/realms/fake-authority/.well-known/openid-configuration
              grant: client_credentials
              client:
                id: workflow-runtime
                secret: "**********"
              scopes: [ api ]
              audiences: [ runtime ]

Catalog

A resource catalog is an external collection of reusable components, such as functions, that can be referenced and imported into workflows. Catalogs allow workflows to integrate with externally defined resources, making it easier to manage reuse and versioning across different workflows.

Each catalog is defined by an endpoint property, specifying the root URL where the resources are hosted, enabling workflows to access external functions and services. For portability, catalogs must adhere to a specific file structure, as defined here.

For more information about catalogs, refer to the Serverless Workflow DSL document.

Properties

Property	Type	Required	Description
endpoint	`endpoint`	`yes`	The endpoint that defines the root URL at which the catalog is located.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: catalog-example
  version: '0.1.0'
use:
  catalogs:
    global:
      endpoint:
        uri: https://github.com/serverlessworkflow/catalog
        authentication:
          basic:
            username: user
            password: '012345'
do:
  - log:
      call: log:0.5.2@global
      with:
        message: The cataloged custom function has been successfully called

Extension

Holds the definition for extending functionality, providing configuration options for how an extension extends and interacts with other components.

Extensions enable the execution of tasks prior to those they extend, offering the flexibility to potentially bypass the extended task entirely using an exit workflow directive.

Properties

Property	Type	Required	Description
extend	`string`	`yes`	The type of task to extend Supported values are: `call`, `composite`, `emit`, `extension`, `for`, `listen`, `raise`, `run`, `set`, `switch`, `try`, `wait` and `all`
when	`string`	`no`	A runtime expression used to determine whether or not the extension should apply in the specified context
before	`map[string, task]`	`no`	The task to execute, if any, before the extended task
after	`map[string, task]`	`no`	The task to execute, if any, after the extended task

Examples

Perform logging before and after any non-extension task is run:

document:
  dsl: '1.0.0'
  namespace: test
  name: logging-extension-example
  version: '0.1.0'
use:
  extensions:
    - logging:
        extend: all
        before:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executing task '\($task.reference)'..." }
        after:
          - sendLog:
              call: http
              with:
                method: post
                endpoint: https://fake.log.collector.com
                body:
                  message: ${ "Executed task '\($task.reference)'..." }
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: https://fake.com/sample

Intercept HTTP calls to 'https://mocked.service.com' and mock its response:

document:  
  dsl: '1.0.0'
  namespace: test
  name: intercept-extension-example
  version: '0.1.0'
use:
  extensions:
    - mockService:
        extend: call
        when: $task.call == "http" and ($task.with.uri != null and ($task.with.uri | startswith("https://mocked.service.com"))) or ($task.with.endpoint.uri != null and ($task.with.endpoint.uri | startswith("https://mocked.service.com")))
        before:
          - intercept:
              set:
                statusCode: 200
                headers:
                  Content-Type: application/json
                content:
                  foo:
                    bar: baz
              then: exit #using this, we indicate to the workflow we want to exit the extended task, thus just returning what we injected
do:
  - sampleTask:
      call: http
      with:
        method: get
        endpoint: https://fake.com/sample

Error

Defines the Problem Details RFC compliant description of an error.

Properties

Property	Type	Required	Description
type	`uri-template`	`yes`	A URI reference that identifies the `error` type. For cross-compatibility concerns, it is strongly recommended to use Standard Error Types whenever possible. Runtimes MUST ensure that the property has been set when raising or escalating the `error`.
status	`integer`	`yes`	The status code generated by the origin for this occurrence of the `error`. For cross-compatibility concerns, it is strongly recommended to use HTTP Status Codes whenever possible. Runtimes MUST ensure that the property has been set when raising or escalating the `error`.
instance	`string`	`no`	A JSON Pointer used to reference the component the `error` originates from. Runtimes MUST set the property when raising or escalating the `error`. Otherwise ignore.
title	`string`	`no`	A short, human-readable summary of the `error` or a runtime expression
detail	`string`	`no`	A human-readable explanation specific to this occurrence of the `error` or a runtime expression

Examples

type: https://serverlessworkflow.io/spec/1.0.0/errors/communication
title: Service Not Available
status: 503

Standard Error Types

Standard error types serve the purpose of categorizing errors consistently across different runtimes, facilitating seamless migration from one runtime environment to another.

Type	Status¹	Description
https://serverlessworkflow.io/spec/1.0.0/errors/configuration	`400`	Errors resulting from incorrect or invalid configuration settings, such as missing or misconfigured environment variables, incorrect parameter values, or configuration file errors.
https://serverlessworkflow.io/spec/1.0.0/errors/validation	`400`	Errors arising from validation processes, such as validation of input data, schema validation failures, or validation constraints not being met. These errors indicate that the provided data or configuration does not adhere to the expected format or requirements specified by the workflow.
https://serverlessworkflow.io/spec/1.0.0/errors/expression	`400`	Errors occurring during the evaluation of runtime expressions, such as invalid syntax or unsupported operations.
https://serverlessworkflow.io/spec/1.0.0/errors/authentication	`401`	Errors related to authentication failures.
https://serverlessworkflow.io/spec/1.0.0/errors/authorization	`403`	Errors related to unauthorized access attempts or insufficient permissions to perform certain actions within the workflow.
https://serverlessworkflow.io/spec/1.0.0/errors/timeout	`408`	Errors caused by timeouts during the execution of tasks or during interactions with external services.
https://serverlessworkflow.io/spec/1.0.0/errors/communication	`500`	Errors encountered while communicating with external services, including network errors, service unavailable, or invalid responses.
https://serverlessworkflow.io/spec/1.0.0/errors/runtime	`500`	Errors occurring during the runtime execution of a workflow, including unexpected exceptions, errors related to resource allocation, or failures in handling workflow tasks. These errors typically occur during the actual execution of workflow components and may require runtime-specific handling and resolution strategies.

¹ Default value. The status code that best describe the error should always be used.

Event Consumption Strategy

Represents the configuration of an event consumption strategy.

Properties

Property	Type	Required	Description
all	`eventFilter[]`	`no`	Configures the workflow to wait for all defined events before resuming execution. Required if `any` and `one` have not been set.
any	`eventFilter[]`	`no`	Configures the workflow to wait for any of the defined events before resuming execution. Required if `all` and `one` have not been set. If empty, listens to all incoming events
one	`eventFilter`	`no`	Configures the workflow to wait for the defined event before resuming execution. Required if `all` and `any` have not been set.
until	`string` `eventConsumptionStrategy`	`no`	Configures the runtime expression condition or the events that must be consumed to stop listening. Only applies if `any` has been set, otherwise ignored. If not present, once any event is received, it proceeds to the next task.

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, 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, 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, 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, that identifies the schema that `data` adheres to.
data	`any`	`no`	The event payload.

Additional properties can be supplied, see the Cloud Events specification documentation for more info.

When used in an eventFilter, 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.

Properties

Property	Type	Required	Description
with	`eventProperties`	`yes`	A name/value mapping of the attributes filtered events must define. Supports both regular expressions and runtime expressions.
correlate	`map[string, correlation]`	`no`	A name/definition mapping of the correlations to attempt when filtering events.

Correlation

A correlation is a link between events and data, established by mapping event attributes to specific data attributes, allowing for coordinated processing or handling based on event characteristics.

Properties

Property	Type	Required	Description
from	`string`	`yes`	A runtime expression used to extract the correlation value from the filtered event.
expect	`string`	`no`	A constant or a runtime expression, if any, used to determine whether or not the extracted correlation value matches expectations. If not set, the first extracted value will be used as the correlation's expectation.

Retry

The Retry is a fundamental concept in the Serverless Workflow DSL, used to define the strategy for retrying a failed task when an error is encountered during execution. This policy provides developers with fine-grained control over how and when to retry failed tasks, enabling robust error handling and fault tolerance within workflows.

Properties

Property	Type	Required	Description
when	`string`	`no`	A a runtime expression used to determine whether or not to retry running the task, in a given context.
exceptWhen	`string`	`no`	A runtime expression used to determine whether or not to retry running the task, in a given context.
limit	`retry`	`no`	The limits, if any, to impose to the retry policy.
backoff	`backoff`	`no`	The backoff strategy to use, if any.
jitter	`jitter`	`no`	The parameters, if any, that control the randomness or variability of the delay between retry attempts.

Retry Limit

The definition of a retry policy.

Property	Type	Required	Description
attempt.count	`integer`	`no`	The maximum attempts count.
attempt.duration	`duration`	`no`	The duration limit, if any, for all retry attempts.
duration	`duration`	`no`	The maximum duration, if any, during which to retry a given task.

Backoff

The definition of a retry backoff strategy.

Property	Type	Required	Description
constant	`object`	`no`	The definition of the constant backoff to use, if any. Required if `exponential` and `linear` are not set, otherwise ignored.
exponential	`object`	`no`	The definition of the exponential backoff to use, if any. Required if `constant` and `linear` are not set, otherwise ignored.
linear	`object`	`no`	The definition of the linear backoff to use, if any. Required if `constant` and `exponential` are not set, otherwise ignored.

Jitter

Represents the definition of the parameters that control the randomness or variability of a delay, typically between retry attempts

Property	Type	Required	Description
from	`duration`	`yes`	The minimum duration of the jitter range.
to	`duration`	`yes`	The maximum duration of the jitter range.

Examples

Input

Documents the structure - and optionally configures the transformation of - workflow/task input data.

It's crucial for authors to document the schema of input data whenever feasible. This documentation empowers consuming applications to provide contextual auto-suggestions when handling runtime expressions.

When set, runtimes must validate raw input data against the defined schema before applying transformations, unless defined otherwise.

Properties

Property	Type	Required	Description
schema	`schema`	`no`	The `schema` used to describe and validate raw 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, if any, used to filter and/or mutate the workflow/task input.

Examples

schema:
  format: json
  document:
    type: object
    properties:
      order:
        type: object
        required: [ pet ]
        properties:
          pet:
            type: object
            required: [ id ]
            properties:
              id:
                type: string
from: .order.pet

Output

Documents the structure - and optionally configures the transformations of - workflow/task output data.

It's crucial for authors to document the schema of output data whenever feasible. This documentation empowers consuming applications to provide contextual auto-suggestions when handling runtime expressions.

When set, runtimes must validate output data against the defined schema after applying transformations, unless defined otherwise.

Properties

Property	Type	Required	Description
schema	`schema`	`no`	The `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, if any, used to filter and/or mutate the workflow/task output.

Examples

output:
  schema:
    format: json
    document:
      type: object
      properties:
        petId:
          type: string
      required: [ petId ]
  as:
    petId: '${ .pet.id }'

Export

Certain task needs to set the workflow context to save the task output for later usage. Users set the content of the context through a runtime expression. The result of the expression is the new value of the context. The expression is evaluated against the transformed task output.

Optionally, the context might have an associated schema which is validated against the result of the expression.

Properties

Property	Type	Required	Description
schema	`schema`	`no`	The `schema` used to describe and validate context. Included to handle the non frequent case in which the context has a known format.
as	`string` `object`	`no`	A runtime expression, if any, used to export the output data to the context.

Examples

Merge the task output into the current context.

as: '$context+.'

Replace the context with the task output.

as: '.'

Schema

Describes a data schema.

Properties

Property	Type	Required	Description
format	`string`	`yes`	The schema format. Supported values are: - `json`, which indicates the JsonSchema format.
document	`object`	`no`	The inline schema document. Required if `resource` has not been set, otherwise ignored.
resource	`externalResource`	`no`	The schema external resource. Required if `document` has not been set, otherwise ignored.

Examples

Example of an inline JsonSchema:

format: json
document:
  type: object
  properties:
    id:
      type: string
    firstName:
      type: string
    lastName:
      type: string
  required: [ id, firstName, lastName ]

Example of a JsonSchema based on an external resource:

format: json
resource:
  endpoint: https://test.com/fake/schema/json/document.json

Timeout

Defines a workflow or task timeout.

Properties

Property	Type	Required	Description
after	`duration`	`yes`	The duration after which the workflow or task times out.

Examples

document:
  dsl: '1.0.0'
  namespace: default
  name: timeout-example
  version: '0.1.0'
do:
  - waitAMinute:
      wait:
        seconds: 60
timeout:
  after:
    seconds: 30

Duration

Defines a duration.

Properties

Property	Type	Required	Description
Days	`integer`	`no`	Number of days, if any.
Hours	`integer`	`no`	Number of hours, if any.
Minutes	`integer`	`no`	Number of minutes, if any.
Seconds	`integer`	`no`	Number of seconds, if any.
Milliseconds	`integer`	`no`	Number of milliseconds, if any.

Examples

Example of a duration of 2 hours, 15 minutes and 30 seconds:

hours: 2
minutes: 15
seconds: 30

Endpoint

Describes an enpoint.

Properties

Property	Type	Required	Description
uri	`string`	`yes`	The endpoint's URI.
authentication	authentication	`no`	The authentication policy to use.

HTTP Response

Describes an HTTP response.

Properties

Property	Type	Required	Description
request	`request`	`yes`	The HTTP request associated with the HTTP response.
statusCode	`integer`	`yes`	The HTTP response status code.
headers	`map[string, string]`	`no`	The HTTP response headers, if any.
content	`any`	`no`	The HTTP response content, if any. If the request's content type is one of the following, should contain the deserialized response content. Otherwise, should contain the base-64 encoded response content, if any.

Examples

request:
  method: get
  uri: https://petstore.swagger.io/v2/pet/1
  headers:
    Content-Type: application/json
headers:
  Content-Type: application/json
statusCode: 200
content:
  id: 1
  name: milou
  status: pending

HTTP Request

Describes an HTTP request.

Properties

Property	Type	Required	Description
method	`string`	`yes`	The request's method.
uri	`uri`	`yes`	The request's URI.
headers	`map[string, string]`	`no`	The HTTP request headers, if any.

Examples

method: get
uri: https://petstore.swagger.io/v2/pet/1
headers:
  Content-Type: application/json

URI Template

The DSL has limited support for URI template syntax as defined by RFC 6570. Specifically, only the Simple String Expansion is supported, which allows authors to embed variables in a URI.

To substitute a variable within a URI, use the {} syntax. The identifier inside the curly braces will be replaced with its value during runtime evaluation. If no value is found for the identifier, an empty string will be used.

This has the following limitations compared to runtime expressions:

Only top-level properties can be interpolated within strings, thus identifiers are treated verbatim. This means that {pet.id} will be replaced with the value of the "pet.id" property, not the value of the id property of the pet property.
The referenced variable must be of type string, number, boolean, or null. If the variable is of a different type an error with type https://https://serverlessworkflow.io/spec/1.0.0/errors/expression and status 400 will be raised.
Runtime expression arguments are not available for string substitution.

Examples

uri: https://petstore.swagger.io/v2/pet/{petId}

Container Lifetime

Configures the lifetime of a container.

Properties

Property	Type	Required	Description
cleanup	`string`	`yes`	The cleanup policy to use. Supported values are: - `always`: the container is deleted immediately after execution. -`never`: the runtime should never delete the container. -`eventually`: the container is deleted after a configured amount of time after its execution. Defaults to `never`.
after	`duration`	`no`	The `duration`, if any, after which to delete the container once executed. Required if `cleanup` has been set to `eventually`, otherwise ignored.

Process Result

Describes the result of a process.

Properties

Name	Type	Required	Description
code	`integer`	`yes`	The process's exit code.
stdout	`string`	`yes`	The process's STDOUT output.
stderr	`string`	`yes`	The process's STDERR output.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: run-container-example
  version: '0.1.0'
do:
  - runContainer:
      run:
        container:
          image: fake-image
          lifetime:
            cleanup: eventually
            after:
              minutes: 30
        return: stderr

  - runScript:
      run:
        script:
          language: js
          code: >
            Some cool multiline script
        return: code

  - runShell:
      run:
        shell:
          command: 'echo "Hello, ${ .user.name }"'
        return: all

  - runWorkflow:
      run:
        workflow:
          namespace: another-one
          name: do-stuff
          version: '0.1.0'
          input: {}
        return: none

AsyncAPI Server

Configures the target server of an AsyncAPI operation.

Properties

Name	Type	Required	Description
name	`string`	`yes`	The name of the server to call the specified AsyncAPI operation on.
variables	`object`	`no`	The target server's variables, if any.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - publishGreetings:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: greet
        server:
          name: greetingsServer
          variables:
            environment:  dev
        message:
          payload:
            greetings: Hello, World!
          headers:
            foo: bar
            bar: baz

AsyncAPI Outbound Message

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.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - publishGreetings:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: greet
        protocol: http
        message:
          payload:
            greetings: Hello, World!
          headers:
            foo: bar
            bar: baz

AsyncAPI Inbound Message

Configures an AsyncAPI message consumed by a subscription.

Properties

Name	Type	Required	Description
payload	`object`	`no`	The message's payload, if any.
headers	`object`	`no`	The message's headers, if any.
correlationId	`string`	`no`	The message's correlation id, if any.

Examples

payload:
  greetings: Hello, World!
headers:
  foo: bar
  bar: baz
correlationid: '123456'

AsyncAPI Subscription

Configures a subscription to an AsyncAPI operation.

Properties

Name	Type	Required	Description
filter	`string`	`no`	A runtime expression, if any, used to filter consumed messages.
consume	`subscriptionLifetime`	`yes`	An object used to configure the subscription's lifetime.
foreach	`subscriptionIterator`	`no`	Configures the iterator, if any, for processing each consumed message.

Note

An AsyncAPI subscribe operation call produces a sequentially ordered array of all the messages it has consumed, and potentially transformed using foreach.output.as.

Note

When foreach is set, the configured operations for a message must complete before moving on to the next one. As a result, consumed messages should be stored in a First-In-First-Out (FIFO) queue while awaiting iteration.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - subscribeToChatInboxForAmount:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: chat-inbox
        protocol: http
        subscription:
          filter: ${ . == $workflow.input.chat.roomId } 
          consume:
            amount: 5
            for:
              seconds: 10

AsyncAPI Subscription Lifetime

Configures the lifetime of an AsyncAPI subscription

Properties

Name	Type	Required	Description
amount	`integer`	`no`	The amount of messages to consume. Required if `while` and `until` have not been set.
for	`duration`	`no`	The `duration` that defines for how long to consume messages.
while	`string`	`no`	A runtime expression, if any, used to determine whether or not to keep consuming messages. Required if `amount` and `until` have not been set.
until	`string`	`no`	A runtime expression, if any, used to determine until when to consume messages. Required if `amount` and `while` have not been set.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - subscribeToChatInboxUntil:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: chat-inbox
        protocol: http
        subscription:
          filter: ${ . == $workflow.input.chat.roomId } 
          consume:
            until: '${ ($context.messages | length) == 5 }'
            for:
              seconds: 10

Subscription Iterator

Configures the iteration over each item (event or message) consumed by a subscription. It encapsulates configuration for processing tasks, output formatting, and export behavior for every item encountered.

Properties

Name	Type	Required	Description
item	`string`	`no`	The name of the variable used to store the current item being enumerated. Defaults to `item`.
at	`string`	`no`	The name of the variable used to store the index of the current item being enumerated. Defaults to `index`.
do	`map[string, task]`	`no`	The tasks to perform for each consumed item.
output	`output`	`no`	An object, if any, used to customize the item's output and to document its schema.
export	`export`	`no`	An object, if any, used to customize the content of the workflow context.

Examples

document:
  dsl: '1.0.0'
  namespace: test
  name: asyncapi-example
  version: '0.1.0'
do:
  - subscribeToChatInboxUntil:
      call: asyncapi
      with:
        document:
          endpoint: https://fake.com/docs/asyncapi.json
        operation: chat-inbox
        protocol: http
        subscription:
          filter: ${ . == $workflow.input.chat.roomId } 
          consume:
            until: '${ ($context.messages | length) == 5 }'
            for:
              seconds: 10
          foreach:
            item: message
            at: index
            do:
              - emitEvent:
                  emit:
                    event:
                      with:
                        source: https://serverlessworkflow.io/samples
                        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

name: greet
namespace: samples
version: '0.1.0-rc2'

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!