AWS Step Functions ExecModule

Overview

AwsStepFunctionsModule brings durable AWS state-machine orchestration into ValkyrAI workflows. It discovers Standard and Express state machines, starts named executions, reads bounded execution state and history, stops reviewed executions, redrives eligible failures, and completes callback tasks. It uses ValkyrAI's native map ABI and a verified IntegrationAccount; credentials never belong in workflow input.

The connector implements twelve operations:

• list_state_machines and describe_state_machine discover bounded state-machine metadata.
• start_execution starts an asynchronous Standard or Express execution.
• start_sync_execution starts an Express workflow and returns its bounded result.
• list_executions, describe_execution, and get_execution_history inspect execution state without returning the original execution input.
• stop_execution terminates a running Standard execution after explicit confirmation.
• redrive_execution restarts eligible unsuccessful Standard executions with an optional client token.
• send_task_success, send_task_failure, and send_task_heartbeat complete or extend callback tasks without echoing the sensitive task token.

n8n's AWS Lambda, SNS, and SQS nodes demonstrate useful AWS workflow patterns: account credentials, region-aware resources, resource discovery, pagination, JSON payloads, and workflow-tool composition. n8n does not currently ship a dedicated Step Functions node in its built-in AWS node tree, so ValkyrAI provides a native lifecycle connector with stricter ARN validation, bounded output, mutation replay boundaries, callback-token redaction, and destructive confirmation.

Usage

1. Select the state machines and executions the workflow may access.
2. Create a least-privilege IAM principal restricted to the required states:* actions and resources.
3. Store its access key ID and secret access key in an AWS IntegrationAccount; verify it and keep it in READY status.
4. Add AwsStepFunctionsModule and bind that account through ExecModuleConfig.authConfig.integrationAccount.
5. Choose one operation and supply only its documented fields. Unexpected fields fail before provider access.
6. Use stable execution names and redrive client tokens where applicable. Reconcile exact AWS state before replaying any timed-out mutation.

Never place an AWS access key, secret key, session token, or credential object in module input. Those fields are rejected before any network request. Treat callback task tokens as sensitive capabilities and keep them in ACL-scoped workflow data.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the twelve documented operations.
region	string	Every execution	None	AWS region such as us-west-2; custom endpoints are not accepted.
stateMachineArn	string	State-machine describe/start/list-executions operations	None	AWS Step Functions state-machine, alias, or version ARN in the selected region.
executionArn	string	Execution describe/history/stop/redrive operations	None	AWS Step Functions execution ARN in the selected region.
executionName	string	Optional start field	AWS-generated	1-80 letters, digits, underscores, or hyphens.
input	object or JSON string	Optional start field	{}	JSON object or array, at most 256 KiB after canonical serialization.
output	object or JSON string	send_task_success	None	JSON object or array, at most 256 KiB.
statusFilter	string	Optional list_executions field	None	RUNNING, SUCCEEDED, FAILED, TIMED_OUT, ABORTED, or PENDING_REDRIVE.
nextToken	string	Optional list/history field	None	Opaque provider token, at most 4,096 characters.
limit	integer	Optional list/history field	100	From 1 through 10,000 total returned items.
returnAll	boolean	Optional list/history field	false	Follow provider pages until limit, exhaustion, or the 100-page guard.
reverseOrder	boolean	Optional history field	false	Return newest history events first.
error	string	Optional stop/failure field	None	Bounded application error code, at most 256 characters.
cause	string	Optional stop/failure field	None	Bounded diagnostic, at most 32,768 UTF-8 bytes.
clientToken	string	Optional redrive field	AWS-generated	1-64 letters, digits, underscores, or hyphens.
taskToken	string	Callback operations	None	Sensitive nonblank token, at most 2,048 UTF-8 bytes; never returned or logged.
confirmStop	boolean	stop_execution	false	Must be exactly true.

State-machine and execution ARNs must use the selected region. This prevents a workflow configured for one region from silently operating on a resource in another. Alias- and version-qualified state-machine ARNs remain supported.

