Documentation

AWS Step Functions State Machine Job

The AWS Step Functions State Machine job type starts an execution of a Step Functions state machine — Standard via StartExecution, Express via StartSyncExecution. Polysync parameters are serialised into the JSON input and (on success) output parameters are extracted from the execution result. The state machine is identified by its ARN — Polysync stores that in the Job's External Id (version and alias ARNs are supported).

This job type is supported on the AWS Step Functions platform.

Required job fields

  • External Id — the State Machine ARN, e.g. arn:aws:states:{region}:{account}:stateMachine:{name}, …:stateMachine:{name}:{version}, or …:stateMachine:{name}:alias:{aliasName}.
  • Job Type — AWS Step Functions State Machine (set automatically on import).

Job attributes captured during discovery:

  • Step Functions Type — STANDARD or EXPRESS (drives whether Polysync polls or runs synchronously).

Optional:

  • Step Functions Trace Header — X-Ray trace header propagated to the execution; overrides the platform-level default.

Job discovery

ListStateMachines (paginated, MaxResults=100), then DescribeStateMachine per state machine to capture Type, RoleArn, and Definition. No parameters are auto-imported — Step Functions has no formal input schema, so users declare parameters manually on the Job.

Parameter handling

Input + Input&Output parameters become top-level properties of the JSON input passed to the execution:

{
  "<param-1>": <typed-value>,
  "<param-2>": <typed-value>
}
Direction Sent in input Updated from execution Output
Input ✅ ❌
Output ❌ ✅
Input&Output ✅ ✅

Data Type handling: boolean → JSON bool, numeric types → JSON number, json/object/array → raw JSON, else string.

Output parameters

On SUCCEEDED, the execution's Output JSON is parsed and any parameter whose Direction is Output / Input&Output is populated from the top-level property whose name matches (case-insensitive). The root output must be a JSON object — bare strings, numbers, or arrays at the root do not populate outputs.

Execution flow

  1. Polysync builds the JSON input, generates a unique execution name (Polysync-<guid>, ≤ 80 chars), and calls:

    • Standard: StartExecution(StateMachineArn, Name, Input, TraceHeader?)
    • Express: StartSyncExecution(...) — returns the terminal result in a single round trip; cannot be cancelled.

  2. The RunId is the raw ExecutionArn. (Express ARNs are detected by the :express: substring.)

  3. Status mapping (DescribeExecution for Standard; terminal status returned synchronously for Express):

    Step Functions status Polysync status
    RUNNING / PENDING_REDRIVE Running
    SUCCEEDED Success
    FAILED / TIMED_OUT Failed
    ABORTED Cancelled
    (other / null) Unknown

  4. Cancel — Standard supports StopExecution(ExecutionArn, Cause="Cancelled by Polysync", Error="PolysyncCancellation"). Express is synchronous and not cancellable.

Monitor URL

https://{region}.console.aws.amazon.com/states/home?region={region}
  #/v2/executions/details/{executionArn}

Standard vs Express — operational notes

  • Standard workflows are durable, audited, and support runs up to 1 year — full Describe / Stop APIs available.
  • Express workflows are designed for high-volume, short-lived executions. Polysync runs them synchronously, so the Polysync run has a hard upper bound matching the Step Functions Express limit (5 minutes). Forensic detail beyond the immediate result lives in CloudWatch Logs.

Best practices

  • Use Standard for any workflow that needs to be paused, replayed, audited, or cancelled by Polysync.
  • Use Express for high-rate event processing and accept that cancellation isn't possible.
  • Cap payloads at 256 KB (the Step Functions input/output limit) — pass S3 references for anything larger.

Troubleshooting

  • InvalidExecutionInputException — the input is not valid JSON. Check json-typed parameter values for well-formedness.
  • StateMachineDoesNotExistException — confirm the ARN is correct in the target region.
  • ExecutionLimitExceeded — the account/region open-execution limit (1,000,000 for Standard) has been reached.
  • Output parameters not populated — confirm the execution reached SUCCEEDED, the Output is a JSON object at the root, and the parameter Direction is Output / Input&Output.