State Machines & Service Integrations

## The suffix is the contract A Task state's `Resource` field says both *what* to call and *when the state is done*. Three patterns exist, and they are distinguished by a suffix on the ARN. ``` arn:aws:states:::ecs:runTask # request-response arn:aws:states:::ecs:runTask.sync # job-run: wait for the task to finish arn:aws:states:::ecs:runTask.waitForTaskToken # callback: wait for someone to report back ``` Getting this wrong is one of the classic Step Functions bugs, so it makes a good interview question: a workflow that "works" but whose downstream step reads results that do not exist yet is almost always a request-response state where the author assumed `.sync`. ## Request-response (the default) Step Functions makes the API call, waits only for the HTTP response, records that response as the state's output, and transitions. For a synchronous API such as `lambda:invoke` (a RequestResponse invocation) that is exactly what you want — the function ran, and its return value is your output. For an *asynchronous* API it is a trap. `ecs:runTask` returns as soon as the task is accepted; `glue:startJobRun` returns a job run id. The state succeeds in a second, and the next state runs against a job that has not started producing output. Nothing errors — the workflow is simply wrong. ## Job-run: `.sync` The `.sync` suffix asks Step Functions to keep the state open until the underlying job reaches a terminal state, and to fail the state if the job failed. Under the hood the service tracks the job (via events and polling) on your behalf, which is why the execution role needs more than just the start permission — it typically also needs describe/stop permissions and, for event-driven tracking, permission for the managed EventBridge rule the service creates. Commonly used ones: ``` arn:aws:states:::ecs:runTask.sync arn:aws:states:::batch:submitJob.sync arn:aws:states:::glue:startJobRun.sync arn:aws:states:::states:startExecution.sync:2 ``` That last one — a state machine invoking another state machine and waiting — is how you compose workflows, and the `:2` variant returns the child's output already parsed as JSON rather than as a string. Not every service offers `.sync`; the supported list is fixed by AWS, and if the one you need is absent, the callback pattern is the fallback. ## Callback: `.waitForTaskToken` This is the pattern that makes Step Functions useful for processes involving things AWS cannot see. When the state runs, Step Functions generates a task token, exposes it through the context object as `$$.Task.Token`, and — crucially — **you must pass it into the payload yourself**, because the token is only useful if the worker receives it: ```json "Parameters": { "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/approvals", "MessageBody": { "orderId.$": "$.orderId", "TaskToken.$": "$$.Task.Token" } } ``` The state then suspends. It does not consume compute, and the workflow's persisted state is exactly where it was. It resumes only when something calls `SendTaskSuccess` (with a JSON output that becomes the state's result) or `SendTaskFailure` with that token. That something can be a Lambda function, an on-premises worker, a support engineer clicking a link in an email, or a partner's webhook handler — anything with credentials for `states:SendTaskSuccess`. The worker needs to be given the token and needs to keep it; losing it means the execution sits until the state's configured timeout, which is why you always configure one on a callback state rather than trusting the caller. ## Optimized versus SDK integrations Alongside the three patterns there is a second axis. **Optimized integrations** are the ones AWS wrote special support for — `lambda:invoke`, `sqs:sendMessage`, `dynamodb:putItem`, `ecs:runTask`, `sns:publish` and friends. They have tailored parameters and they are the ones that offer `.sync` and callbacks. **AWS SDK integrations** are the generic escape hatch, addressed as `arn:aws:states:::aws-sdk:<service>:<apiAction>`, for example `arn:aws:states:::aws-sdk:s3:listObjectsV2`. They expose a very large share of the AWS API surface directly from a Task state, with parameter names taken straight from the API model, and they let you drop a Lambda function whose only job was to call one API. They are request-response by nature, though many also accept `.waitForTaskToken`. ## Choosing Ask what "done" means for this step. If the API's return *is* the result, request-response. If the API starts something whose completion you care about, `.sync` when it exists. If completion is reported by something outside AWS's view — a person, a partner, a long poll-based worker — the callback. And remember Express workflows support only the request-response form, so a state machine that needs `.sync` or a callback is Standard.