Amazon Simple Workflow Service Resources - Amazon Simple Workflow Service
Timeout TypesEndpointsAdditional DocumentationWeb ResourcesRuby Flow Options
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon Simple Workflow Service Resources

This chapter provides additional resources and reference information that is useful when developing workflows with Amazon SWF.

Amazon SWF Timeout Types

To ensure that workflow executions run correctly, Amazon SWF enables you to set different types of timeouts. Some timeouts specify how long the workflow can run in its entirety. Other timeouts specify how long activity tasks can take before being assigned to a worker and how long they can take to complete from the time they are scheduled. All timeouts in the Amazon SWF API are specified in seconds. Amazon SWF also supports the string NONE as a timeout value, which indicates no timeout.

For timeouts related to decision tasks and activity tasks, Amazon SWF adds an event to the workflow execution history. The attributes of the event provide information about what type of timeout occurred and which decision task or activity task was affected. Amazon SWF also schedules a decision task. When the decider receives the new decision task, it will see the timeout event in the history and take an appropriate action by calling the RespondDecisionTaskCompleted action.

A task is considered open from the time that it is scheduled until it is closed. Therefore a task is reported as open while a worker is processing it. A task is closed when a worker reports it as completed, canceled, or failed. A task may also be closed by Amazon SWF as the result of a timeout.

Timeouts in Workflow and Decision Tasks

The following diagram shows how workflow and decision timeouts are related to the lifetime of a workflow:

A workflow's lifetime, with timeouts

There are two timeout types that are relevant to workflow and decision tasks:

  • Workflow Start to Close (timeoutType: START_TO_CLOSE) – This timeout specifies the maximum time that a workflow execution can take to complete. It is set as a default during workflow registration, but it can be overridden with a different value when the workflow is started. If this timeout is exceeded, Amazon SWF closes the workflow execution and adds an event of type WorkflowExecutionTimedOut to the workflow execution history. In addition to the timeoutType, the event attributes specify the childPolicy that is in effect for this workflow execution. The child policy specifies how child workflow executions are handled if the parent workflow execution times out or otherwise terminates. For example, if the childPolicy is set to TERMINATE, then child workflow executions will be terminated. Once a workflow execution has timed out, you can't take any action on it other than visibility calls.

  • Decision Task Start to Close (timeoutType: START_TO_CLOSE) – This timeout specifies the maximum time that the corresponding decider can take to complete a decision task. It is set during workflow type registration. If this timeout is exceeded, the task is marked as timed out in the workflow execution history, and Amazon SWF adds an event of type DecisionTaskTimedOut to the workflow history. The event attributes will include the IDs for the events that correspond to when this decision task was scheduled (scheduledEventId) and when it was started (startedEventId). In addition to adding the event, Amazon SWF also schedules a new decision task to alert the decider that this decision task timed out. After this timeout occurs, an attempt to complete the timed-out decision task using RespondDecisionTaskCompleted will fail.

Timeouts in Activity Tasks

The following diagram shows how timeouts are related to the lifetime of an activity task:

A task's lifetime, with timeouts

There are four timeout types that are relevant to activity tasks:

  • Activity Task Start to Close (timeoutType: START_TO_CLOSE) – This timeout specifies the maximum time that an activity worker can take to process a task after the worker has received the task. Attempts to close a timed out activity task using RespondActivityTaskCanceled, RespondActivityTaskCompleted, and RespondActivityTaskFailed will fail.

  • Activity Task Heartbeat (timeoutType: HEARTBEAT) – This timeout specifies the maximum time that a task can run before providing its progress through the RecordActivityTaskHeartbeat action.

  • Activity Task Schedule to Start (timeoutType: SCHEDULE_TO_START) – This timeout specifies how long Amazon SWF waits before timing out the activity task if no workers are available to perform the task. Once timed out, the expired task will not be assigned to another worker.

  • Activity Task Schedule to Close (timeoutType: SCHEDULE_TO_CLOSE) – This timeout specifies how long the task can take from the time it is scheduled to the time it is complete. As a best practice, this value should not be greater than the sum of the task schedule-to-start timeout and the task start-to-close timeout.

Note

Each of the timeout types has a default value, which is generally set to NONE (infinite). The maximum time for any activity execution is limited to one year, however.

You set default values for these during activity type registration, but you can override them with new values when you schedule the activity task. When one of these timeouts occurs, Amazon SWF will add an event of type ActivityTaskTimedOut to the workflow history. The timeoutType value attribute of this event will specify which of these timeouts occurred. For each of the timeouts, the value of timeoutType is shown in parentheses. The event attributes will also include the IDs for the events that correspond to when the activity task was scheduled (scheduledEventId) and when it was started (startedEventId). In addition to adding the event, Amazon SWF also schedules a new decision task to alert the decider that the timeout occurred.

