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
| Package | Provides | Register with |
|---|---|---|
StellaOps.Workflow.Renderer.ElkSharp | The layout engine ElkSharp: a layered layout that runs in-process, with no external process or runtime | AddWorkflowElkSharpRenderLayout() |
StellaOps.Workflow.Renderer.Svg | An SVG renderer of a positioned diagram | AddWorkflowSvgRenderer() |
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 parameter | Effect |
|---|---|
workflowVersion | A registered version other than the latest |
workflowInstanceId | Adds the instance’s status and runtime status, to show its progress |
layoutProvider | Another registered layout engine |
layoutEffort | Draft, Balanced or Best (the default) |
layoutOrderingIterations, layoutPlacementIterations | Overrides 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
| Setting | Default | Effect |
|---|---|---|
Direction | LeftToRight | LeftToRight or TopToBottom |
Effort | Best | Draft (fastest), Balanced, Best (fewest crossings and bends) |
NodeSpacing | 40 | Space between nodes of one layer |
LayerSpacing | 60 | Space between layers |
OrderingIterations, PlacementIterations | by effort | Finer 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
- The default effort. Without
layoutEffort, the route lays out atBest, which can take minutes. Even atDraft, the order approval of Getting started (9 nodes) took about 11 seconds on a development machine. Ask forDraftorBalancedin interactive views, renderBestahead of time, and cache. - No layout engine registered. The diagram route fails; register
AddWorkflowElkSharpRenderLayout. - Rendering on every request. Cache diagrams by workflow name and version; a version never changes.
