Skip to content

Commit 70006ab

Browse files
msambolmsambol
authored
feat(stepfunctions): add comment ability for when condition (#27010)
Currently you can comment on a `Choice` state. This adds the ability to comment on a when condition. <img width="437" alt="Screenshot 2023-09-05 at 7 47 35 AM" src="https://github.com/aws/aws-cdk/assets/3310356/4cb92427-c16c-4994-9e86-0384c4c2b075"> <img width="473" alt="Screenshot 2023-09-05 at 7 54 29 AM" src="https://github.com/aws/aws-cdk/assets/3310356/4dc1857e-5515-4510-8fde-a5eb8bc93afe"> Closes #27005. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent 54083de commit 70006ab

File tree

11 files changed

+149
-50
lines changed

11 files changed

+149
-50
lines changed

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.js.snapshot/aws-stepfunctions-integ.assets.json

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
{
2-
"version": "32.0.0",
2+
"version": "34.0.0",
33
"files": {
4-
"2b683032648fa932811d781e11acb71f29e8dcde21411e7cf232807cc2565770": {
4+
"6fc80a94a8b95de238e82bf832c22a76af712d24dc10c332baa36571da0a4a41": {
55
"source": {
66
"path": "aws-stepfunctions-integ.template.json",
77
"packaging": "file"
88
},
99
"destinations": {
1010
"current_account-current_region": {
1111
"bucketName": "cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}",
12-
"objectKey": "2b683032648fa932811d781e11acb71f29e8dcde21411e7cf232807cc2565770.json",
12+
"objectKey": "6fc80a94a8b95de238e82bf832c22a76af712d24dc10c332baa36571da0a4a41.json",
1313
"assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-file-publishing-role-${AWS::AccountId}-${AWS::Region}"
1414
}
1515
}

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.js.snapshot/aws-stepfunctions-integ.template.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -115,13 +115,13 @@
115115
"StateMachine2E01A3A5": {
116116
"Type": "AWS::StepFunctions::StateMachine",
117117
"Properties": {
118+
"DefinitionString": "{\"StartAt\":\"wait time\",\"States\":{\"wait time\":{\"Type\":\"Wait\",\"SecondsPath\":\"$.waitSeconds\",\"Next\":\"choice\"},\"choice\":{\"Type\":\"Choice\",\"Comment\":\"this is a comment for the choice state\",\"Choices\":[{\"Variable\":\"$.success\",\"IsPresent\":true,\"Next\":\"success\",\"Comment\":\"this is a comment for the when condition\"},{\"Variable\":\"$.noComment\",\"IsPresent\":true,\"Next\":\"short wait time\"}],\"Default\":\"success\"},\"success\":{\"Type\":\"Succeed\"},\"short wait time\":{\"Type\":\"Wait\",\"Seconds\":1,\"Next\":\"success\"}},\"Comment\":\"a super cool state machine\"}",
118119
"RoleArn": {
119120
"Fn::GetAtt": [
120121
"StateMachineRoleB840431D",
121122
"Arn"
122123
]
123-
},
124-
"DefinitionString": "{\"StartAt\":\"wait time\",\"States\":{\"wait time\":{\"Type\":\"Wait\",\"SecondsPath\":\"$.waitSeconds\",\"End\":true}},\"Comment\":\"a super cool state machine\"}"
124+
}
125125
},
126126
"DependsOn": [
127127
"StateMachineRoleB840431D"

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.js.snapshot/cdk.out

+1-1
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
{"version":"32.0.0"}
1+
{"version":"34.0.0"}

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.js.snapshot/integ.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "32.0.0",
2+
"version": "34.0.0",
33
"testCases": {
44
"integ.state-machine": {
55
"stacks": [

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.js.snapshot/manifest.json

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"version": "32.0.0",
2+
"version": "34.0.0",
33
"artifacts": {
44
"aws-stepfunctions-integ.assets": {
55
"type": "cdk:asset-manifest",
@@ -17,7 +17,7 @@
1717
"validateOnSynth": false,
1818
"assumeRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-deploy-role-${AWS::AccountId}-${AWS::Region}",
1919
"cloudFormationExecutionRoleArn": "arn:${AWS::Partition}:iam::${AWS::AccountId}:role/cdk-hnb659fds-cfn-exec-role-${AWS::AccountId}-${AWS::Region}",
20-
"stackTemplateAssetObjectUrl": "s3://cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}/2b683032648fa932811d781e11acb71f29e8dcde21411e7cf232807cc2565770.json",
20+
"stackTemplateAssetObjectUrl": "s3://cdk-hnb659fds-assets-${AWS::AccountId}-${AWS::Region}/6fc80a94a8b95de238e82bf832c22a76af712d24dc10c332baa36571da0a4a41.json",
2121
"requiresBootstrapStackVersion": 6,
2222
"bootstrapStackVersionSsmParameter": "/cdk-bootstrap/hnb659fds/version",
2323
"additionalDependencies": [

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.js.snapshot/tree.json

+57-33
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,32 @@
1212
"id": "wait time",
1313
"path": "aws-stepfunctions-integ/wait time",
1414
"constructInfo": {
15-
"fqn": "aws-cdk-lib.aws_stepfunctions.Wait",
16-
"version": "0.0.0"
15+
"fqn": "constructs.Construct",
16+
"version": "10.2.70"
17+
}
18+
},
19+
"short wait time": {
20+
"id": "short wait time",
21+
"path": "aws-stepfunctions-integ/short wait time",
22+
"constructInfo": {
23+
"fqn": "constructs.Construct",
24+
"version": "10.2.70"
25+
}
26+
},
27+
"choice": {
28+
"id": "choice",
29+
"path": "aws-stepfunctions-integ/choice",
30+
"constructInfo": {
31+
"fqn": "constructs.Construct",
32+
"version": "10.2.70"
33+
}
34+
},
35+
"success": {
36+
"id": "success",
37+
"path": "aws-stepfunctions-integ/success",
38+
"constructInfo": {
39+
"fqn": "constructs.Construct",
40+
"version": "10.2.70"
1741
}
1842
},
1943
"Role": {
@@ -24,8 +48,8 @@
2448
"id": "ImportRole",
2549
"path": "aws-stepfunctions-integ/Role/ImportRole",
2650
"constructInfo": {
27-
"fqn": "aws-cdk-lib.Resource",
28-
"version": "0.0.0"
51+
"fqn": "constructs.Construct",
52+
"version": "10.2.70"
2953
}
3054
},
3155
"Resource": {
@@ -49,8 +73,8 @@
4973
}
5074
},
5175
"constructInfo": {
52-
"fqn": "aws-cdk-lib.aws_iam.CfnRole",
53-
"version": "0.0.0"
76+
"fqn": "constructs.Construct",
77+
"version": "10.2.70"
5478
}
5579
},
5680
"DefaultPolicy": {
@@ -139,20 +163,20 @@
139163
}
140164
},
141165
"constructInfo": {
142-
"fqn": "aws-cdk-lib.aws_iam.CfnPolicy",
143-
"version": "0.0.0"
166+
"fqn": "constructs.Construct",
167+
"version": "10.2.70"
144168
}
145169
}
146170
},
147171
"constructInfo": {
148-
"fqn": "aws-cdk-lib.aws_iam.Policy",
149-
"version": "0.0.0"
172+
"fqn": "constructs.Construct",
173+
"version": "10.2.70"
150174
}
151175
}
152176
},
153177
"constructInfo": {
154-
"fqn": "aws-cdk-lib.aws_iam.Role",
155-
"version": "0.0.0"
178+
"fqn": "constructs.Construct",
179+
"version": "10.2.70"
156180
}
157181
},
158182
"StateMachine": {
@@ -167,8 +191,8 @@
167191
"id": "ImportRole",
168192
"path": "aws-stepfunctions-integ/StateMachine/Role/ImportRole",
169193
"constructInfo": {
170-
"fqn": "aws-cdk-lib.Resource",
171-
"version": "0.0.0"
194+
"fqn": "constructs.Construct",
195+
"version": "10.2.70"
172196
}
173197
},
174198
"Resource": {
@@ -192,14 +216,14 @@
192216
}
193217
},
194218
"constructInfo": {
195-
"fqn": "aws-cdk-lib.aws_iam.CfnRole",
196-
"version": "0.0.0"
219+
"fqn": "constructs.Construct",
220+
"version": "10.2.70"
197221
}
198222
}
199223
},
200224
"constructInfo": {
201-
"fqn": "aws-cdk-lib.aws_iam.Role",
202-
"version": "0.0.0"
225+
"fqn": "constructs.Construct",
226+
"version": "10.2.70"
203227
}
204228
},
205229
"Resource": {
@@ -208,60 +232,60 @@
208232
"attributes": {
209233
"aws:cdk:cloudformation:type": "AWS::StepFunctions::StateMachine",
210234
"aws:cdk:cloudformation:props": {
235+
"definitionString": "{\"StartAt\":\"wait time\",\"States\":{\"wait time\":{\"Type\":\"Wait\",\"SecondsPath\":\"$.waitSeconds\",\"Next\":\"choice\"},\"choice\":{\"Type\":\"Choice\",\"Comment\":\"this is a comment for the choice state\",\"Choices\":[{\"Variable\":\"$.success\",\"IsPresent\":true,\"Next\":\"success\",\"Comment\":\"this is a comment for the when condition\"},{\"Variable\":\"$.noComment\",\"IsPresent\":true,\"Next\":\"short wait time\"}],\"Default\":\"success\"},\"success\":{\"Type\":\"Succeed\"},\"short wait time\":{\"Type\":\"Wait\",\"Seconds\":1,\"Next\":\"success\"}},\"Comment\":\"a super cool state machine\"}",
211236
"roleArn": {
212237
"Fn::GetAtt": [
213238
"StateMachineRoleB840431D",
214239
"Arn"
215240
]
216-
},
217-
"definitionString": "{\"StartAt\":\"wait time\",\"States\":{\"wait time\":{\"Type\":\"Wait\",\"SecondsPath\":\"$.waitSeconds\",\"End\":true}},\"Comment\":\"a super cool state machine\"}"
241+
}
218242
}
219243
},
220244
"constructInfo": {
221-
"fqn": "aws-cdk-lib.aws_stepfunctions.CfnStateMachine",
222-
"version": "0.0.0"
245+
"fqn": "constructs.Construct",
246+
"version": "10.2.70"
223247
}
224248
}
225249
},
226250
"constructInfo": {
227-
"fqn": "aws-cdk-lib.aws_stepfunctions.StateMachine",
228-
"version": "0.0.0"
251+
"fqn": "constructs.Construct",
252+
"version": "10.2.70"
229253
}
230254
},
231255
"BootstrapVersion": {
232256
"id": "BootstrapVersion",
233257
"path": "aws-stepfunctions-integ/BootstrapVersion",
234258
"constructInfo": {
235-
"fqn": "aws-cdk-lib.CfnParameter",
236-
"version": "0.0.0"
259+
"fqn": "constructs.Construct",
260+
"version": "10.2.70"
237261
}
238262
},
239263
"CheckBootstrapVersion": {
240264
"id": "CheckBootstrapVersion",
241265
"path": "aws-stepfunctions-integ/CheckBootstrapVersion",
242266
"constructInfo": {
243-
"fqn": "aws-cdk-lib.CfnRule",
244-
"version": "0.0.0"
267+
"fqn": "constructs.Construct",
268+
"version": "10.2.70"
245269
}
246270
}
247271
},
248272
"constructInfo": {
249-
"fqn": "aws-cdk-lib.Stack",
250-
"version": "0.0.0"
273+
"fqn": "constructs.Construct",
274+
"version": "10.2.70"
251275
}
252276
},
253277
"Tree": {
254278
"id": "Tree",
255279
"path": "Tree",
256280
"constructInfo": {
257281
"fqn": "constructs.Construct",
258-
"version": "10.2.26"
282+
"version": "10.2.70"
259283
}
260284
}
261285
},
262286
"constructInfo": {
263-
"fqn": "aws-cdk-lib.App",
264-
"version": "0.0.0"
287+
"fqn": "constructs.Construct",
288+
"version": "10.2.70"
265289
}
266290
}
267291
}

