Keeping draw.io diagrams editable in Azure DevOps work items
A diagram pasted into a work item as a screenshot goes stale the first time the design changes. The editable file is on someone’s laptop, so the next person either redraws it or leaves it out of date. Here are the options I know of for keeping diagrams editable in Azure DevOps, from no tooling at all to an extension.
Get Contextra Labs’s stories in your inbox
Join Medium for free to get updates from this writer.
Disclosure: I’m with Contextra Labs, and the last option is our extension. There are other draw.io extensions on the Visual Studio Marketplace too. This story was written with the assistance of an AI writing program.
1. Attach the source file to the work item
Export a PNG from draw.io (or diagrams.net), paste it into the Description, and attach the .drawio file to the same work item. There’s nothing to install, and the source stays with the work item. The cost comes with every edit: download the file, change it in draw.io, export a new PNG, and upload both again. Over time the picture and the attachment drift apart.
2. Keep diagrams in the repo as editable images
draw.io can save a diagram as .drawio.svg or .drawio.png. These are normal image files that also carry the diagram inside them, so draw.io (the desktop app, diagrams.net or the draw.io extension for VS Code) can open them for editing again. Commit them next to the code they describe and link to them from the work item. Diagram changes then go through the same branches and pull requests as the code.
3. Text diagrams with Mermaid
The Azure DevOps wiki renders Mermaid diagrams written between “::: mermaid” and “:::”. They’re plain text, so they diff cleanly and anyone can edit them. The trade-offs: they live in the wiki rather than on the work item, and you give up most control over the layout.
4. A draw.io editor in the work item form
This is the one we built: draw.io Integration with Repo (Files, PRs) and WorkItems, on the Visual Studio Marketplace.
- An organization admin installs it from the Marketplace. Other users can request it there.
- Open any work item, of any type, and find the Diagrams section on the form.
- Draw or edit there. The diagram is saved to the work item automatically, so the next person edits the same diagram rather than a copy.
It also helps with option 2:
- In Repos > Files, the context menu of a .drawio, .drawio.svg or .drawio.png file has “View in Draw.io”, which opens a read-only viewer.
- In a pull request, the “…” menu has “View Draw.io Diagrams”, which shows every draw.io file changed in the PR as a side-by-side diff.
Good to know:
- The diagrams are stored in your work items. Uninstalling it doesn’t delete them.
- It works with Azure DevOps Services and Azure DevOps Server. The editor itself loads from diagrams.net, so browsers need access to it, which is worth checking on a locked-down Server network.
- You edit diagrams in work items only. In Repos and pull requests it’s view and compare. It doesn’t add diagrams to the wiki.
- There’s a 30-day free trial with no credit card. After that it’s priced per organization, and free for up to 10 active users (ask us for the free license token).
Get it here: https://marketplace.visualstudio.com/items?itemName=Contextra-Labs.contextra-draw-app
Which one to pick
- A diagram or two that rarely changes: attaching the file is fine.
- Diagrams that describe the code: keep them in the repo and review them with the code.
- Simple flows anyone should be able to edit: Mermaid in the wiki.
- Diagrams that belong to a work item and get edited by several people: an editor in the work item form.
Originally published on LinkedIn: https://www.linkedin.com/pulse/keeping-drawio-diagrams-editable-azure-devops-work-items-bf1gf/
