feat(stepfunctions): support paths in Pass state (#8070)

The Pass state supports JsonPath values in the `parameters`
field to filter the state input and serve as input to the field.

Added a method to render parameters which will generate the ASL
JSON format if a path is used in a parameter.

Closes #7181


----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

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

@@ -131,20 +131,45 @@ directly in the Amazon States language.
 
 ### Pass
 
-A `Pass` state does no work, but it can optionally transform the execution's
-JSON state.
+A `Pass` state passes its input to its output, without performing work.
+Pass states are useful when constructing and debugging state machines.
+
+The following example injects some fixed data into the state machine through
+the `result` field. The `result` field will be added to the input and the result
+will be passed as the state's output.
 
 ```ts
 // Makes the current JSON state { ..., "subObject": { "hello": "world" } }
 const pass = new stepfunctions.Pass(this, 'Add Hello World', {
-    result: { hello: "world" },
-    resultPath: '$.subObject',
+  result: { hello: 'world' },
+  resultPath: '$.subObject',
 });
 
 // Set the next state
 pass.next(nextState);
 ```
 
+The `Pass` state also supports passing key-value pairs as input. Values can
+be static, or selected from the input with a path.
+
+The following example filters the `greeting` field from the state input
+and also injects a field called `otherData`.
+
+```ts
+const pass = new stepfunctions.Pass(this, 'Filter input and inject data', {
+  parameters: { // input to the pass state
+    input: stepfunctions.DataAt('$.input.greeting')
+    otherData: 'some-extra-stuff'
+  },
+});
+```
+
+The object specified in `parameters` will be the input of the `Pass` state.
+Since neither `Result` nor `ResultPath` are supplied, the `Pass` state copies
+its input through to its output.
+
+Learn more about the [Pass state](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-pass-state.html)
+
 ### Wait
 
 A `Wait` state waits for a given number of seconds, or until the current time

packages/@aws-cdk/aws-stepfunctions/lib/states/pass.ts

@@ -1,5 +1,6 @@
 import * as cdk from '@aws-cdk/core';
 import {Chain} from '../chain';
+import { FieldUtils } from '../fields';
 import {IChainable, INextable} from '../types';
 import { StateType } from './private/state-type';
 import {renderJsonPath, State } from './state';
@@ -147,7 +148,17 @@ export class Pass extends State implements INextable {
       Result: this.result ? this.result.value : undefined,
       ResultPath: renderJsonPath(this.resultPath),
       ...this.renderInputOutput(),
+      ...this.renderParameters(),
       ...this.renderNextEnd(),
     };
   }
+
+  /**
+   * Render Parameters in ASL JSON format
+   */
+  private renderParameters(): any {
+    return FieldUtils.renderObject({
+      Parameters: this.parameters,
+    });
+  }
 }

packages/@aws-cdk/aws-stepfunctions/test/state-machine-resources.test.ts

@@ -274,6 +274,26 @@ describe('State Machine Resources', () => {
     });
   }),
 
+  test('parameters can be selected from the input with a path', () => {
+    // GIVEN
+    const stack = new cdk.Stack();
+    const task = new stepfunctions.Pass(stack, 'Pass', {
+      parameters: {
+        input: stepfunctions.Data.stringAt('$.myField'),
+      },
+    });
+
+    // WHEN
+    const taskState = task.toStateJson();
+
+    // THEN
+    expect(taskState).toEqual({ End: true,
+      Parameters:
+      { 'input.$': '$.myField'},
+      Type: 'Pass',
+    });
+  }),
+
   test('State machines must depend on their roles', () => {
     // GIVEN
     const stack = new cdk.Stack();