Diagrams are an easy was to quickly get an understanding of how processes and applications link together. Technical people responsible for creating and updating these artifacts often find these to be time consuming and as such businesses are sometimes left with old and outdated diagrams. One tool which can be helpful in easing the time it takes to maintain and create these diagrams is a python plugin which can be run easily in Visual Studio Code.
Reaching into Visual Studio code and installing plugins can seem daunting, in this blog post I will go through a simple and straight forward example which will cover off a majority of what is needed to create simple and effective diagrams.
Prerequisites
Python 3.6 or higher
Graphviz installed locally (install Graphviz prior to installing diagrams if not already installed)
Before getting started
Before getting started I would recommend writing down what types of nodes will be in the diagram, for example is this an AWS diagram or an on premise networking diagram? The list does not need to be exhaustive as it is very simple to add references to images needed, however, it is simpler to have some referencing setup from the start. Not to mention an idea of the purpose of the diagram.
Let's get started!
Due to my setup I need to reference the Graphviz install location manually this is done by a simple import
The pieces needed from the diagram plug in in this demo are Cluster, Diagram and Edge. Cluster - Cluster allow for groupings of nodes, i.e. a border around object/nodes which belong together
Diagram – This is what allow us to diagram the nodes/objects , this will always be needed
Edge – Edge is a user preference as this allows for naming of the linkages and formatting of those linkages. If no naming is needed and plain black is desired, then no need to import
From the base now the images need to be imported, in this sample Teams, Power BI, Logic Apps and a custom image set will be used.
Note: For a full list of available nodes go to the diagrams website for an up to date list - https://diagrams.mingrammer.com/docs/nodes/onprem
Now that all the base setup has been done the fun can start!
The name of the diagram will appear at the bottom of the image file, in this case “Sample Workflow”. The Show flag determines if the generated file opens automatically when the code is run, the default setting is true. Filename specifies the name of the file generated and the direction specifies the direction of the nodes within the diagram.
Information on direction options:
"TB" (Top to Bottom, the default): This orientation arranges elements from top to bottom, with the main flow of the diagram moving downwards.
"LR" (Left to Right): This orientation arranges elements from left to right, with the main flow of the diagram moving from left to right.
"RL" (Right to Left): This orientation arranges elements from right to left, with the main flow of the diagram moving from right to left.
"BT" (Bottom to Top): This orientation arranges elements from bottom to top, with the main flow of the diagram moving upwards.
The first group of nodes to be added to the diagram are the SQL tables involved in the process. The diagram images do not currently at the time of writing this blog post include a table image. To allow for custom images a folder in the same location as the python file has been created with the name diagram_assets and a PNG with the desired image has been saved in the folder.
To reference this file the custom nodes were added in the previous section and now the specific file can be referenced.
For each customer, Order and Orderitem the label for the node has been set dbo.Customer for the customer node and the image has been referenced. The prefix of Custom declares that a local file should be used.
The tables are wrapped in a cluster by the name “Sample Database”, running the code now will output the below image.
Adding connections and labels requires a map, this map is done by arrows or dashes depending on the connection type. >> and << signify the arrow going either from left to right or right to left - Signifies that no arrow is needed, this is a simple straight-line connector Note: Formatting or connectors will be elaborated on further down in the blog.
The above will output connectors as per the below image, now the diagram shows where there are links and what they are linked by.
Let’s move on to adding a non-clustered node from one of the built-in images. Note: Make sure to move the indent back one step as otherwise this next line will end up within the previous cluster.
Adding the workflow cluster before the connections are added. Here using the images available for Teams and Logic Apps.
With the addition of Teams, Logic Apps and Power BI more annotation is needed. To deal with this lets expand on the Edge formatting. The available options for Edge are:
Label – Free text label which appears on the line
Style – For example bold, dashed, dotted
Color – Standard colours such as red, dark green, blue etc.
Take note of the indentation here, the first line will create a link between items within a cluster the bottom two will create linkages outside the cluster.
Putting all of this together we end up with the below full script
And the output of these lines will create the below image file.
Making changes is simple and committing the python file (or jupyter notebook if you prefer) to source control is easy and simple way to track changes. It is also easy to see that automating parts of the diagramming part of documentation is possible with a little more work.
I hope you found this blog post helpful; I had a lot of fun playing with the plug-in and it has already been very useful. Please fee free to reach out if you have any questions
Comments