Amazon Simple Workflow Service Endpoints

A list of the current Amazon SWF Regions and Endpoints are provided in the Amazon Web Services General Reference, along with the endpoints for other services.

Amazon SWF domains and all related workflows and activities must exist within the same region to communicate with each other. Furthermore, any registered domains, workflows and activities within a region don't exist in other regions. For example, if you create a domain named "MySampleDomain" in both us-east-1 and in us-west-2, they exist as separate domains: none of the workflows, task lists, activities, or data associated with your domains are shared across regions.

If you use other Amazon resources in your workflows, such as Amazon EC2 instances, these must also exist in the same region as your Amazon SWF resources. The only exceptions to this are services that span regions, such as Amazon S3 and IAM. You can access these services from workflows that exist in any region that supports them.

Additional Documentation for the Amazon Simple Workflow Service

In addition to this Developer Guide, you may find the following documentation useful.

Amazon Simple Workflow Service API Reference

The Amazon Simple Workflow Service API Reference provides detailed information about the Amazon SWF HTTP API, including actions, request and response structures and error codes.

Amazon Flow Framework Documentation

The Amazon Flow Framework is a programming framework that simplifies the process of implementing distributed asynchronous applications that use Amazon SWF to manage their workflows and activities, so you can focus on implementing your workflow logic.

Each Amazon Flow Framework is designed to work idiomatically in the language for which it is designed, so you can work naturally with your language of choice to implement workflows with all of the benefits of Amazon SWF.

There is an Amazon Flow Framework for Java. The Amazon Flow Framework for Java Developer Guide provides information about how to obtain, set up and use the Amazon Flow Framework for Java.

Amazon SDK Documentation

The Amazon Software Development Kits (SDKs) provide access to Amazon SWF in many different programming languages. The SDKs follow the HTTP API closely, but also provide language-specific programming interfaces for some Amazon SWF features. You can find out more information about each SDK by visiting the following links.

Note

Only SDKs that have support for Amazon SWF at the time of writing are listed here. For a full list of the available Amazon SDKs, visit the Tools for Amazon Web Services page.

Java

The Amazon SDK for Java provides a Java API for Amazon infrastructure services.

To view the available documentation, see the Amazon SDK for Java Documentation page. You can also go directly to the Amazon SWF sections in the SDK reference by following these links:

JavaScript

The Amazon SDK for JavaScript allows developers to build libraries or applications that make use of Amazon services using a simple and easy-to-use API available both in the browser or inside of Node.js applications on the server.

To view the available documentation, see the Amazon SDK for JavaScript Documentation page. You can also go directly to the Amazon SWF section in the SDK reference by following this link:

.NET

The Amazon SDK for .NET is a single, downloadable package that includes Visual Studio project templates, the Amazon .NET library, C# code samples, and documentation. The Amazon SDK for .NET makes it easier for Windows developers to build .NET applications for Amazon SWF and other services.

To view the available documentation, see the Amazon SDK for .NET Documentation page. You can also go directly to the Amazon SWF sections in the SDK reference by following these links:

PHP

The Amazon SDK for PHP provides a PHP programming interface to Amazon SWF.

To view the available documentation, see the Amazon SDK for PHP Documentation page. You can also go directly to the Amazon SWF section in the SDK reference by following this link:

Python

The Amazon SDK for Python (Boto) provides a Python programming interface to Amazon SWF.

To view the available documentation, see the boto: A Python interface to Amazon Web Services page. You can also go directly to the Amazon SWF sections in the documentation by following these links:

Ruby

The Amazon SDK for Ruby provides a Ruby programming interface to Amazon SWF.

To view the available documentation, see the Amazon SDK for Ruby Documentation page. You can also go directly to the Amazon SWF section in the SDK reference by following this link:

Amazon CLI Documentation

The Amazon Command Line Interface (Amazon CLI) is a unified tool to manage your Amazon services. With just one tool to download and configure, you can control multiple Amazon services from the command line and automate them through scripts.

For more information about the Amazon CLI, see the Amazon Command Line Interface page.

For an overview of the available commands for Amazon SWF, see swf in the Amazon CLI Command Reference.

Web Resources for the Amazon Simple Workflow Service

There are a number of Web resources that you can use to learn more about Amazon SWF or to get help with using the service and developing workflows.

Amazon SWF Forum