Outputs

Every call returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls including pages and retry-safe reads.
resultType	string	Success	state_machines, state_machine, executions, execution, sync_execution, history_events, or callback.
items	array	List/history success	Bounded normalized state machines, execution summaries, or history event envelopes.
count	integer	List/history success	Number of returned items.
pages	integer	List/history success	Provider pages consumed.
hasMore	boolean	List/history success	Whether AWS returned another page token.
nextToken	string	Another page exists	Opaque continuation token.
data	object	Non-list success	Normalized state-machine, execution, billing, redrive, stop, or callback receipt.
requestId	string	AWS supplies one	Bounded request reference for reconciliation.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Execution input is never copied into output. Describe and synchronous execution responses can return bounded parsed execution output because that value is the operation's intended workflow result. History results contain only event ID, prior event ID, type, and timestamp; execution-data details remain disabled to avoid leaking task inputs or outputs through event history.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Step Functions
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions enabled for the workflow:

• Discovery: states:ListStateMachines and states:DescribeStateMachine.
• Start: states:StartExecution and, for Express workflows, states:StartSyncExecution.
• Execution reads: states:ListExecutions, states:DescribeExecution, and states:GetExecutionHistory.
• Lifecycle mutation: states:StopExecution and states:RedriveExecution where needed.
• Callback tasks: states:SendTaskSuccess, states:SendTaskFailure, and states:SendTaskHeartbeat.

Restrict state-machine and execution resource ARNs wherever AWS supports resource-level permissions. State-machine definitions can invoke other AWS services under the state machine's execution role; the caller's IntegrationAccount does not replace that role. The connector currently supports a long-lived access-key pair. STS session credentials, role assumption, workload identity, and custom endpoints are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, resource ARN, and payload fields belong in mapped input or module parameters.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-step-functions-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"start_execution\",\"region\":\"us-west-2\"}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
list_state_machines	Lists bounded Standard and Express state-machine metadata.	Read-only; each page retries transient failures up to the configured bound.
describe_state_machine	Reads metadata for one exact machine, alias, or version without returning its definition.	Read-only; bounded retry.
start_execution	Starts an asynchronous Standard or Express execution with JSON input.	Billable external side effect; one provider attempt. A repeated Standard start with the same name and input can be idempotent while running, but callers must reconcile exact state.
start_sync_execution	Starts an Express workflow and waits for a terminal provider response.	Billable external side effect; one attempt. HTTP success can still contain a failed execution status.
list_executions	Lists bounded executions for one state machine and optional status.	Read-only; opaque pagination and bounded retry.
describe_execution	Reads one execution and its bounded result metadata.	Read-only; bounded retry.
get_execution_history	Reads bounded event envelopes with execution data disabled.	Read-only; opaque pagination and bounded retry. Standard workflows only.
stop_execution	Stops one running Standard execution after explicit confirmation.	Destructive, single attempt; reconcile status after an ambiguous response.
redrive_execution	Redrives one eligible unsuccessful Standard execution.	State-changing, single attempt; an explicit clientToken provides provider idempotency.
send_task_success	Completes a callback task with bounded JSON output.	State-changing, single attempt; task token is consumed and never echoed.
send_task_failure	Fails a callback task with bounded error/cause.	State-changing, single attempt; task token is consumed and never echoed.
send_task_heartbeat	Extends a callback task's heartbeat deadline.	State-changing, single attempt; it does not create a durable completion receipt beyond AWS request evidence.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/malformed region, ARN, JSON, name, status, token, pagination value, confirmation, or unexpected field.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_STEP_FUNCTIONS_HTTP_400	Invalid ARN, state, execution input, callback token, unsupported workflow type, or provider limit.	Usually no	Inspect the exact resource and operation before changing input.
AWS_STEP_FUNCTIONS_HTTP_403	IAM denies the action or resource.	No	Grant only the missing permission under the intended conditions.
AWS_STEP_FUNCTIONS_HTTP_404	State machine, execution, or callback task no longer exists.	No	Reconcile the immutable ARN/token and workflow state.
AWS_STEP_FUNCTIONS_HTTP_429 / 500 / 503	Throttle or transient provider pressure.	Reads retry; mutations report ambiguity	Inspect AWS state and the request ID before any replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reads retry; mutations report ambiguity	Treat mutation acceptance as unknown until exact provider state is read.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve operation and request evidence for investigation.

