I have a need for a product to dynamically create a 'visio' type image of workflows in my site. I remember years ago there was something for plone to do this, but it is no longer supported.
Use Case: From within an app (Plone, MS Word) when a user has a document open, they need to be able to see the workflow to understand where the document is within the overall publishing process. Viewing would likely be done by clicking a button which would call the file created below to display the WF diagram.
What I've done so far: I've hired an xml program to help me define the requirements.
use python xml parser: xml.etree (I understand there are other products, but i think my need is simple enough that xml.etree would work.)
from this, create the format that can be converted into a WF diagram (UML?) via, for example plantuml.com. (Note: plantuml has the advantage of providing a good layout that can be themed and presents well.
2a) Since WFs seldom change, the local xml/uml files can be date stamped and saved on the plone site. only going thru above process if the WF is updated
Neither of us know now if the WF can be saved on plantuml server, or if they have to be recreated each time.
Note: i have a programmer to handle the API connections in Word.
Questions:
From your Plone expertise, is there a better way?
Are there any blockers you can see?
API to external source to create the image (e.g. plantuml.com)?
UML feels too heavy handed to diagram a fintite state graph. I would strongly consider generating dot-files graphviz can use. This is still likely the easiest path to reasonable output without excessive effort.
I made a .dot file for example for plone_workflow in Plone 5.2, and modified a state to have a highlight / fill color, for example given a file plone_workflow.dot:
// dot graph of plone_workflow
digraph "Community Workflow" {
pending [shape=box,label="Pending review (pending)"];
private [shape=box,label="Private (private)"];
published [shape=box,label="Published (published)"];
visible [shape=box, style="filled", fillcolor="yellow", label="Public draft (visible)"];
pending -> private [label="Make private"];
pending -> published [label="Publish"];
pending -> visible [label="Send back, Retract"];
private -> visible [label="Promote to Draft"];
published -> visible [label="Send back, Retract"];
visible -> private [label="Make private"];
visible -> published [label="Publish"];
visible -> pending [label="Submit for publication"];
}
You could just template a dot file and add inject something like style="filled", fillcolor="yellow", to the current state of a content item.
brew install graphviz && dot -Tsvg plone_workflow.dot will make you an SVG file on a macOS machine; likewise would an install of graphviz in any other environment
you could make a Plone view around making this in a subprocess, just keep in mind that might be blocking in weird ways, which likely means...
the path of least resistance is just making a set of .dot files you keep in version control in an add-on, one for each workflow state, and a corresponding png or svg you made to with that, via one-time invocation of dot manually.
I'd go with dot-files, since there is already good tool support. We are using an add-on called rbco.wfdocumentator by @rafaelbco, which is easy to use. It creates dot graphs like this:
Mermaid is another diagramming tool worth considering.
You can render Mermaid diagrams in the browser.
If you write documentation in Markdown or MyST, there is a Sphinx extension that can render Mermaid diagrams.
Personally I avoid .docx format for writing documentation, but when I need to convert documentation to that format, I generate a single-page HTML then use pandoc to convert the result to .docx.
