Skip to main content

​
Getting Started

This guide will walk you through creating your first Serverless Workflow. You’ll learn how to define a simple workflow that calls an HTTP service, processes data, and produces output.
Before you begin, ensure you have a Serverless Workflow runtime installed, or use one of the available SDKs to validate and test your workflow.

​
Prerequisites

  • Basic understanding of YAML or JSON
  • A text editor or IDE
  • A Serverless Workflow runtime (optional for validation)

​
Create Your First Workflow

1

Define the Workflow Document

Every workflow begins with a document section that provides metadata about your workflow:
document:
  dsl: '1.0.3'
  namespace: examples
  name: my-first-workflow
  version: '1.0.0'
  title: My First Workflow
  summary: A simple workflow that demonstrates basic concepts
The document section includes:
  • dsl: The version of the Serverless Workflow DSL
  • namespace: A logical grouping for your workflows
  • name: A unique identifier for your workflow
  • version: Semantic version of your workflow
  • title and summary: Human-readable documentation
2

Define Input and Output

Configure how your workflow receives and returns data:
input:
  schema:
    type: object
    properties:
      name:
        type: string
    required:
      - name

output:
  schema:
    type: object
    properties:
      greeting:
        type: string
Input validation ensures your workflow receives data in the expected format. If validation fails, the workflow will fault with a validation error.
3

Add Your First Task

Tasks are the fundamental computing units of a workflow. Let’s add a simple set task to create a greeting:
do:
  - greetUser:
      set:
        greeting: Hello, ${ .name }!
This task uses a runtime expression ${ .name } to access the input data and create a personalized greeting.
The Serverless Workflow DSL supports runtime expressions for dynamic data manipulation. By default, expressions use the jq language and must be enclosed in ${ } when in strict mode.
4

Call an External Service

Let’s extend the workflow to call an HTTP service. Add a call task:
do:
  - greetUser:
      set:
        greeting: Hello, ${ .name }!
  
  - fetchData:
      call: http
      with:
        method: get
        endpoint: https://api.example.com/data
The call task invokes external services using protocols like HTTP, gRPC, OpenAPI, and more.
5

Transform Output

Use the output section to shape your workflow’s final result:
do:
  - greetUser:
      set:
        greeting: Hello, ${ .name }!
  
  - fetchData:
      call: http
      with:
        method: get
        endpoint: https://api.example.com/data

output:
  as: |
    {
      greeting: .greeting,
      data: .fetchData.response
    }
The output.as expression transforms the workflow’s data before returning it to the caller.
6

Complete Workflow Example

Here’s the complete workflow:
document:
  dsl: '1.0.3'
  namespace: examples
  name: my-first-workflow
  version: '1.0.0'
  title: My First Workflow
  summary: A simple workflow that demonstrates basic concepts

input:
  schema:
    type: object
    properties:
      name:
        type: string
    required:
      - name

do:
  - greetUser:
      set:
        greeting: Hello, ${ .name }!
  
  - fetchData:
      call: http
      with:
        method: get
        endpoint: https://api.example.com/data

output:
  as: |
    {
      greeting: .greeting,
      data: .fetchData.response
    }
  schema:
    type: object
    properties:
      greeting:
        type: string
      data:
        type: object

​
Understanding Task Flow

In Serverless Workflow, tasks execute in sequence by default:
  1. The workflow begins with the first task defined
  2. Once a task completes, the next task executes
  3. Tasks can explicitly control flow using the then property
  4. The workflow ends when the last task completes or when a task explicitly ends execution
If a task raises an uncaught error, the workflow execution halts abruptly and transitions to a faulted status phase.

​
Task Types Available

The Serverless Workflow DSL provides several built-in task types:

Call

Invoke external services and functions via HTTP, gRPC, OpenAPI, and more

Set

Dynamically set or modify workflow data during execution

For

Iterate over collections and perform tasks for each item

Switch

Execute different paths based on conditions

Wait

Pause execution for a specified duration

Listen

Wait for and react to specific events

Emit

Publish events to external systems

Run

Execute containers, scripts, shell commands, or nested workflows

​
Adding Error Handling

Make your workflow fault-tolerant by adding error handling: 
do:
  - callExternalService:
      try:
        call: http
        with:
          method: get
          endpoint: https://api.example.com/data
      catch:
        errors:
          communication:
            type: https://serverlessworkflow.io/spec/1.0.0/errors/communication
        as: error
        do:
          - logError:
              set:
                errorMessage: ${ .error.message }
The try task attempts to execute a task and handles errors gracefully, allowing the workflow to continue without interruption.

​
Next Steps

Core Concepts

Deep dive into workflows, tasks, events, and data flow

DSL Reference

Complete reference for all workflow definitions and properties

Examples

Explore practical examples demonstrating specific features

Task Types

Learn about all available task types and their configurations

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us