Support and setup guide

Need help? Email support@definitivediagrams.com. We reply within one business day.

Confluence

1. Attach the file

Drag your .vsdx, .bpmn, .mmd or .puml file onto the page while editing, or add it under ••• → Attachments. It must be attached to the same page (or blog post) as the diagram. For Mermaid or PlantUML you can skip this step and type the code into the macro instead.

2. Add the diagram

In the editor, type /Definitive Diagrams and press Enter. In the dialog:

• under Attached file, pick the file from the page's diagram attachments, or under Diagram code, choose Mermaid or PlantUML and paste the code;
• choose a Height: Compact (300 px), Standard (500 px), Tall (800 px), or Whole diagram, no limit.

Save and publish. To change the file or height later, select the diagram in the editor and click the pencil icon.

3. Read it

• Pages: each Visio page gets a tab. Background pages are listed last. PlantUML files with several diagrams, and BPMN files with several processes, get a tab for each too.
• Zoom: use + and −, or hold Ctrl and scroll. Drag to pan when zoomed in.
• Full screen: the corner-arrows button opens the diagram full screen.
• Layers: the layers button shows or hides the file's Visio layers. Layers hidden in the file start hidden.
• Links: links in the diagram work. Links to other Visio pages switch tabs.

Updating a diagram

Edit the file and upload it again with the same file name. Confluence keeps it as a new version of the same attachment, and the page shows the new version. For code, select the diagram in the editor, click the pencil icon and change the code.

Copying pages

When you copy a page, Confluence copies its attachments too. The diagram on the copy shows the copy's own file with the same name.

Jira

Attach the diagram file (.vsdx, .bpmn, .mmd or .puml) to the issue. Then choose Apps → Definitive Diagrams at the top of the issue to add the panel. The panel shows the issue's diagram attachments:

• If there are several, pick one from the list. The panel remembers your choice for that issue.
• After you attach a new file, click the refresh button next to the list.
• People see the diagram only if they can see the issue.

Supported files

• Works: .vsdx drawings and .vsdm (macro-enabled) drawings, the format Visio has used since 2013. Macros are never run.
• Save as .vsdx first: older .vsd drawings and .vdx (Visio XML) drawings. Open the file in Visio and choose File → Save As → Visio Drawing (*.vsdx).
• BPMN: .bpmn files (BPMN 2.0 XML) with diagram layout, as saved by Camunda Modeler, bpmn.io and other BPMN 2.0 modellers. Collapsed sub-processes open with a click.
• Mermaid: .mmd or .mermaid files, or code typed into the macro. Diagrams use Mermaid's standard layout; a diagram that asks for the ELK layout is drawn with the standard one.
• PlantUML: .puml, .plantuml, .pu, .iuml or .wsd files, or code typed into the macro. Each @startuml … @enduml block becomes a tab. Built-in themes and icons work; files included from the internet or the C4 library don't.

Large files are fine. Pages load as you open them: a 13 MB, 82-page file shows its first page in three to four seconds, and later views of a page come from your browser's cache.

Troubleshooting

"No diagram files are attached to this page yet"

The dialog lists the Visio, BPMN, Mermaid and PlantUML files attached to this page, and flags old .vsd files that need saving as .vsdx. Attach the file first, then edit the diagram again, or choose Diagram code.

"This Mermaid diagram has an error" or "This PlantUML diagram has an error on line …"

The code has a mistake the engine can't draw. Edit the macro (or the file) and check the line named in the message. Mermaid's and PlantUML's online editors show more detail about the error.

"This file is no longer attached to this page"

The file was deleted or moved. Attach it again and edit the diagram to pick it.

"Could not read this file as a Visio drawing"

The file may be damaged, or it may not be a Visio drawing despite its name. Open it in Visio, save it as .vsdx, and upload it again.

"You don't have permission to view this file"

Definitive Diagrams follows Confluence and Jira permissions. Ask the owner of the page or issue for access.

"Atlassian is limiting requests right now"

Atlassian throttles very busy sites for a moment. Wait a minute and use Try again.

Text looks slightly different from Visio

If your computer doesn't have a font the diagram uses, your browser uses a similar one, so text can wrap or shift slightly. Installing the font fixes it.

Data and security

Definitive Diagrams runs entirely on Atlassian's Forge platform. Files go from Atlassian straight to the reader's browser and are drawn there; nothing is sent to us or anyone else. See the privacy policy.