Basic Concepts in Amazon SWF

A workflow is a distributed application composed of coordination logic and tasks that run asynchronously across multiple computing devices. In the course of designing a workflow, you analyze your application to identify its component tasks. In Amazon SWF, these tasks are represented by activities. The order in which activities are performed is determined by the workflow's coordination logic.

After the coordination logic and the activities have been designed, you register them as workflow and activity types with Amazon SWF. During registration, you specify for each type a name, a version, and some default configuration values.

Only registered workflow and activity types can be used with Amazon SWF. In the e-commerce example, you would register the CustomerOrder workflow type and the VerifyOrder, ChargeCreditCard, ShipOrder, and RecordCompletion activity types.

After registering your workflow type, you can run it as often you like. A workflow execution is a running instance of a workflow. In the e-commerce example, a new workflow execution is started with each customer order.

A workflow execution can be started by any process or application, even another workflow execution. In the e-commerce example, what type of application initiates the workflow depends on how the customer places the order. The workflow could be initiated by a web site or mobile application or by a customer service representative using an internal company application.

With Amazon SWF, you can associate an identifier—called a workflowId—with your workflow executions, so you can integrate your existing business identifiers into your workflow. In the e-commerce example, each workflow execution might be identified using the customer invoice number.

In addition to the identifier that you provide, Amazon SWF associates a unique system-generated identifier—called a runId—with each workflow execution. Amazon SWF allows only one workflow execution with this identifier to run at any given time; although you can have multiple workflows executions of the same workflow type, each workflow execution has a distinct runId.

The progress of every workflow execution is recorded in its workflow history, which Amazon SWF maintains. The workflow history is a detailed, complete, and consistent record of every event that occurred since the workflow execution started. An event represents a discrete change in your workflow execution's state, such as a new activity being scheduled or a running activity being completed. The workflow history contains every event that causes the execution state of the workflow execution to change, such as scheduled and completed activities, task timeouts, and signals.

Operations that do not change the state of the workflow execution do not typically appear in the workflow history. For example, the workflow history does not show poll attempts or the use of visibility operations.

The workflow history has several key benefits:

The following is a conceptual view of the e-commerce workflow history:

    Invoice0001
    Start Workflow Execution
    Schedule Verify Order
    Start Verify Order Activity
    Complete Verify Order Activity
    Schedule Charge Credit Card
    Start Charge Credit Card Activity
    Complete Charge Credit Card Activity
    Schedule Ship Order
    Start Ship Order Activity

In the preceding example, the order is waiting to ship. In the following example, the order is complete. Because the workflow history is cumulative, the newer events are appended:

    Invoice0001
    Start Workflow Execution
    Schedule Verify Order
    Start Verify Order Activity
    Complete Verify Order Activity
    Schedule Charge Credit Card
    Start Charge Credit Card Activity
    Complete Charge Credit Card Activity
    Schedule Ship Order
    Start Ship Order Activity
    
    Complete Ship Order Activity
    Schedule Record Order Completion
    Start Record Order Completion Activity
    Complete Record Order Completion Activity
    Close Workflow
    

Programmatically, the events in the workflow execution history are represented as JavaScript Object Notation (JSON) objects. The history itself is a JSON array of these objects. Each event has the following:

In addition, each type of event has a distinct set of descriptive attributes that are appropriate to that type. For example, the ActivityTaskCompleted event has attributes that contain the IDs for the events that correspond to the time that the activity task was scheduled and when it was started, as well as an attribute that holds result data.

You can obtain a copy of the current state of the workflow execution history by using the GetWorkflowExecutionHistory action. In addition, as part of the interaction between Amazon SWF and the decider for your workflow, the decider periodically receives copies of the history.

