Graph from table macro

Description

Converts tables found in the rendered body of the macro into a Graphviz graph. Each row found in a table is converted to a node relationship. The Flowchart macro is used for the rendering, so it must be enabled and working correctly. This macro simplifies use of the Graphviz support by eliminating or significantly reducing the need to know the dot language. Advanced users will still need to consult the Graphviz documentation for the multitude of attributes and settings that are possible. The primary reason of this macro is to allow SQL queries to generate graphs easily.

Overview

The table or tables specified in the body of the macro or created as a result of other macros. Specifically, the SQL for ConfluenceCSV Macro, and the Excel macro can be used to produce the tables.

The columns in the table are interpreted as follows:

  1. Node with label equal to the column. The source of a relationship. This is the only required column.
  2. Node with label equal to the column. The target of a relationship.
  3. Relationship attributes.
  4. Source node attributes.
  5. Target node attributes.
  6. First cluster number. A cluster is a subgraph that contains the source and target nodes for this row.
  7. First cluster attributes.
  8. Second cluster number. The second cluster is a subgraph that contains the first cluster.
  9. Second cluster attributes.

Attributes are defined by Graphviz for nodes, relationships, and subgraphs (clusters). They are specified as comma separated list. Attribute values containing blanks must be surrounded by double quotes. Some commonly used attributes are:

  • label - text to display
  • style - examples: filled, bold, dotted, dashed, invis (for invisible)
  • fillcolor - node fill color
  • fontname - standard font name (enclosed in double quotes if contains a blank)
  • fontsize - standard font size
  • fontcolor - color usually specified as a color name like blue, grey, lightyellow
  • shape - examples: rect, box, circle, ellise, triangle, polygon (together with sides attibutes), diamond, ...
  • sides - number of sides for a polygon shape
  • peripheries - number of node boundaries

Graphviz Resources

Graphviz is a powerful way of describing diagrams of any kind, using just text. Graphviz provides automatic layout of diagrams based on the text. Have a look at the following Graphviz resources.

Parameters

Macro Specific Parameters

ParameterDefaultMacro Browser LabelDescription
showDatafalseShow the rendered dataShows the rendered body data after the graph.
directionTBDirection of graph (rankdir)

Sets the graphviz rankdir parameter

  • TB – top to bottom
  • LR – left to right
node
Node parametersSets the graphviz node parameter. The default node attributes are taken from the default Flowchart macro behavior. By specifying the node parameter, you can override these defaults or add additional default attributes. See the Graphviz Documentation for information on attributes and settings.
edge
Edge parametersSets the graphviz edge parameter. The default edge attributes aretaken from the default Flowchart macro behavior. By specifying the edge parameter, you can override these defaults or add additional default attributes. See the Graphviz Documentation for information on attributes and settings.
replace
Replace variablesA comma separated list of key:value pairs that will be used to convert column values to attributes. If a column value for an attribute column matches one of the keys, the associated value will replace the column value. This makes it easy to associate attributes to column data. If more than one attribute needs to be specified for a key, enclose the value in a single quote so that the comma gets treated as a attribute separator.
tablesallTable ids or numbers to includeComma separated list of table ids and/or table numbers contained within the body of the macro that will be used as the data for the graph.
columns
Column numbers to includeAllows selection of the columns of the table that will be used for the graph. It must be a comma separated list of 1 or more positive integers in any order. The default value of blank represents columns=1,2,3,4,5,6,7,8,9. If the table does not contain the column indicated, it will be ignored. For example, if columns=3,13 then column 3 will be used for the source node and column 13 will be used for the target node of the relationship. All other columns will be ignored.


The following parameters are available with all Graphviz macros:
Macro editor labelDefaultDescriptionMacro parameter
Template

Enables users to pick a pre-configured template and make simple changes as per their requirement. Since 3.2.

  • These templates are available in the macro editor only when the macro body is empty. If the macro body is not empty, the user are unable to see the Templates parameter in the macro editor.
  • Only templates listed in the configuration page for the respective diagram types are available to choose from in the macro editor.
  • This parameter is not available in Graph from tableSpace graph and PlantUML macros.
template
Output typepng

Specifies the output type to be generated by Graphviz. Since 2.1.0.

  • png
  • svg
  • pdf
  • jpg
  • gif
output

Location of <type> source

(Where 'type' includes Graphviz/ UML)


Specifies the source from where the macro reads the data. 

  • blank - Data in the body is used.
  • ^attachment - Data is read from an attachment to the current page. Input the value in the format ^Filename.extension.
  • page^attachment - Data is read from an attachment to the page name provided.
  • space:page^attachment - Data is read from an attachment to the page name provided in the space indicated.
  • #filename- Data is read from the file located in the Confluence home directory/script/filename. Subdirectories can be specified.
  • global page template name - Data is read from a global page template.
  • space:page template name - Data is read from a space template.

Graphviz recognizes the commands only when you nest the commands under "noformat", "wiki-markup", "code", or "code-pro" macros, for the sources mentioned below:

  • global page template name 
  • space:page template name 
script

Show <type> markup code

(Where 'type' includes Graphviz/ UML)

FalseShows the markup code, Graphviz or UML, below the generated graph. Useful for fixing syntax errors or to see the markup that is generated by macro processing or macros like the Space graph macro.showCode
Attachment name

Specify the name of the attachment to use, create or update. Use of attachments is optional but can be useful for linking from other places and to work with the Cache macro to improve display performance.

Examples:

  • graphviz.png — the image is saved as an attachment to the current page.
  • page^graphviz.png — the image is saved as an attachment to the page name provided.
  • Space:page^graphviz.png — the image is saved as an attachment to the page name provided in the space indicated.
attachment
Attachment versionnew

