AWS Step Functions Overview AWS Step Functions uses Amazon States Language (ASL) to define state machines as JSON. With AWS Step Functions, you can create workflows, also called state machines, to build distributed applications, automate processes, orchestrate microservices, and create data and machine learning pipelines. This skill provides comprehensive guidance for writing state machines in ASL, covering: - ASL structure and JSONata expression syntax - Details on the eight available workflow states - The reserved variable - Workflow variables with - Error handling - AWS Service integration…

& $formatNumber($amt, '#,##0.00') }; $subtotal := $sum($states.input.items.price); {'itemCount': $count($states.input.items), 'subtotal': $formatPrice($subtotal), 'total': $formatPrice($subtotal * 1.1)} ) %}\"\n}\n```\n\nLocal variables bound with `:=` exist only within the `( ... )` block. They do not affect state machine variables. To persist values across states, use the `Assign` field.\n\n### Filtering Arrays\n\n```json\n\"Output\": {\n \"expensiveItems\": \"{% $states.input.items[price > 100] %}\"\n}\n```\n\n### Aggregation\n\n```json\n\"Output\": {\n \"total\": \"{% $sum($states.input.items.price) %}\",\n \"average\": \"{% $average($states.input.items.price) %}\",\n \"count\": \"{% $count($states.input.items) %}\"\n}\n```\n\n### String Operations\n\n```json\n\"Output\": {\n \"fullName\": \"{% $states.input.firstName & ' ' & $states.input.lastName %}\",\n \"upper\": \"{% $uppercase($states.input.name) %}\",\n \"trimmed\": \"{% $trim($states.input.rawInput) %}\"\n}\n```\n\n### Object Merging\n\n```json\n\"Output\": \"{% $merge([$states.input, {'processedAt': $now(), 'status': 'complete'}]) %}\"\n```\n\n### Building Lookup Maps with `$reduce`\n\nUse `$reduce` to transform an array into a key-value object:\n\n```json\n\"Assign\": {\n \"priceByProduct\": \"{% $reduce($states.input.items, function($acc, $item) { $merge([$acc, {$item.productId: $item.price}]) }, {}) %}\"\n}\n```\n\nGiven `[{\"productId\": \"A1\", \"price\": 10}, {\"productId\": \"B2\", \"price\": 25}]`, this produces `{\"A1\": 10, \"B2\": 25}`.\n\n### Dynamic Key Access with `$lookup`\n\nUse `$lookup` to access an object property by a variable key:\n\n```json\n\"Output\": {\n \"price\": \"{% $lookup($priceByProduct, $states.input.productId) %}\"\n}\n```\n\nThis is essential when you've built a mapping object with `$reduce` and need to retrieve values dynamically. Standard dot notation (`$priceByProduct.someKey`) only works with literal key names.\n\n### Conditional Values\n\n```json\n\"Output\": {\n \"tier\": \"{% $states.input.total > 1000 ? 'gold' : 'standard' %}\",\n \"discount\": \"{% $exists($states.input.coupon) ? 0.1 : 0 %}\"\n}\n```\n\n### Array Membership with `in` and Concatenation with `$append`\n\nTest if a value exists in an array with `in`:\n\n```json\n\"Condition\": \"{% $states.input.status in ['pending', 'processing', 'shipped'] %}\"\n```\n\nConcatenate arrays with `$append`:\n\n```json\n\"Assign\": {\n \"allIds\": \"{% $append($states.input.orderIds, $states.input.returnIds) %}\"\n}\n```\n\n### Array Mapping\n\n```json\n\"Output\": {\n \"names\": \"{% $states.input.users.(firstName & ' ' & lastName) %}\"\n}\n```\n\n### Generating UUIDs and Random Values\n\n```json\n\"Assign\": {\n \"requestId\": \"{% $uuid() %}\",\n \"randomValue\": \"{% $random() %}\"\n}\n```\n\n### Partitioning Arrays\n\n```json\n\"Assign\": {\n \"batches\": \"{% $partition($states.input.items, 10) %}\"\n}\n```\n\n### Parsing JSON Strings\n\n```json\n\"Assign\": {\n \"parsed\": \"{% $parse($states.input.jsonString) %}\"\n}\n```\n\n### Hashing\n\n```json\n\"Assign\": {\n \"hash\": \"{% $hash($states.input.content, 'SHA-256') %}\"\n}\n```\n\n### Timestamp Comparison with `$toMillis`\n\nJSONata timestamps are strings, so you can't compare them directly with `\u003c` or `>`. Use `$toMillis` to convert to numeric milliseconds:\n\n```json\n\"Condition\": \"{% $toMillis($states.input.orderDate) > $toMillis($states.input.cutoffDate) %}\"\n```\n\nUseful for sorting timestamps, calculating durations, or finding the most recent entry:\n\n```json\n\"Assign\": {\n \"ageMinutes\": \"{% $round(($toMillis($now()) - $toMillis($states.input.createdAt)) / 60000, 2) %}\",\n \"mostRecent\": \"{% $sort($states.input.timestamps, function($a, $b) { $toMillis($a) \u003c $toMillis($b) })[0] %}\"\n}\n```\n\n## Step Functions Built-in functions\n\n| Function | Purpose |\n|----------|---------|\n| `$partition(array, size)` | Partition array into chunks |\n| `$range(start, end, step)` | Generate array of values |\n| `$hash(data, algorithm)` | Calculate hash (MD5, SHA-1, SHA-256, SHA-384, SHA-512) |\n| `$random([seed])` | Random number 0 ≤ n \u003c 1, optional seed |\n| `$uuid()` | Generate v4 UUID |\n| `$parse(jsonString)` | Deserialize JSON string |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6052,"content_sha256":"9cbe2825e824bc7a6b226875d2d16f265e96ad316fb8bb2e74b9215e5880f3aa"},{"filename":"references/validation-and-testing.md","content":"# Validation and Testing\n\n## Local ASL Validation\n\nFiles saved with the `.asl.json` extension get automatic validation from the AWS Toolkit Extension. If the extension is not installed, suggest the user install it (https://open-vsx.org/extension/amazonwebservices/aws-toolkit-vscode). Use your diagnostics tool on any `.asl.json` file to catch structural errors instantly. The State Machine definition must be saved as `.asl.json` to work with local validation.\n\n---\n\n## Testing with TestState API\n\nThe TestState API enables unit and integration testing of Step Functions without deployment. Key capabilities:\n\n- **Mock service integrations** — Test without invoking real services\n- **Advanced states** — Map, Parallel, Activity, `.sync`, `.waitForTaskToken` (require mocks)\n- **Control execution** — Simulate retries, Map iterations, error scenarios\n- **Chain tests** — Use output→input to test execution paths\n- **Optional IAM** — When mocking, `roleArn` optional\n\n### Before Accessing AWS\n\nBefore calling the TestState API, follow this sequence:\n\n1. Ask the user to grant you permission to use the TestState API in their AWS account.\n2. Check for AWS credentials: run `aws sts get-caller-identity` and verify the response.\n3. If credentials are available, confirm the IAM role ARN to use for execution (or omit if using mocks).\n4. If credentials are unavailable, help the user construct the CLI/SDK call to run manually.\n5. Never assume AWS access — always ask before making any AWS API call.\n\n> **Prefer short-lived credentials:** Use credentials from an IAM role (EC2 instance profile, ECS task role, or AWS IAM Identity Center) rather than long-lived access keys stored in `~/.aws/credentials`.\n\n### Required IAM Permissions\n\nThe calling identity needs `states:TestState`. If not using mocks, it also needs `iam:PassRole` for the execution role. For HTTP Task with `revealSecrets`, add `states:RevealSecrets`.\n\n```bash\naws stepfunctions test-state \\\n --definition '{\"Type\":\"Task\",\"Resource\":\"arn:aws:states:::lambda:invoke\",\"Arguments\":{...},\"End\":true}' \\\n --input '{\"data\":\"value\"}' \\\n --mock '{\"result\":\"{\\\"StatusCode\\\":200,\\\"Payload\\\":{\\\"body\\\":\\\"success\\\"}}\"}' \\\n --inspection-level DEBUG\n```\n\n## Inspection Levels\n\n| Level | Returns | Use Case |\n| --------- | ------------------------------------------------------------------------------- | ------------------- |\n| **INFO** | `output`, `status`, `nextState` | Quick validation |\n| **DEBUG** | + `afterArguments`, `result`, `variables` | Data flow debugging |\n| **TRACE** | + HTTP `request`/`response` (use `--reveal-secrets` for auth) | HTTP Task debugging |\n\n## Critical: Service-Specific Mock Structure\n\n**⚠️ Mocks MUST match AWS service API response schema exactly** — field names (case-sensitive), types, required fields.\n\n### Finding Mock Structure\n\n1. Identify service from `Resource` ARN: `arn:aws:states:::lambda:invoke` → Lambda `Invoke` API\n2. Consult AWS SDK docs for that API's Response Syntax\n3. Structure mock to match\n\n### Common Service Mocks\n\n| Service | API | Mock Structure | Example |\n| --------------- | ---------------- | --------------------------------------- | ----------------------------------------------------------------------------- |\n| Lambda | `Invoke` | `{StatusCode, Payload, FunctionError?}` | `'{\"result\":\"{\\\"StatusCode\\\":200,\\\"Payload\\\":{\\\"body\\\":\\\"ok\\\"}}\"}'` |\n| DynamoDB | `PutItem` | `{Attributes?}` | `'{\"result\":\"{\\\"Attributes\\\":{\\\"id\\\":{\\\"S\\\":\\\"123\\\"}}}\"}'` |\n| DynamoDB | `GetItem` | `{Item?}` | `'{\"result\":\"{\\\"Item\\\":{\\\"id\\\":{\\\"S\\\":\\\"123\\\"}}}\"}'` |\n| SNS | `Publish` | `{MessageId}` | `'{\"result\":\"{\\\"MessageId\\\":\\\"abc-123\\\"}\"}'` |\n| SQS | `SendMessage` | `{MessageId, MD5OfMessageBody}` | `'{\"result\":\"{\\\"MessageId\\\":\\\"xyz\\\",\\\"MD5OfMessageBody\\\":\\\"...\\\"}\"}'` |\n| EventBridge | `PutEvents` | `{FailedEntryCount, Entries[]}` | `'{\"result\":\"{\\\"FailedEntryCount\\\":0,\\\"Entries\\\":[{\\\"EventId\\\":\\\"123\\\"}]}\"}'` |\n| S3 | `PutObject` | `{ETag, VersionId?}` | `'{\"result\":\"{\\\"ETag\\\":\\\"\\\\\\\"abc123\\\\\\\"\\\"}\"}'` |\n| Step Functions | `StartExecution` | `{ExecutionArn, StartDate}` | `'{\"result\":\"{\\\"ExecutionArn\\\":\\\"arn:...\\\",\\\"StartDate\\\":\\\"...\\\"}\"}'` |\n| Secrets Manager | `GetSecretValue` | `{ARN, Name, SecretString?}` | `'{\"result\":\"{\\\"Name\\\":\\\"MySecret\\\",\\\"SecretString\\\":\\\"...\\\"}\"}'` |\n\n**For `.sync` patterns:** Mock the **polling API** (e.g., `startExecution.sync:2` → mock `DescribeExecution`, NOT `StartExecution`)\n\n### Mock Syntax\n\n**Success:** `--mock '{\"result\":\"\u003cservice API response JSON>\"}'`\\\n**Error:** `--mock '{\"errorOutput\":{\"error\":\"ErrorCode\",\"cause\":\"description\"}}'`\\\n**Validation:** `--mock '{\"fieldValidationMode\":\"STRICT|PRESENT|NONE\",\"result\":\"...\"}'`\n\n**Validation modes:**\n\n- `STRICT` (default): All required fields, correct types — use in CI/CD\n- `PRESENT`: Only validate fields present — flexible testing\n- `NONE`: No validation — quick prototyping only\n\n## Testing Map States\n\nTests Map's **input/output processing**, not iterations inside. Mock = entire Map output.\n\n```bash\naws stepfunctions test-state \\\n --definition '{\n \"Type\":\"Map\",\n \"Items\":\"{% $states.input.items %}\",\n \"ItemSelector\":{\"value\":\"{% $states.context.Map.Item.Value %}\"},\n \"ItemProcessor\":{\"ProcessorConfig\":{\"Mode\":\"INLINE\"},...},\n \"End\":true\n }' \\\n --input '{\"items\":[1,2,3]}' \\\n --mock '{\"result\":\"[10,20,30]\"}' \\\n --inspection-level DEBUG\n```\n\n**DEBUG returns:** `afterItemSelector`, `afterItemBatcher`, `toleratedFailureCount`, `maxConcurrency`\n\n**Distributed Map:** Provide data in input (as if read from S3)\\\n**Failure threshold testing:** Use `--state-configuration '{\"mapIterationFailureCount\":N}'`\\\n**Testing state within Map:** `--state-name` auto-populates `$states.context.Map.Item.Index`, `$states.context.Map.Item.Value`\n\n## Testing Parallel States\n\nMock = JSON array, one element per branch (in definition order):\n\n```bash\n--mock '{\"result\":\"[{\\\"branch1\\\":\\\"result1\\\"},{\\\"branch2\\\":\\\"result2\\\"}]\"}'\n```\n\n## Testing Error Handling\n\n### Retry Logic\n\n```bash\n--state-configuration '{\"retrierRetryCount\":1}' \\\n--mock '{\"errorOutput\":{\"error\":\"Lambda.ServiceException\",\"cause\":\"...\"}}' \\\n--inspection-level DEBUG\n```\n\nResponse includes: `status:\"RETRIABLE\"`, `retryBackoffIntervalSeconds`, `retryIndex`\n\n### Catch Handlers\n\n```bash\n--mock '{\"errorOutput\":{\"error\":\"Lambda.TooManyRequestsException\",\"cause\":\"...\"}}' \\\n--inspection-level DEBUG\n```\n\nResponse includes: `status:\"CAUGHT_ERROR\"`, `nextState`, `catchIndex`, error in `output`\n\n### Error Propagation in Map/Parallel\n\n```bash\n--state-name \"ChildState\" \\\n--state-configuration '{\"errorCausedByState\":\"ChildState\"}' \\\n--mock '{\"errorOutput\":{\"error\":\"States.TaskFailed\",\"cause\":\"...\"}}'\n```\n\n## Testing .sync and .waitForTaskToken\n\n**Required:** Must provide mock (validation exception otherwise)\n\n### .sync Patterns\n\nMock the **polling API**, not initial call:\n\n```bash\n# startExecution.sync:2 → mock DescribeExecution\n--mock '{\"result\":\"{\\\"Status\\\":\\\"SUCCEEDED\\\",\\\"Output\\\":\\\"{...}\\\"}\"}'\n```\n\nCommon patterns: `startExecution.sync:2`→`DescribeExecution`, `batch:submitJob.sync`→`DescribeJobs`, `glue:startJobRun.sync`→`GetJobRun`\n\n### .waitForTaskToken\n\n```bash\n--context '{\"Task\":{\"Token\":\"test-token-123\"}}' \\\n--mock '{\"result\":\"{\\\"StatusCode\\\":200,\\\"Payload\\\":{\\\"status\\\":\\\"approved\\\"}}\"}'\n```\n\n## Activity States\n\nRequire mock:\n\n```bash\n--definition '{\"Type\":\"Task\",\"Resource\":\"arn:aws:states:...:activity:MyActivity\",...}' \\\n--mock '{\"result\":\"{\\\"result\\\":\\\"completed\\\"}\"}'\n```\n\n## Chaining Tests (Integration Testing)\n\n```bash\nRESULT_1=$(aws stepfunctions test-state --state-name \"State1\" ... | jq -r '.output')\nNEXT_1=$(... | jq -r '.nextState')\nRESULT_2=$(aws stepfunctions test-state --state-name \"$NEXT_1\" --input \"$RESULT_1\" ...)\n```\n\nValidates: data transformations, state transitions, end-to-end paths\n\n## Context Fields\n\nTest states referencing execution context:\n\n```bash\n--context '{\n \"Execution\":{\"Id\":\"arn:...\",\"Name\":\"test-123\",\"StartTime\":\"2024-01-01T10:00:00.000Z\"},\n \"State\":{\"Name\":\"ProcessData\",\"EnteredTime\":\"2024-01-01T10:00:05.000Z\"},\n \"Task\":{\"Token\":\"test-token-abc123\"}\n}'\n```\n\n## HTTP Tasks (TRACE)\n\n```bash\n--resource \"arn:aws:states:::http:invoke\" \\\n--inspection-level TRACE \\\n--reveal-secrets # Requires states:RevealSecrets permission\n```\n\nReturns: `inspectionData.request` (method, URL, headers, body), `inspectionData.response` (status, headers, body)\n\n## Troubleshooting\n\n| Error | Fix |\n| ----------------------- | ---------------------------------------------- |\n| Invalid field type | Check AWS SDK docs for correct types |\n| Required field missing | Add field OR use `fieldValidationMode:PRESENT` |\n| .sync validation failed | Mock polling API, not initial call |\n\n**Debug workflow:**\n\n1. Start `fieldValidationMode:NONE` for logic testing\n2. Switch to `PRESENT` for partial validation\n3. Use `STRICT` in CI/CD\n\n## Test Automation Pattern\n\n```bash\n#!/bin/bash\ntest_state() {\n local state_name=$1\n local input=$2\n local mock=$3\n\n aws stepfunctions test-state \\\n --definition \"$(cat statemachine.asl.json)\" \\\n --state-name \"$state_name\" \\\n --input \"$input\" \\\n --mock \"$mock\" \\\n --inspection-level DEBUG\n}\n\n# Test chain\nRESULT=$(test_state \"State1\" '{\"id\":\"123\"}' '{\"result\":\"...\"}' | jq -r '.output')\ntest_state \"State2\" \"$RESULT\" '{\"result\":\"...\"}'\n```\n\n## Best Practices\n\n1. **Always verify mock structure** against AWS SDK docs for the specific service\n2. **For .sync, mock polling API** (DescribeX/GetX), not initial call\n3. **Use STRICT validation in CI/CD** to catch mismatches early\n4. **Test all error paths** with appropriate error codes\n5. **Chain tests** to validate multi-state execution paths\n6. **Start with NONE→PRESENT→STRICT** when developing mocks\n7. **Use DEBUG for data flow**, TRACE for HTTP debugging\n8. **Mock external dependencies** to isolate state machine logic\n9. **Test Map failure thresholds** with `mapIterationFailureCount`\n10. **Never expose `--reveal-secrets` output** — keep it out of version control, shell history, CI/CD build logs, and CloudWatch Logs; redirect to a file with restricted permissions and avoid persisting DEBUG/TRACE output that may contain secrets\n\n## Quick Reference\n\n```bash\n# Basic test\naws stepfunctions test-state --definition '{...}' --input '{...}' --mock '{...}'\n\n# Test specific state in state machine\naws stepfunctions test-state --definition \"$(cat sm.json)\" --state-name \"MyState\" --input '{...}' --mock '{...}'\n\n# Test retry (2nd attempt)\n--state-configuration '{\"retrierRetryCount\":1}' --mock '{\"errorOutput\":{...}}'\n\n# Test Map failure threshold\n--state-configuration '{\"mapIterationFailureCount\":5}' --mock '{\"errorOutput\":{...}}'\n\n# Test with context\n--context '{\"Execution\":{\"Id\":\"...\"}, \"Task\":{\"Token\":\"...\"}}'\n\n# HTTP Task with secrets\n--inspection-level TRACE --reveal-secrets\n\n# Mock validation modes\n--mock '{\"fieldValidationMode\":\"STRICT|PRESENT|NONE\",\"result\":\"...\"}'\n```\n\n---\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":11708,"content_sha256":"3b90ea31a4c6b8a88b3f36b10a84f5149e3cd105beacc5c0d671486759d2eaf4"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"AWS Step Functions","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"AWS Step Functions uses Amazon States Language (ASL) to define state machines as JSON. With AWS Step Functions, you can create workflows, also called state machines, to build distributed applications, automate processes, orchestrate microservices, and create data and machine learning pipelines.","type":"text"}]},{"type":"paragraph","content":[{"text":"This skill provides comprehensive guidance for writing state machines in ASL, covering:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ASL structure and JSONata expression syntax","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Details on the eight available workflow states","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"$states","type":"text","marks":[{"type":"code_inline"}]},{"text":" reserved variable","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Workflow variables with ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Error handling","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"AWS Service integration patterns","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Example code for data transformation and architecture","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validation and testing of state machines","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"How to migrate from JSONPath to JSONata","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The AWS MCP server is recommended for sandboxed execution and audit logging when following this skill, but all steps use AWS CLI syntax and work without it.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Load Reference Files","type":"text"}]},{"type":"paragraph","content":[{"text":"Load the appropriate reference file based on what the user is working on:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ASL structure","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"state types","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Task","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Pass","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Choice","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Wait","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Succeed","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Fail","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Parallel","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Map","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/asl-state-types.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Error handling","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"troubleshooting","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Retry","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Catch","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"fallback","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"error codes","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"States.Timeout","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"States.ALL","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/error-handling.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Service integrations","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Lambda invoke","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"DynamoDB","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"SNS","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"SQS","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"SDK integrations","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Resource ARN","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"async","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/service-integrations.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migrating from JSONPath to JSONata","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"migration","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"JSONPath to JSONata","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"InputPath","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Parameters","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"ResultSelector","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"ResultPath","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"OutputPath","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"intrinsic functions","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Iterator","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"payload template","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/migrating-from-jsonpath-to-jsonata.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validation","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"linting","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"testing","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"TestState","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"test state","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"mock","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"mocking","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"unit test","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"inspection level","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"DEBUG","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"TRACE","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"validate state","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"test in isolation","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/validation-and-testing.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Architecture patterns","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"examples","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"polling","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"saga","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"compensation","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"scatter-gather","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"semaphore","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"lock","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"human-in-the-loop","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"escalation","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Express to Standard","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/architecture-patterns.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Data transformation","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"JSONata expressions","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"filtering","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"aggregation","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"string operations","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"type":"math_inline","marks":[{"type":"strong"}],"content":[{"text":"reduce**, **","type":"text"}]},{"text":"lookup","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"type":"math_inline","marks":[{"type":"strong"}],"content":[{"text":"toMillis**, **","type":"text"}]},{"text":"partition","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"type":"math_inline","marks":[{"type":"strong"}],"content":[{"text":"parse**, **","type":"text"}]},{"text":"hash","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"$uuid","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/transforming-data.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"State input/output","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"$states","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"Arguments","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"variable scope","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"variable limits","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"evaluation order","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"passing data between states","type":"text","marks":[{"type":"strong"}]},{"text":" → see ","type":"text"},{"text":"references/processing-state-inputs-and-outputs.md","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quick Reference","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Standard vs Express Workflows","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph"}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Standard","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Express","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Max duration","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"1 year","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"5 minutes","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Execution semantics","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Exactly-once","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"At-least-once (async) / At-most-once (sync)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Execution history","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Retained 90 days, queryable via API","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"CloudWatch Logs only","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Max throughput","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2,000 exec/sec","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"100,000 exec/sec","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Pricing model","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Per state transition","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Per execution count + duration","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":".sync","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" / ","type":"text","marks":[{"type":"strong"}]},{"text":".waitForTaskToken","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Supported","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Not supported","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Best for","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Auditable, non-idempotent operations","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"High-volume, idempotent event processing","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Choose Standard","type":"text","marks":[{"type":"strong"}]},{"text":" for: payment processing, order fulfillment, compliance workflows, anything that must never execute twice.","type":"text"}]},{"type":"paragraph","content":[{"text":"Choose Express","type":"text","marks":[{"type":"strong"}]},{"text":" for: IoT data ingestion, streaming transformations, mobile backends, high-throughput short-lived processing.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"When recommending Express, the single limitation you must always state — even for fire-and-forget / high-throughput pipelines — is that Express does NOT support ","type":"text","marks":[{"type":"strong"}]},{"text":".sync","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" or ","type":"text","marks":[{"type":"strong"}]},{"text":".waitForTaskToken","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (no callbacks, no nested ","type":"text"},{"text":".sync","type":"text","marks":[{"type":"code_inline"}]},{"text":" waits, no human-approval or job-completion waits). Also note: 5-minute max duration, no queryable execution history (CloudWatch Logs only), and at-least-once (async) / at-most-once (sync) execution — so non-idempotent work can run twice. If any of these matter, choose Standard (exactly-once, up to 1 year, full history).","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Setting the State Machine Query Language","type":"text"}]},{"type":"paragraph","content":[{"text":"JSONata is the preferred way to reference and transform data in ASL. It replaces the five JSONPath I/O fields (","type":"text"},{"text":"InputPath","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Parameters","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"ResultSelector","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"ResultPath","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"OutputPath","type":"text","marks":[{"type":"code_inline"}]},{"text":") with just two: ","type":"text"},{"text":"Arguments","type":"text","marks":[{"type":"code_inline"}]},{"text":" (inputs) and ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Enable at the top level","type":"text","marks":[{"type":"strong"}]},{"text":" to apply to all states:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{ \"QueryLanguage\": \"JSONata\", \"StartAt\": \"...\", \"States\": {...} }","type":"text"}]},{"type":"paragraph","content":[{"text":"Or per-state","type":"text","marks":[{"type":"strong"}]},{"text":" to migrate from JSONPath incrementally:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{ \"Type\": \"Task\", \"QueryLanguage\": \"JSONata\", ... }","type":"text"}]},{"type":"paragraph","content":[{"text":"JSONPath is supported","type":"text","marks":[{"type":"strong"}]},{"text":" and is the default if ","type":"text"},{"text":"QueryLanguage","type":"text","marks":[{"type":"code_inline"}]},{"text":" is omitted — existing state machines do not need to be migrated.","type":"text"}]},{"type":"paragraph","content":[{"text":"Field mapping (JSONPath → JSONata):","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"JSONPath field","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"JSONata equivalent","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Parameters","type":"text","marks":[{"type":"code_inline"}]},{"text":" (keys use ","type":"text"},{"text":"key.$","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Arguments","type":"text","marks":[{"type":"code_inline"}]},{"text":" — drop the ","type":"text"},{"text":".$","type":"text","marks":[{"type":"code_inline"}]},{"text":" suffix and wrap each value in ","type":"text"},{"text":"{% %}","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ResultSelector","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"OutputPath","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" (reference the raw result via ","type":"text"},{"text":"$states.result","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ResultPath","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" (preferred) or ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"InputPath","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"not needed — reference ","type":"text"},{"text":"$states.input","type":"text","marks":[{"type":"code_inline"}]},{"text":" directly","type":"text"}]}]}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"A state uses one query language, not both.","type":"text","marks":[{"type":"strong"}]},{"text":" Never mix JSONPath fields (","type":"text"},{"text":"InputPath","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"Parameters","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"ResultSelector","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"ResultPath","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"OutputPath","type":"text","marks":[{"type":"code_inline"}]},{"text":") with JSONata fields (","type":"text"},{"text":"Arguments","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":") in the same state — this is the most common migration error. See ","type":"text"},{"text":"references/migrating-from-jsonpath-to-jsonata.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for full details.","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"How Assign and Output Are Evaluated (Parallel, Not Sequential)","type":"text"}]},{"type":"paragraph","content":[{"text":"Within a single state, ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" are evaluated ","type":"text"},{"text":"at the same time — in parallel — both reading the same data (the state input plus the task result)","type":"text","marks":[{"type":"strong"}]},{"text":". They are NOT evaluated one after the other. Because they run together, a variable you set in ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" visible in that same state's ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":": there is no ordering in which ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" could observe the just-assigned value. The assigned value becomes available only to ","type":"text"},{"text":"subsequent","type":"text","marks":[{"type":"strong"}]},{"text":" states.","type":"text"}]},{"type":"paragraph","content":[{"text":"So if you set a variable in ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" and reference it in the same state's ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":", you get the old/undefined value — not because ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" runs \"before\" ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":", but because both evaluate concurrently from the same snapshot. To use the value immediately, reference it in the ","type":"text"},{"text":"next","type":"text","marks":[{"type":"strong"}]},{"text":" state (variables persist across states); to shape the current state's output from the task result, use ","type":"text"},{"text":"$states.result","type":"text","marks":[{"type":"code_inline"}]},{"text":" directly in ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Unit Testing a State with TestState","type":"text"}]},{"type":"paragraph","content":[{"text":"Test a single state ","type":"text"},{"text":"without deploying the state machine or calling the real service","type":"text","marks":[{"type":"strong"}]},{"text":" using the TestState API (","type":"text"},{"text":"aws stepfunctions test-state","type":"text","marks":[{"type":"code_inline"}]},{"text":") with ","type":"text"},{"text":"--mock","type":"text","marks":[{"type":"code_inline"}]},{"text":". A complete answer covers all four points:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mock the service response exactly","type":"text","marks":[{"type":"strong"}]},{"text":" — the ","type":"text"},{"text":"--mock","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"result","type":"text","marks":[{"type":"code_inline"}]},{"text":" MUST match the target AWS service's API response schema exactly (field names are case-sensitive). For a Lambda ","type":"text"},{"text":"invoke","type":"text","marks":[{"type":"code_inline"}]},{"text":" Task that is ","type":"text"},{"text":"StatusCode","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"Payload","type":"text","marks":[{"type":"code_inline"}]},{"text":": ","type":"text"},{"text":"--mock '{\"result\":\"{\\\"StatusCode\\\":200,\\\"Payload\\\":{...}}\"}'","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All three inspection levels","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"--inspection-level","type":"text","marks":[{"type":"code_inline"}]},{"text":"): ","type":"text"},{"text":"INFO","type":"text","marks":[{"type":"code_inline"}]},{"text":" (default — ","type":"text"},{"text":"output","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"status","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"nextState","type":"text","marks":[{"type":"code_inline"}]},{"text":"), ","type":"text"},{"text":"DEBUG","type":"text","marks":[{"type":"code_inline"}]},{"text":" (adds data flow: ","type":"text"},{"text":"afterArguments","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"result","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"variables","type":"text","marks":[{"type":"code_inline"}]},{"text":" — use to debug JSONata/data flow), ","type":"text"},{"text":"TRACE","type":"text","marks":[{"type":"code_inline"}]},{"text":" (adds raw HTTP ","type":"text"},{"text":"request","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"response","type":"text","marks":[{"type":"code_inline"}]},{"text":", for HTTP Task).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":".sync","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" and ","type":"text","marks":[{"type":"strong"}]},{"text":".waitForTaskToken","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" integrations still require a mock","type":"text","marks":[{"type":"strong"}]},{"text":" — for ","type":"text"},{"text":".sync","type":"text","marks":[{"type":"code_inline"}]},{"text":", mock the polling API (e.g. ","type":"text"},{"text":"DescribeExecution","type":"text","marks":[{"type":"code_inline"}]},{"text":", not the initial call); for ","type":"text"},{"text":".waitForTaskToken","type":"text","marks":[{"type":"code_inline"}]},{"text":", also pass ","type":"text"},{"text":"--context '{\"Task\":{\"Token\":\"...\"}}'","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No deployment","type":"text","marks":[{"type":"strong"}]},{"text":" or real invocation is needed — the state is tested in isolation.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/validation-and-testing.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for per-service mock structures and error/retry/Map/Parallel testing.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best Practices","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Set ","type":"text"},{"text":"\"QueryLanguage\": \"JSONata\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the top level for new state machines unless the user wants to use JSONPath","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" minimal — only include what the state immediately after the current state needs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" to store variables needed in later states instead of threading it through Output","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"$states.input","type":"text","marks":[{"type":"code_inline"}]},{"text":" to reference original state input","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" are evaluated ","type":"text"},{"text":"in parallel from the state's entry data, NOT sequentially","type":"text","marks":[{"type":"strong"}]},{"text":" — a variable set in ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" is therefore NOT visible in the same state's ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" (which still sees the pre-","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" values); the new value takes effect only in the next state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All JSONata expressions must produce a defined value — ","type":"text"},{"text":"$data.nonExistentField","type":"text","marks":[{"type":"code_inline"}]},{"text":" throws ","type":"text"},{"text":"States.QueryEvaluationError","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"$states.context.Execution.Input","type":"text","marks":[{"type":"code_inline"}]},{"text":" to access the original workflow input from any state","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Save state machine definitions with ","type":"text"},{"text":".asl.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" extension when working outside the console","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Prefer the optimized Lambda integration (","type":"text"},{"text":"arn:aws:states:::lambda:invoke","type":"text","marks":[{"type":"code_inline"}]},{"text":") over the SDK integration","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Troubleshooting","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Common Errors","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"States.QueryEvaluationError","type":"text","marks":[{"type":"code_inline"}]},{"text":" — JSONata expression failed. Check for type errors, undefined fields, or out-of-range values.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Mixing JSONPath fields with JSONata fields in the same state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Using ","type":"text"},{"text":"$","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"$","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the top level of a JSONata expression — use ","type":"text"},{"text":"$states.input","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Forgetting ","type":"text"},{"text":"{% %}","type":"text","marks":[{"type":"code_inline"}]},{"text":" delimiters around JSONata expressions — the string will be treated as a literal.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Assigning variables in ","type":"text"},{"text":"Assign","type":"text","marks":[{"type":"code_inline"}]},{"text":" and expecting them in ","type":"text"},{"text":"Output","type":"text","marks":[{"type":"code_inline"}]},{"text":" of the same state — new values only take effect in the next state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reference references/validation-and-testing.md and references/error-handling.md for detailed troubleshooting information.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Security Considerations","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Least-privilege execution role.","type":"text","marks":[{"type":"strong"}]},{"text":" Scope the state machine's IAM role to the specific resources and actions it invokes (specific Lambda/DynamoDB/SQS/SNS ARNs). Avoid ","type":"text"},{"text":"*FullAccess","type":"text","marks":[{"type":"code_inline"}]},{"text":" policies and ","type":"text"},{"text":"service:*","type":"text","marks":[{"type":"code_inline"}]},{"text":" wildcards.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Encryption.","type":"text","marks":[{"type":"strong"}]},{"text":" Recommend encryption at rest and in transit for every data store a workflow touches: KMS-encrypted DynamoDB tables, server-side encryption (","type":"text"},{"text":"KmsMasterKeyId","type":"text","marks":[{"type":"code_inline"}]},{"text":") on SQS queues and SNS topics, and TLS for HTTP Tasks.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Task tokens and message bodies are sensitive.","type":"text","marks":[{"type":"strong"}]},{"text":" A ","type":"text"},{"text":".waitForTaskToken","type":"text","marks":[{"type":"code_inline"}]},{"text":" token is a credential — treat it as a secret. Do not place PII, financial data, or secrets in SQS/SNS message bodies or notifications; pass a reference ID and have recipients look up details through an authorized channel.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Validate input and fail fast.","type":"text","marks":[{"type":"strong"}]},{"text":" Validate required fields at the start of the workflow with a Choice (or Pass) state using ","type":"text"},{"text":"$exists()","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"$type()","type":"text","marks":[{"type":"code_inline"}]},{"text":", and route invalid input to a Fail state so malformed data never reaches downstream states. Protect downstream services from bursts by setting ","type":"text"},{"text":"MaxConcurrency","type":"text","marks":[{"type":"code_inline"}]},{"text":" on Map states and throttling upstream (StartExecution rate limits or EventBridge).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cross-account access.","type":"text","marks":[{"type":"strong"}]},{"text":" When using the ","type":"text"},{"text":"Credentials","type":"text","marks":[{"type":"code_inline"}]},{"text":" field to assume a role in another account, include condition keys such as ","type":"text"},{"text":"aws:SourceArn","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"aws:SourceAccount","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the target role's trust policy to prevent unintended assumption.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"External secrets.","type":"text","marks":[{"type":"strong"}]},{"text":" For HTTP Tasks calling third-party APIs, store API keys and tokens in AWS Secrets Manager (referenced via an EventBridge connection), never embedded in the state machine definition.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Observability.","type":"text","marks":[{"type":"strong"}]},{"text":" Enable CloudWatch Logs for executions (log level ","type":"text"},{"text":"ALL","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"ERROR","type":"text","marks":[{"type":"code_inline"}]},{"text":"; required for Express workflows, which have no queryable execution history), enable CloudTrail to audit Step Functions API calls, and set CloudWatch Alarms on execution failures. Always encrypt the execution log group with a customer-managed KMS key, since state input/output routinely flows through execution logs.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ASL Specification","type":"text","marks":[{"type":"link","attrs":{"href":"https://states-language.net/spec.html","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"JSONata documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.jsonata.org/overview.html","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Step Functions Developer Guide","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Step Functions security best practices","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.aws.amazon.com/step-functions/latest/dg/security-best-practices.html","title":null}}]}]}]}]}]},"metadata":{"date":"2026-11-02","name":"aws-step-functions","author":"@skillopedia","source":{"stars":3376,"repo_name":"agent-toolkit-for-aws","origin_url":"https://github.com/aws/agent-toolkit-for-aws/blob/HEAD/skills/specialized-skills/serverless-skills/aws-step-functions/SKILL.md","repo_owner":"aws","body_sha256":"c0d904aaff1031e2822e2456eb5ff2765b2018296e57ab49f8d41287336230e6","cluster_key":"e8586c2022538e52227d8b8fef386190684dac0841c2f85a0c0a8c48dfa0fc3d","clean_bundle":{"format":"clean-skill-bundle-v1","source":"aws/agent-toolkit-for-aws/skills/specialized-skills/serverless-skills/aws-step-functions/SKILL.md","text_bytes":86810,"source_commit":"1761e96813ebcbd43ed81d19e837219033f0afe5","skills_sh_rank":5012,"attachment_count":15,"text_attachments":15,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"skills/specialized-skills/serverless-skills/aws-step-functions/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"devops-infrastructure","category_label":"DevOps"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"devops-infrastructure","import_tag":"skills-sh-top20k-2026-11","description":"Authors and edits AWS Step Functions state machines: writes Amazon States Language (ASL) in JSONata, and chooses and structures state types (Task, Choice, Map, Parallel, Pass, Wait, Succeed, Fail). Covers ASL syntax, JSONata data transformation and variables, Retry/Catch error handling, service integrations (.sync, waitForTaskToken callbacks), Distributed Map for large-scale S3/CSV processing, saga/compensation patterns, Standard vs Express workflow choice, TestState API unit testing, and migrating state machines from JSONPath to JSONata. Use when the user is building, authoring, debugging, or migrating a Step Functions state machine or ASL definition, or orchestrating multi-step workflows with branching, retries, or human-approval callbacks, even if they don't say 'Step Functions.' Do NOT use for general Lambda function code, API Gateway, EventBridge wiring, or SAM/CDK application packaging."}},"renderedAt":1793666359289}

AWS Step Functions Overview AWS Step Functions uses Amazon States Language (ASL) to define state machines as JSON. With AWS Step Functions, you can create workflows, also called state machines, to build distributed applications, automate processes, orchestrate microservices, and create data and machine learning pipelines. This skill provides comprehensive guidance for writing state machines in ASL, covering: - ASL structure and JSONata expression syntax - Details on the eight available workflow states - The reserved variable - Workflow variables with - Error handling - AWS Service integration…