Visualizations

Workflows4s provides several visualization modes for representing workflows: BPMN, Mermaid Flowchart, and Debug Renderer. Each mode has its strengths and use cases. Most options are considered experimental, and they are subject to change.

Visualization Modes Overview

Mode	Description	Good For	Limitations
BPMN	Leverages the Business Process Model and Notation (BPMN) standard, widely recognized in workflow and process modeling domains. Requires the workflows4s-bpmn module for conversion and rendering.	Standardized format for workflow representation Integration into BPMN-compatible tools	Basic auto-layout capabilities Weaker integration ecosystem compared to modern alternatives Additional dependency required: workflows4s-bpmn Rendering as image requires 3rd-party, community-provided tool
Mermaid Flowchart	Renders workflows as Mermaid flowcharts using built-in support in workflows4s-core. Provides more flexibility, relies on custom workflow representation.	Better support within tools like GitLab, Markdown, and documentation platforms Good auto-layout support Rendering as image through official mermaid-cli Can visualize both workflow definitions and execution progress	Non-standardized format
Debug Renderer	Renders workflows as a hierarchical text representation using built-in support in workflows4s-core. Provides most important information about executed steps and minimal information about future ones.	Debugging workflow execution Understanding workflow state during development Logging workflow progress	Text-only format, not graphical Primarily for development and debugging, not for end-user visualization

---

Usage Examples

BPMN

"org.business4s" %% "workflows4s-bpmn" % "0.4.0"

val wio: WIO[?, ?, ?, ?] = PullRequestWorkflow.workflow
val bpmnModel            = BpmnRenderer.renderWorkflow(wio.toProgress.toModel, "process")
val bpmnXml              = Bpmn.convertToString(bpmnModel)

Mermaid Flowchart

Visualizing Workflow Definition

val wio: WIO[?, ?, ?, ?] = PullRequestWorkflow.workflow
val mermaidString        = MermaidRenderer.renderWorkflow(wio.toProgress)

Visualizing Workflow Progress

You can also visualize the progress of a workflow instance:

val instance: WorkflowInstance[cats.Id, ?] = ???
val mermaidString                          = MermaidRenderer.renderWorkflow(instance.getProgress)

Debug Renderer

The Debug Renderer provides a hierarchical text representation of workflows, which is useful for debugging and understanding workflow state during development. It's optimized for brevity and hides non-critical details.

Visualizing Workflow Definition

val wio: WIO[?, ?, ?, ?] = PullRequestWorkflow.workflow
val debugString          = DebugRenderer.getCurrentStateDescription(wio.toProgress)

[HandleError](no-name) 
  - base: [Sequence](no-name) 
    - step 0: [HandleSignal](Create PR) Signal: Create Request
    - 3 more steps

Visualizing Workflow Progress

You can also visualize the progress of a workflow instance:

val instance: WorkflowInstance[cats.Id, ?] = ???
val debugString                            = DebugRenderer.getCurrentStateDescription(instance.getProgress)

[HandleError](no-name) Executed: Closed(Checked(some-sha,<Some tests results>),ReviewRejected)