AWS toolkit-for-vscode documentation change
Summary
Restructured documentation with updated section organization, added detailed procedures for creating/viewing state machines, and removed outdated prerequisites/visualization content
Security assessment
Changes focus on workflow reorganization and procedural updates for Step Functions integration in VS Code. No security vulnerabilities, credential handling, or access control changes are mentioned. Removed prerequisite section about credentials configuration doesn't introduce new security context.
Diff
diff --git a/toolkit-for-vscode/latest/userguide/building-stepfunctions.md index e5973df0b..44d44e02b 100644 --- a/toolkit-for-vscode/latest/userguide/building-stepfunctions.md +++ b/toolkit-for-vscode/latest/userguide/building-stepfunctions.md @@ -5 +5 @@ -PrerequisitesWork with state machines in VS CodeState machine templatesState machine graph visualizationCode snippetsCode completion and validation +Viewing Step Functions state machinesCreating a Step Functions state machineCreating a Step Functions state machine from a templateDownloading a Step Functions state machineSaving changes to a Step Functions state machineRunning a Step Functions state machineWorking with code snippetsCode validation @@ -9 +9 @@ PrerequisitesWork with state machines in VS CodeState machine templatesState mac -You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various operations with [state machines](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html). +The following sections describe how to work with AWS Step Functions `Amazon State Language (ASL)` files containing state machine definitions in the AWS Toolkit. For detailed information about AWS Step Functions state machines, see the [Learn about state machines in Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-statemachines.html) topic in the _AWS Step Functions_ Developer Guide. @@ -11 +11 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various -###### Topics +## Viewing Step Functions state machines @@ -13 +13 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various - * Prerequisites +To view your existing `ASL` files containing state machine definitions in the AWS Toolkit Explorer, complete the following steps. @@ -15 +15 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various - * Work with state machines in VS Code + 1. From the AWS Toolkit Explorer, expand the region that contains the `ASL` file that you want to view. @@ -17 +17 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various - * State machine templates + 2. Expand the **Step Functions** heading. @@ -19 +19 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various - * State machine graph visualization + 3. Your `ASL` files are displayed in the AWS Explorer. @@ -21 +20,0 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various - * Code snippets @@ -23 +21,0 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various - * Code completion and validation @@ -25,0 +24 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various +## Creating a Step Functions state machine @@ -26,0 +26 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various +In the AWS Toolkit, you can create a new Step Functions state machine from a file or you can use a template. The following procedure describes how to create a Step Functions state machine from a file. For details about creating a SFN; state machine from a template, see the _State machine templates_ section located below, in this User Guide topic. @@ -28,39 +28 @@ You can use the AWS Toolkit for Visual Studio Code (VS Code) to perform various -## Prerequisites - - * Be sure your system meets the prerequisites specified in [Installing the Toolkit for VS Code](./setup-toolkit.html#setup-prereq), then install the toolkit. - - * Ensure that you have configured your credentials before opening the **AWS Explorer**. - - - - -## Work with state machines in VS Code - -You can use VS Code to interact with remote state machines, and develop state machines locally in JSON or YAML format. You can create or update state machines, list existing state machines, run them, and download them. VS Code also lets you create new state machines from templates, see a visualization of your state machine, and provides code snippets, code completion, and code validation. - -### List existing state machines - -If you've already created state machines, you can view a list of them: - - 1. Open the **AWS Explorer**. - - 2. Select Step Functions - - 3. Verify that it lists all the state machines in your account. - - - - - - -### Download a state machine - -To download a state machine: - - 1. In the **AWS Explorer** , right click the state machine that you want to download. - - 2. Select Download, then select the location where you want to download the state machine. - - 3. Verify that it downloaded correctly. - - +###### Note @@ -67,0 +30 @@ To download a state machine: +To work with Step Functions in VS Code, the extension of your `Amazon State Language`(ASL) file that contains your state machine definition must end with `asl.json`, `asl.yml`, or `.asl.yaml`. @@ -68,0 +32 @@ To download a state machine: +By default, relevant Step Functions files open in Workflow Studio. For detailed information about working in Workflow Studio through the AWS Toolkit, see the [Working with Workflow Studio](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/stepfunctions-workflowstudio.html) topic in this User Guide. @@ -69,0 +34 @@ To download a state machine: + 1. From your workspace in VS Code, create a new file. @@ -71 +36 @@ To download a state machine: -### Create a state machine + 2. Name your file and specify the file extension as `asl.json`, `asl.yml`, or `.asl.yaml`. @@ -73 +38 @@ To download a state machine: -You can create a new state machine yourself, or you can use a template. For more information on creating a state machine from a template, see the **State Machine Templates** section. To create a new state machine: + 3. Upon creation, the AWS Toolkit opens the new file in AWS Step Functions Workflow Studio. @@ -75 +40 @@ You can create a new state machine yourself, or you can use a template. For more - 1. Create a new [Amazon States Language](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html) (ASL) file with your state machine definition. Use the menu at the bottom right to set it as Amazon States Language. + 4. From **Workflow Studio** choose the **Save** button from the utility menu to save your new `ASL` file. @@ -77 +41,0 @@ You can create a new state machine yourself, or you can use a template. For more - 2. Select **Publish to Step Functions**. @@ -79 +42,0 @@ You can create a new state machine yourself, or you can use a template. For more - @@ -81 +43,0 @@ You can create a new state machine yourself, or you can use a template. For more - 3. Select **Quick Create** , choose a role, and name your state machine. @@ -83 +45 @@ You can create a new state machine yourself, or you can use a template. For more - +## Creating a Step Functions state machine from a template @@ -85 +47 @@ You can create a new state machine yourself, or you can use a template. For more - +In the AWS Toolkit, you can create a Step Functions state machine from a template. The template process creates a `ASL` file that contains a state machine definition, providing a starting point for your project. The following procedure describes how to create a Step Functions state machine from a template in the AWS Toolkit. @@ -87 +49 @@ You can create a new state machine yourself, or you can use a template. For more - + 1. From the AWS Toolkit Explorer, expand the region that you want to create a Step Functions state machine in. @@ -88,0 +51 @@ You can create a new state machine yourself, or you can use a template. For more + 2. Open the context menu for (right-click) **Step Functions** and choose **Create a new Step Functions state machine** to open the **Select a starter template(1/2)** wizard in VS Code. @@ -89,0 +53 @@ You can create a new state machine yourself, or you can use a template. For more + 3. From the **Select a starter template(1/2)** wizard, choose the template type for your Step Functions state machine to proceed. @@ -90,0 +55 @@ You can create a new state machine yourself, or you can use a template. For more + 4. From the **Select template format(2/2)** screen, choose either **YAML** or **JSON** for your template format. @@ -92 +57 @@ You can create a new state machine yourself, or you can use a template. For more -### Update a state machine + 5. A new `ASL` file containing your state machine definition is opened in the VS Code editor. @@ -94 +58,0 @@ You can create a new state machine yourself, or you can use a template. For more -To update a state machine: @@ -96 +59,0 @@ To update a state machine: - 1. Edit the ASL file with your state machine definition. @@ -98 +60,0 @@ To update a state machine: - 2. Select **Publish to Step Functions**. @@ -100 +62 @@ To update a state machine: - +## Downloading a Step Functions state machine @@ -102 +64 @@ To update a state machine: - 3. Select **Quick Update** , then select the state machine you want to update. +To download a remotely stored Step Functions state machine to your local instance of VS Code, complete the following steps. @@ -104 +66 @@ To update a state machine: - + 1. From the AWS Toolkit Explorer, expand the region that contains the Step Functions state machine that your want to download. @@ -106 +68 @@ To update a state machine: - + 2. Expand **Step Functions** , then right-click the Step Functions state machine you want to download and choose **Download Definition...**. @@ -107,0 +70 @@ To update a state machine: + 3. Specify a location to store your Step Functions state machine locally to proceed. @@ -108,0 +72 @@ To update a state machine: + 4. The Step Functions state machine opens in Workflow Studio when the procedure is complete. @@ -111 +74,0 @@ To update a state machine: -### Run a state machine @@ -113 +75,0 @@ To update a state machine: -To run a state machine: @@ -115 +77 @@ To run a state machine: - 1. In the **AWS Explorer** , right click the state machine that you want to run. +## Saving changes to a Step Functions state machine @@ -117 +79 @@ To run a state machine: - 2. Provide input for the state machine. You can try both input from a file, and input in a text box. +The following procedure describes how to save changes made to your Step Functions state machine. @@ -119 +81 @@ To run a state machine: - 3. Start the state machine and verify that it runs successfully. +###### Note @@ -121 +83 @@ To run a state machine: - +Edits made in Workflow Studio sync to your local file, but remain unsaved until your work is saved in the VS Code editor or Workflow Studio. If you local file is modified and saved while Workflow Studio is open and there are no errors detected in your `ASL` file, then you receive a **Success** notification in Workflow Studio, when saving is complete. However, if your local file contains invalid `JSON` or `YAML` and you attempt to save, then your local file fails to sync and you receive a **Warning** notification in Workflow Studio. @@ -123 +85 @@ To run a state machine: - + 1. From an open `ASL` file containing a state machine definition in Workflow Studio, navigate to the **Utility buttons**. @@ -124,0 +87 @@ To run a state machine: + 2. Choose the **Save** button. @@ -125,0 +89 @@ To run a state machine: + 3. VS Code notifies you when the file has been saved. @@ -128 +91,0 @@ To run a state machine: -## State machine templates @@ -130 +92,0 @@ To run a state machine: -When you create a state machine, you have the option to create it from a template. The template contains a sample state machine definition with several commonly used states, and provides you with a starting point. To use state machine templates: @@ -132 +94 @@ When you create a state machine, you have the option to create it from a templat - 1. Open the **Command Palette** in VS Code. +## Running a Step Functions state machine @@ -134 +96 @@ When you create a state machine, you have the option to create it from a templat - 2. Select **AWS Toolkit Create a new Step Functions state machine**. +The following procedure describes how to run a Step Functions state machine in the AWS Toolkit. @@ -136 +98 @@ When you create a state machine, you have the option to create it from a templat - 3. Choose the template you want to use. + 1. From the AWS Toolkit Explorer, expand the region containing the Step Functions state machine that you want to run. @@ -138 +100 @@ When you create a state machine, you have the option to create it from a templat - + 2. Expand **Step Functions** , then right-click the Step Functions state machine that you want to run. @@ -140 +102 @@ When you create a state machine, you have the option to create it from a templat - 4. Choose whether you want to use the JSON or the YAML template format. + 3. From the context menu, choose **Start Execution** to initiate the launch process. @@ -142 +104 @@ When you create a state machine, you have the option to create it from a templat - + 4. The status of the launch is displayed in the **AWS Toolkit Output** window in VS Code. @@ -147 +109 @@ When you create a state machine, you have the option to create it from a templat -## State machine graph visualization +## Working with code snippets @@ -149 +111 @@ When you create a state machine, you have the option to create it from a templat -Graph visualizations let you see what your state machine looks like in graphical format. When you create a graph visualization, another tab will open and display a visualizion of the state machine JSON or YAML. You can then compare the state machine definition you are writing concurrently with its visualization. As you change your state machine definition, the visualization will be updated. +Code snippets are automated suggestions that generate based on the code that you're working on. To work with code snippets with Step Functions in the toolkit, complete the following steps. @@ -153,13 +115 @@ Graph visualizations let you see what your state machine looks like in graphical -To create a visualizion of a state machine definition, the definition must be open in the active editor. If you close or rename the definition file, the visualization will close. - -To create a state machine graph visualization: - - 1. Define your state machine. - - 2. Open the **Command Palette** in VS Code. - - 3. To create a visualization, use the visualization button in the upper right corner, or choose **AWS Render graph**. - - - -