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!
4 Answers 4
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
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.
-
Yes I agree that CWL ist not a good choice. Maybe you are right and an informal graph is enough..Karsten W.– Karsten W.2020年09月11日 19:16:46 +00:00Commented Sep 11, 2020 at 19:16
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.
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();
},
};