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.

In this guide

1. Set up the Power BI integration

2. Use Power BI in a metric

3. Troubleshooting

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

• Permission to register an app in Microsoft Entra ID, edit Power BI tenant settings, and add members to your Power BI workspaces

Plan availability

Connecting Power BI is available on the Governance plan.

In Smaply, go to Account Settings > Integrations and click Set up next to Power BI. The Configure Power BI page opens, connecting via a service account: a Microsoft Entra ID app registration acting as a non-user identity, so the connection isn't tied to one person's login.

Configure Power BI, unconfigured

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.

1

Register an app in Microsoft Entra ID

In the Azure portal, open Microsoft Entra ID and click + Add > App registration.

Microsoft Entra ID > + 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.

Register an application

For full background on app registrations, see Microsoft's quickstart on registering an application.

2

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.

Power BI Service > Application permissions > Tenant.Read.All

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.

Important: Without admin consent the connection looks fine but workspaces stay empty

If the Admin consent required column says Yes but the Status isn't Granted, Smaply will authenticate successfully and then return an empty workspace list. The grant button only appears for a tenant admin.

3

Generate a client secret

In the same app, open Certificates & secrets and create a new client secret. Copy the secret Value immediately.

Warning: The client secret value cannot be re-shown

Azure displays the secret value only at creation time. Once you navigate away, only the secret ID stays visible. If you lose the value, generate a new secret.

4

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.

New security group with the service principal added 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.

5

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.

6

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.

Manage access > + Add people or groups > pick the security group and assign Member

The group appears in the Manage access list with Member next to it.

Security group assigned as Member

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.

Important: Personal workspaces aren't supported

A Power BI workspace marked as My workspace can't have a security group assigned to it, so Smaply can't read from it. Move the dataset into a shared workspace to connect it.

7

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.

App registrations > Overview, with the two IDs Smaply needs

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.

---

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.

powerbi_troubleshooting.zip

archive · 13KB

Open

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. 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.

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 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.

Personal workspaces don't connect - 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.

• 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 [e-mail]

---

Related topics

Manage integrations

Disconnect, switch auth, and read connection states across all integrations.

Create and configure a metric

The full metric creation flow, including types, charts, and filters.

Metric cards

Adding metric cards to a journey map and customising their display per card.

Embed cards

Embed a Power BI report as live content on a journey map instead of pulling values as a metric.