Using the Amazon SWF API

Creating a basic sequential workflow involves the following stages.

Modeling Your Workflow and Its Activities

To use Amazon SWF, model the logical steps in your application as activities. An activity represents a single logical step or task in your workflow. For example, authorizing a credit card is an activity that involves providing a credit card number and other information, and receiving an approval code or a message that the card was declined.

In addition to defining activities, you also need to define the coordination logic that handles decision points. For example, the coordination logic might schedule a different follow-up activity depending on whether the credit card was approved or declined.

The following figure shows an example of a sequential customer order workflow with four activities (Verify Order, Charge Credit Card, Ship Order, and Record Completion).

Your workflow and activity types and the workflow execution itself are all scoped to a domain. Domains isolate a set of types, executions, and task lists from others within the same account. You can register a domain by using the AWS Management Console or by using the RegisterDomain action in the Amazon SWF API. The following example uses the API. As discussed earlier, the parameters are in JavaScript Object Notation (JSON) format. The retention period is 60 days. During the retention period, all information about the workflow execution is available through visibility operations using either the AWS Management Console or the Amazon SWF API.

https://swf.us-east-1.amazonaws.com
RegisterDomain
{"name": "867530901",
 "description": "music",
 "workflowExecutionRetentionPeriodInDays": "60"}

After registering the domain, you should register the workflow type and the activity types used by the workflow. You need to register the domain first because a registered domain name is part of the required information when registering workflow and activity types.

For more information, see the RegisterDomain API in the .

The example discussed in this section registers a workflow type using the Amazon SWF API. The name and version that you specify during registration form a unique identifier for the workflow type. The specified domain must have already been registered using the RegisterDomain API.

The timeout parameters in the following example are duration values specified in seconds. For the defaultTaskStartToCloseTimeout parameter, you can use the duration specifier "NONE" to indicate no timeout. However, you cannot specify a value of "NONE" for defaultExecutionStartToCloseTimeout; there is a one-year maximum limit on the time that a workflow execution can run. Exceeding this limit always causes the workflow execution to time out. If you specify a value for defaultExecutionStartToCloseTimeout that is greater than one year, the registration will fail.

https://swf.us-east-1.amazonaws.com
RegisterWorkflowType
{"domain": "867530901",
 "name": "customerOrderWorkflow",
 "version": "1.0",
 "description": "Handle customer orders",
 "defaultTaskStartToCloseTimeout": "600",
 "defaultExecutionStartToCloseTimeout": "3600",
 "defaultTaskList":
  {"name": "mainTaskList"},
 "defaultChildPolicy": "TERMINATE"}

For more information, see the RegisterWorkflowType action in the .

The following example registers an activity type by using the Amazon SWF API. The name and version that you specify during registration form a unique identifier for the activity type within the domain. The specified domain must have already been registered using the RegisterDomain action.

The timeout parameters in this example are duration values specified in seconds. You can use the duration specifier "NONE" to indicate no timeout.

https://swf.us-east-1.amazonaws.com
RegisterActivityType
{"domain": "867530901",
 "name": "activityVerify",
 "version": "1.0",
 "description": "Verify the customer credit",
 "defaultTaskStartToCloseTimeout": "600",
 "defaultTaskHeartbeatTimeout": "120",
 "defaultTaskList":
  {"name": "mainTaskList"},
 "defaultTaskScheduleToStartTimeout": "1800",
 "defaultTaskScheduleToCloseTimeout": "5400"}

For more information, see the RegisterActivityType action in the .

An activity worker provides the implementation of one or more activity types. An activity worker communicates with Amazon SWF to receive activity tasks and perform them. You can have a fleet of multiple activity workers performing activity tasks of the same activity type.

Amazon SWF makes an activity task available to activity workers when the decider schedules the activity task. When a decider schedules an activity task, it provides the data (which you determine) that the activity worker needs to perform the activity task. Amazon SWF inserts this data into the activity task before sending it to the activity worker.

