massfords/asl-puml

generate a plant uml file from an Amazon States Language file

asl-puml

Install

# Use via the CLI
npm install -g asl-puml
# Use in your code
npm install asl-puml

CLI

$ asl-puml --help

  Usage: asl-puml [options]

  Amazon States Language to PUML

  Options:

Amazon States Language to PUML

Options:
  -i --input <input>    path to input file
  -o --output <output>  path to output dir
  -c --config <config>  path to config file
  -h, --help            display help for command

Return status:

• 0 if diagram was generated
• 1 if there was an error

In your code

const aslPuml = require('asl-puml');
const definition = require('./path/to/my/state/machine/json/definition');
const { isValid, puml, message } = aslPuml(definition);
if (isValid) {
  console.log(puml)
} else {
  console.error(message);
}

What does it do?

Generates a plantuml state diagram from a valid Amazon States Language file.

But why? There's already good tooling from AWS.

The existing tools are good, but I'm looking for a simpler rendering that encodes a little more info than the AWS Toolkit.

I also do all of my development in an IDE and don't want to switch to the browser based AWS Workflow Studio.

Example step function

See __tests__/Definitions/demo.asl.json for the step function used for these examples.

The diagrams below show the same step function rendered by:

• asl-puml (this library)
• AWS Toolkit
• AWS Workflow Studio

Feature comparison

Feature or Style Requirement	asl-puml	AWS Toolkit	AWS Workflow Studio
renders the step function as a state diagram
conveys the behavior for the state	✅, via colors and some icons	❌	✅, very familiar AWS icons and colors.
matches the style for instance executions	❌	✅	❌
renders within Webstorm/JetBrains products	✅, via the existing plantuml plugin	❌, not in AWS Toolkit for Webstorm	❌
renders the step function within VS Code	✅, via the existing plantuml plugin	✅, available in AWS Toolkit for VS Code	❌
label the path from a catch	✅, with line weight and color	❌	✅, path is labeled with a Catch
label the path to a Fail state	✅, with line weight and color	❌	❌
identify the compensation path	✅, albeit hard coded by state name regex	❌	❌
avoid drawing duplicate paths to reduce clutter (catches)	✅	✅	❌, all paths are drawn

Compensation Path

The term "compensate" is borrowed from business processes where it refers to the undoing of work as part of handling a fault.

When reviewing a process, it's useful to identify which parts of the process are in service of the happy path versus those in the compensation path.

Currently, the library uses a regex to match on the state's name to decide if it's in the compensation path. This will be made configurable as part of the theme. There isn't a good way to determine the compensation path without hints from the config.

Configuration

A user supplied file that conforms to the config-schema.json type can be provided to control the diagram theme.

{
  "theme": {
    "skinparams": {
      "ArrowColor": "#black"
    },
    "states": {
      "Pass": {
        "BackgroundColor": "#whitesmoke"
      },
      "Map": {
        "BackgroundColor": "#whitesmoke"
      },
      "Choice": {
        "BackgroundColor": "#whitesmoke"
      },
      "Parallel": {
        "BackgroundColor": "#whitesmoke"
      },
      "Wait": {
        "BackgroundColor": "#whitesmoke"
      },
      "Task": {
        "BackgroundColor": "#lightblue"
      },
      "Fail": {
        "BackgroundColor": "#red"
      },
      "Succeed": {
        "BackgroundColor": "#green"
      }
    },
    "lines": {
      "fromCatch": {
        "bold": true,
        "color": "#orange"
      },
      "toFail": {
        "color": "#pink"
      }
    },
    "compensation": {
      "pattern": "^.*(compensate).*$",
      "color": "#orange"
    }
  }
}

See also

• ASL specifications
• ASL documentation on AWS website
• PlantUML state diagram documentation

License

See LICENSE.

asl-puml's Issues

add decoration for waitForTaskToken

this is an important part of the workflow and should appear in the diagram

restore asl-validator once released

Need to get the TS version of asl-validator to be able to validate before trying to build the diagram

Additional style config needed in theme

• support setting the style of the transition conditions
• allow style to apply to non-task states

I'd like to be able to produce a diagram that shows the execution history for a definition.

• use the execution history to create styles for the states that executed
• set the defaults for other states to be light gray or muted to represent dead paths

this is something I'd emit during the build after running MockConfigFile tests.

render comment for choice on path if available

Use the Comments field to decorate a state transition if populated

support new fields for inline and distributed maps

The iterator field was renamed.

render the branch as a parent state within parallel

