From 7d91000448e71d70d4f660cf5b6dd8bf78f80bf7 Mon Sep 17 00:00:00 2001
From: Shiv Lakshminarayan <shivlaks@amazon.com>
Date: Mon, 20 Apr 2020 15:51:21 -0700
Subject: [PATCH] update README

---
 packages/@aws-cdk/aws-stepfunctions/README.md | 68 ++++++++++++++++++-
 1 file changed, 66 insertions(+), 2 deletions(-)

diff --git a/packages/@aws-cdk/aws-stepfunctions/README.md b/packages/@aws-cdk/aws-stepfunctions/README.md
index 6f92f68646923..af8100cd11746 100644
--- a/packages/@aws-cdk/aws-stepfunctions/README.md
+++ b/packages/@aws-cdk/aws-stepfunctions/README.md
@@ -159,17 +159,81 @@ similar to (for example) `inputPath`.
 
 #### Lambda example
 
+[Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) a Lambda function.
+
+You can specify the input to your Lambda function through the `payload` attribute.
+By default, no payload is specified so Step Functions invokes Lambda with the empty
+object `{ }` as input.
+
+The following snippet invokes a Lambda Function with the task context as the input
+by referencing the `$` path.
+
+```ts
+new sfn.Task(this, 'Invoke with task context', {
+  task: new tasks.RunLambdaTask(myLambda, {
+    payload: sfn.TaskInput.fromDataAt('$'),
+  }),
+});
+```
+
+When a function is invoked, the Lambda service sends back the following
+[response elements](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_ResponseElements)
+
+⚠️ The response from the Lambda function is in an attribute called `Payload`
+
+The following snippet invokes a Lambda Function by referencing the `$.Payload` path
+to reference the output of a Lambda executed before it.
+
+```ts
+new sfn.Task(this, 'Invoke with task context', {
+  task: new tasks.RunLambdaTask(myLambda),
+});
+
+new sfn.Task(this, 'Invoke with output from another Lambda', {
+  task: new tasks.RunLambdaTask(myOtherLambda, {
+    payload: sfn.TaskInput.fromDataAt('$.Payload'),
+  }),
+});
+```
+
+The following snippet invokes a Lambda and sets the task output to only include
+the Lambda function response.
+
+```ts
+new sfn.Task(this, 'Invoke and set function response as task output', {
+  task: new tasks.RunLambdaTask(checkJobStateLambda, {
+    payload: sfn.TaskInput.fromDataAt('$'),
+  }),
+  outputPath: '$.Payload',
+});
+```
+
+You can have Step Functions pause a task, and wait for an external process to
+return a task token. Read more about the [callback pattern](https://docs.aws.amazon.com/step-functions/latest/dg/callback-task-sample-sqs.html#call-back-lambda-example)
+
+To use the callback pattern, set the `token` property on the task and have the
+Lambda function Lambda function call the Step Functions API `SendTaskSuccess`
+or `SendTaskFailure` API with the token to indicate that the task has completed
+and the state machine should resume execution.
+
+The following snippet invokes a Lambda with the task token as part of the input
+to the Lambda.
+
 ```ts
-  const task = new sfn.Task(stack, 'Invoke2', {
+  const task = new sfn.Task(stack, 'Invoke with callback', {
     task: new tasks.RunLambdaTask(myLambda, {
       integrationPattern: sfn.ServiceIntegrationPattern.WAIT_FOR_TASK_TOKEN,
       payload: {
-        token: sfn.Context.taskToken
+        token: sfn.Context.taskToken,
+        input: sfn.TaskInput.fromDataAt('$.someField'),
       }
     })
   });
 ```
 
+⚠️ The Lambda function should call `SendTaskSuccess` or `SendTaskFailure` with the
+token provided as input or the State Machine will not resume.
+
 #### Glue Job example
 
 ```ts