Activity workers are managed by you. They can be written in any language. A worker can be run anywhere, as long as it can communicate with Amazon SWF through the API. Because Amazon SWF provides all the information needed to perform an activity task, all activity workers can be stateless. Statelessness enables your workflows to be highly scalable; to handle increased capacity requirements, simply add more activity workers.

This section explains how to implement an activity worker. The activity workers should repeatedly do the following.

To perform activity tasks, each activity worker must poll Amazon SWF by periodically calling the PollForActivityTask action.

In the following example, the activity worker ChargeCreditCardWorker01 polls for a task on the task list, ChargeCreditCard-v0.1. If no activity tasks are available, after 60 seconds, Amazon SWF sends back an empty response. An empty response is a Task structure in which the value of the taskToken is an empty string.

https://swf.us-east-1.amazonaws.com
PollForActivityTask
{"domain": "867530901",
 "taskList":
  {"name": "ChargeCreditCard-v0.1"},
"identity": "ChargeCreditCardWorker01"}

If an activity task becomes available, Amazon SWF returns it to the activity worker. The task contains the data that the decider specifies when it schedules the activity.

After an activity worker receives an activity task, it is ready to perform the work. The next section provides information on performing an activity task.

After receiving an activity task, the activity worker is ready to perform it.

The next section describes how to program your activity workers to provide status updates to Amazon SWF for long running activities.

If a heartbeat timeout was registered with the activity type, then the activity worker must record a heartbeat before the heartbeat timeout is exceeded. If an activity task does not provide a heartbeat within the timeout, the task times out, Amazon SWF closes it and schedules a new decision task to inform a decider of the timeout. The decider can then reschedule the activity task or take another action.

If, after timing out, the activity worker attempts to contact Amazon SWF, such as by calling RespondActivityTaskCompleted, Amazon SWF will return an UnknownResource fault.

This section describes how to provide an activity heartbeat.

To record an activity task heartbeat, program your activity worker to call the RecordActivityTaskHeartbeat action. This action also provides a string field that you can use to store free-form data to quantify progress in whatever way works for your application.

In this example, the activity worker reports heartbeat to Amazon SWF and uses the details field to report that the activity task is 40 percent complete. To report heartbeat, the activity worker must specify the task token of the activity task.

https://swf.us-east-1.amazonaws.com
RecordActivityTaskHeartbeat
{"taskToken": "12342e17-80f6-FAKE-TASK-TOKEN32f0223",
 "details": "40"}

This action does not in itself create an event in the workflow execution history; however, if the task times out, the workflow execution history will contain a ActivityTaskTimedOut event that contains the information from the last heartbeat generated by the activity worker.

After executing a task, the activity worker should report whether the activity task completed or failed.

To complete an activity task, program the activity worker to call the RespondActivityTaskCompleted action after it successfully completes an activity task, specifying the task token.

In this example, the activity worker indicates that the task completed successfully.

https://swf.us-east-1.amazonaws.com
RespondActivityTaskCompleted
{"taskToken": "12342e17-80f6-FAKE-TASK-TOKEN32f0223",
 "results": "40"}

When the activity completes, Amazon SWF schedules a new decision task for the workflow execution with which the activity is associated.

Program the activity worker to poll for another activity task after it has completed the task at hand. This creates a loop where the activity worker continuously polls for and completes tasks.

If the activity does not respond within the StartToCloseTimeout period, or if ScheduleToCloseTimeout has been exceeded, Amazon SWF times out the activity task and schedules a decision task. This enables a decider to take an appropriate action, such as rescheduling the task.

For example, if an Amazon EC2 instance is executing an activity task and the instance fails before the task is complete, the decider receives a timeout event in the workflow execution history. If the activity task is using a heartbeat, the decider receives the event when the task fails to deliver the next heartbeat after the EC2 instance fails. If not, the decider eventually receives the event when the activity task fails to complete before it hits one of its overall timeout values. It is then up to the decider to re-assign the task or take some other action.