Specifies how the generated graph is persisted as an attachment.

  • new — creates a new version of the attachment.
  • replace — replaces all previous versions of the attachment. To replace an existing attachment, the user must be authorized to remove attachments for the page specified.
  • keep — only saves a new attachment if there is no existing attachment. An existing attachment will not be changed or updated.
attachmentVersion
Attachment comment

Specify the comment on the attachment that is created or updated.

attachmentComment
Attachment versions to keep

Limits the number of attachment versions of a file that is attached to a page. If the maximum number of attachments exceeds the limit, then the oldest version is deleted. Since version 3.2. 

This parameter is only applicable if you select new from the drop-down list under Attachment version in the macro editor.

attachmentLimit

ThumbnailFalse

Used when an attachment is specified, and output is PNG, JPG, or GIF. Renders graph as a thumbnail.

  • In some cases, the image and the thumbnail generated are of the same size. This is because the image is too small and fits the preview screen perfectly.
  • This parameter is not applicable for the Flowchart and Space graph macros.
thumbnail
Render wiki markup macros in bodyFalse

Used to render wiki markup macros found in the body before processing as Graphviz markup. This is useful to run macros from Scripting for Confluence or similar that can produce Graphviz markup as output. Since 3.2.

This parameter is not available in the Graph from table and Space graph macros.

macros
Layoutdot

Specifies which default layout algorithm to use. Since 3.2.

  • dot− filter for drawing directed graphs
  • neato − filter for drawing undirected graphs
  • twopi − filter for radial layouts of graphs
  • circo− filter for a circular layout of graphs
  • fdp− filter for drawing undirected graphs

This parameter is not available in the PlantUML macro.

layout
Profile

Specify a profile to be used with the macro. Administrators set up profiles to connect to other applications such as GitHub or GitLab. Profiles contain a basic set of parameters used to access a remote location such as the type of URL, user credentials, and so on. Some profiles may be restricted. Since 3.4.

  • This parameter is not available in the Graph from table and Space graph macros.
  • Contact your administrator to know more about the profiles used in your instance.
  • If a profile is specified, it is recommended to provide the relative path to the location of the required file to be rendered.
profile

URL to <macro> file

(Where 'macro' includes Graphviz/ Diagraph/ Graph/ PlantUML)


Specifies the URL link to the Graphviz file. Administrators may restrict use. Since 3.2.

  • The URLs are restricted to the whitelisted URLs.
  • This parameter is not available in the Graph from table and Space graph macros.
URL
URL user

Specify the user name to access the specified URL via basic authentication. Since 3.2.

user
URL user password
Specify the user password to access the specified URL via basic authentication. Since 3.2.password
URL connection timeout
Specify the time in milliseconds used to increase the wait time to access the specified URL on slower connections. Since 3.2.timeout
File encoding

Specify the encoding of the file attachment if it is different from the Confluence default (like Windows-1252, UTF-8, MacRoman). Since 3.2.

encoding

For multiple macro sources (i.e. template, attachment, and URL), the order of precedence is URL > attachment > template.

Points to remember about profiles:

  • Only raw URLs must be given in either, the URL field in profiles or the URL to Graphviz/Diagraph/Graph/PlantUML file field, in the macros. A raw URL is defined as the part of the URL following the domain information and includes the query string, if present. For example, in the URL string http://www.contoso.com/articles/recent.aspx, the raw URL is /articles/recent.aspx.
  • It is recommended to specify absolute URLs to access files from public locations and to use profiles to access files from private sources. For example, a raw URL that can access a Graphviz file in a public Bitbucket repository is valid. But to render a file located in a private repository, we recommend using a profile.
  • Profiles are a means to access and retrieve contents from external applications such as Bitbucket, GitLab or GitHub. A profile already contains the base URL and the required credentials (user credentials or an access token) to access the relevant application.
  • This method allows multiple users to access a profile across pages and instances of the macro.

Other Parameters 

  • ... - All other parameters are passed through to Graphviz for setting any global Graphviz parameter. Some common examples are:
    • ranksep - Separation in inches between nodes.
    • bgcolor - Background color.
    • size - Size specified as width, height in inches. Example: size="3,5".

Usage

Simple

{graph-from-table}
| A | B |
| A | C |
{graph-from-table}

Relationship and node attributes

Note that headings are ignored

{graph-from-table}
|| heading 1 ignored || heading 2 ignored ||
| A node | B node | label="relationship 1", style=dashed | style=normal | fillcolor=lightblue |
| A node | C node |
| A node | D node | style=invis |
{graph-from-table}

Multiple tables and using parameters

{graph-from-table:node=fillcolor=lightblue,fontsize=20|edge=style=bold,color=red| replace=key1:'style=dashed, color=blue', key2:style=invis|ranksep=2.0}
| A node | B node | | shape=polygon,sides=8,peripheries=3 | |
| A node | B node | | style=dashed |
| A node | C node |
| A node | D node | key2 |

Here is a second table
| E | F | key1 |
| F | G | key1 |
{graph-from-table}

Subgraphs - clusters

{graph-from-table:direction=LR|ranksep=1.5|node=fillcolor=lightblue,fontsize=20| edge=style=bold,color=red|replace=key1:style=dashed}
| A node | B node | label="r1" | | | 100 | key1 |
| F | G | key1 | | | 100 | label="cluster 100" |
| X | Y | key1 | | | 200 | label="cluster 200" | 2000 | label="cluster 2000" |
{graph-from-table}

Using SQL

{graph-from-table:direction=LR|edge=color=blue|displayData=true}

{sql:dataSource=ConfluenceDS}
select PARENTID, TITLE from CONTENT where PARENTID is not NULL
{sql}

{graph-from-table} 

Screenshots