Package: mbonig.state-machine
Workflow Studio compatible State MachineThis is a Workflow Studio compatible AWS Step Function state machine construct.The goal of this construct is to make it easy to build and maintain your state machines using the Workflow Studio but still
leverage the AWS CDK as the source of truth for the state machine.Read more about ithere.How to Use This ConstructStart by designing your initial state machine using the Workflow Studio.
When done with your first draft, copy and paste the ASL definition to a local file.Create a new instance of this construct, handing it a fully parsed version of the ASL.
Then add overridden values.
The fields in theoverridesfield should match theStatesfield of the ASL.Version UsageThe AWS CDK StateMachine construct introduced a change in version2.85.0that deprecated an earlier usage of 'definition'
by this construct. This construct has been updated to use the new 'definitionBody' field.If you are using a version of the CDK before version2.85.0, you should use version0.0.28of this construct.If you are using a version fo the CDK great or equal to2.85.0, you should use version0.0.29+of this construct.Projen componentThere is a projen component included in this library which will help you in using the construct. It works similar
to theauto-discovery feature. To use it, first add the component
to your projen project:// ...const{StepFunctionsAutoDiscover}=require('@matthewbonig/state-machine');constproject=newawscdk.AwsCdkTypeScriptApp({// ...,deps:[// ...,'@matthewbonig/state-machine',]});newStepFunctionsAutoDiscover(project);Now projen will look for any files with a suffix.workflow.jsonand generate new files beside the .json:A typed overrides interface which is based on your workflow.A construct derived from StateMachine that uses this override.Instead of using the StateMachine construct directly you can now use the generated one:.
├── MyFancyThing.workflow.json
└── MyFancyThing-statemachine.tsexportclassSomeStackextendsStack{constructor(scope:Construct,id:string,props:StackProps){super(scope,id,props);consthandler=newNodejsFunction(this,'MyHandler');newSomeFancyThingStateMachine(this,'MyFancyWorkflow',{overrides:{'My First State':{Parameters:{FunctionName:handler.functionName}}}})}}:warning:The interfaces and constructs generated here are NOT jsii compliant (they use Partials and Omits) and cannot be
compiled by jsii into other languages. If you plan to distribute any libraries you cannot use this.Alternative ExtensionsThere is an optional parameter,extensionthat you can pass to have it search for alternative extensions.
AWS recommends that ASL definition files have a.asl.jsonextension, which will be picked up by some IDE
tools. This extension was recommended after initial development of this component. Therefore, the default is
to use the original extension. But, you can override this by passing a different extension to the
AutoDiscover's constructor options. There are two constants defined,JSON_STEPFUNCTION_EXTandAWS_RECOMMENDED_JSON_EXTthat you can use.// ...const{StepFunctionsAutoDiscover,AWS_RECOMMENDED_JSON_EXT}=require('@matthewbonig/state-machine');constproject=newawscdk.AwsCdkTypeScriptApp({// ...,deps:[// ...,'@matthewbonig/state-machine',]});newStepFunctionsAutoDiscover(project,{extension:AWS_RECOMMENDED_JSON_EXT});Yaml filesYaml files are supported as well. You can provide an extension to the AutoDiscover component to have it search for yaml files. If the file has 'yaml' or 'yml' anywhere in the name it will be parsed as yaml. If not, it will be parsed as json.// ...const{StepFunctionsAutoDiscover}=require('@matthewbonig/state-machine');constproject=newawscdk.AwsCdkTypeScriptApp({// ...,deps:[// ...,'@matthewbonig/state-machine',]});newStepFunctionsAutoDiscover(project,{extension:'.yaml.asl'});Examplesconstsecret=newSecret(stack,'Secret',{});newStateMachine(stack,'Test',{stateMachineName:'A nice state machine',definition:JSON.parse(fs.readFileSync(path.join(__dirname,'sample.json'),'utf8').toString()),overrides:{'Read database credentials secret':{Parameters:{SecretId:secret.secretArn,},},},});You can also override nested states in arrays, for example:newStateMachine(stack,'Test',{stateMachineName:'A-nice-state-machine',overrides:{Branches:[{//passanemptyobjecttoooffsetoverrides},{StartAt:'StartInstances',States:{StartInstances:{Parameters:{InstanceIds:['INSTANCE_ID'],},},},}],},stateMachineType:StateMachineType.STANDARD,definition:{States:{Branches:[{StartAt:'ResumeCluster',States:{'Redshift Pass':{Type:'Pass',End:true,},},},{StartAt:'StartInstances',States:{'StartInstances':{Type:'Task',Parameters:{InstanceIds:['MyData',],},Resource:'arn:aws:states:::aws-sdk:ec2:startInstances',Next:'DescribeInstanceStatus',},'DescribeInstanceStatus':{Type:'Task',Next:'EC2 Pass',Parameters:{InstanceIds:['MyData',],},Resource:'arn:aws:states:::aws-sdk:ec2:describeInstanceStatus',},'EC2 Pass':{Type:'Pass',End:true,},},},],},},});For Python, be sure to use a context manager when opening your JSON file.You do not need tostr()the dictionary object you supply as yourdefinitionprop.Elements of your override pathdoneed to be strings.secret=Secret(stack,'Secret')withopen('sample.json','r+',encoding='utf-8')assample:sample_dict=json.load(sample)state_machine=StateMachine(self,'Test',definition=sample_dict,overrides={"Read database credentials secret":{"Parameters":{"SecretId":secret.secret_arn,},},})In this example, the ASL has a state called 'Read database credentials secret' and the SecretId parameter is overridden with a
CDK generated value.
Future changes can be done by editing, debugging, and testing the state machine directly in the Workflow Studio.
Once everything is working properly, copy and paste the ASL back to your local file.IssuesPlease open any issues you have onGithub.ContributingPlease submit PRs from forked repositories if you'd like to contribute.