All of the nodes of a parallel are nested within the same state during the declaration of the states for the diagram

the diagram handles the rendering ok but it would be cleaner if the nodes were arranged in their branches from left to right in the order of their definition.

• include each branch, naming them from Branch 1 to N
• review what's available in plantuml to show the fork/join or just use a single start/end

use stable sort order when emitting plantuml file

The order for the states should be stable when producing the PUML file to avoid introducing any diffs in the diagram when run on the same source

error in graph rendering based on order of state declarations

Describe the bug
The order of the state declarations in the puml file can lead to child nodes being displayed without their parent links and thus break the rendering of the directed graph. This seems like it's a PlantUML bug.

Current behavior for asl-puml is to emit the puml file with the states in the order encountered in the process definition. If a theme is passed to the renderer, then states logically grouped together are emitted first.

In the example below, the diagram is generated from the process execution history with a theme and thus the underlying map of states isn't in the same order as the source file.

Here's the relevant part of the emitted puml:

state "check_fetched" as state9<<Choice>>
state "end_state" as state10<<CustomStyle1>>
state "fetch_todays_scores" as state7<<CustomStyle2>>
state "get_games_to_monitor" as state2<<CustomStyle3>>
state "has_games" as state3<<Choice>>
state "init_state" as state1<<CustomStyle5>>
state "put_scores_deadline" as state4<<CustomStyle6>>
state "put_scores_now" as state5<<CustomStyle9>>
state "update_scores_item" as state8<<CustomStyle7>>
state "wait_for_deadline" as state6<<CustomStyle8>>

The rendering is correct if the state declarations are sorted.

Expected behavior
The directed graph should render based on the graph in the puml and not the order of the state declarations. In both the correct and incorrect renderings above, the directed graph is correct in the source file:

[*] --> state1
state1 --> state2
state2 --> state3
state3 -[#lightgray]-> state5
state3 --> state4
state3 --> state10
state4 --> state6
state5 -[#lightgray]-> state7
state6 --> state7
state7 --> state8
state8 --> state9
state9 --> state2
state9 --> state10
state10 --> [*]

Quick fix:

• change the asl-puml output to report the directed graph ahead of the state declarations
• this works in all cases but unfortunately results in the Choice style being lost (no diamond)

Other possible fix:

• update the decl output to emit the states in the order defined by the graph

While this error appeared with a state execution rendering theme, it seems possible to recreate simply based on the ordering of the states within the process definition. Given that the order of the states doesn't impact the process definition, it shouldn't impact the rendering.

doc: update sample process to include more state types

• include parallel and map states
• remove OrderComplete state

provide better support for generating from a build

Goals:

• limit the amount of changes needed in a package.json
• support a file with paths and config for ASL source files

Add option to use aws plantuml icons in diagrams

Provide an option in the config to use the AWS icons for plantuml:

https://github.com/awslabs/aws-icons-for-plantuml

• include the imports for the referenced services
• use the sprite function in the state's name to generate the icon

Example defines

!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v15.0/dist

!include AWSPuml/AWSCommon.puml
!include AWSPuml/AWSExperimental.puml
!include AWSPuml/Compute/Lambda.puml
!include AWSPuml/ApplicationIntegration/EventBridge.puml
!include AWSPuml/ApplicationIntegration/SimpleQueueService.puml

Example of using sprite function in name:

state "$SimpleQueueServiceIMG()\nReserve Items" as state2

add test for updated iterator support

update an existing test to use the new Map fields and verify rendering

I'm seeing issues rendering processes with ItemProcessor so it's likely I missed a path expression somewhere in the code

convert project to Typescript

• convert from JS to TS
• update linter to require functions to have return values declared
• update linter to disallow any
• add build step to package.json
• update GitHub actions workflows to include compilation

Support description for state names in theme config

Support adding a description for a state to the config.

• there should be no change to the diagram if there is no description for the state
• if the theme provides a description for the state, then include that description in the state declaration (see example)
• update existing test to include a description

example state with description:

state "DetectSentiment" as state2<<CustomStyle3>> : <:warning:><:warning:><:white_check_mark:>

In this example, the theme uses the description to convey how many times the task was retried before working

externalize theme config to properties file

create a config file to allow override of the styling of the generated puml

• fonts and colors for the stereotype skins
• color and weight for the transitions between states
• option to show transition conditions in notes
• regex for compensation path

Parallel within a Map isn't rendering correctly

The decl isn't being nested

automate the release process and publish into npm registry

review what's needed to have a push button release and get the lib published into the npm registry