Documentation of Finite State Machine / Workflow

Question

In my database, I store task data (id, timestamp, input data), and information about the state of the multi-step processing (e.g. prepare, execute, summarize). The program moves from one state to another. If the program breaks, the last state remains persistent. I am thinking in terms of a finite state machine (fsm).

Now I am looking for an easy text format to document the fsm. I want to be able to define the input (available data) that can be expected for a given state, and several possible next states (e.g. finished, failed).

I was looking for over an hour on common workflow language (cwl) and could not figure out whether they have more than one output states or not and so I am asking here.

Any hints appreciated!

EDIT: According to your answer, I realize that this is a too small problem for a standard text format. I guess I was looking for a ready-to-go solution of this. Thanks!

Answer 1

I agree with Hans-Martin Mosner on this: nothing beats a graphical representation for workflows. Not sure how complex your workflows are and how many parameters on each state, but try having a look at the dot language. You might be able to build a graph that displays everything you need.

It's not all that much of a complex language and many times I used to generate graphs by dumping states from the database with SQL queries into a file.

https://graphviz.org/Gallery/directed/fsm.html

Answer 2

For FSMs (unless they have too many states) nothing beats a graphical representation of the states and transitions. A textual description of each state and transition is also needed, of course, but that may well be informal as the formal structure is completely described in the graph.

Just had a look at the CWL page, it doesn't seem to be well suited to describe FSMs, but mainly targeted towards workflows involving multiple programs, file data, etc.

Answer 3

This may be overkill but there is a W3C standard called SCXML that provides a standard representation of a state machine. Being a standard there can be somewhat ugly visualizations that can be made by others like JSSCXML, and hopefully nicer ones in the future.

The advantage of SCXML being a standard is it can executed in another language environment if needed.

However, for documentation purposes it's overkill.

Answer 4

A less overkill answer to this is to use PlantUML or MermaidJS to create and document your state diagram.

It's higher level than dot so it's more expressive.

For TypeScript projects, I use TypeDoc with mermaid plugin to embed mermaid diagrams.

In my projects depending on the situation, I use PlantUML with VuePress so I have the benefits of writing markdown text but embed PlantUML diagrams.

To embed PlantUML in VuePress, I just added markdown-it-plantuml to the .vuepress/config.js

module.exports = {
  chainMarkdown(config) {
    config
      .plugin("plantuml-wbs")
      .use(require("markdown-it-plantuml"), [
        {
          openMarker: "@startwbs",
          closeMarker: "@endwbs",
          diagramName: "wbs",
          render: (tokens, idx) => {
            const src = tokens[idx].attrs
              .filter(attr => attr[0] === "src")
              .map(attr => attr[1])[0];
            return `<EmbedSvg src="${src}" />`;
          }
        }
      ])
      .end()
      .plugin("plantuml")
      .use(require("markdown-it-plantuml"), [
        {
          render: (tokens, idx) => {
            const src = tokens[idx].attrs
              .filter(attr => attr[0] === "src")
              .map(attr => attr[1])[0];
            return `<EmbedSvg src="${src}" />`;
          }
        }
      ])
      .end();
  },
};