Managing document groups

Overview

Document groups organize your Azure subscriptions in Azure Documenter for document generation and diagrams. A document group can contain multiple sub-groups.

Business value

• Organize subscriptions logically so document generation and diagrams stay scoped to the right teams or environments
• Control access at the group level, so permission changes apply consistently across everything in that group

Prerequisites

Required permissions

Only the following roles can manage document groups:

How it works

Document groups form a tree view in Azure Documenter. Each group holds a set of Azure subscriptions granted through Service principal access policies. Sub-groups inherit the tree structure but maintain independent scope selections and access policies. You can reorganize groups by moving them, update subscription access through scope selection, and associate documentation with groups through the group Wiki.

Each document group page has two tabs: Documents and Diagrams. The Documents tab contains document configurations for that group. The Diagrams tab contains diagram configurations, each independently scoped and scheduled. Both tabs are scoped to the subscriptions configured for the group.

Steps

Use the following steps to add, edit, move, or delete a document group, and to manage its scope. Start from the Context menu ( ⋮ ) next to any group in the tree view.

Add a group

Adding a group creates a new node in the tree view scoped to the subscriptions you choose.

1. Click the Context menu ( ⋮ ) next to any group in the tree view.
2. Select New Group.
3. Enter a name for the group and click Next.
4. Choose the subscriptions the group needs access to.
5. Click Save.

Edit a group

Editing lets you update a group's name or description without affecting its subscription access.

1. Click the Context menu ( ⋮ ) next to the group.
2. Select Edit.
3. Modify the name and description as needed.
4. Click Update.

Configure scope selection

Scope selection changes which subscriptions a group can access.

1. Click the Context menu ( ⋮ ) next to the group.
2. Select Scope selection.
3. Choose the required subscriptions and click Proceed.
4. Click Continue in the confirmation dialog.

Move a group

Moving a group restructures it under a new parent. Cost data and resource links remain intact, but the group's access permissions are replaced by those defined in the destination group.

1. Click the Context menu ( ⋮ ) next to the group to move.
2. Select Move.
3. Choose the destination group.
4. Click Move to confirm.

When a group is moved, the user and service principal access policies defined in the source group are overridden by those configured in the destination group. Any custom role assignments, inherited permissions, or explicit access controls from the source group no longer apply after the move.

Delete a group

Deleting a group permanently removes it and all its associated configurations from Azure Documenter and cannot be undone.

1. Click the Context menu ( ⋮ ) next to the group.
2. Select Delete.

Access a group's Wiki

Accessing the Wiki opens the articles associated with the group, giving you a single place to review or add internal documentation for that subscription scope.

1. Click the Context menu ( ⋮ ) next to the group.
2. Select Wiki to view the articles associated with the group.

Example scenario

Your organization restructures and a team previously using a shared subscription scope now needs its own isolated document group. Create a sub-group using New Group and configure its scope via Scope selection to include only that team's subscriptions. Move the existing nested groups for that team under the new sub-group using Move. Before confirming, review the destination group's user and service principal access policies to ensure the team retains the correct permissions after the restructure.

Troubleshooting

1. Scope selection shows no subscriptions
   Cause: The Service principal configured for this document group does not have Reader access to any Azure subscriptions, or the Service principal has not yet been added to Azure Documenter.
   Fix: Verify that at least one Service principal with Reader access to the required subscriptions has been added and linked to this group. See Service principal setup.

2. Move fails or the destination group is not visible
   Cause: The user does not have Contributor or Owner access at the destination group level, or the destination group has been deleted.
   Fix: Confirm the destination group exists in the tree view and that the user's role includes permission to modify the destination group.

3. Access permissions are incorrect after moving a group
   Cause: The moved group's access policies were replaced by the destination group's policies, which may differ from what was intended.
   Fix: After the move, review and update the access policies in the destination group as needed. This cannot be undone automatically. Manually reassign roles if required.

4. Wiki link shows no articles
   Cause: No articles have been associated with this group's Wiki yet.
   Fix: Add articles to the group Wiki through the Azure Documenter interface. The Wiki reflects only articles explicitly linked to the group.

FAQs

1. What happens to a group's data when I move it to a new parent?
   Cost data and resource links remain intact, but the group's access permissions are replaced by those defined in the destination group.

2. Can I undo a group move?
   No. Moving a group is immediate and cannot be reversed, so confirm users and service principals have the correct access in the destination group before proceeding.

Related articles

• Prerequisites
• Service principal setup
• Managing diagram configurations
• Creating your first document