The Amazon SWF forum provides a place for you to communicate with other Amazon SWF developers and members of the Amazon SWF development team at Amazon to ask questions and to get answers.

You can visit the forum at: Forum: Amazon Simple Workflow Service.

Amazon SWF FAQ

The Amazon SWF FAQ provide answers to frequently-asked questions about Amazon SWF, including an overview of common use cases, differences between Amazon SWF and other services, and more.

You can access the FAQ here: Amazon SWF FAQ.

Amazon SWF Videos

The Amazon Web Services channel on YouTube provides video training for all of Amazon's Web Services, including Amazon SWF. For a full list of Amazon SWF-related videos, use the following query: Simple Workflow in Amazon Web Services

Migration options for Ruby Flow

The Amazon Flow Framework for Ruby is no longer under active development. While existing code will continue to work indefinitely, there will be no new features or versions. This topic will cover usage and migration options to continue working with Amazon SWF, and information on how to migrate to Step Functions.

Option Description

Continue to use the Ruby Flow Framework

For now, the Ruby Flow Framework will continue to work. If you do nothing, your code will continue to function as it is. Plan to migrate off of the Amazon Flow Framework for Ruby in the near future.

Migrate to the Java Flow Framework

The Java Flow Framework remains in active development and will continue to receive new features and updates.

Migrate to Step Functions

Step Functions provides a way to coordinate the components of distributed applications using visual workflows controlled by a state machine.
Use the SWF API directly, without the Flow Framework You can continue to work in Ruby and use the SWF API directly instead of the Ruby Flow Framework.

The advantage the Flow Framework provides, for either Ruby or Java, is that it allows you to focus on your workflow logic. The framework handles much of the details of communication and coordination, and some of the complexity is abstracted. You can continue to have the same level of abstraction by migrating to the Java Flow Framework, or you can directly interact with Amazon SWF SDK directly.

Continue to use the Ruby Flow Framework

The Amazon Flow Framework for Ruby will continue to function as it does now in the short term. If you have workflows written in the Amazon Flow Framework for Ruby, these will continue to work. Without updates, support, or security fixes, it is best to have a firm plan to migrate off of the Amazon Flow Framework for Ruby in the near future.

Migrate to the Java Flow Framework

The Amazon Flow Framework for Java will remain in active development. Conceptually, the Amazon Flow Framework for Java is similar to Amazon Flow Framework for Ruby: you can still focus on your workflow logic, and the framework will help manage your decider logic, and will make other aspects of Amazon SWF easier to manage.

Migrate to Step Functions

Amazon Step Functions provides a service that is similar to Amazon SWF, but where your workflow logic is controlled by a state machine. Step Functions enables you to coordinate the components of distributed applications and microservices using visual workflows. You build applications from individual components that each perform a discrete function, or task, allowing you to scale and change applications quickly. Step Functions provides a reliable way to coordinate components and step through the functions of your application. A graphical console provides a way to visualize the components of your application as a series of steps. It automatically triggers and tracks each step, and retries when there are errors, so your application executes in order and as expected, every time. Step Functions logs the state of each step, so when things do go wrong, you can diagnose and debug problems quickly.

In Step Functions, you manage the coordination of your tasks using a state machine, written in declarative JSON, that is defined using the Amazon States Language. By using a state machine, you don't have to write and maintain a decider program to control your application logic. Step Functions provides an intuitive, productive, and agile approach to coordinating application components using visual workflows. You should consider using Amazon Step Functions for all your new applications, and Step Functions provides an excellent platform to migrate to for the workflows you currently have implemented in the Amazon Flow Framework for Ruby.

To help migrate your tasks to Step Functions, while continuing to leverage your Ruby language skills, Step Functions provides an example Ruby activity worker. This example uses best practices for implementing an activity worker, and can be used as a template to migrate your task logic to Step Functions. For more information, see the Example Activity Worker in Ruby topic in the Amazon Step Functions Developer Guide.

Note

For many customers, migrating to Step Functions from the Amazon Flow Framework for Ruby is the best option. But, if you require that signals intervene in your processes, or if you need to launch child processes that return a result to a parent, consider using the Amazon SWF API directly, or migrating to the Amazon Flow Framework for Java.

For more information on Amazon Step Functions, see:

Use the Amazon SWF API directly

While the Amazon Flow Framework for Ruby manages some of the complexity of Amazon SWF, you can also use the Amazon SWF API directly. Using the API directly allows you to build workflows where you have full control over implementing tasks and coordinating them, without worrying about underlying complexities such as tracking their progress and maintaining their state.