What you can export from AWS Step Functions and what you cannot
State machine definitions written in Amazon States Language can be read back through the AWS API, but execution history, IAM policy context and the configuration around each state machine need separate capture. If you are running a migration, a cost review or a cloud exit, treat the definition as one input to the inventory, not the whole of it. The definition comes from the DescribeStateMachine API call, which also returns fields such as roleArn, type and the encryption and logging settings. Record those fields for every state machine, because the role decides which AWS services each Task state can call and the encryption settings decide what your tooling must be able to decrypt.
Step Functions has no single export button, so the migration inventory is built from several sources. Start with the definitions, then add the execution role and its attached policies, the logging and tracing configuration, and any EventBridge rules, schedules or API Gateway integrations that start or call the machines. Each Task state that invokes Lambda, DynamoDB, SQS or another service also points to a resource you must track separately. This page covers only documented export paths. If a definition is encrypted with a customer managed KMS key, confirm in current AWS documentation which permissions your export identity needs to decrypt it, and do not rely on workarounds that AWS does not document.
Execution history is the hardest part to move. Decide early which past runs matter for audit, dispute resolution or reprocessing, and archive those to storage you control while they are still retrievable. Confirm in current AWS documentation how long execution history remains available through the console and API, and whether logging to CloudWatch Logs was enabled for each machine, since that setting determines what you can recover after the fact. Running executions cannot be moved into another engine as they are. Plan a drain period, identify long-running executions that outlast the cutover window, and agree with the business owners who approve the final switch to the state machine.
Which artifacts export, the method and the format
This table lists each artifact to pull from Step Functions, the AWS call or console view that retrieves it, and the output format. Use it to build the migration inventory, and confirm the items marked for AWS verification against current AWS documentation before you rely on them. The main takeaway is that the state machine definition is only one of several artifacts a migration needs.
| Artifact | Export method | Format and limits to confirm |
|---|---|---|
| Amazon States Language definition | DescribeStateMachine API or AWS CLI call that returns the definition field | JSON. Confirm how the definition is returned for each state machine type and any size limit with AWS. |
| State machine metadata (name, type, ARN) | DescribeStateMachine response, or the console details view | JSON from the API. Type indicates Standard or Express; confirm field names in the current API reference. |
| IAM execution role | Read the roleArn from DescribeStateMachine, then export the role and attached policies with IAM calls or the console | JSON policy documents. Confirm which policies are customer managed and which are inline. |
| Logging and tracing settings | Logging configuration and tracing flag in DescribeStateMachine, plus the destination log group and X-Ray settings | JSON. Confirm whether log level and include-execution-data settings are returned in your account. |
| Tags | ListTagsForResource API call or the console tags tab | JSON key and value pairs. Tags are not part of the ASL definition and must be captured separately. |
| Infrastructure-as-code source | Locate the AWS CloudFormation, CDK, Terraform or SAM templates that deployed the state machines | Template files in the source repository. Often more reliable than API output for intent and parameters. |
| Service integration parameters | Review Task states inside the definition for resource ARNs, Lambda functions, queues and tables | Embedded in ASL JSON. Confirm any referenced resources that live outside the definition, such as Secrets Manager or parameter store values. |
| Execution history | GetExecutionHistory or console execution view, retrieved before retention ends | JSON event records. Confirm the retention window with AWS and export before it closes. |
What does not export directly and how teams work around it
Some parts of a Step Functions workflow never appear in the state machine definition. They live in Lambda code, other AWS resources, triggers and execution history. Each card below names one of these items, the workaround that fits it, and the owner who must confirm the inventory entry before cutover.
Lambda code and container images
Task states call Lambda functions or start containers by ARN, and the definition stores only that reference. The code lives in your source repository, build pipeline or container registry, so export it from the team that owns it. Confirm that the deployed version matches the source commit for every ARN in the definition, because a function may have changed after its last deployment. Record the runtime, handler, memory setting, layers and environment variables for each function, and get the application owner to sign off before the inventory is closed.
Service integration resources
Direct service integrations, such as calls to DynamoDB tables and SQS queues, depend on resources in the owning AWS account that Step Functions does not copy. Those resources include table key schemas, indexes, queue visibility timeouts, dead-letter queues and resource policies. Capture them through infrastructure-as-code exports or a stack inventory. Check that every resource ARN in the definition exists in the target environment, and have the owner of each table or queue agree to keep it through cutover.
EventBridge rules and API Gateway triggers
Many state machines run only because an EventBridge rule, schedule, API Gateway route or direct integration starts them. Those triggers hold event patterns, input transformers, schedule expressions and authorizer settings that shape what each execution receives. Export them from the owning service or stack, and list each trigger with its target state machine. Pause every trigger before cutover so that events are not processed by both platforms. The producers of those events must confirm that the event contract is unchanged on the new platform.
Execution history beyond AWS retention
Step Functions keeps execution history for a limited period, and the 90-day window in this migration plan is the deadline to act. The definition alone does not show how past runs behaved, so audit, dispute and open-case teams may need that history. Decide which executions matter, such as failed runs, runs tied to financial or regulated records and long-running ones, and confirm with AWS documentation how each type can be exported. Copy the selected history to your own store before the window closes, and have the records owner approve retention and access controls for that store.
The export sequence, in the order teams should run it
This sequence turns an unmanaged set of Step Functions state machines into a versioned, owned and verified inventory that a migration team can translate and test. Each step produces an artifact that the next step depends on, so gaps surface before any workflow is rebuilt.
Freeze the inventory per account and region
List every state machine in each AWS account and region in scope, including Standard and Express types, and record its name, ARN, type, creation date and last update. Include accounts that are not in your main landing zone, because state machines are scoped to a single account and region. The step is done when the inventory has one row per state machine and a second reviewer has confirmed the account and region list is complete. Freeze the inventory at this point so later changes are visible as differences.
Retrieve each definition and store it in version control
For each state machine, call DescribeStateMachine through the AWS CLI, SDK or console and save the returned Amazon States Language definition as a raw JSON file, without editing it. Commit the files to a Git repository with the account, region and state machine name in the path, so each file has a traceable origin and history. The step is done when every inventory row maps to a committed file and the commit hash is recorded in the inventory.
Decrypt KMS-encrypted definitions only where permitted
If a definition is encrypted with a customer managed KMS key, decryption requires that the calling identity has the key permissions in the key policy. Do not widen key policies to make the export work. Confirm the required KMS actions and key policy conditions in the AWS documentation for KMS and Step Functions, and ask the key owner to approve the export in writing. If approval is not granted, record the state machine as blocked in the inventory rather than exporting it by another route.
Record IAM roles and the permissions each state needs
For each state machine, record the execution role ARN and the policy statements it grants, then list the service integrations each state calls, such as Lambda, DynamoDB, SQS, ECS or nested state machines. Note any callback or wait patterns that depend on external systems. The output is a permissions matrix that maps each state to the actions and resources it uses. Review it with the owners of the target systems, because these permissions define what the replacement runtime must be able to reach.
Capture execution history needed for audit and reconciliation
Execution history in Step Functions is retained for a limited window, so decide which executions must be kept before that window closes. Export the execution records your audit, finance or reconciliation teams need, such as execution ARNs, start and end times, status, input and output for selected business keys, and store them in an access-controlled location. Confirm the current retention behavior in the AWS documentation for Step Functions. The output is a dated archive with a listed scope and an owner who signed off on it.
Verify the stored definitions against fresh retrieval
Run DescribeStateMachine again for every state machine and compare the new definition with the committed file, field by field. Any difference means the definition changed after the freeze, so re-freeze the inventory and repeat the affected steps. The step is done when every file matches its fresh retrieval, and the comparison output is stored with the inventory.
Check resource references against the inventory
Parse each definition for referenced resource ARNs, including Lambda functions, queues, tables, topics, activities and nested state machines, and confirm each one appears in your resource inventory or in a list of external dependencies. Unmatched ARNs usually indicate a resource outside the scope of the export, a cross-account call or an outdated reference. Resolve each one with the owning team. The step is done when every referenced ARN is accounted for in writing.
Confirm an owner for each state machine
Assign a named owner, and a backup owner, to every state machine in the inventory. The owner approves the definition, the permissions matrix and the decision to migrate, retire or keep it. A state machine without an owner is not ready for migration and should be flagged for review by the platform team. The final artifact is a signed-off inventory that a migration team can use to translate states and plan cutover.
What the exported definitions mean for a Temporal or Kestra target
An exported Amazon States Language file describes control flow: which state runs next, how it branches, what it waits for and how it retries. It is not portable code. Neither Temporal nor Kestra can execute it directly, so every state needs a mapping decision before any migration work starts. Temporal expresses the same logic as workflow code in a language such as Go, Java, Python or TypeScript, with Task states becoming activities and Choice, Wait, Parallel and Map states becoming ordinary control structures. Kestra expresses it as declarative YAML flows with triggers and tasks. Temporal is MIT licensed and its server is self-hosted without a license fee, while Temporal Cloud is a separate paid managed service. Kestra's open-source edition is Apache License 2.0 and is described by its vendor as fully functional for production, with basic authentication only. Choose the target by what the workflows do, not by how easily the JSON converts. The translation steps belong to the migration pages, so this section only needs to fix the target before the inventory is finished.
Each exported definition also carries dependencies that do not move with it. Lambda function ARNs, SQS queue URLs, DynamoDB table names and the IAM role named in each state machine are references to AWS resources, not logic. Credentials and secrets must be re-created in the target's own secret model, such as an external secrets manager connected to Kestra or the secret handling your Temporal workers use, and each service connection must be rebuilt with its own credentials. IAM permissions do not carry over at all. Write down the actions each role grants, then assign equivalent access in the target's model. Temporal needs particular attention here. If no Authorizer is configured, self-hosted Temporal uses the default noopAuthorizer, which allows every API request with no authentication or access control. Configure mTLS, a ClaimMapper and an Authorizer before any workflow or worker reaches the cluster, and confirm the chosen settings in the Temporal self-hosted security documentation.
Before committing to a target, ask the team that owns each state machine three questions: which downstream systems it calls, which people or services are allowed to start and cancel it, and which data in its payloads is sensitive enough to need encryption. The answers determine whether Temporal's payload codecs or Kestra's secrets integration is the right fit, and whether the existing IAM boundaries must be reproduced one for one. Record each answer in the inventory alongside the exported file, so the mapping review has a complete picture of what each workflow touches.
How the inventory differs by workload type
State machines that coordinate orders, approvals, onboarding or claims often wait for humans, partners or callbacks for hours or days. For these, the most valuable artifact is the record of what already happened. Execution history tells you which steps completed, which payloads were passed between them and where in-flight executions are waiting. Those in-flight executions are the hardest part of the cutover, because they cannot simply be restarted on a new engine.
- Execution history: Capture completed and running executions with their inputs, outputs and failure states before the 90-day window closes.
- In-flight executions: List every execution waiting on a callback or task token, and decide whether it finishes on Step Functions or is replayed.
- Timeouts and waits: Record
Waitdurations and heartbeat or timeout settings, since these define business deadlines. - Payload sensitivity: Identify which inputs contain personal or regulated data and where they are encrypted.
- Callback owners: Name the systems and teams that send task tokens back, so signals can be wired during translation.
Confirm with the process owners which executions must survive the move unchanged and which can be drained or restarted.
State machines that schedule batch loads, data transformations or reporting jobs are defined less by their branching logic and more by when they run and what they depend on. The most useful artifacts are the schedules, the upstream and downstream data dependencies and the retry behavior that data teams have tuned over time. Losing a schedule or a dependency edge often shows up as a missing report rather than an error.
- Schedules: Export the EventBridge rules or other triggers that start each state machine, including time zones and disabled rules.
- Data dependencies: Map which datasets, buckets or tables each Task reads and writes, because these become the ordering rules in the new platform.
- Retry and catch policies: Record
RetryandCatchsettings per state, since backfills depend on them. - Map state concurrency: Note
MaxConcurrencyand item sources forMapstates that fan out over partitions. - Run history for backfills: Keep a record of past run dates so that backfill windows can be reproduced.
Confirm which schedules are owned by data consumers and whether any downstream reports expect a specific run time or sequence.
Some state machines are thin wrappers that call Lambda, DynamoDB, SQS, ECS or other AWS services in sequence. Their logic is simple, but their permissions and integration patterns are not. When these move to a self-hosted engine, every AWS call becomes an explicit dependency that needs credentials, network paths and error handling. The inventory must therefore focus on the IAM and service integration detail rather than the flow shape.
- Execution role permissions: Export the IAM role attached to each state machine and list the actions it grants, since these define what the new workers will need.
- Service integration patterns: Note whether each Task uses direct SDK integration,
.syncwaits or.waitForTaskTokencallbacks, because each pattern translates differently. - Resource ARNs: Record every Lambda, queue, table and topic referenced in the definition, including those built dynamically.
- KMS-encrypted definitions: Check which definitions or inputs use customer managed keys, and who holds decrypt rights.
- Cross-account calls: Identify roles that assume into other accounts, which affect where self-hosted workers can run.
Confirm which AWS credentials the new platform may hold and whether the workers must stay inside a particular network or account boundary.
What to plan before the AWS contract or account changes
The dates that matter most in an export are set by your AWS contract, your account structure and your target platform, not by the export itself. The cards below cover the decisions that depend on the exit date, from how long AWS workloads run in parallel to who controls IAM and KMS during cutover, and they show what to confirm before any account change is scheduled.
Parallel run window
Decide how long AWS and the target platform must run side by side before the last state machine is switched off. Long-running executions, scheduled jobs and downstream consumers of Step Functions outputs usually set this window, not the migration team's preference. Map every state machine to its trigger type and typical run length, then list which ones cannot stop without a planned pause. Confirm with the business owners of each workflow what a missed run or a duplicated run would cost them.
Execution history copy-out timing
Step Functions execution history is not kept indefinitely, so copy it out before the retention window closes for the oldest records you still need. Set the cutoff date by asking compliance and operations which executions must be retrievable for audits, disputes or incident reviews. Export the history in a format your target platform and archive can read, and verify a sample of records against the console before any deletion step runs.
IAM and KMS administration during cutover
Name the people who hold administrative rights over IAM roles, KMS keys and the Step Functions account during the parallel run. Those rights are needed to read definitions, decrypt payloads and keep both platforms working, and they are also the rights that must be removed once the exit is complete. Write down who approves changes to key policies and role trust relationships, and confirm that break-glass access is logged and reviewed.
Export repository currency
Keep the export repository in step with the live AWS account until the last state machine is retired. Any change made in the console after an export, such as a new state, a changed retry policy or a new service integration, must be re-exported and reviewed, or the target will drift from production. Assign one owner for the sync, record the commit or snapshot used for each cutover, and run a diff between the live definitions and the repository before every switch.
Inventory and dependency ownership
Build the migration inventory with one row per state machine, listing its owner, triggers, IAM role, KMS key, service integrations and downstream systems that read its output. Ownership gaps usually surface here: a state machine that no current team claims or a role shared by several workflows. Confirm each owner signs off on their row before cutover planning starts, since the inventory becomes the checklist for retirement.
Cost components to request
Ask for a cost breakdown with three parts: AWS billing for Step Functions transitions or requests, plus any CloudWatch Logs and retained storage used for execution history, the hosting cost of the target platform, and the staff time for export, translation and parallel running. Ask which AWS charges continue after the last state machine is retired, such as log retention and KMS key fees, and whether the target platform's hosting scales with volume. Compare each component against your current invoice rather than a vendor estimate.
Questions teams ask before exporting Step Functions workflows
How much effort does a full Step Functions export take?
The effort depends mostly on how many state machines you run, how deeply they nest, and how many AWS service integrations each one calls. A team with a handful of linear workflows that call only Lambda has a much smaller inventory than a team with hundreds of state machines that use nested executions, Map states, callback patterns and direct SDK integrations. Retrieving the definitions is the quick part. Each state needs a decision about what it becomes on the new platform, which is where most of the time goes. Ask any provider to size the work from a written inventory of your state machines, not from a head count of workflows.
What does the internal team need to provide for an export?
Plan for three kinds of access and ownership before work starts. You need read access to the AWS accounts and regions where the state machines run, including permission to call DescribeStateMachine and to list executions. You need an IAM administrator who can explain which execution roles each state machine uses, and a KMS administrator who can confirm which keys encrypt definitions or logs and whether the team may decrypt them for the export. You also need a named owner for each workflow who can say what it does, what its inputs look like and which downstream systems depend on it. Confirm these names and access paths with your own security team before scoping.
Can we export Step Functions definitions ourselves with the AWS CLI?
Yes, the definitions can be retrieved with the AWS CLI, typically by listing state machines and calling describe for each one, then saving the Amazon States Language output to files. A short script can cover this for a small estate. The harder parts are outside the definition: resolving the IAM roles and their policies, identifying which KMS keys apply, recording the service integrations and their parameters, and saving execution history before it ages out of the console. A script that only pulls definitions will leave gaps that surface during cutover. Your team can do the inventory itself and then decide whether to hire help for translation and verification.
How long does verification take, and what does it depend on?
Verification time depends on how many workflows you must prove equivalent, how many paths each one has, and whether you can replay real inputs. Linear workflows with stable inputs are quick to check. Workflows with Choice branches, retries, timeouts, Parallel or Map states, and callbacks need test cases for each path and for failure cases. You also need representative data, a staging environment that can call the same downstream systems, and a decision on how long old and new runs execute side by side. Ask the provider how they will confirm behavior for each state machine and what evidence they will hand over at the end.
What does a fixed-scope export engagement include?
A fixed-scope engagement is agreed in writing before work starts, so you should see the list of accounts, regions and state machines in scope, the deliverables and the timeline. For an export, typical deliverables are a complete inventory, the exported definitions stored in version control, a mapping of IAM roles, KMS dependencies and service integrations, a record of retained execution history, and a list of open decisions for the next phase. Ask whether translation into the target platform and cutover are included or are separate phases, and what happens when the inventory finds workflows that are out of scope. DeployOpen does not publish a price list, and a quote follows from the written scope.
What should we confirm about KMS and history retention before starting?
Confirm two things early because they can block the export. First, check whether any state machine definitions or logging configurations use customer-managed KMS keys, and whether the people doing the export have the decrypt permissions and key policies they need. Second, check your Step Functions execution history settings and your own requirements for keeping run records. Execution history in the console is not kept indefinitely, so decide which runs you need to preserve, in what format, and who approves that retention. Your compliance owner should confirm the retention rules that apply to your organization. Do not assume that a default setting meets your requirements.
How DeployOpen scopes and delivers a Step Functions export
DeployOpen treats the export as a fixed-scope piece of work that produces an inventory you can review before any target platform is chosen. We plan and document the extraction of each state machine, its IAM roles, service integrations and retained execution history inside your own AWS accounts.
How we scope
- Written scope lists every state machine, alias and region to be exported from your accounts.
- Scope names the IAM roles, KMS keys and service integrations that each definition depends on.
- Scope states which execution history is retained, in what format, and who approves the retention window.
How we build
- Extraction scripts retrieve Amazon States Language definitions and record the version or revision captured for each one.
- Decryption of KMS-encrypted definitions runs under access controls we agree with your security team before work starts.
- Each state machine is mapped to a row in the migration inventory, with its states, integrations and open questions.
How we hand over
- Deliverables include the exported definitions, the inventory, and a written list of gaps that need a decision.
- Documentation records how each export was run so your team can repeat it or verify the results.
- Handover covers the evidence stored for each export, including where execution history and definitions were placed.
How we support
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work begins.
- Ongoing support, upgrades and continuous testing are available as a retainer after the export is complete.
- Quotes follow from the written scope, so ask for the scope to be itemized by state machine and integration type.