Below is a section of an example workflow execution history in JSON format.

  [
    {"eventId": 11, 
     "eventTimestamp": 1326671603.102, 
     "eventType": "WorkflowExecutionTimedOut", 
     "workflowExecutionTimedOutEventAttributes": 
      {"childPolicy": "TERMINATE", 
       "timeoutType": "START_TO_CLOSE"}
    }, 
    {"decisionTaskScheduledEventAttributes": 
      {"startToCloseTimeout": "600", 
       "taskList": 
        {"name": "specialTaskList"}
      }, 
     "eventId": 10, 
     "eventTimestamp": 1326670566.124, 
     "eventType": "DecisionTaskScheduled"}, 
    {"activityTaskTimedOutEventAttributes": 
      {"details": "Waiting for confirmation", 
       "scheduledEventId": 8, 
       "startedEventId": 0, 
       "timeoutType": "SCHEDULE_TO_START"}, 
     "eventId": 9, 
     "eventTimestamp": 1326670566.124, 
     "eventType": "ActivityTaskTimedOut"}, 
    {"activityTaskScheduledEventAttributes": 
      {"activityId": "verification-27", 
       "activityType": 
        {"name": "activityVerify", 
         "version": "1.0"}, 
       "control": "digital music", 
       "decisionTaskCompletedEventId": 7, 
       "heartbeatTimeout": "120", 
       "input": "5634-0056-4367-0923,12/12,437", 
       "scheduleToCloseTimeout": "900", 
       "scheduleToStartTimeout": "300", 
       "startToCloseTimeout": "600", 
       "taskList": 
        {"name": "specialTaskList"}
      }, 
     "eventId": 8, 
     "eventTimestamp": 1326670266.115, 
     "eventType": "ActivityTaskScheduled"}, 
    {"decisionTaskCompletedEventAttributes": 
      {"executionContext": "Black Friday", 
       "scheduledEventId": 5, 
       "startedEventId": 6}, 
     "eventId": 7, 
     "eventTimestamp": 1326670266.103, 
     "eventType": "DecisionTaskCompleted"}, 
    {"decisionTaskStartedEventAttributes": 
      {"identity": "Decider01", 
       "scheduledEventId": 5}, 
     "eventId": 6, 
     "eventTimestamp": 1326670161.497, 
     "eventType": "DecisionTaskStarted"}, 
    {"decisionTaskScheduledEventAttributes": 
      {"startToCloseTimeout": "600", 
       "taskList": 
        {"name": "specialTaskList"}
      }, 
     "eventId": 5, 
     "eventTimestamp": 1326668752.66, 
     "eventType": "DecisionTaskScheduled"}, 
    {"decisionTaskTimedOutEventAttributes": 
      {"scheduledEventId": 2, 
       "startedEventId": 3, 
       "timeoutType": "START_TO_CLOSE"}, 
     "eventId": 4, 
     "eventTimestamp": 1326668752.66, 
     "eventType": "DecisionTaskTimedOut"}, 
    {"decisionTaskStartedEventAttributes": 
      {"identity": "Decider01", 
       "scheduledEventId": 2}, 
     "eventId": 3, 
     "eventTimestamp": 1326668152.648, 
     "eventType": "DecisionTaskStarted"}, 
    {"decisionTaskScheduledEventAttributes": 
      {"startToCloseTimeout": "600", 
       "taskList": 
        {"name": "specialTaskList"}
      }, 
     "eventId": 2, 
     "eventTimestamp": 1326668003.094, 
     "eventType": "DecisionTaskScheduled"}
  ], 

For a detailed list of the different types of events that can appear in the workflow execution history, see the HistoryEvent data type in the .

Amazon SWF stores the complete history of all workflow executions for a configurable number of days after the execution closes. This period, which is known as the workflow history retention period, is specified when you register a Domain for your workflow. Domains are discussed in greater detail later in this section.

In the course of its operations, Amazon SWF interacts with a number of different types of programmatic actors. Actors can be workflow starters, deciders, or activity workers. These actors communicate with Amazon SWF through its API. You can develop these actors in any programming language.

