> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/power-bi/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

The Power BI connector imports who has access to which Power BI workspaces, reports, semantic models, dashboards and apps into Elimity Insights.

## 1. Which data is imported from Power BI?

The gateway reads your whole Power BI (Microsoft Fabric) tenant through the read-only Power BI admin APIs and imports:

* `Principals`: users, groups and service principals with access somewhere.
* `Workspaces`: shared workspaces. Personal "My workspace" workspaces are not imported.
* `Workspace Roles`: Admin, Member, Contributor and Viewer per workspace. All four exist for every workspace except Admin monitoring, also when nobody holds them.
* `Reports`, `Semantic Models`, `Dashboards` and `Apps`.
* `Report / Semantic Model / Dashboard / App Access Rights`: one access level on one item, for example "Budget - ReadWrite".

Access always runs Principal → access right → resource, for example *Jane → "Finance - Admin" → Finance workspace*. A group appears as one principal.

```mermaid
graph TD
Principal[Principal]
WorkspaceRole[Workspace Role]
Workspace[Workspace]
ReportAR[Report Access Right]
Report[Report]
ModelAR[Semantic Model Access Right]
Model[Semantic Model]
DashboardAR[Dashboard Access Right]
Dashboard[Dashboard]
AppAR[App Access Right]
App[App]
Principal --> WorkspaceRole --> Workspace
Principal --> ReportAR --> Report
Principal --> ModelAR --> Model
Principal --> DashboardAR --> Dashboard
Principal --> AppAR --> App
```

#### Main attributes

| Entity type                          | Attributes                                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Principal                            | `principal_type` (User, Group, App, Organization), `user_type` (Member or Guest), `email_address`, `identifier`                             |
| Workspace                            | `state`, `type`, `is_on_dedicated_capacity`                                                                                                 |
| Workspace Role and the access rights | `access_right`                                                                                                                              |
| Report                               | `workspace_name`, `semantic_model_name`, `created_by`, `modified_by`, `created_date_time`, `modified_date_time`, `is_app_report`, `web_url` |
| Semantic Model                       | `workspace_name`, `configured_by`, `created_date`, `is_effective_identity_required`, `is_effective_identity_roles_required`                 |
| Dashboard                            | `workspace_name`, `web_url`                                                                                                                 |
| App                                  | `workspace_name`, `published_by`, `last_update`, `description`                                                                              |

Principal IDs are Entra object IDs (for service principals the object ID, not the application ID), so they match the users, groups and service principals of the Entra ID source. "\[App]" reports and dashboards are the copies inside a published app.

## 2. Prepare Microsoft Entra ID and Fabric

You need the **Application Administrator** or **Global Administrator** role in Entra to register an app, and the **Fabric Administrator** (Power BI Administrator) role to change tenant settings.

#### 2a. Register an application

* Sign in to the Azure Portal and open **Microsoft Entra ID → App registrations → New registration**.
* Name it, for example `elimity-insights-powerbi`, choose *Accounts in this organizational directory only (Single tenant)*, leave **Redirect URI** empty and click **Register**.
* On the overview page, note the **Application (client) ID** and the **Directory (tenant) ID**.

{% hint style="warning" %}
Do not add Power BI Service API permissions (such as `Tenant.Read.All`) to this app. Access to the admin APIs is controlled by the tenant settings in 2c, and those permissions with admin consent make the admin API calls fail with 401. The app needs no API permissions at all; you can remove the default Microsoft Graph `User.Read` permission.
{% endhint %}

#### 2b. Create a client secret

* On the app registration, go to **Certificates & secrets → Client secrets → New client secret**.
* Enter a description and an expiry, and click **Add**.
* Copy the secret's **Value** immediately: it is shown only once. Use the Value, not the Secret ID.

#### 2c. Allow the app to use the Power BI admin APIs

* In the Azure Portal, create a security group under **Microsoft Entra ID → Groups → New group** (type *Security*), for example `Elimity Power BI API access`, and add the app from 2a as a member.
* Sign in to the Fabric admin portal as Fabric Administrator and open the tenant settings.
* Under **Developer settings**, enable **Service principals can use Fabric APIs** for **Specific security groups** and add the group.
* Under **Admin API settings**, enable **Service principals can access read-only admin APIs** for **Specific security groups** and add the same group.

Tenant setting changes can take up to 15 minutes to take effect. The read-only admin APIs only give read access: the gateway never changes anything in Power BI.

## 3. Configure the source in Elimity Insights

* Go to 'Sources' in the left navigation bar and click 'Add Source'.
* Search for 'Custom' and click 'Set Up'.
* Click 'Set Up' again and fill in the name of the Source (e.g. Power BI).
* Select 'Upload export file'.
* Click 'Continue' and upload the data model export file `insights-client-power-bi-data-model-export.json`:

{% file src="/files/JH2h6Eu7OaGf7wod26DN" %}

* Now go to the 'Config' tab and click 'Edit'.
* Set 'Enable automatic imports via custom gateway' to true and fill in the Gateway URL: `https://power-bi-gateway-1027270379075.europe-west1.run.app` for the gateway hosted by Elimity, or the URL of your own deployment.
* Leave 'SDK version' on `1`.
* Click 'Add configuration value' and add the following configuration values:

| Key             | Type       | Description                               |
| --------------- | ---------- | ----------------------------------------- |
| `tenant_id`     | `Text`     | The Directory (tenant) ID from step 2a.   |
| `client_id`     | `Text`     | The Application (client) ID from step 2a. |
| `client_secret` | `Password` | The client secret Value from step 2b.     |

Now click 'Save and run'! You can monitor the progress in the 'Logs' tab. Also the 'Imports' tab gives more information if anything went wrong.

## 4. How an import runs

Every import is a full import, there is no delta:

* The gateway lists all non-personal workspaces and scans them with the Power BI scanner API in batches of 100 workspaces, which returns the workspaces, their items and who has access to each item.
* Apps and their users are read separately, because they are not part of the scan result.
* When Power BI throttles a request (HTTP 429) or has a temporary error, the gateway waits and retries up to five times, following the `Retry-After` header, and logs each retry.

The import log ends with a summary of the number of principals, workspaces, workspace roles, reports, semantic models, dashboards, apps, item access rights and relationships that were imported.

## 5. Troubleshooting

#### `Missing or invalid config field: tenant_id` (or `client_id`, `client_secret`)

A configuration value is empty or has another name. Add all three keys from step 3 with exactly these names.

#### `AADSTS700016`: application not found

The tenant ID or client ID is wrong. Copy both again from the app overview page.

#### `AADSTS7000215`: invalid client secret

The secret is mistyped or expired, or the Secret ID was used instead of the Value. Create a new secret (step 2b) and paste its Value.

#### `401` on an `/admin/` URL

The app is not in the security group, the tenant settings are off, or Power BI Service API permissions are set on the app. Check step 2c and the note in step 2a, and wait 15 minutes after changes.

#### Log lines `retrying in …s`

Power BI is rate limiting the gateway. Nothing to do: the gateway waits and retries. If the import still fails, run it again later.


---

# 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.elimity.com/power-bi/step-by-step-deployment-guide.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.
