User guide

Cloud Certainty StateCraft is a web console for AWS Step Functions that runs in your organisation's own AWS account. You watch and search executions, find out why they failed, start, stop and redrive them, and design and deploy workflows by mouse, keyboard or voice, across the AWS accounts and Regions your administrator connected.

Open the portal URL your administrator gave you and sign in with your company account. You see the state machines an administrator granted you; what you may do with each depends on your permissions:

Permissions are granted per AWS account (connection), Region and state machine name pattern, so you may be able to run orders-* and only view billing-*. Buttons for actions you can't take are greyed out, and their tooltip says why.

Some features depend on your organisation's plan (Starter, Team, Business or Enterprise). A feature the plan doesn't include shows a plan badge, for example Team or Business. This guide notes the plan next to each such feature.

The top bar has Fleet, Executions, Designer, Bulk jobs and, for administrators, Administration, plus the command field and the microphone (see Voice and typed commands). The footer has a theme switch (System, Light, Dark).

#Signing in

StateCraft uses your organisation's sign-in: AWS IAM Identity Center, another SAML or OIDC identity provider, or StateCraft's own user pool with multi-factor authentication. Your administrator chose one when installing StateCraft (Identity providers).

The first time you sign in you may see no state machines at all: nobody sees anything until an administrator gives them a grant. Ask your StateCraft administrator for access, naming the AWS account, the Region and the state machines you need, and whether you need to see data or run executions.

#Fleet

Fleet lists every state machine you may view, in every connection and Region you have a grant in, with:

• the type (STANDARD or EXPRESS);
• executions started, succeeded, failed, timed out, aborted and throttled, and redrives;
• the success rate and the p50 and p95 duration;
• a sparkline of started and failed executions.

Choose the period (1 hour, 24 hours, 7 days or 30 days), filter by connection, Region, type or name, and sort by any column, for example by failures to see what is on fire. Figures come from CloudWatch metrics; StateCraft refreshes them every few minutes and shows how old they are. Refresh reads them again.

Screenshot

#State machine page

Open a state machine from the fleet. The page has these tabs:

Open in designer copies the definition into a new draft.

Screenshot

#Versions and aliases

With deploy, you can publish a version of the current definition, delete a version no alias routes to, and create or change an alias. An alias routes to one version, or splits traffic between two versions by weight for a canary: for example 90% to version 7 and 10% to version 8. Weights are whole percentages that add up to 100. Raise the canary's weight as its executions succeed, then send 100% to it. Every change is recorded in the audit log.

#Starting an execution

With run, choose Start execution on a state machine:

• Input: type JSON, or pick a saved input. The meter shows its size against the 256 KiB limit.
• Name (optional): letters, digits, - and _, up to 80 characters. Step Functions refuses a name already used in the last 90 days.
• Version or alias (optional).
• Wait for the result (Express only): runs the execution synchronously and shows its output.

Save input keeps the input with a name and a description for next time. Saved inputs are private unless you share them (Team and above).

#Execution page

Open an execution from any list, search result or link. The header shows its status, start and stop times, duration, the version or alias it ran, who started it (when it was started through StateCraft), its estimated cost, and, for a child of a Distributed Map, its parent.

#Graph

The graph of the definition the execution actually ran (not the current one), with each state's status: succeeded, failed, caught, running, not reached. States that retried show the number of attempts; Map and Parallel states show their iterations and branches, which you can expand. Running executions update live. Select a state to see its input, output, error and retries.

Screenshot

#Timeline

A Gantt chart of every state over time. Each retry is its own bar, and Map iterations and Parallel branches get their own lanes, so you can see where the time went and what ran at once. Failed only hides the rest.

Screenshot

#Events

The full event history, 1,000 events at a time, up to the 25,000 events Step Functions allows per execution; StateCraft warns when an execution is getting close to that limit. Filter by event type, state or failures, search the text, switch to the compact view (one line per state), and Download the history as JSON. Without data, events show no inputs, outputs, parameters or error causes.

