Skip to content

Commit

Permalink
revamp step functions docs (#1237)
Browse files Browse the repository at this point in the history
  • Loading branch information
@HarshCasper
HarshCasper committed May 3, 2024
1 parent 56e2629 commit 851265c
Show file tree
Hide file tree
Showing 3 changed files with 38 additions and 90 deletions.
128 changes: 38 additions & 90 deletions content/en/user-guide/aws/stepfunctions/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,9 @@ description: >
Get started with Step Functions on LocalStack
---

## Introduction

{{< alert title="Note" >}}
A new [StepFunctions]({{< ref "user-guide/aws/lambda" >}}) implementation is now active by default since LocalStack&nbsp;3.0 (Docker `latest` since 2023-09-11).

If you experience any issues please open an issue on GitHub.
You can revert to the old behavior in the meantime by setting `PROVIDER_OVERRIDE_STEPFUNCTIONS=legacy`
{{</alert>}}

Step Functions is a serverless workflow engine that enables the orchestrating of multiple AWS services. It provides a JSON-based structured language called Amazon States Language (ASL) which allows to specify how to manage a sequence of tasks and actions that compose the application's workflow. Thus making it easier to build and maintain complex and distributed applications. Step Functions allows for the definition of both standard and express workflows for long-running and high-volume event processing.
Step Functions is a serverless workflow engine that enables the orchestrating of multiple AWS services. It provides a JSON-based structured language called Amazon States Language (ASL) which allows to specify how to manage a sequence of tasks and actions that compose the application's workflow. Thus making it easier to build and maintain complex and distributed applications.

LocalStack allows you to use the Step Functions APIs in your local environment to create, execute, update, and delete state machines locally. The supported APIs are available on our [API coverage page](https://docs.localstack.cloud/references/coverage/coverage_stepfunctions/), which provides information on the extent of Step Function's integration with LocalStack.

Expand Down Expand Up @@ -56,48 +50,8 @@ The output of the above command is the ARN of the state machine:

```json
{
"stateMachineArn": "arn:aws:states:<AWS_REGION>:000000000000:stateMachine:CreateAndListBuckets",
"creationDate": "<DATE>"
}
```

You can retrieve the details of a state machine using the [`DescribeStateMachine`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeStateMachine.html) API. Run the following command to describe the state machine:

{{< command >}}
$ awslocal stepfunctions describe-state-machine --state-machine-arn "arn:aws:states:us-east-1:000000000000:stateMachine:CreateAndListBuckets"
{{< /command >}}

The output of the above command is the execution ARN:
```json
{
"stateMachineArn": "arn:aws:states:<REGION>:000000000000:stateMachine:CreateAndListBuckets",
"name": "CreateAndListBuckets",
"status": "ACTIVE",
"definition": "{\n \"Comment\": \"Create bucket and list buckets\",\n \"StartAt\": \"CreateBucket\",\n \"States\": {\n \"CreateBucket\": {\n \"Type\": \"Task\",\n \"Resource\": \"arn:aws:states:::aws-sdk:s3:createBucket\",\n \"Parameters\": {\n \"BucketName\": \"new-sfn-demo-bucket\"\n },\n \"Next\": \"ListBuckets\"\n },\n \"ListBuckets\": {\n \"Type\": \"Task\",\n \"Resource\": \"arn:aws:states:::aws-sdk:s3:listBuckets\",\n \"End\": true\n }\n }\n }",
"roleArn": "arn:aws:iam::000000000000:role/stepfunctions-role",
"type": "STANDARD",
"creationDate": "<DATE>"
}
```

You can list the state machines using the [`ListStateMachines`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_ListStateMachines.html) API. Run the following command to list the state machines:

{{< command >}}
$ awslocal stepfunctions list-state-machines
{{< /command >}}

The output of the above command is a list of state machines:

```json
{
"stateMachines": [
{
"stateMachineArn": "arn:aws:states:<REGION>:000000000000:stateMachine:CreateAndListBuckets",
"name": "CreateAndListBuckets",
"type": "STANDARD",
"creationDate": "<DATE>"
}
]
"stateMachineArn": "arn:aws:states:us-east-1:000000000000:stateMachine:CreateAndListBuckets",
"creationDate": 1714643996.18017
}
```

Expand All @@ -111,67 +65,46 @@ $ awslocal stepfunctions start-execution \
{{< /command >}}

The output of the above command is the execution ARN:

```json
{
"executionArn": "arn:aws:states:<REGION>:000000000000:execution:CreateAndListBuckets:<ID>",
"startDate": "<DATE>"
"executionArn": "arn:aws:states:us-east-1:000000000000:execution:CreateAndListBuckets:bf7d2138-e96f-42d1-b1f9-41f0c1c7bc3e",
"startDate": 1714644089.748442
}
```

### Check the execution status

To check the status of the execution, you can use the [`DescribeExecution`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DescribeExecution.html) API. Run the following command to describe the execution:

{{< command >}}
$ awslocal stepfunctions describe-execution \
--execution-arn "arn:aws:states:<REGION>:000000000000:execution:CreateAndListBuckets:<ID>"
--execution-arn "arn:aws:states:us-east-1:000000000000:execution:CreateAndListBuckets:bf7d2138-e96f-42d1-b1f9-41f0c1c7bc3e"
{{< /command >}}

Replace the `execution-arn` with the ARN of the execution you want to describe.

The output of the above command is the execution status:

```json
{
"executionArn": "arn:aws:states:<REGION>:000000000000:execution:CreateAndListBuckets:<ID>",
"stateMachineArn": "arn:aws:states:<REGION>:000000000000:stateMachine:CreateAndListBuckets",
"name": "<EXECUTION-NAME",
"executionArn": "arn:aws:states:us-east-1:000000000000:execution:CreateAndListBuckets:bf7d2138-e96f-42d1-b1f9-41f0c1c7bc3e",
"stateMachineArn": "arn:aws:states:us-east-1:000000000000:stateMachine:CreateAndListBuckets",
"name": "bf7d2138-e96f-42d1-b1f9-41f0c1c7bc3e",
"status": "SUCCEEDED",
"startDate": "<DATE>",
"stopDate": "<DATE>",
"startDate": 1714644089.748442,
"stopDate": 1714644089.907964,
"input": "{}",
"inputDetails": {"included": true},
"output": "{\"Buckets\":[{\"Name\":\"new-sfn-bucket\",\"CreationDate\":\"<DATE\"}],\"Owner\":{\"DisplayName\":\"webfile\",\"ID\":\"<ID>\"}}",
"outputDetails": {"included": true}
"inputDetails": {
"included": true
},
"output": "{\"Buckets\":[{\"Name\":\"cdk-hnb659fds-assets-000000000000-us-east-1\",\"CreationDate\":\"2024-05-02T09:53:54+00:00\"},{\"Name\":\"new-sfn-bucket\",\"CreationDate\":\"2024-05-02T10:01:29+00:00\"}],\"Owner\":{\"DisplayName\":\"webfile\",\"Id\":\"75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a\"}}",
"outputDetails": {
"included": true
}
}
```

### Update and delete the state machine

You can update the state machine definition using the [`UpdateStateMachine`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_UpdateStateMachine.html) API. The API requires the ARN of the state machine and the new state machine definition. Run the following command to update the state machine definition:

{{< command >}}
$ awslocal stepfunctions update-state-machine \
--state-machine-arn "arn:aws:states:us-east-1:000000000000:stateMachine:CreateAndListBuckets" \
--definition file://path/to/your/statemachine.json \
--role-arn "arn:aws:iam::000000000000:role/stepfunctions-role"
{{< /command >}}

You can delete the state machine using the [`DeleteStateMachine`](https://docs.aws.amazon.com/step-functions/latest/apireference/API_DeleteStateMachine.html) API. Run the following command to delete the state machine:

{{< command >}}
$ awslocal stepfunctions delete-state-machine \
--state-machine-arn "arn:aws:states:us-east-1:000000000000:stateMachine:CreateAndListBuckets"
{{< /command >}}

## Resource Browser

The LocalStack Web Application provides a Resource Browser for managing Step Functions state machines. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the **Resources** section, and then clicking on **Step Functions** under the **App Integration** section.

<img src="stepfunctions-resource-browser.png" alt="Step Functions Resource Browser" title="Step Functions Resource Browser" width="900" />

The Resource Browser allows you to perform the following actions:

- **View State Machines**: View a list of all state machines you have created locally.
- **View Executions and Flow Chart**: View a list of all executions for a given state machine and the flow chart for each execution. You can also check the Execution Status, Timestamp, and Type for each execution.

## Supported services and operations

Step Functions integrates with AWS services, allowing you to invoke API actions for each service within your workflow. LocalStack's Step Functions emulation supports the following AWS services:
Expand All @@ -188,6 +121,21 @@ Step Functions integrates with AWS services, allowing you to invoke API actions
| | AWS Step Functions | &#10003; | &#10003; | &#10003; | &#10003; |
| AWS SDK integrations | All LocalStack services | &#10003; | | | &#10003; |

## Resource Browser

The LocalStack Web Application provides a Resource Browser for managing Step Functions state machines. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the **Resource Browser** section, and then clicking on **Step Functions** under the **App Integration** section.

<img src="stepfunctions-resource-browser.png" alt="Step Functions Resource Browser" title="Step Functions Resource Browser" width="900" />
<br>
<br>

The Resource Browser allows you to perform the following actions:

- **Create state machine**: Create a new state machine by clicking on the **Create state machine** button and providing the required information.
- **View state machine details**: Click on a state machine to view its details, including the state executions, definition details, such as the schema and flowchart, and the state machine's ARN.
- **Start execution**: Start a new execution of the state machine by clicking on the **Start Execution** button and providing the input data.
- **Delete state machine**: Delete a state machine by selecting it and clicking on the **Actions** button followed by **Remove Selected** button.

## Examples

The following code snippets and sample applications provide practical examples of how to use Step Functions in LocalStack for various use cases:
Expand Down
Binary file removed content/en/user-guide/aws/stepfunctions/stepfuctions-resource-browser.png
View file
Binary file not shown.
Binary file added content/en/user-guide/aws/stepfunctions/stepfunctions-resource-browser.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 851265c

Please sign in to comment.