Rendering diagrams

The engine draws a workflow as a graph of steps, tasks and decisions. You can get the diagram as positioned nodes and edges (JSON, for your own front end) or as an SVG document (for reports and documentation). This page describes both, the layout engine and its settings.

Packages

PackageProvidesRegister with
StellaOps.Workflow.Renderer.ElkSharpThe layout engine ElkSharp: a layered layout that runs in-process, with no external process or runtimeAddWorkflowElkSharpRenderLayout()
StellaOps.Workflow.Renderer.SvgAn SVG renderer of a positioned diagramAddWorkflowSvgRenderer()

The engine compiles a definition into a render graph without these packages; it needs a layout engine to position the graph, and the SVG renderer to draw it.

// `endpoint` and `http` calls (WorkflowEndpointTransport:Services, WorkflowHttpTransport:Targets).
builder.Services.AddWorkflowHttpTransport(builder.Configuration);

// `graphql` calls (WorkflowGraphqlTransport:Targets).
builder.Services.AddWorkflowGraphqlTransport(builder.Configuration);

// Diagrams: the ElkSharp layout engine and the SVG renderer.
builder.Services.AddWorkflowElkSharpRenderLayout();
builder.Services.AddWorkflowSvgRenderer();

WorkflowRendering:LayoutProvider names the layout engine; unset, it is ElkSharp. A name that no registered engine has fails the render.

Diagrams over HTTP

GET /api/workflow/diagrams/{name} returns the positioned diagram of a registered workflow:

curl -s "http://localhost:5090/api/workflow/diagrams/OrderApproval?layoutEffort=Balanced" \
  -H "Authorization: Bearer $TOKEN"
Query parameterEffect
workflowVersionA registered version other than the latest
workflowInstanceIdAdds the instance’s status and runtime status, to show its progress
layoutProviderAnother registered layout engine
layoutEffortDraft, Balanced or Best (the default)
layoutOrderingIterations, layoutPlacementIterationsOverrides of the effort’s iteration counts

The response has the workflow name, version and display name, the layout settings used, the instance status when an instance was named, and the nodes and edges with their positions.

GET /api/workflow/definitions/{id}/render-graph returns the unpositioned render graph of a stored definition.

SVG without a host

A build step, a documentation generator or a test can render a registered workflow outside any HTTP request:

/// <summary>Renders a registered workflow as an SVG diagram, outside any HTTP request.</summary>
public static class DiagramExport
{
    public static async Task<string> RenderSvgAsync(
        IServiceProvider services,
        string workflowName,
        CancellationToken cancellationToken = default)
    {
        // The canonical definition of the registered workflow, compiled into a graph of nodes and edges.
        var definition = services.GetRequiredService<IWorkflowRuntimeDefinitionStore>().GetRequiredDefinition(workflowName);
        var graph = services.GetRequiredService<IWorkflowRenderGraphCompiler>().Compile(definition);

        // The layout engine named by WorkflowRendering:LayoutProvider (ElkSharp when unset).
        var engine = services.GetRequiredService<IWorkflowRenderLayoutEngineResolver>().Resolve();
        var layout = await engine.LayoutAsync(
            graph,
            new WorkflowRenderLayoutRequest
            {
                Direction = WorkflowRenderLayoutDirection.LeftToRight,
                Effort = WorkflowRenderLayoutEffort.Balanced,
            },
            cancellationToken);

        // The SVG renderer adds the licence notice when the host passes none.
        return services.GetRequiredService<IWorkflowRenderSvgRenderer>()
            .RenderSvg(layout, definition.Descriptor.DisplayName, licenceNotice: null);
    }
}

The service collection needs AddWorkflowEngineCoreServices, the layout engine, the SVG renderer and the workflow registration; no store is needed. Tutorial 10 runs it.

Layout settings

SettingDefaultEffect
DirectionLeftToRightLeftToRight or TopToBottom
EffortBestDraft (fastest), Balanced, Best (fewest crossings and bends)
NodeSpacing40Space between nodes of one layer
LayerSpacing60Space between layers
OrderingIterations, PlacementIterationsby effortFiner control of the search

The layout is deterministic: the same definition and settings give the same diagram on every host.

The licence notice in an SVG

Every SVG carries a licence notice along its bottom edge. A host that runs the engine passes the notice of its latest licence evaluation; without one (licenceNotice: null), the renderer writes the notice for an installation without a licence record. Do not remove the notice from published diagrams.

Pitfalls