Visualise your Workflow in Kontent.AI

Kontent.aiCMSContent modelling

Kontent.AI enables the creation of complex editorial workflows, but visualising them can be challenging. Transforming workflows into flow diagrams allows easy comparison with design plans. A LINQPad script can generate a dynamic Mermaid diagram, providing clear visualisation that can be integrated into documentation.

Kontent.AI provides the ability to build workflows that support the editorial process for your content.

While the editor for workflows lets us build something fairly complex, it can be difficult to - at a glance - understand how content can move through the workflow due to the linear layout of the workflow.

In a recent project, I wanted to be able to quickly determine if my workflows match what we had designed in our Miro board, and be able to share and update documentation about the implemented workflow. The best way to do this for me is a simple flow diagram. As Kontent.AIs documentation on workflow says, a drawing prevents gray hairs! I didn't want to have to keep manually updating the flow diagram each time there were some changes made to the workflow.

Building the Solution

To make this simple, I decided to create a program in .NET to create a Mermaid diagram on demand. 

First, create a dictionary to store the steps in. This is just improve the readability of the code when we do lookups.

var workflows = await managementClient.ListWorkflowsAsync();
var workflow = workflows.First();

// Precompute steps in a dictionary for faster lookup
var stepDictionary = workflow.Steps.ToDictionary(s => s.Id, s => s.Codename);

Next, we create a dictionary of the colours in Kontent.AI. Without it, the output is quite bland. As the colour names in Kontent.AI are not just standard CSS colours, and because we also want to change the text colour we use this lookup.

var colorDictionary = new Dictionary<string, (string Fill, string Color)> {
	{ "gray", ("#6F6F6F", "#FFFFFF") },
	{ "red", ("#DB0000", "#FFFFFF")},
	{ "rose", ("#D9006F", "#FFFFFF")},
	{ "lightpurple", ("#DAB8FF", "#000000")},
	{ "darkpurple", ("#AD00FB", "#FFFFFF")},
	{ "darkblue", ("#006CDC", "#FFFFFF")},
	{ "lightblue", ("#B1C5FF", "#000000")},
	{ "skyblue", ("#72D1FF", "#000000")},
	{ "mintgreen", ("#00E293", "#000000")},
	{ "persiangreen", ("#007F51", "#FFFFFF")},
	{ "darkgreen", ("#4B7C00", "#FFFFFF")},
	{ "lightgreen", ("#89DC00", "#000000")},
	{ "yellow", ("#FFB865", "#000000")},
	{ "pink", ("#FE9A9A", "#000000")},
	{ "orange", ("#C54300", "#FFFFFF")},
	{ "brown", ("#996400", "#FFFFFF")},
};

With that in place - using LINQPad's Dump command - we then initialise the Mermaid diagram with flowchart TD to create a top-down flow chart, and then also write out the styles from our colour dictionary. In addition, because Published and Archived don't live in the Steps collection in the workflow, we'll add these manually to the output and create their won relationship. We've also got some methods in here to generate some convenient style names.

"flowchart TD".Dump();
foreach (var key in colorDictionary.Keys)
{
	$"classDef {key} fill:{colorDictionary[key].Fill},color:{colorDictionary[key].Color},stroke:none;".Dump();
}
"published(Published):::persiangreen;".Dump();
"archived(Archived):::gray;".Dump();
"published --> archived".Dump();

The final thing to do is to loop through the steps in the workflow. For each step we create a node with text and a style. For the node name, we just use the workflow step's codename. 

As the order of nodes in Mermaid does not matter, we also go ahead and list out all of the Transition To steps, building links using the codename from the dictionary.

foreach (var step in workflow.Steps)
{
	$"{step.Codename}(\"{step.Name}\"):::{step.Color.ToString().ToLowerInvariant()};".Dump();

	foreach (var transition in step.TransitionsTo)
	{
		string targetCodename = transition.Step.Id == workflow.PublishedStep.Id ? "published"
			: transition.Step.Id == workflow.ArchivedStep.Id ? "archived"
			: stepDictionary.TryGetValue(transition.Step.Id??Guid.Empty, out var nextStepCodename) ? nextStepCodename
			: "unknown"; // Fallback if step ID not found

		$"{step.Codename} --> {targetCodename}".Dump();
	}
}

The output from this I then copy and paste into a viewer for Mermaid diagrams. For example https://mermaid.js.org/ or Notion.

The output of this particular script is a simple flow diagram in Mermaid as follows:

This is 10-15 minutes of effort, but it makes sharing a workflow for documentation much simpler, and makes the workflow easier to digest.