Using draw.io in Jira Cloud

draw.io is a fully featured diagramming tool, with large shape libraries and templates for a wide range of diagrams.

Jira administrators: Before any diagram can be added to a Jira issue, an administrator must install the draw.io app in the Jira Cloud instance. Jump to the administration section below.

Jira users: If you are new to diagramming, learn the layout of the draw.io editor first, and then create a simple flowchart to learn the basics of diagramming.

Draw diagrams and attach them to Jira Cloud issues with the draw.io app

Getting started

With the draw.io app for Jira Cloud, you can embed diagrams in issues in four different ways.

We recommend that you embed a diagram from a Confluence Cloud instance to take advantage of the real-time collaboration tools, data security, customisation, mass import, diagram search and versioning capabilities.

Alternatives:

Any changes you make to an embedded diagram file will automatically update diagrams on any Jira Cloud issues its embedded on.

To store diagram files directly attached to Jira Cloud issues, follow the steps in the sections below.

Attach a new diagram to a Jira Cloud issue

  1. Click on the Actions in the top right of an issue and select _Add draw.io diagram.
    Add a draw.io diagram to a Jira Cloud issue
  2. Create your diagram in the draw.io editor. When you save your diagram, you’ll be prompted to provide a filename.

Your diagram will be added as a file attached to the issue.
Your draw.io diagram file is added as an attachment to the Jira Cloud issue

See the draw.io diagrams on a Jira issue

By default, the draw.io Diagrams section is not displayed in Jira issues to keep them as uncluttered as possible.

  • Click on the draw.io icon directly above the issue description to display the draw.io Diagrams section.
    Display the draw.io diagrams section in your Jira Cloud issue

Tip: draw.io diagram thumbnails in a Jira issue will automatically change colours to match the user’s Jira Cloud theme settings - either dark or light. If you want the diagram to always display on a specific coloured background, set a background colour in the draw.io editor.
Adding a diagram background ensures your diagram looks the same in both Jira's light and dark themes

View a diagram

  • Click on the thumbnail in the draw.io Diagrams section in the Jira issue to open it in the lightbox viewer.
  • Hover over the diagram to see the viewer toolbar.
    • Zoom in and out, print or export the diagram from this toolbar.
    • If the diagram has them, step through diagram pages and select the layers to display.
  • Click on the cross or the tick in the top right to return to the Jira issue.
    View a draw.io diagram attached to a Jira Cloud issue in the lightbox viewer

Edit a diagram attached to a Jira issue

  • Hover over the thumbnail in the draw.io Diagrams section in the Jira issue and click on the pencil icon to edit the diagram.
    Edit the draw.io diagram attached to a Jira Cloud issue

Delete a diagram from a Jira issue

  • Hover over the thumbnail in the draw.io Diagrams section in the Jira issue and click on the trash can icon (delete).
    Delete a draw.io diagram attached to a Jira Cloud issue

Export or print a diagram from a Jira issue

From within the draw.io editor

  1. Select File > Export as and select the format you want to export the diagram as.
  2. Choose the export options that apply. These will depend on what format you export to. For example, exporting to a PNG image:
    Choose the export settings for the PNG image

Learn more about exporting diagrams

From the lightbox viewer

Note: Image files generated from the lightbox viewer do not include the diagram data, unlike if you export to a PNG file from within the draw.io editor.

  1. Click on the diagram attached to the Jira issue to open it in the lightroom viewer.
  2. Use the toolbar to view the diagram page and select the layers you want to include.
    Select which layers to see in the draw.io lightbox viewer toolbar
  3. Click on the Export tool (camera) to generate a PNG image thumbnail, or Print to print the diagram.
  4. Right-click on the generated PNG thumbnail and download it. Left-click on the thumbnail to open the image in a new browser tab.
    Export the draw.io diagram from the lightbox viewer in Jira Cloud

Administration and licensing

Security and Licensing