The following diagram shows the Amazon SWF architecture, including Amazon SWF and its actors.

Workflow Starters

A workflow starter is any application that can initiate workflow executions. In the e-commerce example, one workflow starter could be the website at which the customer places an order. Another workflow starter could be a mobile application or system used by a customer service representative to place the order on behalf of the customer.

Deciders

A decider is an implementation of a workflow's coordination logic. Deciders control the flow of activity tasks in a workflow execution. Whenever a change occurs during a workflow execution, such as the completion of an activity task, Amazon SWF creates a decision task that contains the workflow history up to that point in time and assigns the task to a decider. When the decider receives the decision task from Amazon SWF, it analyzes the workflow execution history to determine the next appropriate steps in the workflow execution. The decider communicates these steps back to Amazon SWF using decisions. A decision is an Amazon SWF data type that can represent various next actions. For a list of the possible decisions, go to Decision in the .

Here is an example of a decision in JSON format, the format in which it is transmitted to Amazon SWF. This decision schedules a new activity task.

{"decisionType": "ScheduleActivityTask", 
 "scheduleActivityTaskDecisionAttributes": 
  {"activityType": 
    {"name": "activityVerify", 
     "version": "1.0"}, 
   "activityId": "verification-27", 
   "control": "digital music", 
   "input": "5634-0056-4367-0923,12/12,437", 
   "scheduleToCloseTimeout": "900", 
   "taskList": 
    {"name": "specialTaskList"}, 
   "scheduleToStartTimeout": "300", 
   "startToCloseTimeout": "600", 
   "heartbeatTimeout": "120"}
}

A decider receives a decision task when the workflow execution starts and each time a state change occurs in the workflow execution. Deciders continue to move the workflow execution forward by receiving decision tasks and responding to Amazon SWF with more decisions until the decider determines that the workflow execution is complete. It then responds with a decision to close the workflow execution. After the workflow execution closes, Amazon SWF will not schedule additional tasks for that execution.

In the e-commerce example, the decider determines if each step was performed correctly, and then either schedules the next step or manages any error conditions.

A decider represents a single computer process or thread. Multiple deciders can process tasks for the same workflow type.

Activity Workers

An activity worker is a process or thread that performs the activity tasks that are part of your workflow. The activity task represents one of the tasks that you identified in your application.

To use an activity task in your workflow, you must register it using either the Amazon SWF console or the RegisterActivityType action.

Each activity worker polls Amazon SWF for new tasks that are appropriate for that activity worker to perform; certain tasks can be performed only by certain activity workers. After receiving a task, the activity worker processes the task to completion and then reports to Amazon SWF that the task was completed and provides the result. The activity worker then polls for a new task. The activity workers associated with a workflow execution continue in this way, processing tasks until the workflow execution itself is complete. In the e-commerce example, activity workers are independent processes and applications used by people, such as credit card processors and warehouse employees, that perform individual steps in the process.

An activity worker represents a single computer process (or thread). Multiple activity workers can process tasks of the same activity type.

Data Exchange Between Actors

Input data can be provided to a workflow execution when it is started. Similarly, input data can be provided to activity workers when they schedule activity tasks. When an activity task is complete, the activity worker can return results to Amazon SWF. Similarly, a decider can report the results of a workflow execution when the execution is complete. Each actor can send data to, and receive data from, Amazon SWF through strings, the form of which is user-defined. Depending on the size and sensitivity of the data, you can pass data directly or pass a pointer to data stored on another system or service (e.g., Amazon Simple Storage Service or Amazon SimpleDB). Both the data passed directly and the pointers to other data stores are recorded in the workflow execution history; however, Amazon SWF does not copy or cache any of the data from external stores as part of the history.

Because Amazon SWF maintains the complete execution state of each workflow execution, including the inputs and the results of tasks, all actors can be stateless. As a result, workflow processing is highly scalable. As the load on your system grows, you can simply add more actors to increase capacity.

