---
title: "Managing diagram configurations"
slug: "managing-diagram-configurations"
updated: 2026-10-29T11:13:41Z
published: 2026-10-29T11:13:41Z
canonical: "docs.turbo360.com/managing-diagram-configurations"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turbo360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing diagram configurations

## Overview

Diagram configurations define how Azure Documenter generates auto-diagrams for the Azure resources in a document group. Each configuration specifies the diagram type, the subscriptions and scope to draw from, an optional schedule, and notification channels. Configurations are created through the **New diagram** wizard and managed from the Diagrams tab of the document group.

Clicking a diagram name opens the interactive canvas directly, where you can inspect resources, filter the view, compare versions, and export the diagram.

### Business value

Diagram configurations give your team automatically generated, up-to-date visual maps of your Azure infrastructure without switching to the Azure portal or maintaining diagrams manually. Scheduled configurations keep diagrams current as your environment changes. Generation history tracks every run with notification delivery status per channel, giving you full visibility into what was generated and when.

## Prerequisites

### Required permissions

Diagrams access is controlled by the **Diagrams** feature permission in your role configuration.

| Role | Access |
| --- | --- |
| Account Owner, Owner, Contributor | Full access: create, edit, generate, view canvas, view generation history, delete diagram configurations |
| Custom role: Diagrams Read | View existing diagram configurations, open the canvas, download diagrams |
| Custom role: Diagrams Manage | Full access: create, edit, generate, view canvas, view generation history, delete diagram configurations |

Custom role users without Diagrams access cannot open the Diagrams tab.

### Dependencies

