The Detail Department

You are here: Home / confluence / Using Graphviz in Confluence – A Tutorial

Using Graphviz in Confluence – A Tutorial

by

I have always liked to do flowcharts. Simple flowcharts are good flowcharts – a picture tells a thousand words. I also love Confluence, and love the hierarchical nature of the structure of Confluence – much like a flowchart. Now we combine the two and we have a great way to communicate information. Enter Graphviz and the Graphviz Confluence Plugin.

This is a Tutorial to get you started with using Graphviz in Confluence to produce flowcharts quickly and easily.

Graphviz Features

Graphviz creates simple and flexible flowcharts from text. There is no need to draw boxes and connectors between the boxes, and then try to line everything up nicely. Graphviz takes care of that for you.

Other features are:

  • Boxes (Nodes) and Connectors (Lines) can be many shapes and colours.
  • Lines can link any number of Nodes together.
  • Nodes can link directly to Confluence pages or external URLs.
  • You can create a flowchart of a Space’s Page hierarchy with one line of text.

You can’t control the positioning of Nodes exactly – but the idea is that Graphviz does the positioning automatically so that you only have to worry about and document the Nodes and the relationships between them, so don’t get hung up on the layout too much.

Graphviz is a very powerful application and the documentation is quite overwhelming for a newbie, so I’ve tried to do a straightforward tutorial to get you started.

All of the concepts here except for the page linking between Confluence pages can be done with Graphviz on it’s own. The Confluence plugin just adds the goodness of page linking and displaying the graph inside your page.

Create a simple Flowchart

A Flowchart uses the {flowchart} Macro. The {flowchart} macro must be added to the page inside a Wiki Markup Macro (Insert > Wiki Markup).

This code inside a Wiki Markup box:

{flowchart}
 "Node 1"
 "Node 2"
 "Node 1" -> "Node 2"
 {flowchart}

Produces this flowchart:

Notes

  • Node Names with spaces are enclosed in quotation marks.
  • Node Names without spaces quotation marks are not required.
  • Define the Notes on a separate line, even though this is not entirely necessary (the graph will produce without the “Node 1” and “Node 2” lines above). This just makes it easier for editing and adding colours and links.
  • The relationship is denoted by a hyphen then a greater than sign.

Other Node Options

  • NodeName [label="This is the Label"] – Set the Label of the Node.
  • NodeName [label="This is thenLabel"] – a Multi Line Label.

Add Some Links

Now lets add some links to some existing pages in Confluence.

This code:

{flowchart}
 Documentation [URL="Home" target="_blank"]
 Content [URL="Content"]
 "More Content" [URL="[SPK:Home]"]
 Documentation -> Content
 Documentation -> "More Content"
 {flowchart}

Produces this flowchart, (of course, the links are not available in this blog post, but they will be in Confluence):

Notes

  • Links will break if the page name is changed.
  • Unlike Regular links within Confluence, the Node will not tell you if the page has been removed or renamed and the link no longer works.
  • The target="_blank" attribute inside the URL Parameter will mean the page is opened in a new tab.
  • Add a tooltip to the box with a URL with [tooltip="This is my tooltip"].
  • A wiki markup style link can be placed between the square brackets. See the Links Page in the Confluence documentation.

Add Some Shape

Now we can add some shape to the Nodes.

This code:

{flowchart}
 Start 
 Decision [shape=diamond]
 Start -> Decision
 Decision -> "Choice 1"
 Decision -> "Choice 2"
 {flowchart}

Produces this flowchart:

Notes

Add Some Colour and Notes

Now we can add Colour to the Nodes and Lines.

Examples

  • Node1 -> Node2 [style=dotted,color=red] – make the line between these two Nodes coloured Red and a dotted line.
  • Node 1 -> Node2 [label="A Note on a Line"] – adds a note to the line between two Nodes.
  • Node [shape=box,style=filled,fillcolor=lightblue,color=blue,peripheries=2] – produces a rectangle with a light blue fill colour, a blue border and a double border (peripheries).

This code:

{flowchart}
 Start 
 Decision [shape=diamond]
 Start -> Decision
 node [shape=box,color=blue,style=filled,fillcolor=lightblue]
 edge [color=darkgreen,fontname="sans serif",fontsize=8]
 Decision -> "Choice 1" 
 Decision -> "Choice 2" [label="Best Choice"]
 {flowchart}

