feat(sfn): allow setting comment on state machine

Author: Chelsea Urquhart

packages/aws-cdk-lib/aws-stepfunctions/README.md

@@ -59,6 +59,7 @@ const definition = submitJob
 new sfn.StateMachine(this, 'StateMachine', {
   definition,
   timeout: Duration.minutes(5),
+  comment: 'a super cool state machine',
 });
 ```
 
@@ -520,6 +521,7 @@ const chain = sfn.Chain.start(custom)
 const sm = new sfn.StateMachine(this, 'StateMachine', {
   definition: chain,
   timeout: Duration.seconds(30),
+  comment: 'a super cool state machine',
 });
 
 // don't forget permissions. You need to assign them

packages/aws-cdk-lib/aws-stepfunctions/lib/state-graph.ts

@@ -35,6 +35,16 @@ export class StateGraph {
    */
   public timeout?: Duration;
 
+  /**
+   * Set a comment to render into the graph JSON.
+   *
+   * Read/write. Only makes sense on the top-level graph, subgraphs
+   * do not support this feature.
+   *
+   * @default No comment
+   */
+  public comment?: string;
+
   /**
    * The accumulated policy statements
    */
@@ -113,6 +123,7 @@ export class StateGraph {
       StartAt: this.startState.stateId,
       States: states,
       TimeoutSeconds: this.timeout && this.timeout.toSeconds(),
+      Comment: this.comment,
     };
   }
 

packages/aws-cdk-lib/aws-stepfunctions/lib/state-machine.ts

@@ -107,6 +107,13 @@ export interface StateMachineProps {
    */
   readonly timeout?: Duration;
 
+  /**
+   * Comment that describes this state machine
+   *
+   * @default No comment
+   */
+  readonly comment?: string;
+
   /**
    * Type of the state machine
    *
@@ -410,6 +417,7 @@ export class StateMachine extends StateMachineBase {
 
     const graph = new StateGraph(props.definition.startState, `State Machine ${id} definition`);
     graph.timeout = props.timeout;
+    graph.comment = props.comment;
 
     this.stateMachineType = props.stateMachineType ?? StateMachineType.STANDARD;
 

packages/aws-cdk-lib/aws-stepfunctions/test/state-machine.test.ts

@@ -44,6 +44,27 @@ describe('State Machine', () => {
 
   }),
 
+  test('Instantiate Standard State Machine With Comment', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+
+    // WHEN
+    new sfn.StateMachine(stack, 'MyStateMachine', {
+      stateMachineName: 'MyStateMachine',
+      definition: sfn.Chain.start(new sfn.Pass(stack, 'Pass')),
+      stateMachineType: sfn.StateMachineType.STANDARD,
+      comment: 'zorp',
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::StepFunctions::StateMachine', {
+      StateMachineName: 'MyStateMachine',
+      StateMachineType: 'STANDARD',
+      DefinitionString: '{"StartAt":"Pass","States":{"Pass":{"Type":"Pass","End":true}},"Comment":"zorp"}',
+    });
+
+  }),
+
   test('Instantiate Express State Machine', () => {
     // GIVEN
     const stack = new cdk.Stack();