‎packages/@aws-cdk-testing/framework-integ/test/aws-stepfunctions/test/integ.state-machine.ts

+19-1
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,30 @@ const wait = new sfn.Wait(stack, 'wait time', {
1414
time: sfn.WaitTime.secondsPath('$.waitSeconds'),
1515
});
1616

17+
const shortWait = new sfn.Wait(stack, 'short wait time', {
18+
time: sfn.WaitTime.duration(cdk.Duration.seconds(1)),
19+
});
20+
21+
const choice = new sfn.Choice(stack, 'choice', {
22+
comment: 'this is a comment for the choice state',
23+
});
24+
25+
const success = new sfn.Succeed(stack, 'success');
26+
27+
choice.when(sfn.Condition.isPresent('$.success'), success, {
28+
comment: 'this is a comment for the when condition',
29+
});
30+
choice.when(sfn.Condition.isPresent('$.noComment'), shortWait);
31+
choice.otherwise(success);
32+
wait.next(choice);
33+
shortWait.next(success);
34+
1735
const role = new iam.Role(stack, 'Role', {
1836
assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
1937
});
2038

2139
const stateMachine = new sfn.StateMachine(stack, 'StateMachine', {
22-
definition: wait,
40+
definitionBody: sfn.DefinitionBody.fromChainable(wait),
2341
comment: 'a super cool state machine',
2442
});
2543

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