Amazon SWF interacts with activity workers and deciders by providing them with work assignments known as tasks. There are two types of tasks in Amazon SWF:

Amazon SWF schedules a decision task when the workflow starts and whenever the state of the workflow changes, such as when an activity task completes. Each decision task contains a paginated view of the entire workflow execution history. The decider analyzes the workflow execution history and responds back to Amazon SWF with a set of decisions that specify what should occur next in the workflow execution. Essentially, every decision task gives the decider an opportunity to assess the workflow and provide direction back to Amazon SWF.

To ensure that no conflicting decisions are processed, Amazon SWF assigns each decision task to exactly one decider and allows only one decision task at a time to be active in a workflow execution.

The following table shows the relationship between the different constructs related to workflows and deciders.

When an activity worker has completed the activity task, it reports to Amazon SWF that the task was completed, and it includes any relevant results that were generated. Amazon SWF updates the workflow execution history with an event that indicates the task completed and then schedules a decision task to transmit the updated history to the decider.

Amazon SWF assigns each activity task to exactly one activity worker. Once the task is assigned, no other activity worker can claim or perform that task.

The following table shows the relationship between the different constructs related to activities.

Domains provide a way of scoping Amazon SWF resources within your AWS account. All the components of a workflow, such as the workflow type and activity types, must be specified to be in a domain. It is possible to have more than one workflow in a domain; however, workflows in different domains cannot interact with each other.

When setting up a new workflow, before you set up any of the other workflow components you need to register a domain if you have not already done so.

When you register a domain, you specify a workflow history retention period. This period is the length of time that Amazon SWF will continue to retain information about the workflow execution after the workflow execution is complete.

The following list describes how Amazon SWF objects, such as workflow executions, are uniquely identified.

Task lists provide a way of organizing the various tasks associated with a workflow. You could think of task lists as similar to dynamic queues. When a task is scheduled in Amazon SWF, you can specify a queue (task list) to put it in. Similarly, when you poll Amazon SWF for a task you say which queue (task list) to get the task from.

Task lists provide a flexible mechanism to route tasks to workers as your use case necessitates. Task lists are dynamic in that you don't need to register a task list or explicitly create it through an action: simply scheduling a task creates the task list if it doesn't already exist.

There are separate lists for activity tasks and decision tasks. A task is always scheduled on only one task list; tasks are not shared across lists.

Decision Task Lists

Each workflow execution is associated with a specific decision task list. When a workflow type is registered (RegisterWorkflowType action), you can specify a default task list for executions of that workflow type. When the workflow starter initiates the workflow execution (StartWorkflowExecution action), it has the option of specifying a different task list for that workflow execution.

When a decider polls for a new decision task (PollForDecisionTask action), the decider specifies a decision task list to draw from. A single decider could serve multiple workflow executions by calling PollForDecisionTask multiple times, using a different task list in each call, where each task list is specific to a particular workflow execution. Alternatively, the decider could poll a single decision task list that provides decision tasks for multiple workflow executions. You could also have multiple deciders serving a single workflow execution by having all of them poll the task list for that workflow execution.

Activity Task Lists

A single activity task list can contain tasks of different activity types. Tasks are scheduled on the task list in order. Amazon SWF returns the tasks from the list in order on a best effort basis. Under some circumstances, the tasks may not come off the list in order.

When an activity type is registered (RegisterActivityType action), you can specify a default task list for that activity type. By default, activity tasks of this type will be scheduled on the specified task list; however, when the decider schedules an activity task (ScheduleActivityTask decision), the decider can optionally specify a different task list on which to schedule the task. If the decider does not specify a task list, the default task list is used. As a result, you can place activity tasks on specific task lists according to attributes of the task. For example, you could place all instances of an activity task for a given credit card type on a particular task list.

Task Routing

