---
title: "Keep documented network diagrams"
description: "Keep a client's network diagrams in Outpost with revisions, let Outpost check them against the live network, review proposed updates, and share them."
url: "https://support.outpostplatform.com/network-maps/documented-diagrams/"
product: "depot"
type: "how-to"
status: "draft"
ai_summary: "Documented network diagrams in Outpost: create one from the live map (L1, L2, or L3 for a site), a .drawio or .vsdx upload, a blank page, or a Pioneer AI drawing. Revisions with restore, live values, a drift score checked every 6 hours and after each save, proposals to accept or reject, a drift alert threshold, Visible to client, and delete. Needs network_map:edit."
availability:
  plans: ["home-lab", "essentials", "enterprise", "msp"]
  permission: "network_map:edit"
  preview: false
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/network-maps/documented-diagrams.md"
license: "CC BY 4.0"
---

# Keep documented network diagrams

A documented diagram is a network drawing that Outpost keeps for a client,
with every saved version, and checks against the live network. When the
network changes, Outpost proposes the edits that would bring the drawing up
to date, and can raise an alert when the drawing falls too far behind. Use
documented diagrams for the drawings you hand to a client, an auditor, or the
next technician, so they stay correct without anyone redrawing them.

Documented diagrams are on the **Diagrams** tab of **Endpoints** > **Network
map**, with [racks](/network-maps/racks/).

## Before you begin

- Viewing diagrams needs `discovery:read`. Creating, editing, and deleting
  them, and deciding proposals, needs `network_map:edit`.
- Network discovery must be on for the client to make a diagram from the live
  map or to check one. See [Network discovery](/endpoints/network-discovery/).
- Deleting a diagram deletes every revision and its proposals, and cannot be
  undone. Files you already exported are not affected.

## Create a diagram

1. On **Endpoints** > **Network map**, select the **Diagrams** tab.
2. Under **Diagrams**, select **New diagram**.
3. Under **Start from**, choose one:

   | Choice | Use it when |
   | --- | --- |
   | **The live map, laid out by Outpost** | You want a drawing of the network as it is now. Choose the **View**: **Physical (L1): cables and ports**, **Switching (L2): VLANs and trunks**, or **Routing (L3): subnets and gateways**, and the **Site** to draw. |
   | **A .drawio or .vsdx file from this computer** | You already have a drawing. Choose it under **Diagram file**, up to 10 MB. |
   | **A blank page** | You want to draw from scratch in the [diagram editor](/network-maps/diagram-editor/). |

4. Enter a **Title**, up to 200 characters. For an upload, an empty title uses
   the file name.
5. Optional: choose a **Site** to file the diagram under.
6. Select **Make the diagram**.

The diagram opens on its own page as revision 1.

How each source becomes a diagram:

- **From the live map**, every device and link on the drawing is linked to the
  device or link it stands for. Outpost checks linked shapes first and most
  reliably.
- **A .drawio file** is kept as it is, with your layout. A file Outpost
  exported keeps its links to devices. Other shapes are matched to devices by
  name, IP address, and MAC address.
- **A .vsdx file** is read for its devices, links, and groups, and redrawn by
  Outpost's own layout as a .drawio drawing. The Visio file's own positions
  and styling are not kept. To keep a Visio layout, open the file in draw.io
  first, save it as .drawio, and upload that.

You can also save a drawing Pioneer AI made as a documented diagram. See
[Network maps with Pioneer AI and MCP](/network-maps/pioneer-and-mcp/).

## Edit and save a revision

Every save makes a new revision. Nothing is overwritten.

1. Open the diagram and select **Open in editor**.
2. Optional: before opening, select **Show live values** to open the drawing
   with today's status, addresses, VLANs, and ports on linked devices and
   links. The layout and styles are not changed. Saving keeps those values.
3. Optional: enter a **Note for the next save**, up to 500 characters. It is
   shown in the revision list.
4. Make your changes and select **Save** in the editor's bar. See
   [Edit a diagram in the diagram editor](/network-maps/diagram-editor/).

The page says **Saved as revision** and the number. If the drawing is the same
as the current revision, it says **Nothing changed since revision** and the
number, and writes no revision.

### Restore an earlier revision

1. Under **Revisions**, find the revision. Each shows a picture, its author,
   date, and note.