+14
Original file line numberDiff line numberDiff line change
@@ -353,6 +353,20 @@ const shipTheItem = new sfn.Pass(this, 'ShipTheItem');
353353
choice.afterwards().next(shipTheItem);
354354
```
355355

356+
You can add comments to `Choice` states as well as conditions that use `choice.when`.
357+
358+
```ts
359+
const choice = new sfn.Choice(this, 'What color is it?', {
360+
comment: 'color comment',
361+
});
362+
const handleBlueItem = new sfn.Pass(this, 'HandleBlueItem');
363+
const handleOtherItemColor = new sfn.Pass(this, 'HanldeOtherItemColor');
364+
choice.when(sfn.Condition.stringEquals('$.color', 'BLUE'), handleBlueItem, {
365+
comment: 'blue item comment',
366+
});
367+
choice.otherwise(handleOtherItemColor);
368+
```
369+
356370
If your `Choice` doesn't have an `otherwise()` and none of the conditions match
357371
the JSON state, a `NoChoiceMatched` error will be thrown. Wrap the state machine
358372
in a `Parallel` state if you want to catch and recover from this.

‎packages/aws-cdk-lib/aws-stepfunctions/lib/states/choice.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import { Construct } from 'constructs';
22
import { StateType } from './private/state-type';
3-
import { State } from './state';
3+
import { ChoiceTransitionOptions, State } from './state';
44
import { Chain } from '../chain';
55
import { Condition } from '../condition';
66
import { IChainable, INextable } from '../types';
@@ -53,8 +53,8 @@ export class Choice extends State {
5353
/**
5454
* If the given condition matches, continue execution with the given state
5555
*/
56-
public when(condition: Condition, next: IChainable): Choice {
57-
super.addChoice(condition, next.startState);
56+
public when(condition: Condition, next: IChainable, options?: ChoiceTransitionOptions): Choice {
57+
super.addChoice(condition, next.startState, options);
5858
return this;
5959
}
6060

‎packages/aws-cdk-lib/aws-stepfunctions/lib/states/state.ts

+17-4
Original file line numberDiff line numberDiff line change
@@ -318,16 +318,16 @@ export abstract class State extends Construct implements IChainable {
318318
/**
319319
* Add a choice branch to this state
320320
*/
321-
protected addChoice(condition: Condition, next: State) {
322-
this.choices.push({ condition, next });
321+
protected addChoice(condition: Condition, next: State, options?: ChoiceTransitionOptions) {
322+
this.choices.push({ condition, next, ...options });
323323
next.startState.addIncoming(this);
324324
if (this.containingGraph) {
325325
next.startState.bindToGraph(this.containingGraph);
326326
}
327327
}
328328

329329
/**
330-
* Add a paralle branch to this state
330+
* Add a parallel branch to this state
331331
*/
332332
protected addBranch(branch: StateGraph) {
333333
this.branches.push(branch);
@@ -479,7 +479,7 @@ export interface FindStateOptions {
479479
/**
480480
* A Choice Transition
481481
*/
482-
interface ChoiceTransition {
482+
interface ChoiceTransition extends ChoiceTransitionOptions {
483483
/**
484484
* State to transition to
485485
*/
@@ -491,13 +491,26 @@ interface ChoiceTransition {
491491
condition: Condition;
492492
}
493493

494+
/**
495+
* Options for Choice Transition
496+
*/
497+
export interface ChoiceTransitionOptions {
498+
/**
499+
* An optional description for the choice transition
500+
*
501+
* @default No comment
502+
*/
503+
readonly comment?: string;
504+
}
505+
494506
/**
495507
* Render a choice transition
496508
*/
497509
function renderChoice(c: ChoiceTransition) {
498510
return {
499511
...c.condition.renderCondition(),
500512
Next: c.next.stateId,
513+
Comment: c.comment,
501514
};
502515
}
503516

0 commit comments

Comments
 (0)