Screenshot

#Input and output

The execution's input and output, formatted, with meters against the 256 KiB limit. Needs data.

#Map Runs

For executions with a Distributed Map: each Map Run's progress, item and child execution counts by status, its max concurrency and tolerated failures, and its child executions, which you can filter by status and open. Failure clusters group failed children by error and cause. With run, change the max concurrency and the tolerated failure percentage or count while the Map Run is running; the change is recorded in the audit log.

Screenshot

#Cost

The estimated cost of the execution. For Standard workflows: its state transitions, times the price per 1,000 transitions (retries and redrives count). For Express workflows: the request and the billed duration and memory. Prices are set by your administrator; your AWS bill is the record.

#Stop, redrive and re-run

With run:

• Stop a running Standard execution, with an optional error and cause.
• Redrive a failed, timed out or aborted Standard execution: it restarts from the states that didn't succeed, with the original definition. The redrive helper shows whether the execution can be redriven, and if not, why (for example, it is older than 14 days, or it reached the event limit), and a countdown to the end of the 14-day window. Add a reason for the record.
• Start again with this input opens Starting an execution with the same input, for when the fix needs the current definition rather than the original one.

Each action is recorded in the audit log and in the execution records, so StateCraft shows who did it.

#Compare

Compare puts two executions of the same state machine side by side: status, duration, the states each one took with their timings, and, with data, the differences in their inputs and outputs.

Screenshot

#Searching executions

Executions searches across many state machines at once, up to 200 per search: choose the connection, Region and state machines (all you may view by default), the statuses, the time range (the last 24 hours by default) and a name prefix. Results are newest first, up to 500. If the search reaches its limit or runs out of time, it says the results are incomplete; narrow it.

Failure clusters groups the failed executions in the results by error and cause, with a count and the newest example of each. The link in your browser holds the filters, so you can share a search with a colleague, who sees only what their own grants allow.

Search by input or output content isn't available yet.

Screenshot

#Bulk jobs

Team and above, with run. Select executions in any list or search result, or a failure cluster, and choose Stop, Redrive or Re-run (start a new execution with the same input and the same version or alias). A bulk job takes up to 100 executions on Team, 250 on Business and 500 on Enterprise, all in one connection and Region, and runs up to 20 at a time (5 by default).

StateCraft's own Step Functions workflow in your organisation's account carries out the job, as you: for each execution it checks your grants again, so if your access is removed during a job, the remaining items fail with "You no longer have run permission". Bulk jobs lists your jobs with their progress, and each item's result: succeeded, failed with the reason, or skipped. Cancel stops a running job; items not yet done are skipped.

Screenshot

#Designer

Designer lists your drafts and the shared ones (Team and above). A draft is a workflow you are designing: its definition, its layout, and the state machine it deploys to. Drafts save themselves as you work, and every save is kept as a version (5 on Starter, 25 on Team, 50 on Business, 100 on Enterprise) that you can compare and restore. A draft is private unless you share it; colleagues can open a shared draft, and if two people save at once, the second is told to reload.

New draft starts from a blank workflow or from the templates gallery, for example a sequence of Lambda functions, a choice with an approval, a Map over items, or a Distributed Map over an S3 prefix. Open in designer on a state machine starts from its definition.

Screenshot

#Canvas, palette and inspector

• Palette: flow states (Pass, Choice, Wait, Parallel, Map, Succeed, Fail) and service integrations (Lambda, Amazon SNS, Amazon SQS, Amazon DynamoDB, AWS Step Functions, Amazon EventBridge, HTTP endpoints, any AWS SDK call and more). Drag one onto the canvas, or onto an arrow to insert it there.
• Inspector: select a state to edit it in forms. JSONata states have arguments, output and Assign; JSONPath states have InputPath, Parameters, ResultSelector, ResultPath and OutputPath. The query language is set for the workflow and can be changed per state.
• Choice rules: build each rule from a variable, an operator and a value, combine rules with and, or and not, and pick the next state for each rule and for the default.
• Retry and Catch: the errors to match, interval, maximum attempts, backoff rate, maximum delay and jitter; for Catch, the next state and where the error goes.
• Map and Distributed Map: the items path or item reader (for example a JSON or CSV file or an S3 prefix), item selector, batching, max concurrency, tolerated failures and the result writer.

