1

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!

3

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.

enter image description here https://graphviz.org/Gallery/directed/fsm.html

1

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.

1
  • Yes I agree that CWL ist not a good choice. Maybe you are right and an informal graph is enough.. – Karsten W. Sep 11 '20 at 19:16
1

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.

1

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();
  },
};

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.