If an activity worker cannot perform an activity task for some reason, but it can still communicate with Amazon SWF, you can program it to fail the task.

To program an activity worker to fail an activity task

Program the activity worker to call the RespondActivityTaskFailed action that specifies the task token of the task.

https://swf.us-east-1.amazonaws.com
RespondActivityTaskFailed
{"taskToken": "12342e17-80f6-FAKE-TASK-TOKEN32f0223",
 "reason": "CC-Invalid",
 "details": "Credit Card Number Checksum Failed"}

As the developer, you define the values that are stored in the reason and details fields. These are free-form strings; you can use any error code conventions that serve your application. Amazon SWF does not process these values. However, Amazon SWF may display these values in the console.

When an activity task is failed, Amazon SWF schedules a decision task for the workflow execution with which the activity task is associated to inform the decider of the failure. Program your decider to handle failed activities, such as by rescheduling the activity or failing the workflow execution, depending on the nature of the failure.

To launch activity workers, package your logic into an executable that you can use on your activity worker platform. For example, you might package your activity code as a Java executable that you can run on both Linux and Windows servers.

Once launched, your workers start polling for tasks. Until the decider schedules activity tasks, though, these polls time out with no tasks and your workers just continue polling.

Because polls are outbound requests, activity worker can run on any network that has access to the Amazon SWF endpoint.

You can launch as many activity workers as you like. As the decider schedules activity tasks, Amazon SWF automatically distributes the activity tasks to the polling activity workers.

A decider is an implementation of the coordination logic of your workflow type that runs during the execution of your workflow. You can run multiple deciders for a single workflow type.

Because the execution state for a workflow execution is stored in its workflow history, deciders can be stateless. Amazon SWF maintains the workflow execution history and provides it to a decider with each decision task. This enables you to dynamically add and remove deciders as necessary, which makes the processing of your workflows highly scalable. As the load on your system grows, you simply add more deciders to handle the increased capacity. Note, however, that there can be only one decision task open at any time for a given workflow execution.

Every time a state change occurs for a workflow execution, Amazon SWF schedules a decision task. Each time a decider receives a decision task, it does the following:

This section describes how to develop a decider, which involves:

The examples in this section show how you might program a decider for the e-commerce example workflow.

You can implement the decider in any language that you like and run it anywhere, as long as it can communicate with Amazon SWF through its service API.

The first thing to do when developing a decider is to define the coordination logic. In the e-commerce example, coordination logic that schedules each activity after the previous activity completes might look similar to the following:

IF lastEvent = "StartWorkflowInstance"
 addToDecisions ScheduleVerifyOrderActivity

ELSIF lastEvent = "CompleteVerifyOrderActivity"
 addToDecisions ScheduleChargeCreditCardActivity

ELSIF lastEvent = "CompleteChargeCreditCardActivity"
 addToDecisions ScheduleCompleteShipOrderActivity

ELSIF lastEvent = "CompleteShipOrderActivity"
 addToDecisions ScheduleRecordOrderCompletion

ELSIF lastEvent = "CompleteRecordOrderCompletion"
 addToDecisions CloseWorkflow

ENDIF

The decider applies the coordination logic to the workflow execution history, and creates a list of decisions when completing the decision task using the RespondDecisionTaskCompleted action.

Each decider polls for decision tasks. The decision tasks contain the information that the decider uses to generate decisions such as scheduling activity tasks. To poll for decision tasks, the decider uses the PollForDecisionTask action.

In this example, the decider polls for a decision task, specifying the customerOrderWorkflow-0.1 tasklist.

https://swf.us-east-1.amazonaws.com
PollForDecisionTask
{"domain": "867530901",
 "taskList":
  {"name": "customerOrderWorkflow-v0.1"},
 "identity": "Decider01",
 "maximumPageSize": 500,
 "reverseOrder": true}

