> For the complete documentation index, see [llms.txt](https://helpdesk.smaply.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helpdesk.smaply.app/integrations/metrics-tools/power-bi/how-to-use-power-bi-in-a-metric.md).

# How to use Power BI in a metric

Turn a Power BI table into a live chart on any journey map.

{% hint style="warning" icon="list-check" %}

#### Prerequisites

* The Power BI integration is set up at the account level. See [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration.md).
* Editor role at the workspace level.
  {% endhint %}

#### Add a Power BI metric

You can create a Power BI metric from two places:

* **From the workspace Metrics tab** - Click **Metrics** in the sidebar, then **+ Create metric**. The full-page **Add metric** form opens.
* **From a journey map** - Click **+ Add card** on a card slot and pick **Metric** under **Advanced cards**. In the **Add metric** picker, pick an existing metric or type a name and click **Create**. The metric opens in a compact modal; use **Full screen view** to switch to the full-page form.

<figure><img src="/files/5hgIFupRgFtQo65HaIUp" alt="Journey map Add card picker open on a card slot, showing the Basic Cards group (Image, Stage, Icons, Slider) and the Advanced Cards group (Embed, Planning, Metric, Link journey map) plus a Text quick-select row at the top."><figcaption><p>Add card picker on a journey map, Metric under Advanced cards</p></figcaption></figure>

The steps below walk the workspace-tab flow because the full-page form shows every field on screen. The journey map modal has the same fields in a more compact layout.

{% stepper %}
{% step %}
**Open the Add metric form**

In the workspace sidebar, click **Metrics**, then **+ Create metric**. The **Add metric** form opens with the two-column layout: **Metric data source** on the left and **Default card preview** on the right.

<figure><img src="/files/N28ic7pURq7vkaC1Wpp7" alt="Add metric page in the empty state. Left column shows Metric data source heading with Name, Source, Type, and Metric tags fields. Right column shows Default card preview heading with a Preview tile, chart-type chip strip, Chart heading and Chart subheading inputs."><figcaption><p>Add metric, empty form</p></figcaption></figure>
{% endstep %}

{% step %}
**Name the metric and pick Power BI as the source**

Type a name that describes what the metric shows (for example, `Employee count by city`). In **Source**, pick **Power BI**.

<figure><img src="/files/cyUl4czvjSuRxKtjkt62" alt="Source dropdown open on the Add metric form, listing Manual (includes CSV upload), Google Analytics, Power BI, Excel (Office 365), Google Sheet, and Qualtrics."><figcaption><p>Source dropdown, all sources listed</p></figcaption></figure>

If you see a pink **Power BI setup required** block below the Source field, the integration isn't connected for this account yet. Click **Setup Power BI** in the block and follow [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration.md) before continuing.
{% endstep %}

{% step %}
**Set Type to Series**

Open the **Type** dropdown and pick **Series**. Power BI metrics are series only, so this is the only option.

<figure><img src="/files/8D4JLFcrPhyapyxuLpzv" alt="Type dropdown open on the Add metric form with Source set to Power BI. The dropdown shows Series as the only selectable option, with a small line-chart icon to the left of the label."><figcaption><p>Type dropdown, Series only for Power BI</p></figcaption></figure>

If you need a single value or a side-by-side comparison instead of a series, see [How to choose a metric type](/metrics/how-to-choose-a-metric-type.md) for which sources support which types.
{% endstep %}

{% step %}
**Map the Power BI fields**

Five Power BI fields drive what the metric pulls: **Workspace**, **Dataset**, **Table**, **Data label**, and **Data value**. The screenshots below walk one concrete example: workspace `Smaply Workspace`, dataset `Employee_Sample_Data`, table `EmployeeCountByCityTable`, label column `City`, value column `Value`.

* Pick the Power BI workspace under **Workspace**. Only workspaces the connection has access to appear in the list.
* Pick the dataset inside that workspace under **Dataset**.
* Type the table name into **Table** and click **Enter** next to the field. This is a text field, not a dropdown, and pressing Enter is what loads the table's columns into the next two selectors.
* Pick the column for the chart's categories under **Data label** (for example, `City`).
* Pick the column for the numerical value under **Data value** (for example, `Value`).

<figure><img src="/files/dfIalIIB8oZSxsQYutyo" alt="Smaply Add metric form on the left fully filled in with Name Employee count by city, Source Power BI, Type Series, Workspace Smaply Workspace, Dataset Employee_Sample_Data, Table EmployeeCountByCityTable, Data label City, Data value Value, and a chart preview rendering a bar chart. The right side shows the matching Power BI workspace in app.powerbi.com with the EmployeeCountByCityTable previewed and the City and Value columns visible."><figcaption><p>Add metric form with Power BI fields populated, alongside the source table in Power BI</p></figcaption></figure>

For a deeper reference of how each field maps to objects in Power BI, see [Field mapping](#field-mapping) below.
{% endstep %}

{% step %}
**Set the row cap and chart options**

Under **Number of rows**, set how many rows from the table to pull into the chart. The maximum is 50.

In the **Default card preview** panel on the right, pick a default chart type from the chip strip (**Bar chart**, **Horizontal bar**, **Pie chart**, **Line chart**, or **Table**). Add an optional **Chart heading** and **Chart subheading** if you want labels above the chart. The preview updates as you change the selections. These settings are the defaults for new metric cards built from this metric; each card can override them on a journey map. For the full chart-options reference, see [How to create and configure a metric](/metrics/how-to-create-and-configure-a-metric.md).
{% endstep %}

{% step %}
**Save the metric**

Click **Save**. The metric appears in the workspace **Metrics** list and is ready to drop onto any journey map as a metric card.

<figure><img src="/files/UGUjfYmud74rA7xlqLxn" alt="Workspace Metrics tab with a populated list showing one metric. Columns are NAME, SOURCE, TYPE, CREATED, UPDATED, USED IN, and TAGS. Search, filter, and + Create metric buttons sit above the table."><figcaption><p>Workspace Metrics tab with a saved metric</p></figcaption></figure>

For placing the metric as a card and customising it per-map, see [How to use metric cards](/journey-maps/cards/how-to-use-metric-cards.md).
{% endstep %}
{% endstepper %}

***

#### Field mapping

Each Power BI field in the **Add metric** form points at a specific object in Power BI. The selectors only populate once the field above them is filled in, so work down the form in order.

* **Workspace** - The Power BI workspace that holds the dataset. Smaply lists only workspaces the connection identity can read. Equivalent to a workspace in app.powerbi.com.
* **Dataset** - The dataset inside the chosen workspace. Drives what loads when the table name is entered.
* **Table** - The table inside the dataset. Free-text field, not a dropdown. Type the table name exactly as it appears in Power BI and click **Enter** to load its columns into the next two selectors.
* **Data label** - The column whose values become categories on the chart (the x-axis on a bar or line chart, the slice labels on a pie chart). Example: a `City` column with values like Austin, Beijing, Chengdu.
* **Data value** - The column whose values become the numbers plotted on the chart. Example: a `Value` column with the employee count per city.
* **Number of rows** - Caps how many rows the metric pulls from the table. Maximum 50.

<figure><img src="/files/HZWoNZq0Nr7d84W3GNoq" alt="Diagram with the Add metric form in Smaply on the left and a Power BI table view on the right. Arrows connect the Workspace, Dataset, Data label, and Data value fields in Smaply to a workspace, a dataset, and the corresponding column ticks in Power BI."><figcaption><p>How each Smaply field maps to a workspace, dataset, table, and column in Power BI</p></figcaption></figure>

***

#### Refresh behaviour

Power BI metrics refresh on a rough hourly cycle. When a journey map containing a Power BI metric loads, Smaply pulls fresh values if the last update was more than about an hour ago. There's no manual refresh button. The next on-load check brings the values up to date.

The metric shows whatever the underlying Power BI dataset has cached, so a stalled dataset refresh in Power BI itself appears as stale or empty values in Smaply.

{% hint style="success" icon="lightbulb" %}

#### **Tip: Match the dataset shape to the journey context**

Pick a dataset shape that matches the journey context. If the journey is regional, a table with one row per region usually reads more cleanly than raw event rows. If the journey is weekly, weekly cohorts read more cleanly than daily values. The metric pulls and renders whatever shape Power BI gives it, so a pre-aggregated table in Power BI usually beats a raw fact table.
{% endhint %}

***

#### Troubleshooting

If the connection itself isn't working, see [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration.md) for connection troubleshooting. The issues below cover data-side problems once the connection is in place.

<details>

<summary><strong>"Power BI setup required" error in the metric form</strong> - Connection not configured</summary>

Picking **Source** = **Power BI** shows a pink block reading "You need to set up the Power BI connection in this workspace before you can use it in metrics."

The connection hasn't been configured for this account, or it was disconnected. Click **Setup Power BI** in the block to jump to the integrations page, then follow [How to set up the Power BI integration](/integrations/metrics-tools/power-bi/how-to-set-up-the-power-bi-integration.md).

</details>

<details>

<summary><strong>Workspace, Dataset, or Table dropdowns are empty</strong> - Connection identity lacks access</summary>

The Source dropdown shows Power BI is connected, but the **Workspace**, **Dataset**, or **Data label / Data value** dropdowns come back empty.

* For service-account auth, the connection's service principal hasn't been granted access to the workspace. Check that the security group is assigned the **Member** role on the Power BI workspace, and that the tenant setting **Service principals can call Fabric public APIs** is enabled for the group. If the access was assigned in the last 30 to 60 minutes, give the change time to propagate before re-testing.
* For OAuth auth, the connecting user account doesn't have access to the workspace in Power BI. Sign in to app.powerbi.com as that user and confirm the workspace appears under **Workspaces**.
* The workspace may genuinely have no datasets, or the dataset may have no tables exposed to the connection identity. Open it in Power BI to confirm.

</details>

<details>

<summary><strong>Pressed Enter on Table but Data label and Data value stayed empty</strong> - Table not found</summary>

The **Table** field accepted text and **Enter** was clicked, but the **Data label** and **Data value** dropdowns didn't populate.

* The table name might be off by a character or different in casing. Open the dataset in Power BI and copy the table name exactly as it appears, including any underscores or capitalisation.
* The table might not exist in the chosen dataset. Confirm both the dataset and the table in Power BI before re-entering.
* The connection identity might not have access to that specific table inside the dataset. Confirm dataset-level read access for the service principal or OAuth account in Power BI.

</details>

<details>

<summary><strong>Metric returns no data or unexpected values</strong> - Data mapping or row cap</summary>

The metric saves and shows on a journey map, but the values are blank, wrong, or surprising.

* Confirm **Data label** and **Data value** are pointing at the columns you meant. It's easy to swap a label column for a value column, especially when both are numeric.
* The **Number of rows** cap is 50. If the underlying table has more rows than that, pre-aggregate the data in Power BI so the rows you care about fit within the cap.
* Open the dataset in Power BI and check its last refresh. Smaply reads whatever Power BI has cached, so a failed dataset refresh in Power BI shows as stale or empty values here.

</details>

<details>

<summary><strong>Dataset, Table, or Column renamed in Power BI</strong> - References broken</summary>

A metric that previously worked starts returning errors or no data.

If the dataset, table, **Data label** column, or **Data value** column was renamed or moved in Power BI, the metric's references break until they're re-pointed. Edit the metric, re-pick the renamed objects, and save. The same applies if a workspace was renamed or the dataset was migrated to a different workspace.

</details>

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see [How to manage integrations](/integrations/how-to-manage-integrations-at-account-level.md).

{% hint style="info" icon="headset" %}
**Still not working?** Contact support at <code class="expression">space.vars.supportEmail</code>
{% endhint %}

***

#### Related topics

<table data-column-title-hidden data-view="cards"><thead><tr><th>Title</th><th>Description</th><th data-hidden data-card-target data-type="content-ref">Target</th></tr></thead><tbody><tr><td><strong>Set up Power BI</strong></td><td>Connect Power BI at the account level using service account or OAuth.</td><td><a href="/pages/f9sIHKFz3MDellnzuV0j">/pages/f9sIHKFz3MDellnzuV0j</a></td></tr><tr><td><strong>Create and configure a metric</strong></td><td>The full metric creation flow, including types, charts, and filters.</td><td><a href="/pages/UlZ0vwT23WaSlpB6ae7r">/pages/UlZ0vwT23WaSlpB6ae7r</a></td></tr><tr><td><strong>Metric cards</strong></td><td>Place a metric card on a journey map and customise its display per card.</td><td><a href="/pages/598LDg8aKf90gVjRC9GG">/pages/598LDg8aKf90gVjRC9GG</a></td></tr><tr><td><strong>Manage integrations</strong></td><td>Disconnect, switch auth, and read connection states across all integrations.</td><td><a href="/pages/eVJNZWbpULcbx2YE06fQ">/pages/eVJNZWbpULcbx2YE06fQ</a></td></tr></tbody></table>


---

# 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://helpdesk.smaply.app/integrations/metrics-tools/power-bi/how-to-use-power-bi-in-a-metric.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.