A service principal with Reader access to the target Azure subscriptions is required before you can create a diagram configuration. See [Managing service principals](https://docs.turbo360.com/docs/service-principal-setup-2).

## How it works

Each diagram configuration is created through the **New diagram** wizard and saved to the Diagrams tab of the document group. A configuration stores everything needed to generate a diagram: the diagram name, type, Azure subscription scope, optional schedule, and notification channels. Once saved, a configuration can be generated on demand, edited, or deleted from the Diagrams tab.

**Diagram types.** Three diagram types are available, each suited to a different use case:

- **Network:** maps virtual network topology including VNets, subnets, NICs, VMs, NSGs, and public IPs. Use this for network architecture reviews, incident response, and infrastructure documentation.
- **Workload:** maps an application stack per resource group, including App Services, SQL databases, and Storage. Use this to document application-level dependencies and workload architecture.
- **Resource visualizer:** generates an ARG-query-based dependency map across subscriptions, including external dependencies. Use this for a broad, cross-subscription view of how resources connect, with optional enrichment from App Insights, Log Analytics, App settings, and external dependency data.

**Generation pipeline.** Each run consumes one document license. When a diagram is generated, Azure Documenter queries Azure using the configured service principal and subscriptions, builds the diagram, and delivers notifications to configured channels. The completed diagram is stored as a versioned snapshot accessible from the canvas.

**Schedule column.** The Diagrams tab list shows the schedule for each configuration. Configurations without a schedule show **Manual**. Scheduled configurations show the frequency and the next scheduled run datetime, for example "Weekly / Next run 14/09/2026 02:00:00".

**Version history.** Every generation creates a new version. You can switch between versions using the version picker on the canvas to compare how your infrastructure has changed over time.

**Interactive canvas.** Opening a diagram configuration launches the canvas, which shows the generated diagram with tools for navigating and inspecting it. The canvas supports:

- **Group by:** change how resources are clustered, for example by VNet or subnet
- **Fit / Focus:** zoom to fit the full diagram or focus on a selected node
- **Show isolated:** toggle visibility of resources with no connections
- **Search:** find specific resources by name
- **Filters:** narrow the view by Resource Types, Subscriptions, or Resource groups
- **Connection view:** switch between Direct connections, All connected, External dependencies, or Show all
- **Node inspection:** click any node to see its resource type, resource group, location, SKU, subscription, and full resource ID, with an option to open the resource directly in the Azure portal or copy the resource ID
- **Export:** download the diagram as draw.io, PNG, or SVG

## Steps

The following operations are available from the Diagrams tab of a document group. Navigate to the document group in Azure Documenter and select the **Diagrams** tab to get started.

### Create a diagram configuration

Creating a configuration saves the diagram type, subscription scope, schedule, and notification settings that Azure Documenter reuses each time the diagram is generated.

1. Select **+ New diagram**.
2. Complete the **New diagram** wizard:
  - **Basics:** enter a Name (required) and optional Description. Under **Diagram type**, select **Network**, **Workload**, or **Resource visualizer**.
  - **Azure scope & filters:** select the subscriptions to include. Each subscription listed belongs to a service principal already configured in Azure Documenter. Select **+ Add service principal** to add a new one if the required subscriptions are not listed. For the **Resource visualizer** type, select a **Resource Graph query** template to define which Azure resources the diagram covers. Four preset templates are available:

All four templates expose the same query editor below the selector, so you can refine any preset before proceeding. A **Custom** option does not appear when creating a new configuration. It becomes available as a fifth option in the Resource Graph query selector only after you modify a preset query and save the configuration. When you return to edit the configuration later, the saved query appears under **Custom**.

After selecting or editing a template, configure **Runtime link enrichment** options as needed (App Insights dependencies, Log Analytics, App settings / connection strings, Include external dependencies). Select **Test query** to validate the query and confirm the resource count before proceeding.
    - **Complete architecture:** returns all resources across the selected subscriptions. Use this for a full-coverage infrastructure map with no resource type filtering.
    - **Infrastructure / IaaS:** focuses on classic infrastructure resources: virtual machines, disks, NICs, network security groups, and related compute and storage components. Use this when your documentation scope is traditional IaaS workloads.
    - **Container / AKS:** returns all AKS managed clusters and all resources deployed into the associated node resource groups. Use this when your environment is primarily Kubernetes-based.
    - **Per-resource-group:** scopes the query to individual resource groups rather than the full subscription. Use this to generate a focused view of a single workload or team boundary without cross-group noise.
  - **Schedule:** optionally enable a recurring schedule. Each run consumes one document license, so frequent schedules spend the monthly allowance faster. Set the Frequency (Weekly or Monthly), days, and time. Select **+ Add schedule** to add multiple schedules, for example one weekly and one monthly.
  - **Notifications:** optionally enable **Download diagram from notifications (open link)** to include a draw.io file download link in notifications. Enter a Recipient email address and select an Email template. Under **Configure notification channels**, select any additional channels to notify when a generation completes.
  - **Review:** confirm all settings, then select **Generate** to save the configuration and generate the diagram immediately.

### Download the latest diagram

The download icon on the Diagrams tab list lets you download the most recently generated version of a diagram as a draw.io file, without opening the canvas.

1. On the Diagrams tab, locate the diagram configuration you want to download.
2. Select the download icon in the **Last generation** column.

The latest generated version downloads as a draw.io file. To download a specific historical version, use the download icon in the Generation history dialog instead.

### Open and navigate the canvas

Opening a diagram configuration launches the interactive canvas where you can inspect resources and navigate the generated diagram.

1. On the Diagrams tab, select the diagram name to open the canvas.
2. If no generation has run yet, the canvas displays a prompt to generate a new version. Select **Generate now** to run the first generation.
3. Use the toolbar controls to navigate:
  - Select **Group by** to change the clustering of resources.
  - Select **Fit** to zoom to the full diagram, or **Focus** to zoom to a selected node.
  - Toggle **Show isolated** to show or hide resources with no connections.
4. Use the **Search resources** field and the **Resource Types**, **Subscriptions**, and **Resource groups** filters to narrow the visible resources.
5. Use the connection view tabs at the top right (**Direct connections**, **All connected**, **External dependencies**, **Show all**) to change which connections are displayed.
6. Click any node on the canvas to inspect its details in the right panel, including resource type, resource group, location, SKU, subscription, and resource ID. Select **Open in Azure portal** to navigate directly to the resource, or **Copy resource ID** to copy it to the clipboard.
7. Select the **Latest version** dropdown to open the version history picker and switch to a previous generation snapshot.
8. Select **Export** to download the diagram as **Download draw.io**, **Download PNG**, or **Download SVG**.

### Generate a diagram now

Generating on demand produces an updated diagram immediately using the current state of your Azure subscriptions.

1. On the Diagrams tab, select the **Actions** menu (**...**) next to the diagram configuration.
2. Select **Generate now**.
3. Review the configuration summary shown in the dialog, then select **Generate**.

Azure Documenter begins generation. When complete, the new version appears in the canvas version history.

### Edit a diagram configuration

Editing lets you update any setting on an existing configuration, including the diagram type, without recreating it.

1. On the Diagrams tab, select the **Actions** menu next to the configuration you want to edit.
2. Select **Edit**.
3. Update any settings across the wizard steps: name, description, diagram type, subscriptions, scope filters, schedule, or notification channels.
4. Select **Save changes** on the Review step.

### View generation history

Generation history shows every generation run for a configuration, with status and notification delivery details per channel.

1. On the Diagrams tab, select the **Actions** menu next to the configuration.
2. Select **Generation history**.
3. The Generation history dialog lists each run with its timestamp, status (Success or failure), and a **View details** link.
4. Select **View details** on a run to see notification details: the configured recipients and diagram link option, and the transmission result per channel including whether the notification was transmitted, the timestamp, and any exception or issue reported.
5. Select the download icon next to a run to download that specific version of the diagram as a draw.io file.

### Delete a diagram configuration

Deleting a configuration permanently removes it and all its settings. Previously generated versions are not recoverable after deletion.

1. On the Diagrams tab, select the **Actions** menu next to the configuration you want to delete.
2. Select **Delete**.
3. Confirm the deletion.

## Permission behavior

Users assigned Account Owner, Owner, or Contributor have full access to all diagram configuration operations by default.

Users on a custom role require the Diagrams feature permission. Read permission allows viewing existing configurations, opening the canvas, and downloading diagrams. Manage permission adds the ability to create, edit, generate, and delete configurations.

Custom role users without Diagrams permission cannot open the Diagrams tab.

## Example scenario

A platform team maintains documentation for their production Azure environment. They create a Resource visualizer diagram configuration scoped to five production subscriptions, using the Complete architecture ARG query template with App Insights dependencies and Log Analytics enrichment enabled. They set a weekly schedule every Monday at 02:00 and configure Teams and email notifications so the team is alerted when the new version is ready.

Each Monday, Azure Documenter generates an updated diagram. The Schedule column shows the next scheduled run datetime so the team always knows when to expect the next version. A team member opens the canvas, uses the Subscriptions filter to focus on a single subscription, and clicks a Kubernetes Service node to inspect its resource details and open it directly in the Azure portal. When a resource shows unexpected external dependencies, they switch to the External dependencies connection view to investigate. They export the diagram as PNG to share in a team review, and download the draw.io file directly from the list for a colleague who wants to edit it offline.

## Limitations

- Each diagram generation consumes one document license. Frequent schedules spend the monthly allowance faster.
- The download icon on the Diagrams tab list downloads the latest generated version as draw.io only. To download PNG or SVG, open the canvas and use the Export menu.
- The Resource visualizer type requires a valid ARG query. Use **Test query** to verify the query returns results before saving the configuration.
- Notification channel delivery failures are recorded in generation history and do not prevent the diagram from being generated.
- Version history retains all previous generation snapshots. There is no automatic pruning of old versions.

## Troubleshooting

1. **Subscriptions do not appear in the Azure scope & filters step** Cause: no service principal is configured in Azure Documenter, or the configured service principal does not have access to the required subscriptions. Fix: verify that a service principal is configured and has Reader access to the target subscriptions. Select **+ Add service principal** to add one if needed. See [Managing service principals](https://docs.turbo360.com/docs/service-principal-setup-2).
2. **Resource visualizer query returns no resources** Cause: the selected subscriptions have no resources matching the ARG query template, or the service principal lacks Reader access to those subscriptions. Fix: select **Test query** on the Azure scope & filters step to confirm the query returns resources. Verify the service principal has Reader access on all selected subscriptions.
3. **Generation fails or shows an error in generation history** Cause: the service principal has lost access to one or more selected subscriptions, or the subscription scope has changed since the configuration was saved. Fix: open the configuration for editing, navigate to the Azure scope & filters step, and verify the subscriptions and service principal. Re-save and regenerate.
4. **Notification channel does not receive the generation alert** Cause: the notification channel is misconfigured, or the recipient email address is missing. Fix: open the configuration for editing, navigate to the Notifications step, and verify the recipient email address and channel configuration. Check generation history under View details for the specific transmission error.
5. **Canvas shows no resources after opening a diagram** Cause: the diagram has not been generated yet, or you opened an older version that has no interactive view. Fix: if no generation has run, select **Generate now** directly from the canvas prompt to create the first version. If you opened an older version from the version history picker and the canvas displays a message that the version has no interactive view, select **Load latest version** to switch to the most recent interactive snapshot. If the latest version also shows no resources, toggle **Show isolated** to on and check the Subscriptions and Resource Types filters to confirm the expected resources are in scope.

## FAQs

1. **Can I add multiple schedules to a single diagram configuration?** Yes. In the Schedule step, select **+ Add schedule** to add more than one recurring schedule. For example, you can configure a weekly schedule for operational reviews and a monthly schedule for reporting, each with different days and times.
2. **Can I use the same service principal in multiple diagram configurations?** Yes. A service principal can be selected across multiple configurations. This is useful when several diagrams cover overlapping subscription scopes that the same service principal can access.
3. **What is the difference between the Network, Workload, and Resource visualizer diagram types?** Network maps VNet topology including subnets, NICs, VMs, NSGs, and public IPs. Workload maps application stacks per resource group including App Services, SQL, and Storage. Resource visualizer uses an ARG query to generate a cross-subscription dependency map with optional external dependency enrichment.
4. **Can I change the diagram type of an existing configuration?** Yes. The diagram type can be changed when editing an existing configuration. Open the **Actions** menu next to the configuration, select **Edit**, and update the diagram type in the Basics step.
5. **What export formats are available for a generated diagram?** The download icon on the Diagrams tab list downloads the latest version as draw.io only. From the canvas Export menu, you can download draw.io, PNG, or SVG. Specific historical versions can be downloaded as draw.io from the Generation history dialog.

## Related articles

- [Managing service principals](https://docs.turbo360.com/docs/service-principal-setup-2)
- [Managing document groups](https://docs.turbo360.com/docs/managing-document-groups)
- [Managing document configurations](https://docs.turbo360.com/docs/managing-document-configurations)
- [Diagrams](https://docs.turbo360.com/docs/diagrams)