If a decision task is available from the task list specified, Amazon SWF returns it immediately. If no decision task is available, Amazon SWF holds the connection open for up to 60 seconds, and returns a task as soon as it becomes available. If no task becomes available, Amazon SWF returns an empty response. An empty response is a Task structure in which the value of taskToken is an empty string. Make sure to program your decider to poll for another task if it receives an empty response.

If a decision task is available, Amazon SWF returns a response that contains the decision task as well as a paginated view of the workflow execution history.

In this example, the type of the most recent event indicates the workflow execution started and the input element contains the information needed to perform the first task.

{"events": 
  [
    {"decisionTaskStartedEventAttributes": 
      {"identity": "Decider01", 
       "scheduledEventId": 2}, 
     "eventId": 3, 
     "eventTimestamp": 1326593394.566, 
     "eventType": "DecisionTaskStarted"}, 
    {"decisionTaskScheduledEventAttributes": 
      {"startToCloseTimeout": "600", 
       "taskList": 
        {"name": "specialTaskList"}
      }, 
     "eventId": 2, 
     "eventTimestamp": 1326592619.474, 
     "eventType": "DecisionTaskScheduled"}, 
    {"eventId": 1, 
     "eventTimestamp": 1326592619.474, 
     "eventType": "WorkflowExecutionStarted", 
     "workflowExecutionStartedEventAttributes": 
      {"childPolicy": "TERMINATE", 
       "executionStartToCloseTimeout": "3600", 
       "input": "data-used-decider-for-first-task", 
       "parentInitiatedEventId": 0, 
       "tagList": 
        ["music purchase", "digital", "ricoh-the-dog"], 
       "taskList": 
        {"name": "specialTaskList"}, 
       "taskStartToCloseTimeout": "600", 
       "workflowType": 
        {"name": "customerOrderWorkflow", 
         "version": "1.0"}
      }
    }
  ],

After receiving the workflow execution history, the decider interprets history and makes decisions based on its coordination logic.

Because the number of workflow history events for a single workflow execution might be large, the result returned might be split up across a number of pages. To retrieve subsequent pages, make additional calls to PollForDecisionTask using the nextPageToken returned by the initial call. Note that you do not call GetWorkflowExecutionHistory with this nextPageToken. Instead, call PollForDecisionTask again.

After the decider receives a decision task, program it to interpret the workflow execution history to determine what has happened so far. Based on this, it should generate a list of decisions.

In the e-commerce example, we are concerned only with the last event in the workflow history, so we define the following logic.

IF lastEvent = "StartWorkflowInstance"
 addToDecisions ScheduleVerifyOrderActivity

ELSIF lastEvent = "CompleteVerifyOrderActivity"
 addToDecisions ScheduleChargeCreditCardActivity

ELSIF lastEvent = "CompleteChargeCreditCardActivity"
 addToDecisions ScheduleCompleteShipOrderActivity

ELSIF lastEvent = "CompleteShipOrderActivity"
 addToDecisions ScheduleRecordOrderCompletion

ELSIF lastEvent = "CompleteRecordOrderCompletion"
 addToDecisions CloseWorkflow

ENDIF

If the lastEvent is CompleteVerifyOrderActivity, you would add the ScheduleChargeCreditCardActivity activity to the list of decisions.

After the decider determines the decision(s) to make, it can respond to Amazon SWF with appropriate decisions.

After interpreting the workflow history and generating a list of decisions, the decider is ready to respond back to Amazon SWF with those decisions.

Program your decider to extract the data that it needs from the workflow execution history, then create decisions that specify the next appropriate actions for the workflow. The decider transmits these decision back to Amazon SWF using the RespondDecisionTaskCompleted action. See the for a list of the available decision types.

In the e-commerce example, when the decider responds with the set of decisions that it generated, it also includes the credit card input from the workflow execution history. The activity worker then has the information it needs to perform the activity task.

When all activities in the workflow execution are complete, the decider closes the workflow execution.

https://swf.us-east-1.amazonaws.com
RespondDecisionTaskCompleted
{
  "taskToken": "12342e17-80f6-FAKE-TASK-TOKEN32f0223",
  "decisions":[
      {
          "decisionType":"ScheduleActivityTask",
          "scheduleActivityTaskDecisionAttributes":{
              "control":"OPTIONAL_DATA_FOR_DECIDER",
              "activityType":{
                  "name":"ScheduleChargeCreditCardActivity",
                  "version":"1.1"
              },
              "activityId":"3e2e6e55-e7c4-beef-feed-aa815722b7be",
              "scheduleToCloseTimeout":"360",
              "taskList":{
                  "name":"CC_TASKS"
              },
              "scheduleToStartTimeout":"60",
              "startToCloseTimeout":"300",
              "heartbeatTimeout":"60",
              "input": "4321-0001-0002-1234: 0212 : 234"
          }
      }
  ]
}

When the decider determines that the business process is complete, that is, that there are no more activities to perform, the decider generates a decision to close the workflow execution.

To close a workflow execution, program your decider to interpret the events in the workflow history to determine what has happened in the execution so far and see if the workflow execution should be closed.

If the workflow has completed successfully, then close the workflow execution by calling RespondDecisionTaskCompleted with the CompleteWorkflowExecution decision. Alternatively, you can fail an erroneous execution using the FailWorkflowExecution decision.

In the e-commerce example, the decider reviews the history and based on the coordination logic adds a decision to close the workflow execution to its list of decisions, and initiates a RespondDecisionTaskCompleted action with a close workflow decision.

You might also support cancellation of workflow executions. This could be especially useful for long running workflows. To support cancellation, your decider should handle the WorkflowExecutionCancelRequested event in the history. This event indicates that cancellation of the execution has been requested. Your decider should perform appropriate clean-up actions, such as canceling ongoing activity tasks, and closing the workflow calling the RespondDecisionTaskCompleted action with the CancelWorkflowExecution decision.

The following example calls RespondDecisionTaskCompleted to specify that the current workflow execution is canceled.

https://swf.us-east-1.amazonaws.com
RespondDecisionTaskCompleted
{
  "taskToken": "12342e17-80f6-FAKE-TASK-TOKEN32f0223",
  "decisions":[
      {
          "decisionType":"CancelWorkflowExecution",
          "CancelWorkflowExecutionAttributes":{
            "Details": "Customer canceled order"
          }
      }
  ]
}

Amazon SWF checks to ensure that the decision to close or cancel the workflow execution is the last decision sent by the decider. That is, it isn't valid to have a set of decisions in which there are decisions after the one that closes the workflow.

There are a number of different types of errors that can occur during the course of a workflow execution.

Validation Errors

Validation errors occur when a request to Amazon SWF fails because it is not properly formed or it contains invalid data. In this context, a request could be an action such as DescribeDomain or it could be a decision such as StartTimer. If the request is an action, Amazon SWF returns an error code in the response. Check this error code as it may provide information about what aspect of the request caused the failure. For example, one or more of the arguments passed with the request might be invalid. For a list of common error codes, go to the topic for the action in the .

If the request that failed is a decision, an appropriate event will be listed in the workflow execution history. For example, if the StartTimer decision failed, you would see a StartTimerFailed event in the history. The decider should check for these events when it receives the history in response to PollForDecisionTask or GetWorkflowExecutionHistory. Below is a list of possible decision failure events that can occur when the decision is not correctly formed or contains invalid data.

Errors in Enacting Actions or Decisions

Even if the request is properly formed, errors may occur when Amazon SWF attempts to carry out the request. In these cases, one of the following events in the history will indicate that an error occurred. Look at the reason field of the event to determine the cause of failure.

Timeouts

Deciders, activity workers, and workflow executions all operate within the constraints of timeout periods. In this type of error, a task or a child workflow times out. An event will appear in the history that describes the timeout. The decider should handle this event by, for example, rescheduling the task or restarting the child workflow. For more information about timeouts, see Timeout Types

Errors raised by user code

Examples of this type of error condition are activity task failures and child-workflow failures. As with timeout errors, Amazon SWF adds an appropriate event to the workflow execution history. The decider should handle this event, possibly by rescheduling the task or restarting the child workflow.

Errors related to closing a workflow execution

Deciders may also see the following events if they attempt to close a workflow that has a pending decision task.

For more information about any of the events listed above, see History Event in the Amazon SWF API Reference.

After completing decider development, you are ready to launch one or more deciders.

To launch deciders, package your coordination logic into an executable that you can use on your decider platform. For example, you might package your decider code as a Java executable that you can run on both Linux and Windows computers.

Once launched, your deciders should start polling Amazon SWF for tasks. Until you start workflow executions and Amazon SWF schedules decision tasks, these polls will time out and get empty responses. An empty response is a Task structure in which the value of taskToken is an empty string. Your deciders should simply continue to poll.

Amazon SWF ensures that only one decision task can be active for a workflow execution at any time. This prevents issues such as conflicting decisions. Additionally, Amazon SWF ensures that a single decision task is assigned to a single decider, regardless of the number of deciders that are running.

If something occurs that generates a decision task while a decider is processing another decision task, Amazon SWF queues the new task until the current task completes. After the current task completes, Amazon SWF makes the new decision task available. Also, decision tasks are batched in the sense that, if multiple activities complete while a decider is processing a decision task, Amazon SWF will create only a single new decision task to account for the multiple task completions. However, each task completion will receive an individual event in the workflow execution history.

Because polls are outbound requests, deciders can run on any network that has access to the Amazon SWF endpoint.

In order for workflow executions to progress, one or more deciders must be running. You can launch as many deciders as you like. Amazon SWF supports multiple deciders polling on the same task list.

You can start a workflow execution of a registered workflow type from any application using the StartWorkflowExecution action. When you start the execution you associate an identifier, called the workflowId, with it. The workflowId can be any string that is appropriate for your application, such as the order number in an order processing application. You cannot use the same workflowId for multiple open workflow executions within the same domain. For example, if you start two workflow executions with the workflowId Customer Order 01, the second workflow execution will not start and the request will fail. You can, however, reuse the workflowId of a closed execution. Amazon SWF also associates a unique system generated identifier, called the runId, with each workflow execution.

After the workflow and activity types are registered, start the workflow by calling the StartWorkflowExecution action. The value of the input parameter can be any string specified by the application that is starting the workflow. The executionStartToCloseTimeout is the length of time in seconds that the workflow execution can consume from start to close. Exceeding this limit causes the workflow execution to time out. Unlike some of the other timeout parameters in Amazon SWF, you cannot specify a value of "NONE" for this timeout; there is a one-year maximum limit on the time that a workflow execution can run. Similarly, the taskStartToCloseTimeout is the length of time in seconds that a decision task associated with this workflow execution can take before timing out.

https://swf.us-east-1.amazonaws.com
StartWorkflowExecution
{"domain": "867530901",
 "workflowId": "20110927-T-1",
 "workflowType":
  {"name": "customerOrderWorkflow",
   "version": "1.1"},
 "taskList":
  {"name": "specialTaskList"},
 "input": "arbitrary-string-that-is-meaningful-to-the-workflow",
 "executionStartToCloseTimeout": "1800",
 "tagList":
  ["music purchase", "digital", "ricoh-the-dog"],
 "taskStartToCloseTimeout": "1800",
 "childPolicy": "TERMINATE"

If the StartWorkflowExecution action is successful, Amazon SWF returns the runId for the workflow execution. The runId uniquely identifies this workflow execution from any other workflow executions currently running under Amazon SWF. Save the runId in case you later need to specify this workflow execution in a call to Amazon SWF. For example, you would use the runId if you later needed to send a signal to the workflow execution.

{"runId": "9ba33198-4b18-4792-9c15-7181fb3a8852"}