Skip navigation links

@Stability(value=Experimental)

Package software.amazon.awscdk.services.stepfunctions

AWS Step Functions Construct Library

See: Description

Package software.amazon.awscdk.services.stepfunctions Description

AWS Step Functions Construct Library

---

cfn-resources: Stable

All classes with the Cfn prefix in this module (CFN Resources) are always stable and safe to use.

cdk-constructs: Experimental

The APIs of higher level constructs in this module are experimental and under active development. They are subject to non-backward compatible changes or removal in any future version. These are not subject to the Semantic Versioning model and breaking changes will be announced in the release notes. This means that while you may use them, you may need to update your source code when upgrading to a newer version of this package.

The @aws-cdk/aws-stepfunctions package contains constructs for building serverless workflows using objects. Use this in conjunction with the @aws-cdk/aws-stepfunctions-tasks package, which contains classes used to call other AWS services.

Defining a workflow looks like this (for the Step Functions Job Poller example):

TypeScript example

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.stepfunctions.*;
 import software.amazon.awscdk.services.stepfunctions.tasks.*;
 import software.amazon.awscdk.services.lambda.*;
 
 Function submitLambda = new Function(this, "SubmitLambda", new FunctionProps()...);
 Function getStatusLambda = new Function(this, "CheckLambda", new FunctionProps()...);
 
 Task submitJob = new Task(this, "Submit Job", new TaskProps()
         .task(new RunLambdaTask(submitLambda))
         // Lambda's result is in the attribute `Payload`
         .outputPath("$.Payload"));
 
 Wait waitX = new Wait(this, "Wait X Seconds", new WaitProps()
         .time(sfn.WaitTime.secondsPath("$.waitSeconds")));
 
 Task getStatus = new Task(this, "Get Job Status", new TaskProps()
         .task(new RunLambdaTask(getStatusLambda))
         // Pass just the field named "guid" into the Lambda, put the
         // Lambda's result in a field called "status" in the response
         .inputPath("$.guid")
         .outputPath("$.Payload"));
 
 Fail jobFailed = new Fail(this, "Job Failed", new FailProps()
         .cause("AWS Batch Job Failed")
         .error("DescribeJob returned FAILED"));
 
 Task finalStatus = new Task(this, "Get Final Job Status", new TaskProps()
         .task(new RunLambdaTask(getStatusLambda))
         // Use "guid" field as input
         .inputPath("$.guid")
         .outputPath("$.Payload"));
 
 Chain definition = submitJob
     .next(waitX)
     .next(getStatus).next(new sfn.Choice(this, 'Job Complete?')
         // Look at the "status" field
         .when(sfn.Condition.stringEquals('$.status', 'FAILED'), jobFailed)
         .when(sfn.Condition.stringEquals('$.status', 'SUCCEEDED'), finalStatus).otherwise(waitX));
 
 new StateMachine(this, "StateMachine", new StateMachineProps()
         .definition(definition)
         .timeout(Duration.minutes(5)));

You can find more sample snippets and learn more about the service integrations in the @aws-cdk/aws-stepfunctions-tasks package.

State Machine

A stepfunctions.StateMachine is a resource that takes a state machine definition. The definition is specified by its start state, and encompasses all states reachable from the start state: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var startState = new Pass(this, "StartState");
 
 StateMachine.Builder.create(this, "StateMachine")
         .definition(startState)
         .build();

State machines execute using an IAM Role, which will automatically have all permissions added that are required to make all state machine tasks execute properly (for example, permissions to invoke any Lambda functions you add to your workflow). A role will be created by default, but you can supply an existing one as well.

Amazon States Language

This library comes with a set of classes that model the Amazon States Language. The following State classes are supported:

An arbitrary JSON object (specified at execution start) is passed from state to state and transformed during the execution of the workflow. For more information, see the States Language spec.

Task

A Task represents some work that needs to be done. The exact work to be done is determine by a class that implements IStepFunctionsTask, a collection of which can be found in the @aws-cdk/aws-stepfunctions-tasks module.

The tasks in the @aws-cdk/aws-stepfunctions-tasks module support the service integration pattern that integrates Step Functions with services directly in the Amazon States language.

Pass

A Pass state does no work, but it can optionally transform the execution's JSON state. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 // Makes the current JSON state { ..., "subObject": { "hello": "world" } }
 var pass = Pass.Builder.create(this, "Add Hello World")
         .result(Map.of("hello", "world"))
         .resultPath("$.subObject")
         .build();
 
 // Set the next state
 pass.next(nextState);

Wait

