Simple Workflow Service (SWF)

Get started with Simple Workflow Service (SWF) on LocalStack

3 minute read

Introduction

Simple Workflow Service (SWF) is a fully managed service offered by Amazon Web Services (AWS) that enables you to build and manage applications with distributed components and complex workflows. SWF allows you to define workflows in a way that’s separate from the actual application code, making it easier to modify and adapt workflows without changing the application logic. SWF also provides a programming framework to design, coordinate, and execute workflows that involve multiple tasks, steps, and decision points.

LocalStack allows you to use the SWF APIs in your local environment to monitor and manage workflow design, task coordination, activity implementation, and error handling. The supported APIs are available on our API coverage page, which provides information on the extent of SWF’s integration with LocalStack.

Getting started

This guide is designed for users new to Simple Workflow Service and assumes basic knowledge of the AWS CLI and our awslocal wrapper script.

Start your LocalStack container using your preferred method. We will demonstrate how to register an SWF domain and workflow using the AWS CLI.

Registering a domain

You can register an SWF domain using the RegisterDomain API. Execute the following command to register a domain named test-domain:

$ awslocal swf register-domain \
    --name test-domain \
    --workflow-execution-retention-period-in-days 1

You can use the DescribeDomain API to verify that the domain was registered successfully. Run the following command to describe the test-domain domain:

$ awslocal swf describe-domain \
    --name test-domain

The following output would be retrieved:

{
    "domainInfo": {
        "name": "test-domain",
        "status": "REGISTERED",
        "arn": "arn:aws:swf:us-east-1:000000000000:/domain/test-domain"
    },
    "configuration": {
        "workflowExecutionRetentionPeriodInDays": "1"
    }
}

List the domains

You can list all registered domains using the ListDomains API. Run the following command to list all registered domains:

$ awslocal swf list-domains --registration-status REGISTERED

To deprecate a domain, use the DeprecateDomain API. Run the following command to deprecate the test-domain domain:

$ awslocal swf deprecate-domain \
    --name test-domain

You can now list the deprecated domains using the --registration-status DEPRECATED flag:

$ awslocal swf list-domains --registration-status DEPRECATED

Registering a workflow

You can register a workflow using the RegisterWorkflowType API. Execute the following command to register a workflow named test-workflow:

$ awslocal swf register-workflow-type \
    --domain test-domain \
    --name test-workflow \
    --default-task-list name=test-task-list \
    --default-task-start-to-close-timeout 30 \
    --default-execution-start-to-close-timeout 60 \
    --default-child-policy TERMINATE \
    --workflow-version "1.0"

You can use the DescribeWorkflowType API to verify that the workflow was registered successfully. Run the following command to describe the test-workflow workflow:

$ awslocal swf describe-workflow-type \
    --domain test-domain \
    --workflow-type name=test-workflow,version=1.0

The following output would be retrieved:

{
    "typeInfo": {
        "workflowType": {
            "name": "test-workflow",
            "version": "1.0"
        },
        "status": "REGISTERED",
        "creationDate": 1420066800.0
    },
    "configuration": {
        "defaultTaskStartToCloseTimeout": "30",
        "defaultExecutionStartToCloseTimeout": "60",
        "defaultTaskList": {
            "name": "test-task-list"
        },
        "defaultChildPolicy": "TERMINATE"
    }
}

Registering an activity

You can register an activity using the RegisterActivityType API. Execute the following command to register an activity named test-activity:

$ awslocal swf register-activity-type \
    --domain test-domain \
    --name test-activity \
    --default-task-list name=test-task-list \
    --default-task-start-to-close-timeout 30 \
    --default-task-heartbeat-timeout 30 \
    --default-task-schedule-to-start-timeout 30 \
    --default-task-schedule-to-close-timeout 30 \
    --activity-version "1.0"

You can use the DescribeActivityType API to verify that the activity was registered successfully. Run the following command to describe the test-activity activity:

$ awslocal swf describe-activity-type \
    --domain test-domain \
    --activity-type name=test-activity,version=1.0

The following output would be retrieved:

{
    "typeInfo": {
        "activityType": {
            "name": "test-activity",
            "version": "1.0"
        },
        "status": "REGISTERED",
        "creationDate": 1420066800.0
    },
    "configuration": {
        "defaultTaskStartToCloseTimeout": "30",
        "defaultTaskHeartbeatTimeout": "30",
        "defaultTaskList": {
            "name": "test-task-list"
        },
        "defaultTaskScheduleToStartTimeout": "30",
        "defaultTaskScheduleToCloseTimeout": "30"
    }
}

Starting a workflow execution

You can start a workflow execution using the StartWorkflowExecution API. Execute the following command to start a workflow execution for the test-workflow workflow:

$ awslocal swf start-workflow-execution \
    --domain test-domain \
    --workflow-type name=test-workflow,version=1.0 \
    --workflow-id test-workflow-id \
    --task-list name=test-task-list \
    --input '{"foo": "bar"}'

The following output would be retrieved:

{
    "runId": "0602601afc71403abb934d8094c51668"
}

Last modified July 18, 2024: setup markdownlint (#1382) (f2ebb421e)