# Understanding AWS Flow Framework for Java
The AWS Flow Framework for Java works with Amazon SWF to make it easy to create scalable and fault-tolerant applications to perform asynchronous tasks that may be long running, remote, or both. The "Hello World\$1" examples in [What is the AWS Flow Framework for Java?](welcome.md) introduced the basics of how to use the AWS Flow Framework to implement basic workflow applications. This section provides conceptual information about how AWS Flow Framework applications work. The first section summarizes the basic structure of an AWS Flow Framework application, and the remaining sections provide further detail about how AWS Flow Framework applications work.
**Topics**
+ [Application Structure](awsflow-basics-application-structure.md)
+ [Reliable Execution](awsflow-basics-reliable-execution.md)
+ [Distributed Execution](awsflow-basics-distributed-execution.md)
+ [Task Lists and Task Execution](awsflow-basics-task-lists.md)
+ [Scalable Applications](awsflow-basics-scalable.md)
+ [Data Exchange Between Activities and Workflows](awsflow-basics-data-exchange-activities-workflows.md)
+ [Data Exchange Between Applications and Workflow Executions](awsflow-basics-data-exchange-workflows-application.md)
+ [Timeout Types](swf-timeout-types.md)
# AWS Flow Framework Basic Concepts: Application Structure
Conceptually, an AWS Flow Framework application consists of three basic components: *workflow starters*, *workflow workers*, and *activity workers*. One or more host applications are responsible for registering the workers (workflow and activity) with Amazon SWF, starting the workers, and handling cleanup. The workers handle the mechanics of executing the workflow and may be implemented on several hosts.
This diagram represents a basic AWS Flow Framework application:
![\[Schematic AWS Flow Framework application\]](http://docs.aws.amazon.com/amazonswf/latest/awsflowguide/images/swf-application-model.png)
**Note**
Implementing these components in three separate applications is convenient conceptually, but you can create applications to implement this functionality in a variety of ways. For example, you can use a single host application for the activity and workflow workers, or use separate activity and workflow hosts. You can also have multiple activity workers, each handling a different set of activities on separate hosts, and so on.
The three AWS Flow Framework components interact indirectly by sending HTTP requests to Amazon SWF, which manages the requests. Amazon SWF does the following:
+ Maintains one or more decision task lists, which determine the next step to be performed by a workflow worker.
+ Maintains one or more activities task lists, which determine which tasks will be performed by an activity worker.
+ Maintains a detailed step-by-step history of the workflow's execution.
With the AWS Flow Framework, your application code doesn't need to deal directly with many of the details shown in the figure, such as sending HTTP requests to Amazon SWF. You simply call AWS Flow Framework methods and the framework handles the details behind the scenes.
## Role of the Activity Worker
The activity worker performs the various tasks that the workflow must accomplish. It consists of:
+ The activities implementation, which includes a set of activity methods that perform particular tasks for the workflow.
+ An [ActivityWorker](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/ActivityWorker.html) object, which uses HTTP long poll requests to poll Amazon SWF for activity tasks to be performed. When a task is needed, Amazon SWF responds to the request by sending the information required to perform the task. The [ActivityWorker](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/ActivityWorker.html) object then calls the appropriate activity method, and returns the results to Amazon SWF.
## Role of the Workflow Worker
The workflow worker orchestrates the execution of the various activities, manages data flow, and handles failed activities. It consists of:
+ The workflow implementation, which includes the activity orchestration logic, handles failed activities, and so on.
+ An activities client, which serves as a proxy for the activity worker and enables the workflow worker to schedule activities to be executed asynchronously.
+ A [WorkflowWorker](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/simpleworkflow/flow/WorkflowWorker.html) object, which uses HTTP long poll requests to poll Amazon SWF for decision tasks. If there are tasks on the workflow task list, Amazon SWF responds to the request by returning the information that is required to perform the task. The framework then executes the workflow to perform the task and returns the results to Amazon SWF.
## Role of the Workflow Starter
The workflow starter starts a workflow instance, also referred to as a *workflow execution*, and can interact with an instance during execution in order to pass additional data to the workflow worker or obtain the current workflow state.
The workflow starter uses a workflow client to start the workflow execution, interacts with the workflow as needed during execution, and handles cleanup. The workflow starter could be a locally-run application, a web application, the AWS CLI or even the AWS Management Console.
## How Amazon SWF Interacts with Your Application
Amazon SWF mediates the interaction between the workflow components and maintains a detailed workflow history. Amazon SWF doesn't initiate communication with the components; it waits for HTTP requests from the components and manages the requests as required. For example:
+ If the request is from a worker, polling for available tasks, Amazon SWF responds directly to the worker if a task is available. For more information about how polling works, see [Polling for Tasks](https://docs.aws.amazon.com/amazonswf/latest/developerguide/swf-dg-basic.html#swf-dev-comm-proto) in the *Amazon Simple Workflow Service Developer Guide*.
+ If the request is a notification from an activity worker that a task is complete, Amazon SWF records the information in the execution history and adds a task to the decision task list to inform the workflow worker that the task is complete, allowing it to proceed to the next step.
+ If the request is from the workflow worker to execute an activity, Amazon SWF records the information in the execution history and adds a task to the activities task list to direct an activity worker to execute the appropriate activity method.
This approach allows workers to run on any system with an Internet connection, including Amazon EC2 instances, corporate data centers, client computers, and so on. They don't even have to be running the same operating system. Because the HTTP requests originate with the workers, there is no need for externally visible ports; workers can run behind a firewall.
## For More Information
For a more thorough discussion of how Amazon SWF works, see [Amazon Simple Workflow Service Developer Guide](https://docs.aws.amazon.com/amazonswf/latest/developerguide/).
# AWS Flow Framework Basic Concepts: Reliable Execution
Asynchronous distributed applications must deal with reliability issues that are not encountered by conventional applications, including:
+ How to *provide reliable communication* between asynchronous distributed components, such as long-running components on remote systems.
+ How to *ensure that results are not lost* if a component fails or is disconnected, especially for long-running applications.
+ How to *handle failed distributed components*.
Applications can rely on the AWS Flow Framework and Amazon SWF to manage these issues. We'll explore how Amazon SWF provides mechanisms to ensure that your workflows operate reliably and in a predictable way, even when they are long-running and depend on asynchronous tasks carried out computationally and with human interaction.
## Providing Reliable Communication
AWS Flow Framework provides reliable communication between a workflow worker and its activities workers by using Amazon SWF to dispatch tasks to distributed activities workers and return the results to the workflow worker. Amazon SWF uses the following methods to ensure reliable communication between a worker and its activities:
+ Amazon SWF durably stores scheduled activity and workflow tasks and guarantees that they will be performed at most once.
+ Amazon SWF guarantees that an activity task will either complete successfully and return a valid result or it will notify the workflow worker that the task failed.
+ Amazon SWF durably stores each completed activity's result or, for failed activities, it stores relevant error information.
The AWS Flow Framework then uses the activity results from Amazon SWF to determine how to proceed with the workflow's execution.
## Ensuring that Results are Not Lost
### Maintaining Workflow History
An activity that performs a data-mining operation on a petabyte of data might take *hours* to complete, and an activity that directs a human worker to perform a complex task might take *days*, or even *weeks* to complete\$1
To accommodate scenarios such as these, AWS Flow Framework workflows and activities can take arbitrarily long to complete: *up to a limit of one year* for a workflow execution. Reliably executing long running processes requires a mechanism to durably store the workflow's execution history on an ongoing basis.
The AWS Flow Framework handles this by depending on Amazon SWF, which maintains a running history of each workflow instance. The workflow's history provides a complete and authoritative record of the workflow's progress, including all the workflow and activity tasks that have been scheduled and completed, and the information returned by completed or failed activities.
AWS Flow Framework applications usually don't need to interact with the workflow history directly, although they can access it if necessary. For most purposes, applications can simply let the framework interact with the workflow history behind the scenes. For a full discussion of workflow history, see [Workflow History](https://docs.aws.amazon.com/amazonswf/latest/developerguide/swf-dg-basic.html#swf-dev-about-workflow-history) in the *Amazon Simple Workflow Service Developer Guide*.
### Stateless Execution
The execution history allows workflow workers to be *stateless*. If you have multiple instances of a workflow or activity worker, any worker can perform any task. The worker receives all the state information that it needs to perform the task from Amazon SWF.
This approach makes workflows more reliable. For example, if an activity worker fails, you don't have to restart the workflow. Just restart the worker and it will start polling the task list and processing whatever tasks are on the list, regardless of when the failure occurred. You can make your overall workflow fault-tolerant by using two or more workflow and activity workers, perhaps on separate systems. Then, if one of the workers fails, the others will continue to handle scheduled tasks without any interruption in workflow progress.
## Handling Failed Distributed Components
Activities often fail for ephemeral reasons, such as a brief disconnection, so a common strategy for handling failed activities is to retry the activity. Instead of handling the retry process by implementing complex message passing strategies, applications can depend on the AWS Flow Framework. It provides several mechanisms for retrying failed activities, and provides a built-in exception-handling mechanism that works with asynchronous, distributed execution of tasks in a workflow.
# AWS Flow Framework Basic Concepts: Distributed Execution
A *workflow instance* is essentially a virtual thread of execution that can span activities and orchestration logic running on multiple remote computers. Amazon SWF and the AWS Flow Framework function as an operating system that manages workflow instances on a virtual CPU by:
+ Maintaining each instance's execution state.
+ Switching between instances.
+ Resuming execution of an instance at the point that it was switched out.
## Replaying Workflows
Because activities can be long-running, it's undesirable to have the workflow simply block until it completes. Instead, the AWS Flow Framework manages workflow execution by using a *replay* mechanism, which relies on the workflow history maintained by Amazon SWF to execute the workflow in episodes.
Each episode replays the workflow logic in a way that *executes each activity only once*, and ensures that activities and asynchronous methods don't execute until their [Promise](awsflow-basics-data-exchange-activities-workflows.md) objects are ready.
The workflow starter initiates the first replay episode when it starts the workflow execution. The framework calls the workflow's entry point method and:
1. Executes all workflow tasks that don't depend on activity completion, including calling all activity client methods.
1. Gives Amazon SWF a list of activities tasks to be scheduled for execution. For the first episode, this list consists of only those activities that don't depend on a Promise and can be executed immediately.
1. Notifies Amazon SWF that the episode is complete.
Amazon SWF stores the activity tasks in the workflow history and schedules them for execution by placing them on the activity task list. The activity workers poll the task list and execute the tasks.
When an activity worker completes a task, it returns the result to Amazon SWF, which records it in the workflow execution history and schedules a new *workflow task* for the workflow worker by placing it on the workflow task list. The workflow worker polls the task list and when it receives the task, it runs the next replay episode, as follows:
1. The framework runs the workflow's entry point method again and:
+ Executes all workflow tasks that don't depend on activity completion, including calling all activity client methods. However, the framework checks the execution history and doesn't schedule duplicate activity tasks.
+ Checks the history to see which activity tasks have completed and executes any asynchronous workflow methods that depend on those activities.
1. When all workflow tasks that can be executed have completed, the framework reports back to Amazon SWF:
+ It gives Amazon SWF a list of any activities whose input `Promise` objects have become ready since the last episode and can be scheduled for execution.
+ If the episode generated no additional activity tasks but there are still uncompleted activities, the framework notifies Amazon SWF that the episode is complete. It then waits for another activity to complete, initiating the next replay episode.
+ If the episode generated no additional activity tasks and all activities have completed, the framework notifies Amazon SWF that the workflow execution is complete.
For examples of replay behavior, see [AWS Flow Framework for Java Replay Behavior](programming-replay.md).
## Replay and Asynchronous Workflow Methods
Asynchronous workflow methods are often used much like activities, because the method defers execution until all input `Promise` objects are ready. However, the replay mechanism handles asynchronous methods differently than activities.
+ Replay doesn't guarantee that an asynchronous method will execute only once. It defers execution on an asynchronous method until its input Promise objects are ready, but it then executes that method for all subsequent episodes.
+ When an asynchronous method completes, it doesn't start a new episode.
An example of replaying an asynchronous workflow is provided in [AWS Flow Framework for Java Replay Behavior](programming-replay.md).
## Replay and Workflow Implementation
For the most part, you don't need to be concerned with the details of the replay mechanism. It is basically something that happens behind the scenes. However, replay has two important implications for your workflow implementation.
+ Do not use workflow methods to perform long-running tasks, because replay will repeat that task multiple times. Even asynchronous workflow methods typically run more than once. Instead, use activities for long running tasks; replay executes activities only once.
+ Your workflow logic must be completely deterministic; every episode must take the same control flow path. For example, the control flow path should not depend on the current time. For a detailed description of replay and the determinism requirement, see [Nondeterminism](details.md#details.non).
# AWS Flow Framework Basic Concepts: Task Lists and Task Execution
Amazon SWF manages workflow and activity tasks by posting them to named lists. Amazon SWF maintains at least two task lists, one for workflow workers and one for activity workers.
**Note**
You can specify as many task lists as you need, with different workers assigned to each list. There is no limit to the number of task lists. You typically specify a worker's task list in the worker host application when you create the worker object.
The following excerpt from the `HelloWorldWorkflow` host application creates a new activity worker and assigns it to the `HelloWorldList` activities task list.
```
public class GreeterWorker {
public static void main(String[] args) throws Exception {
...
String domain = " helloWorldExamples";
String taskListToPoll = "HelloWorldList";
ActivityWorker aw = new ActivityWorker(service, domain, taskListToPoll);
aw.addActivitiesImplementation(new GreeterActivitiesImpl());
aw.start();
...
}
}
```
By default, Amazon SWF schedules the worker's tasks on the `HelloWorldList` list. Then the worker polls that list for tasks. You can assign any name to a task list. You can even use the same name for both workflow and activity lists. Internally, Amazon SWF puts workflow and activity task list names in different namespaces, so the two lists will be distinct.
If you don't specify a task list, the AWS Flow Framework specifies a default list when the worker registers the type with Amazon SWF. For more information, see [Workflow and Activity Type Registration](features.registration.md).
Sometimes it's useful to have a specific worker or group of workers perform certain tasks. For example, an image processing workflow might use one activity to download an image and another activity to process the image. It's more efficient to perform both tasks on the same system, and avoid the overhead of transferring large files over the network.
To support such scenarios, you can explicitly specify a task list when you call an activity client method by using an overload that includes a `schedulingOptions` parameter. You specify the task list by passing the method an appropriately configured `ActivitySchedulingOptions` object.
For example, suppose that the `say` activity of the `HelloWorldWorkflow` application is hosted by an activity worker different from `getName` and `getGreeting`. The following example shows how to ensure that `say` uses the same task list as `getName` and `getGreeting`, even if they were originally assigned to different lists.
```
public class GreeterWorkflowImpl implements GreeterWorkflow {
private GreeterActivitiesClient operations1 = new GreeterActivitiesClientImpl1(); //getGreeting and getName
private GreeterActivitiesClient operations2 = new GreeterActivitiesClientImpl2(); //say
@Override
public void greet() {
Promise name = operations1.getName();
Promise greeting = operations1.getGreeting(name);
runSay(greeting);
}
@Asynchronous
private void runSay(Promise greeting){
String taskList = operations1.getSchedulingOptions().getTaskList();
ActivitySchedulingOptions schedulingOptions = new ActivitySchedulingOptions();
schedulingOptions.setTaskList(taskList);
operations2.say(greeting, schedulingOptions);
}
}
```
The asynchronous `runSay` method gets the `getGreeting` task list from its client object. Then it creates and configures an `ActivitySchedulingOptions` object that ensures that `say` polls the same task list as `getGreeting`.
**Note**
When you pass a `schedulingOptions` parameter to an activity client method, it overrides the original task list only for that activity execution. If you call the activities client method again without specifying a task list, Amazon SWF assigns the task to the original list, and the activity worker will poll that list.
# AWS Flow Framework Basic Concepts: Scalable Applications
Amazon SWF has two key features that make it easy to scale a workflow application to handle the current load:
+ A complete workflow execution history, which allows you to implement a stateless application.
+ Task scheduling that is loosely coupled to task execution, which makes it easy to scale your application to meet current demands.
Amazon SWF schedules tasks by posting them to dynamically allocated task lists, not by communicating directly with workflow and activity workers. Instead, the workers use HTTP requests to poll their respective lists for tasks. This approach loosely couples task scheduling to task execution and allows workers to run on any suitable system, including Amazon EC2 instances, corporate data centers, client computers, and so on. Because the HTTP requests originate with the workers, there is no need for externally visible ports, which enables workers to even run behind a firewall.
The long-polling mechanism that workers use to poll for tasks ensures that workers don't get overloaded. Even if there is a spike in scheduled tasks, workers pull tasks at their own pace. However, because workers are stateless, you can dynamically scale an application to meet increased load by starting additional worker instances. Even if they are running on different systems, each instance polls the same task list and the first available worker instance executes each task, regardless of where the worker is located or when it started. When the load declines, you can reduce the number of workers accordingly.
# AWS Flow Framework Basic Concepts: Data Exchange Between Activities and Workflows
When you call an asynchronous activity client method, it immediately returns a *Promise* (also known as a *Future*) object, which represents the activity method's return value. Initially, the Promise is in an unready state and the return value is undefined. After the activity method completes its task and returns, the framework marshals the return value across the network to the workflow worker, which assigns a value to the Promise and puts the object in a ready state.
Even if an activity method has no return value, you can still use the Promise for managing workflow execution. If you pass a returned Promise to an activity client method or an asynchronous workflow method, it defers execution until the object is ready.
If you pass one or more Promises to an activity client method, the framework queues the task but defers scheduling it until all the objects are ready. It then extracts the data from each Promise and marshals it across the internet to the activity worker, which passes it to the activity method as a standard type.
**Note**
If you need to transfer large amounts of data between workflow and activity workers, the preferred approach is to store the data in a convenient location and just pass the retrieval information. For example, you can store the data in an Amazon S3 bucket and pass the associated URL.
## The Promise Type
The `Promise` type is similar in some ways to the Java `Future` type. Both types represent values returned by asynchronous methods and are initially undefined. You access an object's value by calling its `get` method. Beyond that, the two types behave quite differently.
+ `Future` is a synchronization construct that allows an application to wait on an asynchronous method's completion. If you call `get` and the object isn't ready, it blocks until the object is ready.
+ With `Promise`, synchronization is handled by the framework. If you call `get` and the object isn't ready, `get` throws an exception.
The primary purpose of `Promise` is to manage data flow from one activity to another. It ensures that an activity doesn't execute until the input data is valid. In many cases, workflow workers don't need to access `Promise` objects directly; they simply pass the objects from one activity to another and let the framework and the activity workers handle the details. To access a `Promise` object's value in a workflow worker, you must be certain that the object is ready before calling its `get` method.
+ The preferred approach is to pass the `Promise` object to an asynchronous workflow method and process the values there. An asynchronous method defers execution until all of its input `Promise` objects are ready, which guarantees that you can safely access their values.
+ `Promise` exposes an `isReady` method that returns `true` if the object is ready. Using `isReady` to poll a `Promise` object isn't recommended, but `isReady` is useful in certain circumstances.
The AWS Flow Framework for Java also includes a `Settable` type, which is derived from `Promise` and has similar behavior. The difference is that the framework usually sets the value of a `Promise` object and the workflow worker is responsible for setting the value of a `Settable`.
There are some circumstance where a workflow worker needs to create a `Promise` object and set its value. For example, an asynchronous method that returns a `Promise` object needs to create a return value.
+ To create an object that represents a typed value, call the static `Promise.asPromise` method, which creates a `Promise` object of the appropriate type, sets its value, and puts it in the ready state.
+ To create a `Promise` object, call the static `Promise.Void` method.
**Note**
`Promise` can represent any valid type. However, if the data must be marshaled across the internet, the type must be compatible with the data converter. See the next section for details.
## Data Converters and Marshaling
The AWS Flow Framework marshals data across the internet by using a data converter. By default, the framework uses a data converter that is based on the [Jackson JSON processor](https://github.com/codehaus/jackson). However, this converter has some limitations. For example, it can't marshal maps that don't use strings as keys. If the default converter isn't sufficient for your application, you can implement a custom data converter. For details, see [DataConverters](dataconverters.md).
# AWS Flow Framework Basic Concepts: Data Exchange Between Applications and Workflow Executions
A workflow entry point method can have one or more parameters, which allows the workflow starter to pass initial data to the workflow. It can also useful to provide additional data to the workflow during execution. For example, if a customer changes their shipping address, you could notify the order-processing workflow so that it can make appropriate changes.
Amazon SWF allows workflows to implement a *signal* method, which allows applications such as the workflow starter to pass data to the workflow at any time. A signal method can have any convenient name and parameters. You designate it as a signal method by including it in your workflow interface definition, and applying a `@Signal` annotation to the method declaration.
The following example shows an order processing workflow interface that declares a signal method, `changeOrder`, which allows the workflow starter to change the original order after the workflow has started.
```
@Workflow
@WorkflowRegistrationOptions(defaultExecutionStartToCloseTimeoutSeconds = 300)
public interface WaitForSignalWorkflow {
@Execute(version = "1.0")
public void placeOrder(int amount);
@Signal
public void changeOrder(int amount);
}
```
The framework's annotation processor creates a workflow client method with the same name as the signal method and the workflow starter calls the client method to pass data to the workflow. For an example, see [AWS Flow Framework Recipes](https://aws.amazon.com/code/2535278400103493)
# Amazon SWF Timeout Types
To ensure that workflow executions run correctly, you can set different types of timeouts with Amazon SWF. 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](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondDecisionTaskCompleted.html) 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](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondActivityTaskCompleted.html), [canceled](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondActivityTaskCanceled.html), or [failed](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondActivityTaskFailed.html). 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\]](http://docs.aws.amazon.com/amazonswf/latest/awsflowguide/images/workflow_timeouts.png)
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](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_HistoryEvent.html) of type [WorkflowExecutionTimedOut](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_WorkflowExecutionTimedOutEventAttributes.html) 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](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_DecisionTaskTimedOutEventAttributes.html) 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\]](http://docs.aws.amazon.com/amazonswf/latest/awsflowguide/images/activity_timeouts.png)
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](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondActivityTaskCanceled.html), [RespondActivityTaskCompleted](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondActivityTaskCompleted.html), and [RespondActivityTaskFailed](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_RespondActivityTaskFailed.html) 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](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_ScheduleActivityTaskDecisionAttributes.html) the activity task. When one of these timeouts occurs, Amazon SWF will add an [event](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_HistoryEvent.html) of type [ActivityTaskTimedOut](http://docs.aws.amazon.com/amazonswf/latest/apireference/API_ActivityTaskTimedOutEventAttributes.html) 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.