A Wait state waits for a given number of seconds, or until the current time hits a particular time. The time to wait may be taken from the execution's JSON state. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 // Wait until it's the time mentioned in the the state object's "triggerTime"
 // field.
 var wait = Wait.Builder.create(this, "Wait For Trigger Time")
         .time(stepfunctions.WaitTime.timestampPath("$.triggerTime"))
         .build();
 
 // Set the next state
 wait.next(startTheWork);

Choice

A Choice state can take a different path through the workflow based on the values in the execution's JSON state: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var choice = new Choice(this, "Did it work?");
 
 // Add conditions with .when()
 choice.when(stepfunctions.Condition.stringEqual("$.status", "SUCCESS"), successState);
 choice.when(stepfunctions.Condition.numberGreaterThan("$.attempts", 5), failureState);
 
 // Use .otherwise() to indicate what should be done if none of the conditions match
 choice.otherwise(tryAgainState);

If you want to temporarily branch your workflow based on a condition, but have all branches come together and continuing as one (similar to how an if ... then ... else works in a programming language), use the .afterwards() method: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var choice = new Choice(this, "What color is it?");
 choice.when(stepfunctions.Condition.stringEqual("$.color", "BLUE"), handleBlueItem);
 choice.when(stepfunctions.Condition.stringEqual("$.color", "RED"), handleRedItem);
 choice.otherwise(handleOtherItemColor);
 
 // Use .afterwards() to join all possible paths back together and continue
 choice.afterwards().next(shipTheItem);

If your Choice doesn't have an otherwise() and none of the conditions match the JSON state, a NoChoiceMatched error will be thrown. Wrap the state machine in a Parallel state if you want to catch and recover from this.

Parallel

A Parallel state executes one or more subworkflows in parallel. It can also be used to catch and recover from errors in subworkflows. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var parallel = new Parallel(this, "Do the work in parallel");
 
 // Add branches to be executed in parallel
 parallel.branch(shipItem);
 parallel.branch(sendInvoice);
 parallel.branch(restock);
 
 // Retry the whole workflow if something goes wrong
 parallel.addRetry(Map.of("maxAttempts", 1));
 
 // How to recover from errors
 parallel.addCatch(sendFailureNotification);
 
 // What to do in case everything succeeded
 parallel.next(closeOrder);

Succeed

Reaching a Succeed state terminates the state machine execution with a succesful status. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var success = new Succeed(this, "We did it!");

Fail

Reaching a Fail state terminates the state machine execution with a failure status. The fail state should report the reason for the failure. Failures can be caught by encompassing Parallel states. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var success = Fail.Builder.create(this, "Fail")
         .error("WorkflowFailure")
         .cause("Something went wrong")
         .build();

Map

A Map state can be used to run a set of steps for each element of an input array. A Map state will execute the same steps for multiple entries of an array in the state input.

While the Parallel state executes multiple branches of steps using the same input, a Map state will execute the same steps for multiple entries of an array in the state input. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var map = Map.Builder.create(this, "Map State")
         .maxConcurrency(1)
         .itemsPath(stepfunctions.Data.stringAt("$.inputForMap"))
         .build();
 map.iterator(new Pass(this, "Pass State"));

Custom State

It's possible that the high-level constructs for the states or stepfunctions-tasks do not have the states or service integrations you are looking for. The primary reasons for this lack of functionality are:

If a feature is not available, a CustomState can be used to supply any Amazon States Language JSON-based object as the state definition.

Code Snippets are available and can be plugged in as the state definition.

Custom states can be chained together with any of the other states to create your state machine definition. You will also need to provide any permissions that are required to the role that the State Machine uses.

The following example uses the DynamoDB service integration to insert data into a DynamoDB table. 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 import software.amazon.awscdk.services.dynamodb.*;
 import software.amazon.awscdk.core.*;
 import software.amazon.awscdk.services.stepfunctions.*;
 
 // create a table
 Table table = new Table(this, "montable", new TableProps()
         .partitionKey(new Attribute()
                 .name("id")
                 .type(ddb.AttributeType.getSTRING())));
 
 Pass finalStatus = new Pass(stack, "final step");
 
 // States language JSON to put an item into DynamoDB
 // snippet generated from https://docs.aws.amazon.com/step-functions/latest/dg/tutorial-code-snippet.html#tutorial-code-snippet-1
 __object stateJson = Map.of(
         "Type", "Task",
         "Resource", "arn:aws:states:::dynamodb:putItem",
         "Parameters", Map.of(
                 "TableName", table.getTableName(),
                 "Item", Map.of(
                         "id", Map.of(
                                 "S", "MyEntry"))),
         "ResultPath", null);
 
 // custom state which represents a task to insert data into DynamoDB
 CustomState custom = new CustomState(this, "my custom task", new CustomStateProps()
         .stateJson(stateJson));
 
 Chain chain = sfn.Chain.start(custom).next(finalStatus);
 
 StateMachine sm = new StateMachine(this, "StateMachine", new StateMachineProps()
         .definition(chain)
         .timeout(cdk.Duration.seconds(30)));
 
 // don't forget permissions. You need to assign them
 table.grantWriteData(sm.getRole());