Produces this flowchart:

 Notes

  • Both Nodes and Lines can be styled.
  • You can add the Style properties on a separate line and all Nodes and Lines drawn after that will have those properties.
    • node [properties] – for defining the style of the node, or
    • edge [properties] for defining the style of the lines.
  • Other Attributes:
    • fontcolor – the font inside the Node or on the Line.
    • fontsize – the size of the font.
    • fontface – the type of font – eg "helvetica", "times-roman".
    • bgcolor – the background colour of the whole diagram – used at the beginning of the flowchart.
    • labelloc – the location of the label within the Node.
    • labeljust – the justification of the label.

Colour Schemes

Not sure about your ability to choose colours that go with each other? Then use the Colour Schemes feature.

node [colorscheme=accent5]
 "Node 1" [color=1]
 "Node 2" [color=2]
 "Node 1" -> "Node 2"

Layout Your Diagram

There are a few things you can do to change the layout for your whole diagram. Laying out the diagrams is the trickiest part of Graphviz. It is really all about trial and error. Here are some tips I have learned from my first look at Graphviz:

  • Constrain the size of the overall diagram – add size="5,5" as the first line inside the flowchart Macro. Note: The size is in inches, unfortunately.
  • Change the direction the diagram flows in – rankdir=LR – Placed at the top of a diagram, makes the diagram go Left to Right (use BT to for Bottom to Top or RL for Right to Left). Note, this command affects the whole diagram. Different directions are not possible within Subgraphs.
  • Add Comments inside the text. /* This is a Comment */ placed on a separate line or // Another Comment Placed at the end of a line.
  • Try a small section of the graph in new diagram on another page.
  • Add each section into a subgraph and cluster. See the Subgraph and Cluster paragraph in the Graphviz documentation.
  • Then link each subgraph together OR separate the graphs onto each page and then join them together. See example below.
  • Try some of the following tricks when joining two Nodes:
    • constraint=false – makes the positioning of the two nodes more fluid
    • dir=back – use this if there is a line that goes from a lower placed node to a higher placed node.
    • rank=same – align two nodes vertically (or horizontally if using rankdir=LR)
    • minlength=2 – set the minimum length of the line between two nodes as being 2 inches. Graphviz will try to make the diagram as short as possible on the page, so this may help clusters slip below each other on the page.
  • If you are getting stuck there are many helpful examples and tricks in Stack Overflow.

Notes

  • The order the Nodes are defined within the flowchart Macro determines the location of that Node in relation to other Nodes.
  • Start with your diagram from the top, and add the node, then the relationships from that node directly under it.

Example

An example to break up a large document into smaller sections:

{flowchart}
 Back [shape=house,color=gray,style=filled,fillcolor=lightgray] [URL="Back Page"] [tooltip="Back to Main Diagram"]
 subgraph cluster0 {
         Node1
         Back -> Node1 
         Node2
         Node1 -> Node2
         Node3
         Node1 -> Node3
         color=invis
 }
 Forward [shape=invhouse,color=gray,style=filled,fillcolor=lightgray] [URL="Forward Page"] [tooltip="On to Next Diagram"]
 Node3 -> Forward
 {flowchart}

Resulting in this flowchart (Note, URLs don’t point to anywhere):

Editing Tips

The Confluence editor can be a bit finicky and doing graphviz diagrams seems to require a lot of memory on the server. Don’t be afraid if you see a large pink error page. It is usually because of spaces.

  • Check for spaces at the end of the line that is noted in the top line of the error message
  • Check for spaces within the line that is noted
  • Check for missing closing brackets and quotation marks
  • Check for spaces that have crept in in place of tabs

In the above example, I have kept different Node attributes in different square brackets. All of these can be within the same brackets, but I like to keep them separate for quick and easy spotting of each section when editing the diagram.

Conclusion

I hope this has got you started on your path to creating great looking flowcharts in Confluence.

Please get back to me in the comments if I have missed something, or you have anything more to add to help others.

Comments

  1. Nicole (@Schnicka) says

    Flow charts – girl you’re SO retro! I love a good Venn diagram myself 😉

    I have a client who is going to love this plugin, thanks

    (I hope this doesn’t end up in the Spam box)