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
Admin role at the Smaply account level
A Microsoft Entra ID tenant and a Power BI workspace your organisation uses
For service account auth: permission to register an app in Microsoft Entra ID, edit Power BI tenant settings, and add members to your Power BI workspaces
In Smaply, go to Account Settings > Integrations and click Set up next to Power BI.
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).
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.
Plan availability
Service account auth is available on the Governance plan. OAuth auth (the other tab) is available on all plans that include metrics integrations.
A service account is a Microsoft Entra ID app registration acting as a non-user identity, sometimes called a service principal. You register the app, grant it the right Power BI permissions, add it to a security group, give the group access to your workspaces, and enter the three credentials in Smaply.
Keep the Configure Power BI page open in another tab. You'll come back to it at the end of this flow to enter the credentials.
Register an app in Microsoft Entra ID
In the Azure portal, open Microsoft Entra ID and click + Add > App registration.
On the Register an application page, give the app a recognisable name (for example, Smaply Power BI connector), choose Accounts in this organizational directory only (Single tenant), leave the Redirect URI blank, and click Register.
For full background on app registrations, see Microsoft's quickstart on registering an application.
Assign API permissions
On the registered app, open API permissions and click + Add a permission. Choose Power BI Service, then Application permissions, tick Tenant.Read.All, and click Add permissions.
Back on the API permissions page, click Grant admin consent for [your tenant] and confirm. Smaply only needs Tenant.Read.All. You can ignore Tenant.ReadWrite.All, which the screenshot above also shows ticked.
Generate a client secret
In the same app, open Certificates & secrets and create a new client secret. Copy the secret Value immediately.
Create a security group and add the service principal
In Microsoft Entra ID, open Groups > All groups and click New group. Set Group type to Security, give the group a recognisable name (for example, smaply-powerbi), and add the registered app to the group as a member.
To find the app in the Add members picker, search by the app name you used in step 1.
Important: The group name has to match exactly across three places
You'll reference this group name again in the Power BI tenant setting (step 5) and on each workspace (step 6). A mismatched character or different casing in any of the three places breaks the connection silently. Pick a name and reuse it verbatim.
Enable the Power BI tenant setting for the group
In the Power BI Admin Portal, open Tenant settings > Developer settings > Service principals can call Fabric public APIs. Microsoft previously called this setting Allow service principals to use Power BI APIs, so older guides and screenshots may use that name.
Switch the setting to Enabled, set Apply to to Specific security groups, type in the name of the security group you just created (for example, smaply-powerbi), and click Apply.
Important: This step is the most common reason a setup looks correct but no workspaces appear
Without this tenant setting enabled for the group, Smaply authenticates but every workspace and dataset list comes back empty. If you're not a Power BI tenant admin, ask whoever is to enable it before continuing. For the authoritative reference, see Microsoft's documentation on enabling the Power BI service principal.
Assign the security group to each Power BI workspace
In Power BI, open each workspace you want Smaply to read. Click Manage access, then + Add people or groups, search for the security group by name (for example, smaply-powerbi), set the role to Member, and click Add.
The group appears in the Manage access list with Member next to it.
Admin also works, but Member is the minimum role Smaply needs to read datasets.
Important: Wait 30 to 60 minutes for the assignment to propagate
Power BI takes 30 to 60 minutes to propagate new workspace access for a service principal. Until propagation finishes, Smaply may show an empty workspace list or Connection Error even though the setup is correct. If everything looks right and the integration still doesn't work, wait out the full 30 to 60 minute window before re-checking.
Repeat for every workspace you plan to use. Personal workspaces (workspaces marked as My workspace in Power BI) can't have a security group assigned to them, so they aren't supported by the service account method. Use OAuth if you need to read from a personal workspace.
Enter the credentials in Smaply
Back in Microsoft Entra ID, open the registered app's Overview page. Copy the Application (client) ID and the Directory (tenant) ID.
Return to the Configure Power BI page in Smaply and paste the values into the three fields:
Tenant ID - The Directory (tenant) ID from the app overview.
Client ID - The Application (client) ID from the same page.
Client Secret - The secret Value you copied when you generated the client secret.
Click Save Service Account.
OAuth signs Smaply in as you. The connection inherits whatever Power BI workspaces your Microsoft account already has access to, and tokens are tied to your individual permissions in Microsoft.
Prerequisites
A Microsoft account with read access to the Power BI workspaces you want to use
If your organisation requires admin approval for third-party app consent, a Microsoft tenant admin available to approve the grant
Choose Login with your Power BI account (oAuth)
On the Configure Power BI page, select Login with your Power BI account (oAuth). The right pane changes to Connect Power BI with a three-step info panel and the Connect Power BI button.
Click Connect Power BI. Smaply redirects you to Microsoft.
Sign in and grant permissions
Sign in with the Microsoft account that has access to the Power BI workspaces you want to use in Smaply. On Microsoft's consent screen, click Accept to grant the three permissions Smaply requests:
Read all datasets and reports that you have access to
Sign you in and read your profile
Optionally, Consent on behalf of your organization (only available to tenant admins)
If your Microsoft organisation requires admin approval for third-party apps, the consent screen tells you to ask an admin instead. The connection completes once an admin approves it.
Authorise the connection
Microsoft sends you back to Smaply. The Configure Power BI page shows the connected state, with the connecting account listed under Added by. Smaply refreshes OAuth tokens automatically, so you don't need to sign in again unless the token is revoked.
If you sign out of Microsoft, revoke Smaply's access in your Microsoft account, or lose access to a Power BI workspace, the connection drops and metrics that depend on it stop pulling data. For team-wide use, switch to a Service account so the connection isn't tied to one person's login.
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 python3Linux -
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
Related topics
Last updated