> For the complete documentation index, see [llms.txt](https://docs.powermonitor.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.powermonitor.com.br/en/power-monitor/mapeamento/dominios.md).

# Domains

Follow, trigger, pause and resume the daily collection of Microsoft Fabric organizational domains and check the Service Principal's permission.

The **Domains** collection brings the **organizational domains** configured in Microsoft Fabric: name, description, parent domain (hierarchy) and how many workspaces are associated with each one. The list and the tree of domains are in Governance; this screen shows the collection history and lets you trigger it, pause it and check whether the Service Principal has the required permission.

**How to access:** *Mapping › Inventory › Domains* (page title: **Domains**). Only **Administrators** can access the screen and the actions.

<figure><picture><source srcset="/files/yoKe7C4dFRlbMaCXZxWn" media="(prefers-color-scheme: dark)"><img src="https://3938213054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH2bFRBmIfyK3kwVKbldl%2Fuploads%2Fgit-blob-46a0c9e2d551628807a8c1938d58b950d0658785%2Fpm-mapeamento-dominios-en.png?alt=media" alt="Domains screen with the collection and permission buttons and the run history"></picture><figcaption><p>Domains</p></figcaption></figure>

## What it is for

* Keep the list of domains used in Governance up to date.
* Confirm whether the Fabric Admin API permission is correct for the Service Principal.
* Collect the domains right away, after creating or reorganizing domains in Fabric.

## Features

The screen is a single card with two action bars (collection and permissions) and the run history. The features are: **Run now** / **Resume**, **Pause**, collection state badges, **Add permissions**, **Check permissions**, **Instructions**, run history and **View failures**.

<figure><picture><source srcset="/files/N4acxEru7tYr0WCeQEru" media="(prefers-color-scheme: dark)"><img src="https://3938213054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH2bFRBmIfyK3kwVKbldl%2Fuploads%2Fgit-blob-774ee0888b5b425c360bbd60bb478d6cf9481544%2Fpm-mapeamento-scan-dominios-acoes-en.png?alt=media" alt="Domains screen action bar with Run now, Add permissions, Check permissions and Instructions"></picture><figcaption><p>Collection and permission action bars</p></figcaption></figure>

### Run now / Resume

**What it is:** a button that triggers a manual collection of the domains. When there is a **Paused** collection, the same button is renamed **Resume** and continues the run from where it stopped.

**What it is for:** reflect right away, in [Governance › Tenant › Domains](/en/power-monitor/governanca/tenant/dominios.md), domains you have just created or reorganized in Fabric, without waiting for the daily collection.

**How to use:**

1. Click **Run now**. There is no confirmation modal; the button shows **Running…** while it sends the request.
2. The message **Domain collection queued. The history updates when it starts.** confirms it; if a collection is already running, **A domain collection is already running for this organization.** appears. While the collection service has not picked up the run, the button shows **Queued** and the card says *Run queued, waiting to start…*; then the button changes to **In progress** and the bar shows the processed items (for example, *12 of 40*) and the estimated time left (*\~3 min left*). The screen tracks the run until it finishes, without reloading.
3. Follow the **Collection in progress** badge and the row in the history until **Completed**.
4. Check the domains in [Governance › Tenant › Domains](/en/power-monitor/governanca/tenant/dominios.md).

To resume a paused collection, click **Resume** (the button shows **Resuming…**). The message **Domain collection resumed successfully.** confirms it.

**How it works / rules:**

* It works even with the automatic run turned off in *Settings › Monitoring › Scans and Collections*.
* There is only one active collection (running or paused) per organization.

### Pause

**What it is:** a button that appears only while a collection is running and asks it to stop.

**What it is for:** temporarily interrupt a long collection (for example, to relieve the Admin API at a critical time) without losing what has already been processed.

**How to use:**

1. During a collection, click **Pause** (the button shows **Pausing…**). The badge **Pause requested: the run stops at the next processed item.** appears.
2. The run changes to **Paused** and the main button becomes **Resume**.
3. Click **Resume** when you want to continue from the point where it stopped.

**How it works / rules:** the pause is cooperative: it respects the domain being processed and only stops at the next one. When resumed, the collection keeps the failures already recorded. A paused collection does not expire.

### Collection state badges

**What it is:** badges at the top of the card that show the current state: **Collection in progress (n)** (blue, with a spinning indicator), **Collection paused** (yellow) and **Pause requested: the run stops at the next processed item.** (gray). During a running collection, an animated progress bar appears above the table.

**What it is for:** know, without opening anything, whether a collection is running, paused or about to pause.

**How to use:** just observe; the screen updates by itself while there is an active collection.

### Add permissions

**What it is:** a button that opens, in a new browser tab, the Tenant settings of the Fabric Admin portal.

**What it is for:** go straight to the place where a Fabric administrator enables the tenant setting required by the collection.

**How to use:** click **Add permissions** and follow the step-by-step in [How to enable the domain collection permission](#how-to-enable-the-domain-collection-permission). You must be signed in with a Fabric administrator account.

### Check permissions

**What it is:** a button that tests, right away, whether the Service Principal can read the domains. It does not save anything and does not start a collection.

**What it is for:** confirm that the tenant setting has been applied, before triggering the collection or after an **Access denied** failure.

<figure><picture><source srcset="/files/PafzZBSM4EQ3zlrXvi1P" media="(prefers-color-scheme: dark)"><img src="https://3938213054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH2bFRBmIfyK3kwVKbldl%2Fuploads%2Fgit-blob-4bb090e65a5c37b2b116d1a761fc793ac0468da7%2Fpm-mapeamento-scan-dominios-verificar-permissoes-en.png?alt=media" alt="Badge with the result of Check permissions next to the permission buttons"></picture><figcaption><p>Result of the permission check</p></figcaption></figure>

**How to use:**

1. Click **Check permissions** (the button shows **Checking…**).
2. Read the badge that appears next to the buttons:

| Result                                      | Meaning                                                                                              |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Permission OK** (green)                   | The Service Principal reads the domains normally                                                     |
| **Service Principal not configured** (gray) | Missing or invalid credentials                                                                       |
| **Access denied** (red)                     | Fabric refused the access (tenant setting turned off or Service Principal outside the allowed group) |
| **Error checking** (yellow)                 | Network failure or another error; try again                                                          |

**How it works / rules:** if the check cannot be performed, **Could not check permissions right now. Please try again.** appears. After changing the setting in Fabric, wait a few minutes for propagation before checking.

### Instructions

**What it is:** a button that opens the **How to enable Domains collection** modal, with the step-by-step of the tenant setting and the **Open Fabric Admin Portal** button.

**What it is for:** have the configuration script at hand, inside Power Monitor itself, to pass on to the Fabric administrator.

<figure><picture><source srcset="/files/BYUmB9I1XlScGZDUHwPq" media="(prefers-color-scheme: dark)"><img src="https://3938213054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH2bFRBmIfyK3kwVKbldl%2Fuploads%2Fgit-blob-6edcc048a54d5d038bd3b959d8d54f103dbe337b%2Fpm-mapeamento-scan-dominios-modal-instrucoes-en.png?alt=media" alt="How to enable Domains collection modal with the step-by-step"></picture><figcaption><p>Permission instructions</p></figcaption></figure>

**How to use:**

1. Click **Instructions**.
2. Follow the listed steps (the same as in [How to enable the domain collection permission](#how-to-enable-the-domain-collection-permission)).
3. Use **Open Fabric Admin Portal** to go to the portal, or close the modal.

### Run history

**What it is:** a paginated table with the collection runs, from most recent to oldest (10 per page; the **Items per page** selector below the table offers 10, 25, 50 or 100).

**What it is for:** confirm that the daily collection ran, how many domains it processed and whether there were failures or stalls.

<figure><picture><source srcset="/files/ZrFjEv8Hx0eW3zPf4wAe" media="(prefers-color-scheme: dark)"><img src="https://3938213054-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FH2bFRBmIfyK3kwVKbldl%2Fuploads%2Fgit-blob-1932f4bbedc3c74b95d4e3211b641607fade1450%2Fpm-mapeamento-dominios-historico-en.png?alt=media" alt="Run history of the domain collection"></picture><figcaption><p>Run history</p></figcaption></figure>

| Column                                    | Content                                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Trigger**                               | **Scheduled** or **Manual** (for manual runs, hover over the person icon to see who triggered it)      |
| **Started** / **Finished** / **Duration** | Run times (no end and duration while it is active)                                                     |
| **Status**                                | **Running** (blue), **Paused** (yellow), **Completed** (green), **Failed** (red), **Stalled** (yellow) |
| **Domains Processed**                     | Number of domains saved                                                                                |
| **Failures**                              | Domains with errors; **View failures** link                                                            |
| **Error**                                 | Icon with the run's general error message (hover over it)                                              |

**How to use:**

1. Locate the run by the **Started** column.
2. For a general error, hover over the icon in the **Error** column.
3. Navigate through the pages with **Previous**, **Next** or the numbers below the table, and use **Items per page** to see more rows.

**How it works / rules:** while there is an active collection, the table is updated automatically every 20 seconds. With no runs, **No run recorded yet** appears.

### View failures

**What it is:** a link in the **Failures** column that opens the **Failures for the {date} run** modal, with the **Item** (domain name and identifier), **Reason** and **Detail** columns.

**What it is for:** find out which domains were not fully processed and why.

**How to use:**

1. Click **View failures** on the run (available when the run finished with failures).
2. Read the **Reason** and **Detail** of each domain.
3. Click **Close**.

**How it works / rules:** if the run did not store the details, **No detail available for this run.** appears. When there are many failures, the end of the list shows **and n more not listed**.

## Rules and behavior

* **Where the data comes from:** Fabric Admin API (list of domains and workspaces of each domain), with the organization's Service Principal.
* **Automatic frequency:** by default, daily at **06:15** (Brasília time, UTC-3), for active organizations with a configured Service Principal. Under *Settings › Monitoring › Scans and Collections*, **Others** group, the **Organizational Domains** card lets you turn off automatic collection and choose the **Frequency**: **Daily**, **Weekly** or **Monthly**. With weekly and monthly, the run happens on a day distributed per organization, and the card shows **Next expected run** and **Last run**. **Run now** is not affected: it works with the toggle off and at any frequency.
* **A per-domain failure does not bring down the collection:** if it is not possible to count the workspaces of a domain, it is saved with 0 workspaces and counted as a failure.
* **Cooperative pause:** the pause respects the item being processed; when resumed, the collection continues from the point where it stopped and keeps the failures already recorded. A paused collection does not expire.
* **Stalled:** a collection with no progress for **10 minutes** is closed as **Stalled** ("Execução interrompida após 10 minutos sem progresso.", that is, run interrupted after 10 minutes without progress).
* **Concurrency:** one active collection (running or paused) per organization.

### Required permission

Tenant setting **Service principals can access read-only admin APIs** (on some tenants it appears as "Service principals can use Fabric APIs"), enabled for a **security group that contains the Service Principal**. Power Monitor never changes this setting automatically: a Fabric administrator must enable it.

### How to enable the domain collection permission

{% stepper %}
{% step %}

### Open the portal

Click **Add permissions** (or, in Fabric, gear icon › **Admin portal**) with a Fabric administrator account.
{% endstep %}

{% step %}

### Locate the setting

Go to **Tenant settings** › **Admin API settings** section (on some tenants, "Developer settings").
{% endstep %}

{% step %}

### Enable it for the Service Principal's group

Enable **Service principals can access read-only admin APIs**, select **Specific security groups** and add the group that contains the organization's Service Principal. Click **Apply**.
{% endstep %}

{% step %}

### Check

Wait a few minutes for propagation, return to Power Monitor and click **Check permissions**. The expected result is **Permission OK**.
{% endstep %}
{% endstepper %}

## Common errors and how to resolve them

| Message / symptom                                                                                                                      | How to resolve                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Access denied** / "Falha ao listar domínios: HTTP 403" (failed to list domains)                                                      | Enable the tenant setting for the Service Principal's group, wait for propagation and click **Check permissions**. |
| **Service Principal not configured** / "Não foi possível adquirir token app-only Fabric" (could not acquire the Fabric app-only token) | Review the Service Principal's App ID and secret.                                                                  |
| **Stalled** status                                                                                                                     | The run stopped making progress. Click **Run now** again.                                                          |
| Domain with **Falha ao contar workspaces do domínio.** (failed to count the domain's workspaces)                                       | A one-off API error; the domain was saved with 0 workspaces. Run the collection again.                             |

## Frequently asked questions

<details>

<summary>Where can I see the list of collected domains?</summary>

In *Governance › Tenant › Domains*, available to all profiles. This screen shows only the collection run.

</details>

<details>

<summary>My tenant does not use domains. Do I need this collection?</summary>

No. The collection finishes with 0 domains processed. If you prefer, turn it off in *Settings › Monitoring › Scans and Collections*.

</details>

## Related pages

* [Governance › Tenant › Domains](/en/power-monitor/governanca/tenant/dominios.md)
* [Governance › Workspaces](/en/power-monitor/governanca/workspaces.md)
* [Settings › Monitoring](/en/power-monitor/configuracoes/monitoramento.md)
* [Mapping](/en/power-monitor/mapeamento.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.powermonitor.com.br/en/power-monitor/mapeamento/dominios.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.