> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/consume/activate/bi-tools/power-bi/service.md).

# Service

Publish your semantic-model reports to Power BI Service so the team uses dashboards from the cloud, no Power BI Desktop required.

Power BI Service reaches DataOS through an on-premises data gateway running inside your network.

{% hint style="info" %}
Just need the gateway part? See [Set up an on-premises gateway](#1-set-up-the-on-premises-gateway).
{% endhint %}

## How it works

Build and test the report in [Power BI Desktop](/consume/activate/bi-tools/power-bi/desktop.md), then publish it to Power BI Service.

The on-premises gateway bridges Power BI's cloud to your DataOS endpoint. Visual queries from Power BI Service route through the gateway to the DataOS semantic layer and back.

## Prerequisites

{% hint style="warning" %}
DataOS uses port `3306`. Whitelist it between the gateway machine and DataOS. If you connect through a VPN, you may also need firewall rules between the VPN network and Power BI Service.
{% endhint %}

<table><thead><tr><th width="271.42633056640625">Requirement</th><th>Detail</th></tr></thead><tbody><tr><td><strong>Power BI Desktop</strong></td><td>Version <code>2.132.908.0</code> or later. Complete <a href="/pages/OENvjjT3vSpznKK6G3Eo">Desktop setup</a> first.</td></tr><tr><td><strong>Power BI Service account</strong></td><td>An active Power BI Pro or Premium account.</td></tr><tr><td><strong>On-premises Data Gateway</strong></td><td>Download from <a href="https://www.microsoft.com/en-us/download/details.aspx?id=53127">Microsoft</a>. Install on a Windows machine that can reach your DataOS endpoint.</td></tr><tr><td><strong>DataOS Power BI connector</strong></td><td>Drop <code>DataOS.mez</code> into <code>C:\PowerBI\CustomConnectors\</code> on the gateway machine. Get it from the DataOS.mez link from the UI.</td></tr><tr><td><strong>DataOS Username</strong></td><td>Used as the gateway connection username.</td></tr><tr><td><strong>DataOS API token</strong></td><td>Used as the gateway connection password. Generate one from <a href="/pages/7rh6mFCr0rhl6vO76XjW#get-a-dataos-api-token">API tokens</a>.</td></tr></tbody></table>

Most organizations install the gateway and connector inside their own network. Talk to your DataOS administrator if port whitelisting is needed.

{% stepper %}
{% step %}

### Set up the on-premises gateway

If the gateway is already configured, skip to [Publish the report](#2-publish-the-report).

#### Install the gateway

1. Download the gateway installer from [Microsoft](https://www.microsoft.com/en-us/download/details.aspx?id=53127).
2. Run the installer, keep the default installation path, accept the terms, and click **Install**.
3. Enter the same email address that is used while setting up the powerbi desktop and sign in.

{% hint style="info" %}
The sign-in account must be an organization account. Personal Microsoft accounts don't work.
{% endhint %}

#### Register the gateway

1. Select **Register a new gateway on this computer** and click **Next**.
2. Enter a name for the gateway — it must be unique across.
3. Enter a recovery key and store it somewhere safe. You will need it to recover or move the gateway later.
4. Click **Configure**, then **Close** once the setup completes.

#### Add the DataOS connector

1. Create the folder `C:\PowerBI\CustomConnectors\` on the gateway machine if it doesn't exist.
2. Download `DataOS.mez` from the DataOS.mez link from the UI.
3. Drop the file in `C:\PowerBI\CustomConnectors\`.
4. Open the **On-premises data gateway** app.
5. Go to **Connectors**.
6. Set the custom connectors folder to `C:\PowerBI\CustomConnectors\`.
7. Restart the gateway.

{% hint style="info" %}
After the restart, **DataOS** should appear in the connectors list.
{% endhint %}
{% endstep %}

{% step %} <img src="/files/dgJU3gP5YSOGWhTITbNo" alt="Image" data-size="original">
{% endstep %}

{% step %}

### Publish the report

If you haven't built the report yet, start with [Desktop](/consume/activate/bi-tools/power-bi/desktop.md), save (do not translate to TMDL) and come back.

1. In Power BI Desktop, open the **Home** tab, Click **Publish**.
2. On the **Publish to Power BI** screen, select your workspace (e.g. **My Workspace**) and click **Select**.
3. [Sign in](https://app.powerbi.com/singleSignOn?ru=https%3A%2F%2Fapp.powerbi.com%2F%3FnoSignUpCheck%3D1) to Power BI Service if prompted.
4. When the success message appears, click **Open** to view the report in Power BI Service.
   {% endstep %}

{% step %}

### Configure the gateway connection in Power BI Service

#### Create a new gateway connection

1. In **Settings**, expand **Manage connections and gateway**.
2. Go to **On-premises data gateways**, find your gateway name, click the three dots, select **Settings**, and tick the checkbox that allows the required permission, as shown in the image. ![Image](/files/1Jn2gmgY4BfbRwv4a2rp)
3. Click **+ New** or **Create a connection**.
4. Make sure **On-premises** is selected.
5. Enter the following:

| Field                           | Value                                               |
| ------------------------------- | --------------------------------------------------- |
| **Gateway cluster name**        | The gateway you registered.                         |
| **Connection name**             | Anything you like, e.g. `on-prem`.                  |
| **Connection type**             | **DataOS**                                          |
| **Server / DataOS Data Source** | `DATAOS_TCP_HOST:3306;<tenant>.<data-product-name>` |
| **Database**                    | Leave blank.                                        |
| **Authentication**              | `Basic`                                             |
| **Username**                    | Your DataOS username.                               |
| **Password**                    | Your DataOS API token.                              |
| **Encrypted connection**        | `Not encrypted`                                     |

5. Click **Add**.

#### Map the connection to the semantic model

1. Go back to the semantic model **Settings** page.
2. Under **Gateway and cloud connections**, pick the connection you just created.
3. Click **Apply**.
4. Open the report. The visuals should now load data.
   {% endstep %}
   {% endstepper %}

{% hint style="success" %}

### You're connected

Power BI Service dashboards now query your DataOS semantic layer live through the gateway.
{% endhint %}

## Troubleshooting

For the full troubleshooting guide, see the [Reference Guide → Troubleshooting](/concepts/foundations/activation/bi-tools/power-bi/service.md).

| Symptom                                          | Fix                                                                                                                                            |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| DataOS connector isn't visible in the gateway    | Confirm `DataOS.mez` is in `C:\PowerBI\CustomConnectors\` and restart the gateway.                                                             |
| Gateway connection fails on save                 | Confirm port `3306` is whitelisted between the gateway machine and DataOS. Re-check username and API token.                                    |
| `Connection reset` in Power BI Desktop           | Go to **Home → Queries → Refresh**.                                                                                                            |
| `Unknown cluster` error                          | Redeploy the cluster, then click **Refresh** in Power BI Desktop.                                                                              |
| Semantic model shows no data in Power BI Service | The gateway connection isn't mapped yet. Complete [Connect the published model to the gateway](#3-connect-the-published-model-to-the-gateway). |
| Schema changes don't show up in Power BI Service | Re-publish the updated `.pbip` from Power BI Desktop. Schema changes don't propagate automatically.                                            |

***

## Reference

For how the gateway connection works, supported connection types, data refresh behavior, and the full troubleshooting guide, see [Power BI Service](/concepts/foundations/activation/bi-tools/power-bi/service.md) in Concepts.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/consume/activate/bi-tools/power-bi/service.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.