2. Select **Restore**, then **Restore** again to confirm.

Restoring copies the old revision forward as a new one, so the revisions in
between are kept.

## Review proposed changes

Outpost compares each diagram with the live network every 6 hours, and after
each save. What it finds becomes proposals under **Proposals** on the
diagram's page:

| Proposal | Means |
| --- | --- |
| **New device** | A firewall, router, switch, access point, server, or other infrastructure device is on the network and not on the diagram. |
| **New link** | A link between infrastructure devices is on the network and not on the diagram. |
| **Device gone** | A linked device has not been seen for 7 days. |
| **Link gone** | A linked link has not been seen for 7 days. |
| **Changed** | A linked device or link has a different IP address, port, VLAN, or media. |

1. Select **Accept** or **Reject** on a proposal. To decide several at once,
   select them, or **Select all**, then **Accept selected** or **Reject
   selected**.
2. Read the result:
   - Accepting draws the changes into the diagram as a new revision, noted
     **Accepted** and the number of changes. A new device is placed beside the
     device it links to, in your [map style](/network-maps/map-styles/).
   - Rejecting keeps the change out of the diagram until the network changes
     again. A rejected proposal is not offered again while the device or link
     stays as it is.

A revision made by accepting proposals has no picture until you open it in the
editor and save it.

## Watch the drift score

The **Drift** card shows how much of the diagram still matches the network,
such as **92% matches**, and when Outpost last checked. The **Matches the
network** column on the **Diagrams** tab shows the same score for every
diagram. **Not checked yet** means Outpost has not compared it yet.

The score is the share of devices and links that match, out of everything
matched, missing from the network, new on the network, or moved.

To be alerted when a diagram falls behind:

1. On the diagram's page, in **Alert below**, enter a score from 0 to 100.
2. Select **Save threshold**.

When the score falls below it, Outpost raises a warning alert, **Network
diagram out of date:** followed by the diagram's title, in the **Network
discovery** category. It resolves on its own when the score recovers, when you
select **Clear** to remove the threshold, or when the diagram is deleted. See
[Alerts](/service-desk/alerts/).

## Share a diagram with the client

On the MSP plan, you can let the client's own console users see a diagram.

1. On the diagram's page, under **Details**, turn on **Visible to client**.

They see only the current revision and its drift score. They never see
earlier revisions or proposals, and they cannot change the diagram. Diagrams
are hidden from them until you turn this on. The **Client can see** column on
the **Diagrams** tab shows which diagrams are shared.

## Rename, move, or delete a diagram

- **Rename or move it.** Under **Details**, change the **Title** or the
  **Site**, then select **Save**.
- **Delete it.** Under **Delete**, select **Delete diagram**, then confirm.

## Verify

On the **Diagrams** tab, the diagram is listed with its **View**, **Site**,
**Revision**, and a score under **Matches the network** within 6 hours of
creating it.

## If something goes wrong

| Symptom | Cause | Fix |
| --- | --- | --- |
| **No picture of this revision** | The revision is an uploaded .drawio file, or was written by accepting proposals. Outpost keeps a picture only of drawings it draws itself or you save from the editor. | Open it in the editor and select **Save**. |
| **The file is not a .drawio or .vsdx diagram Outpost can read.** | The upload is another format, or damaged. | Open it in draw.io or Visio and save it again as .drawio or .vsdx. |
| **The diagram is too large: at most 5,000 shapes and 10 MB uncompressed.** | The file is past the size limit. | Split it into several diagrams. |
| **The Visio diagram is too large to draw: at most 2,000 devices.** | A .vsdx file is redrawn by Outpost, which draws up to 2,000 devices. | Split it, or convert it to .drawio in draw.io and upload that. |
| Exporting a revision as PNG, SVG, or PDF fails with "Open it in the editor and save it" | The same. | Open it in the editor and select **Save**, then export again. |
| **This diagram is not here** | It was deleted, or, for a client user, it is not shared. | Check the **Diagrams** tab. |
| An uploaded diagram scores low | Its device names do not match the names Outpost knows. | Accept the proposals, or rename the shapes in the editor to match the devices. |

## Next steps

- [Edit a diagram in the diagram editor](/network-maps/diagram-editor/)
- [Export network maps and diagrams](/network-maps/export/)
- [Record rack elevations](/network-maps/racks/)