Skip to main content

Excalidraw Diagrams plus Whiteboards — User Guide

What is Excalidraw Diagrams plus Whiteboards?​

Excalidraw Diagrams plus Whiteboards adds a diagram editor to every Jira issue. You can create flowcharts, architecture diagrams, wireframes, ER models, mind maps, and more — all without leaving Jira. Diagrams are saved as attachments on the issue, and a preview is shown directly in the issue panel.

Requirements​

  • A Jira Cloud instance
  • A Jira administrator must install the app from the Atlassian Marketplace
  • To create or edit diagrams, you need the Edit Issues permission on the issue
  • Anyone with view access to the issue can see the diagram preview

Installation​

  1. Go to Jira Settings → Manage apps.
  2. Click Find new apps and search for Excalidraw Diagrams plus Whiteboards.
  3. Click Install and confirm.
  4. The app appears automatically on all issues — no additional setup required.

How to Find the App​

Open any Jira issue and look at the right-side panel. The Excalidraw Diagrams plus Whiteboards panel appears below the issue details.

  • If no diagram exists yet, users with edit permission see a Create Diagram button (with a + icon).
  • If a diagram exists, all users see the SVG preview. Users with edit permission also see an Edit Diagram button (with a pencil icon).

Using the App​

Creating a Diagram​

  1. Open a Jira issue.
  2. In the right-side panel, find the Excalidraw Diagrams plus Whiteboards section.
  3. Click the + (Create Diagram) button.
  4. A full-screen editor opens with a blank canvas.
  5. Draw your diagram using the toolbar — shapes, text, arrows, lines, and freehand drawing are all available.
  6. When finished, click Save Drawing. The editor closes and the diagram preview appears in the panel.

Editing an Existing Diagram​

  1. Open the issue that has a diagram.
  2. Click the pencil Edit Diagram button in the panel.
  3. The full-screen editor opens with the existing diagram loaded.
  4. Make your changes and click Save Drawing.

Cancelling Edits​

To close the editor without saving, click Cancel. Any unsaved changes are discarded.

Using Shape Libraries​

The editor includes 229 bundled shape libraries with icons for AWS, Azure, GCP, UML, networking, and more.

  1. Open the editor.
  2. Open the library panel from the left sidebar.
  3. Click Browse libraries to open the library browser.
  4. In the library browser you can:
    • Search by name or description using the search box
    • Sort by Name, Created date, or Updated date using the sort buttons
    • Preview any library by clicking its thumbnail image
    • Add a library by clicking the blue + button on the right
  5. Once added, the library shapes appear in your library panel and can be dragged onto the canvas.

Generating Diagrams from Mermaid Syntax​

The editor supports Mermaid, a text-based diagram language. This lets you type a definition and get a visual diagram instantly.

  1. Open the editor.
  2. From the toolbar, use the Mermaid diagram tool.
  3. Type or paste your Mermaid definition (e.g., a flowchart or ER diagram).
  4. The diagram is generated and placed on the canvas.
  5. You can then move, resize, and style the generated elements like any other shape.

Tips & Common Workflows​

  • Architecture decisions — Open the relevant epic and sketch the proposed architecture. The diagram stays attached to the issue for the team to reference.
  • Bug reproduction flows — Draw a step-by-step flowchart showing how to reproduce a bug, directly on the bug issue.
  • Wireframe reviews — Sketch a quick wireframe on a story issue so designers and developers can discuss it in context.
  • Reuse libraries — Once you add a shape library in one diagram, it stays available in the editor for that issue. Add the libraries you use most (AWS, UML, etc.) on your first diagram.

Troubleshooting​

The panel shows "No diagram has been added to this issue yet" but I can't see a create button. → You don't have the Edit Issues permission on this issue. Ask a project administrator to grant you permission, or ask someone with access to create the diagram.

The diagram preview doesn't update after saving. → The panel refreshes automatically when the editor closes. Try reloading the issue page. If the preview still doesn't show, check that the attachment excalidraw-diagram.json still exists on the issue (Issue → Attachments).

The editor opens but shows a blank canvas instead of the existing diagram. → The diagram attachment may have been deleted manually. Check the issue's attachments section. If the attachment is missing, the editor will start with a blank canvas.

A library fails to load. → All 229 libraries are bundled with the app and require no internet connection. If a library doesn't load, try closing and reopening the editor. If the issue persists, try removing and re-adding the library from the library browser.

The app shows a license warning. → The app requires an active license. Contact your Jira administrator to subscribe on the Atlassian Marketplace.