For the complete documentation index, see llms.txt. This page is also available as Markdown.

How to set up the Power BI integration

Connect Power BI to bring report and dataset values into journey map metric cards.

An Admin connects Power BI once at the account level. After that, anyone in the workspace can build metrics from your datasets.

Set up the Power BI integration

Prerequisites

In Smaply, go to Account Settings > Integrations and click Set up next to Power BI.

Smaply Account settings page with the Integrations tab open. The Metrics integrations section lists Google Analytics, Office 365 Excel, Power BI, Google Sheets, and Qualtrics, each with a Set up button to the right.
Account settings > Integrations

The Configure Power BI page opens with two options under Select integration type: Service account (selected by default and marked Recommended) and Login with your Power BI account (oAuth).

Configure Power BI page in the unconfigured state. The left pane shows Select integration type with Service account selected (marked Recommended) and Login with your Power BI account (oAuth) below it. The right pane shows Power BI Service Account with a How to setup Power BI service account info panel and empty Tenant ID, Client ID, and Client Secret fields above a Save Service Account button.
Configure Power BI, unconfigured

Pick the authentication method that fits:

  • Service account (recommended) - Uses a Microsoft Entra ID service principal, so the connection isn't tied to one person's login. Best when your team works on the same Smaply account.

  • OAuth - Simpler when only one person needs the data, or for connecting personal workspaces that can't have a security group assigned to them.


Verify the setup

After saving credentials, open the Configure Power BI page. If your workspaces appear in the picker, the connection is working.

Verify end-to-end with the verification tool (powerbi_troubleshooting.zip, Python 3.6+)

powerbi_troubleshooting.zip is a Python 3.6+ script that checks the three exact-match conditions the integration depends on: workspace name, table name, and security group name.

You need Python 3.6 or higher installed:

  • Windows - download Python and run the installer.

  • Mac - brew install python3

  • Linux - sudo apt-get install python3

Download the tool below, unzip it, and follow the instructions in test_scripts/README inside the archive. Run the script after setup completes, read the output carefully, and share it with Smaply support if you escalate.

If workspaces don't appear or any check fails, see Troubleshooting below.


Use Power BI in a metric

With the connection verified, anyone in your account can add Power BI data to a metric card on any journey map. See How to use Power BI in a metric for the field mapping and dataset selection.


Troubleshooting

The Integrations tab in Account Settings shows the integration's current state. Pick the symptom below that matches what you're seeing.

Connection Failed or Connection Error banner - Connection issue

A red banner on the Configure Power BI page means Smaply cannot reach Power BI with the stored credentials.

  • For service account: re-check the Tenant ID, Client ID, and Client Secret values for typos or trailing whitespace, and confirm the client secret hasn't expired in Microsoft Entra ID. If you're inside the propagation window (the first 30 to 60 minutes after assigning workspace access), wait until it elapses before troubleshooting further.

  • For OAuth: click Connect Power BI again from the Configure page. The token may have expired or been revoked.

The workspace picker is empty or shows "no workspaces" - Configuration issue

The connection succeeds but no workspaces appear in the metric builder. The fix depends on which exact-match constraint slipped:

  • Tenant setting not enabled for the group. Open the Power BI Admin Portal, Tenant settings > Service principals can call Fabric public APIs, and confirm it's enabled and applied to the security group your service principal belongs to.

  • Security group name mismatched across surfaces. The group's exact name (case included) has to match in three places: the Microsoft Entra ID group itself, the Power BI tenant setting's Specific security groups entry, and the Manage access assignment on each workspace. A single character off in any of the three breaks workspace listing silently.

  • Propagation wait not elapsed. Power BI takes 30 to 60 minutes to propagate a new workspace assignment. If you've assigned access in the last 30 to 60 minutes, wait and try again.

A metric returns no data or unexpected values - Data issue

The connection works but the metric returns nothing or values that don't look right.

  • Confirm the service principal (or your OAuth account) has been added to the source workspace with at least Member access. The workspace can be visible in the picker without the dataset being readable.

  • Open the dataset in Power BI and confirm it has been refreshed recently. Smaply reads whatever Power BI has cached, so a failed dataset refresh shows as stale or empty data on the Smaply side.

  • Verify the Workspace, Dataset, and the table or column the metric points at still exist with the same names. Renaming or moving any of them in Power BI breaks the metric until it's re-pointed.

OAuth: Microsoft asked for admin approval - Authentication issue

The Microsoft consent screen tells you the app needs admin approval before you can complete the connection.

  • Some Microsoft organisations require a tenant admin to pre-approve third-party app grants. Ask your Microsoft admin to approve Smaply for the tenant, then return to the Configure Power BI page and click Connect Power BI again.

  • If admin approval isn't an option for your org, use the Service account method instead.

OAuth: Previously working integration stopped pulling - Token revoked

Metrics that worked previously show errors and stop pulling data.

  • The most common cause is the OAuth grant being revoked, either by the user signing out of Microsoft everywhere, or by a tenant admin removing the Smaply app from approved apps. Open the Configure Power BI page and click Connect Power BI to re-establish the grant.

  • If the same user keeps losing the connection, switch to a Service account so the connection isn't tied to one person's Microsoft session.

Personal workspaces don't work with Service account - Edge case

A Power BI workspace marked as My workspace can't have a security group assigned to it, so the service principal can't be granted access.

  • Use the OAuth method to read from a personal workspace, signed in as the workspace owner.

  • If you want the data in a Smaply metric long-term, move the dataset into a shared workspace and assign the security group there.

For wider questions about how integrations behave across tools (refresh frequency, switching auth, what happens on disconnect), see How to manage integrations.

Still not working? Contact support at help@smaply.com


Last updated