#Code view

Code shows the definition as JSON, side by side with the graph. Change either one and the other follows. Invalid JSON is underlined and the graph keeps its last valid state until you fix it.

#Lint and validation

StateCraft checks the workflow as you edit: states nobody reaches, missing next states, a Choice without a default, a Catch that points to a missing state, a Map without an item path, a JSONPath field in a JSONata state and the like. Many problems have a quick fix. Validate also asks Step Functions (ValidateStateMachineDefinition), which checks the definition the way a deploy will.

#TestState workbench

With run on the target state machine, select a state and choose Test. Give it an input, and if you like the context, variables and a mock (a result or an error to return instead of calling the service), then run it in Step Functions. The result shows the status (succeeded, failed, retriable, or caught), the next state, the output, and each data-flow stage: the input after InputPath, the arguments or parameters, the result, and the output after ResultSelector and ResultPath. Without a mock, the state really calls the service with the state machine's own execution role; with deploy, you can choose another role your administrator allows StateCraft to pass.

Screenshot

#JSONata playground

JSONata opens a playground: an expression, an input and the result, evaluated in your browser as you type. Use it to build arguments and conditions before putting them into a state.

#Deploy

With deploy on a connection with the Full access level, Deploy creates the target state machine or updates it: choose the connection, Region, name, type and execution role (or keep the draft's target), whether to publish a version, and optionally an alias to point at it. StateCraft validates the definition first. If someone changed the state machine since you opened the draft, the deploy is refused ("Someone changed this state machine since you opened it.") so you don't overwrite their change: compare, then deploy again.

#Export and IAM policy

Export gives the workflow as an AWS CloudFormation resource, an AWS SAM resource, AWS CDK code or a Terraform resource, to paste into your infrastructure code. IAM policy generates the policy the execution role needs for the services the workflow calls, scoped to the resources in the definition where it can tell.

#Voice and typed commands

Everything you can say, you can also type: the command field in the top bar takes the same commands. Press Alt+V (or the microphone) to start talking and again, or Esc, to stop. StateCraft shows what it heard and what it did; "help" lists what it understands.

Your administrator chose how speech becomes text:

• Amazon Transcribe (the usual choice): audio goes from your browser to Amazon Transcribe in your organisation's AWS account, and nowhere else.
• Your browser's speech service: in Chrome and Edge, audio goes to the browser vendor's speech service, outside your organisation's AWS account. The microphone button says so.
• Off: only the command field.

StateCraft never stores your audio or what you said. The first time, your browser asks for permission to use the microphone.

#Building and changing workflows

In the designer:

Each command changes the draft at once, in the graph and the code, so you see exactly what it did; "undo" takes it back. Command words are English in this release.

#Navigation

Anywhere: "go to the fleet", "open orders-processing", "show failed executions", "go to the designer", "help".

Screenshot

#Assist

Business and above, when your administrator turned it on. In the designer, choose Assist and describe a workflow ("validate the order, charge the card with retries, and send a confirmation email; if the amount is over 1,000 wait for a manual approval") or a change to the current one ("add error handling that sends failures to the alerts topic").

Claude on Amazon Bedrock, in your organisation's AWS account, proposes the workflow. StateCraft validates it and shows it as a diff against your draft, with a summary and notes on what to check. Accept applies it to the draft (and "undo" takes it back); Reject discards it. Nothing is applied or deployed without you. Only your description and, for a change, the current definition are sent; the first part of your description is recorded in the audit log.

Screenshot

#Keyboard shortcuts

On a Mac, use ⌘ where the table says Ctrl and Option for Alt.

#When something is refused