Provider exception messages are never copied into workflow output. This prevents credentials, task tokens, execution payloads, or unbounded service detail from leaking through errors.

Example

Start a named order-approval execution:

{
  "operation": "start_execution",
  "region": "us-west-2",
  "stateMachineArn": "arn:aws:states:us-west-2:123456789012:stateMachine:OrderApproval",
  "executionName": "order-A-1042",
  "input": {
    "orderId": "A-1042",
    "riskTier": "reviewed",
    "requestedAction": "approve"
  }
}

Expected result shape:

{
  "status": "success",
  "operation": "start_execution",
  "attempts": 1,
  "resultType": "execution",
  "data": {
    "started": true,
    "executionArn": "arn:aws:states:us-west-2:123456789012:execution:OrderApproval:order-A-1042",
    "startDate": "2026-09-06T09:05:00Z"
  },
  "requestId": "aws-request-reference"
}

The receipt proves that AWS accepted the start request. It does not prove the execution completed successfully. Use describe_execution, EventBridge execution-status events, or an explicit callback path for terminal evidence.

Notes

• Pagination: state-machine, execution, and history operations return one page unless returnAll=true; the connector follows opaque tokens with unchanged filters and stops at limit, exhaustion, or 100 pages.
• Rate limits: Step Functions quotas vary by account, region, workflow type, and action. Read calls use at most five configured attempts with bounded backoff. Starts, stops, redrives, and callbacks never retry automatically.
• API limits: JSON input/output is capped at 256 KiB, list/history output at 10,000 items, provider pages at 1,000 items, execution names at 80 characters, client tokens at 64, task tokens at 2,048 UTF-8 bytes, and diagnostics at 32 KiB.
• Idempotency: Standard StartExecution uses the execution name and input for provider idempotency while the execution is running; Express starts are not idempotent. Redrive can use clientToken. ValkyrAI still sends each mutation once and requires read-after-ambiguity reconciliation.
• Synchronous Express behavior: start_sync_execution can return HTTP success with FAILED, TIMED_OUT, or another terminal status in its body. Branch on the returned execution status, not only module status=success.
• Destructive behavior: stop_execution requires confirmStop=true, applies only to running Standard executions, and cannot be undone.
• Callback behavior: callback task tokens are bearer capabilities. Keep them private, send them once, and treat timeout/heartbeat acceptance as ambiguous until execution state is checked.
• Execution history: event payload details are deliberately excluded. Use purpose-built downstream observability when a task's input/output detail must be retained under separate ACL controls.
• State-machine definitions: discovery returns metadata, not Amazon States Language definitions. Definition create/update/validate/test belongs in a separately reviewed infrastructure deployment surface.
• Deferred operations: create/update/delete state machine, versions/aliases, activities, Map Run controls, tagging, CloudWatch Logs configuration, X-Ray configuration, KMS configuration, and state-definition testing are not implemented.
• Provider verification boundary: deterministic tests cover validation, region/ARN binding, JSON bounds, pagination, operation families, retry boundaries, stop confirmation, callback-token and credential redaction, error normalization, registration, and metadata. Live AWS behavior remains unverified until an authorized AWS account and reviewed state machine are supplied.
• Functional reference: n8n's AWS Lambda node and AWS credential model inform resource discovery, JSON input, region, and tool-use ergonomics. ValkyrAI adds the Step Functions lifecycle and governance controls described above.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsStepFunctionsModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS EventBridge ExecModule
• AWS Lambda ExecModule
• AWS Step Functions API
• Integration Account Console