Task Chaining

To make defining work flows as convenient (and readable in a top-to-bottom way) as writing regular programs, it is possible to chain most methods invocations. In particular, the .next() method can be repeated. The result of a series of .next() calls is called a Chain, and can be used when defining the jump targets of Choice.on or Parallel.branch: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var definition = step1
     .next(step2)
     .next(choice
         .when(condition1, step3.next(step4).next(step5))
         .otherwise(step6)
         .afterwards())
     .next(parallel
         .branch(step7.next(step8))
         .branch(step9.next(step10))).next(finish);
 
 StateMachine.Builder.create(this, "StateMachine")
         .definition(definition)
         .build();

If you don't like the visual look of starting a chain directly off the first step, you can use Chain.start: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var definition = stepfunctions.Chain
     .start(step1)
     .next(step2).next(step3);

State Machine Fragments

It is possible to define reusable (or abstracted) mini-state machines by defining a construct that implements IChainable, which requires you to define two fields:

Since states will be named after their construct IDs, you may need to prefix the IDs of states if you plan to instantiate the same state machine fragment multiples times (otherwise all states in every instantiation would have the same name).

The class StateMachineFragment contains some helper functions (like prefixStates()) to make it easier for you to do this. If you define your state machine as a subclass of this, it will be convenient to use: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 public class MyJobProps {
     private String jobFlavor;
     public String getJobFlavor() {
         return this.jobFlavor;
     }
     public MyJobProps jobFlavor(String jobFlavor) {
         this.jobFlavor = jobFlavor;
         return this;
     }
 }
 
 public class MyJob extends StateMachineFragment {
     public final Object startState;
     public final Array endStates;
 
     public MyJob(Construct parent, String id, MyJobProps props) {
         super(parent, id);
 
         var first = Task.Builder.create(this, "First")....build();
         // ...
         var last = Task.Builder.create(this, "Last")....build();
 
         this.startState = first;
         this.endStates = asList(last);
     }
 }
 
 // Do 3 different variants of MyJob in parallel
 new stepfunctions.Parallel(this, 'All jobs')
     .branch(new MyJob(this, 'Quick', { jobFlavor: 'quick' }).prefixStates())
     .branch(new MyJob(this, 'Medium', { jobFlavor: 'medium' }).prefixStates()).branch(new MyJob(this, 'Slow', { jobFlavor: 'slow' }).prefixStates());

A few utility functions are available to parse state machine fragments.

Activity

Activities represent work that is done on some non-Lambda worker pool. The Step Functions workflow will submit work to this Activity, and a worker pool that you run yourself, probably on EC2, will pull jobs from the Activity and submit the results of individual jobs back.

You need the ARN to do so, so if you use Activities be sure to pass the Activity ARN into your worker pool: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var activity = new Activity(this, "Activity");
 
 // Read this CloudFormation Output from your application and use it to poll for work on
 // the activity.
 // Read this CloudFormation Output from your application and use it to poll for work on
 // the activity.
 CfnOutput.Builder.create(this, "ActivityArn").value(activity.getActivityArn()).build();

Metrics

Task object expose various metrics on the execution of that particular task. For example, to create an alarm on a particular task failing: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Alarm.Builder.create(this, "TaskAlarm")
         .metric(task.metricFailed())
         .threshold(1)
         .evaluationPeriods(1)
         .build();

There are also metrics on the complete state machine: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Alarm.Builder.create(this, "StateMachineAlarm")
         .metric(stateMachine.metricFailed())
         .threshold(1)
         .evaluationPeriods(1)
         .build();

And there are metrics on the capacity of all state machines in your account: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 Alarm.Builder.create(this, "ThrottledAlarm")
         .metric(StateTransitionMetrics.metricThrottledEvents())
         .threshold(10)
         .evaluationPeriods(2)
         .build();

Logging

Enable logging to CloudWatch by passing a logging configuration with a destination LogGroup: 

 // Example automatically generated without compilation. See https://github.com/aws/jsii/issues/826
 var logGroup = new LogGroup(stack, "MyLogGroup");
 
 StateMachine.Builder.create(stack, "MyStateMachine")
         .definition(stepfunctions.Chain.start(new Pass(stack, "Pass")))
         .logs(Map.of(
                 "destinations", logGroup,
                 "level", stepfunctions.LogLevel.getALL()))
         .build();

Future work

Contributions welcome:

Skip navigation links

Copyright © 2020. All rights reserved.