Reading Time: 11 min

Most organizations have a lot of data in spreadsheets. Of course, spreadsheet programs are great at creating charts from purely numerical data. But what if your data isn’t just numbers?

Maybe you are tracking your supply chain in a spreadsheet or a database – that would be ideal as a process diagram. Or perhaps you have staff information that you want to format as an organization chart.

With, you can take your comma delimited data (your CSV file), add some configuration ‘code’ to define how it should be formatted and connected, and create a diagram automatically!

Insert CSV data and create a diagram automatically

In a previous post, you saw how you can import comma-delimited data (such as a CSV file) into a diagram:

  1. Click on Arrange > Insert > Advanced > CSV.
  2. Edit the configuration on the lines starting with a single hash (#) character and specify how your data should be formatted into an actual diagram.
  3. Add the comma delimited data at the bottom of the file.
  4. Click Import, and will automatically build your diagram and arrange it on the drawing area.

The organization chart example above is the sample ‘code’ in the Arrange > Insert > CSV dialog. It can be a bit overwhelming to work out what the configuration code is meant to do when you want to configure how your own data should be displayed. So let’s start with simpler example, and work our way up to something more difficult.

Hello World – a simple CSV flowchart

When you paste the following text into the Insert > CSV dialog, you’ll see a very simple flowchart with five shapes.

## Hello World
# label: %step%
# style: shape=%shape%;fillColor=%fill%;strokeColor=%stroke%;
# namespace: csvimport-
# connect: {"from":"refs", "to":"id", "invert":true, "style":"curved=0;endArrow=blockThin;endFill=1;"}
# width: auto
# height: auto
# padding: 15
# ignore: id,shape,fill,stroke,refs
# nodespacing: 40
# levelspacing: 100
# edgespacing: 40
# layout: auto
## CSV starts under this line
1,Hello World,#dae8fc,#6c8ebf,rectangle,
2,Am I alive?,#fff2cc,#d6b656,rhombus,1

Configuration section at the top

The top (larger) section of the text above the actual CSV data, is the configuration – you need to specify the shape, label and connector styles, how the shapes are connected, and the layout of the diagram. Each line in the configuration must start with a hash (#).

Tip: Lines that start with two hashes (##) are ignored and are perfect for writing explanatory comments.

Stepping through the configuration, the most important definitions are as follows:

  • The label of each shape in this example is an entry in the ‘step’ column, and this variable is indicated by the percentage symbols that surround it: %step%.
  • The style definition includes a shape (specified by the ‘shape’ column in the CSV data), sets the corners of the shape to be rounded, uses a fill and border color defined by the ‘fill’ and ‘stroke’ columns in the CSV data.
  • The connect line in the configuration defines which shapes are connected to the other shapes (from the ‘refs’ column to the ‘id’ column), whether the connector direction is inverted or not, and the style of the connector and the arrows.
  • The node-, level- and edgespacing lines indicate how far apart the shapes (and levels) should be in the diagram.
  • And finally, layout indicates the actual layout of the diagram. This follows the same auto-layout as in Arrange > Layout.

Note: You can break up long style configurations (within curly brackets) with a slash, but make sure the next line – the continuation – starts with a hash (#) character!

The CSV data at the bottom

At the bottom of the example, you’ll see a handful of lines that don’t start with a hash (#). This is the comma delimited (CSV) data. Each row is one shape in your diagram. The first row of the CSV data is the column ‘titles’ – they are used as variable names in the configuration section and are not displayed in your diagram.

Style and formatting options

Shapes, connectors and labels can all have different styles – backgrounds, gradients, rounded corners, dashed borders, arrow styles, different fonts, … There are a huge range of options to style your diagram components in the configuration section above your CSV data. Please refer to the following posts for more information:

Habit Tracker app infrastructure diagram with AWS

A slightly more complex example to illustrate how to use a few more complex shapes, is the infrastructure for a Habit Tracker app that uses Amazon Web Services.

It’s designed to be a very simple serverless web app, using standard AWS components, all of which you can find in the various AWS shape libraries in

There are few extra style settings, such as moving the shape labels underneath the shapes and using a dotted connector with no arrows.

AWS diagram
# label: %component%
# style: shape=%shape%;fillColor=%fill%;strokeColor=%stroke%;verticalLabelPosition=bottom;aspect=fixed;
# namespace: csvimport-
# connect: {"from":"refs", "to":"id", "invert":true, "style": \
#            "curved=0;endArrow=none;endFill=0;dashed=1;strokeColor=#6c8ebf;"}
# width: 80
# height: 80
# ignore: id,shape,fill,stroke,refs
# nodespacing: 40
# levelspacing: 40
# edgespacing: 40
# layout: horizontaltree
## CSV data starts below this line
1,Habit Tracker HTML App,#ffe6cc,#d79b00,,
2,UI Assets,#277116,#ffffff,mxgraph.aws4.s3,1
3,User Authentication,#C7131F,#ffffff,mxgraph.aws4.cognito,1
4,API Gateway,#5A30B5,#ffffff,mxgraph.aws4.api_gateway,1
5,AWS Lambda,#277116,none,mxgraph.aws4.lambda_function,4

What shape name do I use in the CSV?

You can discover the name of any (non-complex) shape in by selecting it, then clicking on Edit Style in the format panel.

In this example, we’ve used shapes from the AWS libraries – they are not the in the basic or advanced shape libraries in For example the shape name of the UI Assets bucket is: mxgraph.aws4.s3

Habit Tracker app use case diagram from CSV data

To make it a little more complex, this next example recreates the Habit Tracker app UML use case diagram from an earlier post. It has three different connector types – one from the users to the actions, and then an includes and an extends relationship between various use cases.

Each of these different connections is represented in the CSV data in its own column, and there are three different styles for each of the connection types.

Note: Because the layout is being automatically worked out by, it will be readable, but not necessarily the most sensible for such a diagram – the User and the Coach actors would be better positioned on either side of the diagram.

Below is the configuration code for the three different connectors, followed by a few lines of the CSV data so you can see how this example was built. For the full code, please open the example diagram in and expand the container shape beneath the use case diagram.

## Habit Tracker UML use case diagram - connector styles
# connect: {"from":"refs", "to":"id", "style":"curved=0;endArrow=blockThin;endFill=1;"}
# connect: {"from":"includes", "to":"id", "label":"includes", "style": \
#             "curved=0;endArrow=blockThin;endFill=1;dashed=1;"}
# connect: {"from":"extends", "to":"id", "label":"extends", "style": \
#            "curved=0;endArrow=blockThin;endFill=1;dashed=1;"}

## Partial CSV data for the Habit Tracker UML use case diagram example
3,Add a habit,#dae8fc,#6c8ebf,ellipse,9,,
6,List habits,#dae8fc,#6c8ebf,ellipse,,,
7,View habit history,#dae8fc,#6c8ebf,ellipse,,8,
10,Add a comment,#dae8fc,#6c8ebf,ellipse,9,5,

A complex example – a supply chain diagram from CSV data

This is a partial supply chain for just one component in a car – the transmission. Cars have hundreds of thousands of parts and hundreds of suppliers of those parts. Many of these companies need to be able to trace the supply chain back to the raw materials supplier for safety (and insurance) reasons. Of course, a full supply chain diagram may not be sensible, but … you could do it with!

In this example, each type of supplier or component in the diagram has a different shape and style, and all of them are defined in the configuration section.

Note: Only the configuration ‘code’ for the different shapes is included below. For the full configuration and CSV data, please open the diagram in, and expand the Configuration & CSV code container shape positioned below the diagram.

## Shapes and their styles
# stylename: shapeType
# styles: {"raw": "shape=parallelogram;fillColor=#f5f5f5;strokeColor=#666666;perimeter=parallelogramPerimeter;", \
# "well": "shape=cylinder;fillColor=#f5f5f5;strokeColor=#666666;", \
# "foundry": "shape=trapezoid;fillColor=#dae8fc;strokeColor=#6c8ebf;perimeter=trapezoidPerimeter;", \
# "manufacturer":"shape=hexagon;fillColor=#d5e8d4;strokeColor=#82b366;perimeter=hexagonPerimeter;", \
# "chemicals":"rounded=0;fillColor=#f8cecc;strokeColor=#b85450", \
# "electronics":"rounded=1;fillColor=#fff2cc;strokeColor=#d6b656", \
# "assembly":"shape=triangle;fillColor=#ffe6cc;strokeColor=#d79b00;perimeter=trianglePerimeter;", \
# "component":"shape=ellipse;fillColor=#ffffff;strokeColor=#000000;perimeter=ellipsePerimeter;"}

By moving the shape colors into the style definition in the configuration section, the CSV becomes a lot cleaner. Here are a few lines from this example:

## Partial CSV data for the Supply Chain example
mb,Mine B,,raw
w1,Well 1,,well
fc,Foundry C,"ma,md",foundry
o1,Oil and Gas 1,w2,raw
man5,Manufacturer 5,ca,manufacturer
ca,Chemicals A,o3,chemicals
eb,Electronics B,cc,electronics
a1,Assembly 1,"3,4,5",assembly
1,gearbox housing,fb,component

More basic examples of CSV data and configuration

We’ve added a number of basic examples of CSV data with detailed explanations in configuration comments for each line – please visit our GitHub repository to see the text files for each of these diagrams.