AWS step-functions documentation change
Summary
Updated error handling tutorial with revised Lambda integration patterns, simplified error catching configuration, and improved state machine definition syntax
Security assessment
Changes focus on improving error handling patterns and updating syntax to modern standards (ES modules). No security vulnerabilities or security feature enhancements are mentioned. The IAM role configuration remains at basic Lambda permissions level without new security controls.
Diff
diff --git a/step-functions/latest/dg/tutorial-handling-error-conditions.md b/step-functions/latest/dg/tutorial-handling-error-conditions.md index 290ad1d95..d6678664f 100644 --- a//step-functions/latest/dg/tutorial-handling-error-conditions.md +++ b//step-functions/latest/dg/tutorial-handling-error-conditions.md @@ -5 +5 @@ -Step 1: Create a Lambda function that failsStep 2: Test the Lambda functionStep 3: Create a state machine with a Catch fieldStep 4: Run the state machine +Step 1: Create a Lambda function that throws an errorStep 2: Test your Lambda functionStep 3: Create your state machine machineStep 4: Configure your state machineStep 5: Run the state machine @@ -7 +7 @@ Step 1: Create a Lambda function that failsStep 2: Test the Lambda functionStep -# Handling error conditions using a Step Functions state machine +# Handling error conditions in a Step Functions state machine @@ -13,5 +13 @@ For more information, see [AWS Lambda function errors in Node.js](https://docs.a -###### Note - -You can also create state machines that [Retry](./concepts-error-handling.html#error-handling-retrying-after-an-error) on timeouts or those that use `Catch` to transition to a specific state when an error or timeout occurs. For examples of these error handling techniques, see [Examples Using Retry and Using Catch](./concepts-error-handling.html#error-handling-examples). - -## Step 1: Create a Lambda function that fails +## Step 1: Create a Lambda function that throws an error @@ -21,4 +16,0 @@ Use a Lambda function to simulate an error condition. -###### Important - -Ensure that your Lambda function is under the same AWS account and AWS Region as your state machine. - @@ -29 +21,3 @@ Ensure that your Lambda function is under the same AWS account and AWS Region as - 3. Choose **Use a blueprint** , enter `step-functions` into the search box, and then choose the **Throw a custom error** blueprint. + 3. Choose **Use a blueprint** , search for `Step Functions`, and choose **Throw a custom error**. + + 4. For **Function name** , enter `ThrowErrorFunction`. @@ -31 +25 @@ Ensure that your Lambda function is under the same AWS account and AWS Region as - 4. For **Function name** , enter `FailFunction`. + 5. For **Role** , choose **Create a new role with basic Lambda permissions**. @@ -33 +27 @@ Ensure that your Lambda function is under the same AWS account and AWS Region as - 5. For **Role** , keep the default selection (**Create a new role with basic Lambda permissions**). + 6. Choose **Create function**. @@ -35 +29 @@ Ensure that your Lambda function is under the same AWS account and AWS Region as - 6. The following code is displayed in the **Lambda function code** pane. +The following code should be displayed in the **code** pane. @@ -37 +31 @@ Ensure that your Lambda function is under the same AWS account and AWS Region as - exports.handler = async (event, context) => { + export const handler = async () => { @@ -47,3 +40,0 @@ Ensure that your Lambda function is under the same AWS account and AWS Region as -The `context` object returns the error message `This is a custom error!`. - - 7. Choose **Create function**. @@ -51 +41,0 @@ The `context` object returns the error message `This is a custom error!`. - 8. After your Lambda function is created, copy the function's Amazon Resource Name (ARN) displayed in the upper-right corner of the page. The following is an example ARN: @@ -53 +42,0 @@ The `context` object returns the error message `This is a custom error!`. - arn:aws:lambda:region:123456789012:function:FailFunction @@ -55 +43,0 @@ The `context` object returns the error message `This is a custom error!`. - 9. Choose **Deploy**. @@ -56,0 +45 @@ The `context` object returns the error message `This is a custom error!`. +## Step 2: Test your Lambda function @@ -57,0 +47 @@ The `context` object returns the error message `This is a custom error!`. +Before creating a state machine, verify your Lambda function throws the error when invoked. @@ -58,0 +49 @@ The `context` object returns the error message `This is a custom error!`. + 1. Choose the **Test** tab. @@ -60 +51 @@ The `context` object returns the error message `This is a custom error!`. -## Step 2: Test the Lambda function + 2. Choose **Create a new event** and keep the default **Event JSON** @@ -62 +53 @@ The `context` object returns the error message `This is a custom error!`. -Test your Lambda function to see it in operation. + 3. Choose **Test** to invoke your function with your test event. @@ -64 +55 @@ Test your Lambda function to see it in operation. - 1. On the **FailFunction** page, choose the **Test** tab, and then choose **Test**. You don't need to create a test event. + 4. Expand **Executing function** to review the details of the thrown error. @@ -66 +56,0 @@ Test your Lambda function to see it in operation. - 2. To review the test results (the simulated error), under **Execution result** , expand **Details**. @@ -69,0 +60 @@ Test your Lambda function to see it in operation. +**Congratulations!** You have a Lambda function ready to throw an error that your new state machine will catch. @@ -71 +62 @@ Test your Lambda function to see it in operation. -## Step 3: Create a state machine with a Catch field +## Step 3: Create your state machine machine @@ -73 +64 @@ Test your Lambda function to see it in operation. -Use the Step Functions console to create a state machine that uses a [Task workflow state](./state-task.html) state with a `Catch` field. Add a reference to your Lambda function in the Task state. The state machine invokes the Lambda function, which fails during execution. Step Functions retries the function twice using exponential backoff between retries. +Use the Step Functions console to create a state machine that uses a [Task workflow state](./state-task.html) with a `Catch` configuration. The state machine will invoke the Lambda function, which you've built to simulate throwing an error when the function is invoked. Step Functions retries the function twice using exponential backoff between retries. @@ -77 +68 @@ Use the Step Functions console to create a state machine that uses a [Task workf - 2. In the **Choose a template** dialog box, select **Blank**. + 2. For **State machine name** , enter `CatchErrorStateMachine`. @@ -79 +70 @@ Use the Step Functions console to create a state machine that uses a [Task workf - 3. Choose **Select** to open Workflow Studio in [Design mode](./workflow-studio.html#wfs-interface-design-mode). + 3. Choose **Continue** to edit your state machine in Workflow Studio. @@ -81,3 +72 @@ Use the Step Functions console to create a state machine that uses a [Task workf - 4. Choose **Code** to open the code editor. In the code editor, you write and edit the [Amazon States Language](./concepts-amazon-states-language.html) (ASL) definition of your workflows. - - 5. Paste the following code, but replace the ARN of the Lambda function that you created earlier in the `Resource` field. + 4. Choose **Code** to switch to the ASL editor, then replace the code with following state machine definition: @@ -86 +75 @@ Use the Step Functions console to create a state machine that uses a [Task workf - "Comment": "A Catch example of the Amazon States Language using an AWS Lambda function", + "Comment": "Example state machine that can catch a custom error thrown by a function integration.", @@ -91,3 +80,11 @@ Use the Step Functions console to create a state machine that uses a [Task workf - "Resource": "arn:aws:lambda:region:123456789012:function:FailFunction", - "Catch": [ { - "ErrorEquals": ["CustomError"], + "Resource": "arn:aws:states:::lambda:invoke", + "Output": "{% $states.result.Payload %}", + "Arguments": { + "FunctionName": "arn:aws:lambda:region>:account-id:function:ThrowErrorFunction:$LATEST", + "Payload": "{% $states.input %}" + }, + "Catch": [ + { + "ErrorEquals": [ + "CustomError" + ], @@ -95,5 +92,5 @@ Use the Step Functions console to create a state machine that uses a [Task workf - }, { - "ErrorEquals": ["States.TaskFailed"], - "Next": "ReservedTypeFallback" - }, { - "ErrorEquals": ["States.ALL"], + }, + { + "ErrorEquals": [ + "States.ALL" + ], @@ -101 +98,2 @@ Use the Step Functions console to create a state machine that uses a [Task workf - } ], + } + ], @@ -106,7 +104,4 @@ Use the Step Functions console to create a state machine that uses a [Task workf - "Result": "This is a fallback from a custom Lambda function exception", - "End": true - }, - "ReservedTypeFallback": { - "Type": "Pass", - "Result": "This is a fallback from a reserved error code", - "End": true + "End": true, + "Output": { + "Result": "Fallback from a custom error function." + } @@ -116,2 +111,3 @@ Use the Step Functions console to create a state machine that uses a [Task workf - "Result": "This is a fallback from any error code", - "End": true + "End": true, + "Output": { + "Result": "Fallback from all other error codes." @@ -119,0 +116,2 @@ Use the Step Functions console to create a state machine that uses a [Task workf + }, + "QueryLanguage": "JSONata" @@ -122,13 +119,0 @@ Use the Step Functions console to create a state machine that uses a [Task workf -This is a description of your state machine using the Amazon States Language. It defines a single `Task` state named `CreateAccount`. For more information, see [State Machine Structure](./statemachine-structure.html). - -For more information about the syntax of the `Retry` field, see [State machine examples using Retry and using Catch](./concepts-error-handling.html#error-handling-examples). - -###### Note - -Unhandled errors in Lambda runtimes were historically reported only as `Lambda.Unknown`. In newer runtimes, timeouts are reported as `Sandbox.Timedout` in the error output. - -When Lambda exceeds the maximum number of invocations, the reported error will be `Lambda.TooManyRequestsException`. - -Match on `Lambda.Unknown`, `Sandbox.Timedout`, `States.ALL`, and `States.TaskFailed` to handle possible errors. For more information about Lambda `Handled` and `Unhandled` errors, see `FunctionError` in the [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html#API_Invoke_ResponseSyntax). - - 6. (Optional) In the [Graph visualization](./workflow-studio.html#wfs-interface-code-graph-viz), see the real-time graphical visualization of your workflow. @@ -136 +120,0 @@ Match on `Lambda.Unknown`, `Sandbox.Timedout`, `States.ALL`, and `States.TaskFai - 7. Specify a name for your state machine. To do this, choose the edit icon next to the default state machine name of **MyStateMachine**. Then, in **State machine configuration** , specify a name in the **State machine name** box. @@ -138 +121,0 @@ Match on `Lambda.Unknown`, `Sandbox.Timedout`, `States.ALL`, and `States.TaskFai -For this tutorial, enter `Catchfailure`. @@ -140 +123 @@ For this tutorial, enter `Catchfailure`. - 8. (Optional) In **State machine configuration** , specify other workflow settings, such as state machine type and its execution role. +## Step 4: Configure your state machine @@ -142 +125 @@ For this tutorial, enter `Catchfailure`. -For this tutorial, keep all the default selections in **State machine settings**. +Before you run your state machine, you must first connect to the function you previously created. @@ -144 +127 @@ For this tutorial, keep all the default selections in **State machine settings** - 9. In the **Confirm role creation** dialog box, choose **Confirm** to continue. + 1. Switch back to **Design** mode and select the **Lambda : Invoke** task state named **CreateAccount**. @@ -146,5 +129 @@ For this tutorial, keep all the default selections in **State machine settings** -You can also choose **View role settings** to go back to **State machine configuration**. - -###### Note - -If you delete the IAM role that Step Functions creates, Step Functions can't recreate it later. Similarly, if you modify the role (for example, by removing Step Functions from the principals in the IAM policy), Step Functions can't restore its original settings later. + 2. For **Function name** in API Arguments, choose the Lambda function that you created earlier. @@ -151,0 +131 @@ If you delete the IAM role that Step Functions creates, Step Functions can't rec + 3. Choose **Create** , review roles, then choose **Confirm** to create your state machine. @@ -155 +134,0 @@ If you delete the IAM role that Step Functions creates, Step Functions can't rec -## Step 4: Run the state machine @@ -157 +136 @@ If you delete the IAM role that Step Functions creates, Step Functions can't rec -After you create your state machine, you can run it. +## Step 5: Run the state machine @@ -159 +138 @@ After you create your state machine, you can run it. - 1. On the **State machines** page, choose **Catchfailure**. +After you create and configure your state machine, you can run start it. @@ -161 +140 @@ After you create your state machine, you can run it. - 2. On the **Catchfailure** page, choose **Start execution**. The **Start execution** dialog box is displayed. + 1. Choose **Start execution**. @@ -163 +142 @@ After you create your state machine, you can run it. - 3. In the **Start execution** dialog box, do the following: + 2. In the **Start execution** dialog box, do the following: @@ -179 +157,0 @@ To review the execution results, choose individual states on the **Graph view** -For example, to view your custom error message, choose the **CreateAccount** step in **Graph view** , and then choose the **Output** tab. @@ -181 +158,0 @@ For example, to view your custom error message, choose the **CreateAccount** ste - @@ -183 +159,0 @@ For example, to view your custom error message, choose the **CreateAccount** ste -###### Note @@ -185 +161 @@ For example, to view your custom error message, choose the **CreateAccount** ste -You can preserve the state input with the error by using `ResultPath`. See [Use ResultPath to include both error and input in a Catch](./input-output-resultpath.html#input-output-resultpath-catch). +Your state machine should invoke the Lambda function. The function will throw a `CustomError`. Choose the **CreateAccount** step in the **Graph view** to see the state output. Your state machine output should look similar to the following illustration: @@ -186,0 +163,3 @@ You can preserve the state input with the error by using `ResultPath`. See [Use +