# Discover service integration patterns in Step Functions For service integrations, you can specify various integration patterns to control how your state machine interacts with the integrated AWS services : + [Request Response](#connect-default) - Call a service and Step Functions will progress to the next state immediately after it receives an HTTP response. + [Run a Job (.sync)](#connect-sync) - Call a service and have Step Functions wait for a job to complete. + [Wait for a Callback with Task Token](#connect-wait-token) - Call a service with a task token and have Step Functions wait until that token is returned with a payload. Each of these service integration patterns is controlled by how you create a URI in the `"Resource"` field of your [task definition](state-task.md). An ASL Resource value in Step Functions is a unique name (URI) which conforms to [ARN format](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html#arns-syntax), but typically does not identify an actual *Resource* in your account. The prefix "`arn:aws:states:`" sets up a namespace that Step Functions uses for integrations. The `:::` portion of the value denotes empty `region` and `account-id` fields which are unnecessary because both are inferred from the region and account in which the workflow runs. Legacy integrations to AWS Lambda are the one exception where the Resource value specifies an actual Lambda function resource. The Step Functions console will display these legacy Resources, but you cannot create or edit such resources in the present day graphical UI, unless you choose to edit the ASL code directly. ## Integration pattern support Standard Workflows and Express Workflows support the same **integrations** but not the same **integration patterns**. + **Standard Workflows** support *Request Response* integrations. Certain services support *Run a Job (.sync)*, or *Wait for Callback (.waitForTaskToken)* , and both in some cases. See the following optimized integrations table for details. + **Express Workflows** only support *Request Response* integrations. To help decide between the two types, see [Choosing workflow type in Step Functions](choosing-workflow-type.md). **AWS SDK integrations in Step Functions** | Integrated service | Request Response | Run a Job - *.sync* | Wait for Callback - *.waitForTaskToken* | | --- | --- | --- | --- | | [Over two hundred services](supported-services-awssdk.md#supported-services-awssdk-list) | Standard & Express | Not supported | Standard | **Optimized integrations in Step Functions** | Integrated service | Request Response | Run a Job - *.sync* | Wait for Callback - *.waitForTaskToken* | | --- | --- | --- | --- | | [Amazon API Gateway](connect-api-gateway.md) | Standard & Express | Not supported | Standard | | [Amazon Athena](connect-athena.md) | Standard & Express | Standard | Not supported | | [AWS Batch](connect-batch.md) | Standard & Express | Standard | Not supported | | [Amazon Bedrock](connect-bedrock.md) | Standard & Express | Standard | Standard | | [AWS CodeBuild](connect-codebuild.md) | Standard & Express | Standard | Not supported | | [Amazon DynamoDB](connect-ddb.md) | Standard & Express | Not supported | Not supported | | [Amazon ECS/Fargate](connect-ecs.md) | Standard & Express | Standard | Standard | | [Amazon EKS](connect-eks.md) | Standard & Express | Standard | Standard | | [Amazon EMR](connect-emr.md) | Standard & Express | Standard | Not supported | | [Amazon EMR on EKS](connect-emr-eks.md) | Standard & Express | Standard | Not supported | | [Amazon EMR Serverless](connect-emr-serverless.md) | Standard & Express | Standard | Not supported | | [Amazon EventBridge](connect-eventbridge.md) | Standard & Express | Not supported | Standard | | [AWS Glue](connect-glue.md) | Standard & Express | Standard | Not supported | | [AWS Glue DataBrew](connect-databrew.md) | Standard & Express | Standard | Not supported | | [AWS Lambda](connect-lambda.md) | Standard & Express | Not supported | Standard | | [AWS Elemental MediaConvert](connect-mediaconvert.md) | Standard & Express | Standard | Not supported | | [Amazon SageMaker AI](connect-sagemaker.md) | Standard & Express | Standard | Not supported | | [Amazon SNS](connect-sns.md) | Standard & Express | Not supported | Standard | | [Amazon SQS](connect-sqs.md) | Standard & Express | Not supported | Standard | | [AWS Step Functions](connect-stepfunctions.md) | Standard & Express | Standard | Standard | ## Request Response When you specify a service in the `"Resource"` string of your task state, and you *only* provide the resource, Step Functions will wait for an HTTP response and then progress to the next state. Step Functions will not wait for a job to complete. The following example shows how you can publish an Amazon SNS topic. ``` "Send message to SNS": { "Type":"Task", "Resource":"arn:aws:states:::sns:publish", "Parameters": { "TopicArn":"arn:aws:sns:region:123456789012:myTopic", "Message":"Hello from Step Functions!" }, "Next":"NEXT_STATE" } ``` This example references the [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html) API of Amazon SNS. The workflow progresses to the next state after calling the `Publish` API. **Tip** To deploy a sample workflow that uses the Request Response service integration pattern, see [Integrate a service](getting-started.md#step-4-integrate-a-service) in the getting started tutorial in this guide, or in the [Request Response module](https://catalog.workshops.aws/stepfunctions/integrating-services/1-request-response) in *The AWS Step Functions Workshop*. ## Run a Job (.sync) For integrated services such as AWS Batch and Amazon ECS, Step Functions can wait for a request to complete before progressing to the next state. To have Step Functions wait, specify the `"Resource"` field in your task state definition with the `.sync` suffix appended after the resource URI. For example, when submitting an AWS Batch job, use the `"Resource"` field in the state machine definition as shown in this example. ``` "Manage Batch task": { "Type": "Task", "Resource": "arn:aws:states:::batch:submitJob.sync", "Parameters": { "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition", "JobName": "testJob", "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue" }, "Next": "NEXT_STATE" } ``` Having the `.sync` portion appended to the resource Amazon Resource Name (ARN) means that Step Functions waits for the job to complete. After calling AWS Batch `submitJob`, the workflow pauses. When the job is complete, Step Functions progresses to the next state. For more information, see the AWS Batch sample project: [Manage a batch job with AWS Batch and Amazon SNS](batch-job-notification.md). If a task using this (`.sync`) service integration pattern is aborted, and Step Functions is unable to cancel the task, you might incur additional charges from the integrated service. A task can be aborted if: + The state machine execution is stopped. + A different branch of a Parallel state fails with an uncaught error. + An iteration of a Map state fails with an uncaught error. Step Functions will make a best-effort attempt to cancel the task. For example, if a Step Functions `states:startExecution.sync` task is aborted, it will call the Step Functions `StopExecution` API action. However, it is possible that Step Functions will be unable to cancel the task. Reasons for this include, but are not limited to: + Your IAM execution role lacks permission to make the corresponding API call. + A temporary service outage occurred. When you use the `.sync` service integration pattern, Step Functions uses polling that consumes your assigned quota and events to monitor a job's status. For `.sync` invocations within the same account, Step Functions uses EventBridge events and polls the APIs that you specify in the `Task` state. For [cross-account](concepts-access-cross-acct-resources.md) `.sync` invocations, Step Functions only uses polling. For example, for `states:StartExecution.sync`, Step Functions performs polling on the [DescribeExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) API and uses your assigned quota. **Tip** To deploy an example workflow that uses the .sync integration pattern, see [Run a Job (.sync)](https://catalog.workshops.aws/stepfunctions/integrating-services/2-sync-job) in *The AWS Step Functions Workshop*. To see a list of what integrated services support waiting for a job to complete (`.sync`), see [Integrating services with Step Functions](integrate-optimized.md). **Note** Service integrations that use the `.sync` or `.waitForTaskToken` patterns require additional IAM permissions. For more information, see [How Step Functions generates IAM policies for integrated services](service-integration-iam-templates.md). In some cases, you may want Step Functions to continue your workflow before the job is fully complete. You can achieve this in the same way as when using the [Wait for a Callback with Task Token](#connect-wait-token) service integration pattern. To do this, pass a task token to your job, then return it using a [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) or [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) API call. Step Functions will use the data you provide in that call to complete the task, stop monitoring the job, and continue the workflow. ## Wait for a Callback with Task Token Callback tasks provide a way to pause a workflow until a task token is returned. A task might need to wait for a human approval, integrate with a third party, or call legacy systems. For tasks like these, you can pause Step Functions until the workflow execution reaches the one year service quota (see, [Quotas related to state throttling](service-quotas.md#service-limits-api-state-throttling)), and wait for an external process or workflow to complete. For these situations Step Functions allows you to pass a task token to the AWS SDK service integrations, and also to some Optimized service integrations. The task will pause until it receives that task token back with a [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) or [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) call. If a `Task` state using the callback task token times out, a new random token is generated. You can access the task tokens from the [Context object](input-output-contextobject.md#contextobject-access). To use `.waitForTaskToken` with an AWS SDK integration, the API you use must have a parameter field in which to place the task token. **Note** You must pass task tokens from principals within the same AWS account. The tokens won't work if you send them from principals in a different AWS account. **Tip** To deploy an example workflow that uses a callback task token integration pattern, see [Callback with Task Token](https://catalog.workshops.aws/stepfunctions/integrating-services/3-callback-token) in *The AWS Step Functions Workshop*. To see a list of what integrated services support waiting for a task token (`.waitForTaskToken`), see [Integrating services with Step Functions](integrate-optimized.md). **Topics** + [Task Token Example](#connect-wait-example) + [Get a Token from the Context object](#wait-token-contextobject) + [Configure a Heartbeat Timeout for a Waiting Task](#wait-token-hearbeat) ### Task Token Example In this example, a Step Functions workflow needs to integrate with an external microservice to perform a credit check as a part of an approval workflow. Step Functions publishes an Amazon SQS message that includes a task token as a part of the message. An external system integrates with Amazon SQS, and pulls the message off the queue. When that's finished, it returns the result and the original task token. Step Functions then continues with its workflow. ![\[SQS task waiting for a task token to be returned\]](http://docs.aws.amazon.com/step-functions/latest/dg/images/wait-for-task-token.png) The `"Resource"` field of the task definition that references Amazon SQS includes `.waitForTaskToken` appended to the end. ``` "Send message to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue", "MessageBody": { "Message": "Hello from Step Functions!", "TaskToken.$": "$$.Task.Token" } }, "Next": "NEXT_STATE" } ``` This tells Step Functions to pause and wait for the task token. When you specify a resource using `.waitForTaskToken`, the task token can be accessed in the `"Parameters"` field of your state definition with a special path designation (`$$.Task.Token`). The initial `$$.` designates that the path accesses the [Context object](#wait-token-contextobject), and gets the task token for the current task in a running execution. When it's complete, the external service calls [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) or [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) with the `taskToken` included. Only then does the workflow continue to the next state. **Note** To avoid waiting indefinitely if a process fails to send the task token with `SendTaskSuccess` or `SendTaskFailure`, see [Configure a Heartbeat Timeout for a Waiting Task](#wait-token-hearbeat). ### Get a Token from the Context object The Context object is an internal JSON object that contains information about your execution. Like state input, it can be accessed with a path from the `"Parameters"` field during an execution. When accessed from within a task definition, it includes information about the specific execution, including the task token. ``` { "Execution": { "Id": "arn:aws:states:region:account-id:execution:stateMachineName:executionName", "Input": { "key": "value" }, "Name": "executionName", "RoleArn": "arn:aws:iam::account-id:role...", "StartTime": "2019-03-26T20:14:13.192Z" }, "State": { "EnteredTime": "2019-03-26T20:14:13.192Z", "Name": "Test", "RetryCount": 3 }, "StateMachine": { "Id": "arn:aws:states:region:account-id:stateMachine:stateMachineName", "Name": "name" }, "Task": { "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W" } } ``` You can access the task token by using a special path from inside the `"Parameters"` field of your task definition. To access the input or the Context object, you first specify that the parameter will be a path by appending a `.$` to the parameter name. The following specifies nodes from both the input and the Context object in a `"Parameters"` specification. ``` "Parameters": { "Input.$": "$", "TaskToken.$": "$$.Task.Token" }, ``` In both cases, appending `.$` to the parameter name tells Step Functions to expect a path. In the first case, `"$"` is a path that includes the entire input. In the second case, `$$.` specifies that the path will access the Context object, and `$$.Task.Token` sets the parameter to the value of the task token in the Context object of a running execution. In the Amazon SQS example, `.waitForTaskToken` in the `"Resource"` field tells Step Functions to wait for the task token to be returned. The `"TaskToken.$": "$$.Task.Token"` parameter passes that token as a part of the Amazon SQS message. ``` "Send message to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "Parameters": { "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue", "MessageBody": { "Message": "Hello from Step Functions!", "TaskToken.$": "$$.Task.Token" } }, "Next": "NEXT_STATE" } ``` For more information about the Context object, see [Accessing execution data from the Context object in Step Functions](input-output-contextobject.md) in the [Processing input and output](concepts-input-output-filtering.md) section in this guide. ### Configure a Heartbeat Timeout for a Waiting Task A task that is waiting for a task token will wait until the execution reaches the one year service quota (see, [Quotas related to state throttling](service-quotas.md#service-limits-api-state-throttling)). To avoid stuck executions you can configure a heartbeat timeout interval in your state machine definition. Use the [`HeartbeatSeconds`](state-task.md) field to specify the timeout interval. ``` { "StartAt": "Push to SQS", "States": { "Push to SQS": { "Type": "Task", "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken", "HeartbeatSeconds": 600, "Parameters": { "MessageBody": { "myTaskToken.$": "$$.Task.Token" }, "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue" }, "ResultPath": "$.SQS", "End": true } } } ``` In this state machine definition, a task pushes a message to Amazon SQS and waits for an external process to call back with the provided task token. The `"HeartbeatSeconds": 600` field sets the heartbeat timeout interval to 10 minutes. The task will wait for the task token to be returned with one of these API actions: + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskFailure.html) + [https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskHeartbeat.html) If the waiting task doesn't receive a valid task token within that 10-minute period, the task fails with a `States.Timeout` error name. For more information, see the callback task sample project [Create a callback pattern example with Amazon SQS, Amazon SNS, and Lambda](callback-task-sample-sqs.md).