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	❌	❌
label the state transition if conditional	✅, limited support with StringEquals	❌	✅, expression is shown in a note on the line
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.