When an activity worker polls for a new task (PollForActivityTask action), it can specify an activity task list to draw from. If it does, the activity worker will accept tasks only from that list. In this way, you can ensure that certain tasks get assigned only to particular activity workers. For example, you might create a task list that holds tasks that require the use of a high-performance computer. Only activity workers running on the appropriate hardware would poll that task list. Another example would be to create a task list for a particular geographic region. You could then ensure that only workers deployed in that region would pick up those tasks. Or you could create a task list for high-priority orders and always check that list first.

Assigning particular tasks to particular activity workers in this way is called task routing. Task routing is optional; if you do not specify a task list when scheduling an activity task, the task is automatically placed on the default task list.

Once you start a workflow execution, it is open. An open workflow execution could be closed as completed, canceled, failed, or timed out. It could also be continued as a new execution, or it could be terminated. A workflow execution could be closed by the decider, by the person administering the workflow, or by Amazon SWF.

If the decider determines that the activities of the workflow have finished, it should close the workflow execution as completed by using the RespondDecisionTaskCompleted action and pass the CompleteWorkflowExecution decision.

Alternatively, a decider might close the workflow execution as canceled or failed. In order to cancel the execution, the decider should use the RespondDecisionTaskCompleted action and pass the CancelWorkflowExecution decision.

A decider should fail the workflow execution if it enters a state outside the realm of normal completion. In order to fail the execution, the decider should use the RespondDecisionTaskCompleted action and pass the FailWorkflowExecution decision.

Amazon SWF monitors workflow executions to ensure that they do not exceed any user-specified timeout settings. If a workflow execution times out, Amazon SWF automatically closes it. For more information about timeout values, see the Timeout Types section.

A decider might also close the execution and logically continue it as a new execution using the RespondDecisionTaskCompleted action and passing the ContinueAsNewWorkflowExecution decision. This is a useful strategy for long-running workflow executions for which the history may grow too large over time.

Finally, you could terminate workflow executions directly from the Amazon SWF console or programmatically by using the TerminateWorkflowExecution API. Termination forces closure of the workflow execution. Cancellation is preferred over termination, because your deciders can manage closure of the workflow execution.

Amazon SWF would terminate a workflow execution if the execution exceeds certain service-defined limits. Amazon SWF would also terminate a child workflow if the parent workflow has terminated and the applicable child policy indicates that the child workflow should also be terminated.

The next section describes the life cycle of a workflow execution and focuses on tasks and the actors that interact with them.

From the start of a workflow execution to its completion, Amazon SWF interacts with actors by assigning them appropriate tasks, either activity tasks or decision tasks.

The following diagram shows the life cycle of an order-processing workflow execution from the perspective of components that act on it.

The following table explains each task in the preceding image.

Workflow Execution Life Cycle

Deciders and activity workers communicate with Amazon SWF using long polling. The decider or activity worker periodically initiates communication with Amazon SWF, notifying Amazon SWF of its availability to accept a task, and then specifies a task list to get tasks from. If a task is available on the specified task list, Amazon SWF returns it immediately in the response. If no task is available, Amazon SWF holds the TCP connection open for up to 60 seconds so that, if a task becomes available during that time, it can be returned in the same connection. If no task becomes available within 60 seconds, it returns an empty response and closes the connection. (An empty response is a Task structure in which the value of taskToken is an empty string.) If this happens, the decider or activity worker should poll again.

Long polling works well for high-volume task processing. Deciders and activity workers can manage their own capacity, and is easy to use when the deciders and activity workers are behind a firewall.

For more information, see Polling for Decision Tasks and Polling for Activity Tasks.

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.

For examples of how timeouts are used in Amazon SWF with the service API, see Using the Amazon SWF API.

The following timeouts apply to activity tasks. 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 below, 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 SWF places limits on the sizes of certain workflow parameters, such as the number of domains and the size of the workflow execution history. For the most recent information on the limits, see the Amazon SWF Frequently Asked Questions.