Documentation

AWS Step Functions

AWS Step Functions is the AWS serverless workflow orchestrator. Polysync uses the official AWS SDK for .NET v4 (AWSSDK.StepFunctions and AWSSDK.SecurityToken) to list state machines, start executions with a JSON input, poll execution status, parse output parameters from the execution result, and surface a direct link to the AWS Step Functions console for monitoring.

Required attributes

  • Region — the AWS region containing the state machine (e.g., us-east-1, ap-southeast-2). All Step Functions API calls are region-scoped.

Optional platform-level defaults

  • Trace Header — an AWS X-Ray trace header propagated to the execution. Allows linking Polysync executions to an X-Ray trace. Overridable per job.

Authentication methods

  • Web Identity Federation ⭐ (recommended for Polysync SaaS) — Polysync exchanges its Microsoft Entra ID workload identity token for short-lived AWS credentials via sts:AssumeRoleWithWebIdentity. No long-lived secrets stored. Required attributes: Role ARN.
    • In AWS, create an IAM Identity Provider (OIDC) trusting Polysync's Entra ID issuer (https://login.microsoftonline.com/<polysync-tenant-id>/v2.0) with audience sts.amazonaws.com.
    • Create an IAM role whose trust policy allows sts:AssumeRoleWithWebIdentity from that provider with a condition on the Polysync workload identity's sub/oid claim.
  • Access Key — Provide Access Key Id, Secret Access Key, and optionally Session Token. Simplest, but the secret must be rotated and stored in a Secret Vault.
  • Assume Role — Provide a bootstrap Access Key Id and Secret Access Key, plus the Role ARN to assume. The bootstrap user only needs sts:AssumeRole on the target role; the assumed role holds the Step Functions permissions.
  • Instance Profile — Uses the host EC2/ECS instance profile. Only viable when Polysync is deployed inside AWS.

IAM permissions checklist

The role / user used to call Step Functions must hold (at minimum):

  • states:ListStateMachines — discover available state machines.
  • states:DescribeStateMachine — read state machine metadata, including ARN, type, and execution role.
  • states:StartExecution — start executions (scope to specific state-machine ARNs in production).
  • states:DescribeExecution — poll execution status and read output.
  • states:StopExecution — cancel running executions.

Plus any IAM permissions the state machine's own execution role needs to call downstream services (defined on the state machine's role, not the Polysync caller).

Job discovery

Polysync calls ListStateMachines (paginated via NextToken) and for each entry calls DescribeStateMachine to capture metadata: the State Machine ARN, the Type (STANDARD or EXPRESS), and the execution role ARN. State machines are imported as Polysync Jobs identified by their ARN — Step Functions calls require the ARN (not the name).

State Functions has no formal input/output schema declaration, so Polysync imports no parameters by default. Users declare input and output parameters manually on the Job and tag each parameter's Direction (Input, Output, InputOutput).

Parameter conventions

  • Input parameters become top-level properties of a JSON input payload supplied to StartExecution. The provider honours each parameter's declared data type (number, boolean, JSON object/array) when serialising. Parameters whose value is already a valid JSON object or array string are embedded as raw JSON, not strings.
  • Output parameters are extracted from the execution's Output JSON once the execution reaches the terminal SUCCEEDED state. The provider parses the output and updates any parameter whose Direction is Output or Input&Output and whose name matches a top-level property of the output (case-insensitive).

Execution flow

  1. ExecutePipelineAsync builds the JSON input from input parameters, generates a unique 80-char execution name (Polysync-<guid>), and calls StartExecution(StateMachineArn, Name, Input, TraceHeader?).
  2. The provider returns a PipelineRun with the execution's ExecutionArn as the RunId — Step Functions accepts the ARN directly on follow-up calls, so no composite encoding is needed.
  3. GetPipelineRunStatusAsync calls DescribeExecution(ExecutionArn) and maps the status:
    • RUNNING / PENDING_REDRIVE → Running
    • SUCCEEDED → Success (Output JSON parsed for output parameters)
    • FAILED / TIMED_OUT → Failed (Error + Cause surfaced on the run message)
    • ABORTED → Cancelled
  4. CancelPipelineRunAsync calls StopExecution(ExecutionArn, cause="Cancelled by Polysync", error="PolysyncCancellation").

Monitor URL

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

This deep-links into the AWS Step Functions console for the specific execution, showing the visual workflow, the per-state event history, and CloudWatch logs.

State machine types — Standard vs Express

  • Standard workflows are durable, audited, and support long-running executions (up to 1 year). All execution APIs (DescribeExecution, StopExecution) work normally.
  • Express workflows are designed for high-volume, short-lived executions. Synchronous Express invocations (StartSyncExecution) are not used by this provider — Polysync uses the asynchronous StartExecution API for both Standard and Express, then polls with DescribeExecution. Note that Express executions may complete and become unqueryable before Polysync's next poll; in that case the provider relies on CloudWatch Logs for forensic detail.

Troubleshooting

  • AccessDeniedException on StartExecution — the caller's IAM principal is missing states:StartExecution on arn:aws:states:{region}:{account}:stateMachine:{name}.
  • StateMachineDoesNotExistException — confirm the state machine ARN is correct in the target region and the caller's IAM principal can DescribeStateMachine.
  • InvalidExecutionInputException — the input payload is not valid JSON. Check that parameters declared with DataType=json contain well-formed JSON.
  • ExecutionLimitExceeded — the account/region open-execution limit (default 1,000,000 for Standard, much higher for Express) has been reached.
  • Web Identity Federation InvalidIdentityToken — check that the IAM Identity Provider's thumbprint matches login.microsoftonline.com, the audience is sts.amazonaws.com, and the role trust policy allows the Polysync workload identity's sub / oid.
  • Output parameters not populated — confirm the execution reached SUCCEEDED, the output is a valid JSON object (not a JSON string, number, or array at the root), the parameter's Direction is Output or Input&Output, and the parameter name matches a top-level property name in the output (case-insensitive).
  • Payload too large — Step Functions input/output payloads are limited to 256 KB. For larger data, write to S3 from a Task state and pass S3 references through Polysync parameters.