Setting up the Power BI Enterprise Integration

This guide walks you through connecting Power BI Enterprise to Q-Play, so your reports and dashboards can be displayed inside the platform.

Before you start: You'll need access to a Power BI Admin account (or someone on your team who has one) to complete this setup, since some steps involve tenant-level settings that only an admin can change.

Capacity requirement: Embedding Power BI content requires your workspace to run on a paid capacity — A (Power BI Embedded), P (Premium), or F (Fabric) SKU. Shared or Pro capacity does not support embed token generation. If your workspace is on shared/Pro capacity, jobs will fail with a 403 error until you upgrade to one of these capacities.

Using an SoC player? SoC players are the built-in smart TV platform found in displays like LG, Samsung, or Sony — as opposed to an external media player box. These aren't powerful enough to render a live, interactive Power BI embed, so if your display runs on one, you'll need to use one of the Screenshot job types instead of the live Report/Dashboard type — more on this in Step 6 below.

Step 1: Create the integration

Follow our general guide on working with integrations in Q-Play to start a new integration, and choose Power BI Enterprise as the type.

Step 2: Settings

Set your Timezone and Language for the integration, then click Next.

Step 3: Credentials — authorize the integration

This is the step that connects Q-Play to your Power BI tenant.

1. Under Authentication type, choose Authorize with Microsoft.

   If you'd rather use your own custom App Registration instead, that option is also available here — but we assume you already know how to set this up if you choose it, as we can't provide support for custom app registration setups.

2. Under Admin consent, click Authorize to approve access now, or skip this and click Create Integration to finish setup and authorize later.
   • If you authorize now, you'll be taken to a Microsoft sign-in and consent screen. Since Q-Play is a third-party app, this step may need to be approved by an administrator in your Microsoft organization.
   • If you skip it, the integration is created but won't work yet — you'll need to come back and finish authorizing (see below).

Finishing authorization later

If you clicked Create Integration without authorizing, you'll land on the Integration status tab. To complete the setup:

1. Go back into the integration's settings (not the status tab).
2. Complete the Microsoft authorization as described above.
3. Click Save at the bottom of the screen once done.

Step 4: Give Q-Play access to your Power BI workspace

When you authorize with Microsoft, Q-Play creates a service principal user in your Power BI tenant called "Q-Play PowerBi v1.1". This is what actually lets Q-Play read your reports — it needs explicit access to work.

1. In Power BI, open the workspace containing the reports or dashboards you want to display in Q-Play.
2. Add "Q-Play PowerBi v1.1" as a member of that workspace.
3. Set its permission level to at least Member. (This is the minimum needed — it needs Member level to actually read report content, not just Viewer.)

Step 5: Check your tenant settings

This is usually a one-time setup — if it's already been done in your organization (e.g. for another third-party integration), you can skip it. It requires Power BI Admin access.

Open the Admin Portal

1. Sign in to Power BI with a Power BI Admin account.
2. Click the gear icon (⚙️) in the top-right corner.
3. Select Admin portal.
4. Select Tenant settings from the left-hand menu.

Check these two settings are enabled

• Service Principals can call Fabric public APIs — Without this, the service principal Q-Play uses can't authenticate or pull data via the Power BI API. The integration simply won't work without it.
• Embed content in apps — This is what allows Power BI content to actually be embedded and displayed inside Q-Play.

For both settings:

• Set the toggle to Enabled.
• Under scope, choose either Entire organization, or a specific security group that includes the Q-Play service principal.

Once Steps 4 and 5 are completed, your integration is fully set up. Now you're ready to set up your first job.

Step 6: Add a job

A job is what actually pulls a specific report or dashboard into Q-Play. Each report or dashboard you want to display needs its own job.

From the integration's Overview page, click Add Job.

Job Name

Give the job a descriptive name — this is just for your own reference in Q-Play.

Job Type

Choose what kind of Power BI content this job displays:

• Report — embeds a live, interactive Power BI report.
• Dashboard — embeds a live, interactive Power BI dashboard.
• Report Screenshot — takes a still image of a report instead of embedding it live.
• Dashboard Screenshot — takes a still image of a dashboard instead of embedding it live.

Using an SoC player? SoC players are the built-in smart TV platform found in displays like LG, Samsung, or Sony — as opposed to an external media player box. These aren't powerful enough to render a live embed. Use one of the Screenshot job types instead — the result looks the same, it's just a static image rather than an interactive embed.

Step 7: Find your Workspace ID and Report/Dashboard ID

This is the part people get stuck on most, so let's go through it carefully.

Once you've chosen Report or Dashboard as the Job Type, you'll need to fill in a Workspace ID and a Report ID (or Dashboard ID). Both of these come from the URL of the report or dashboard when you have it open in Power BI.

Here's an example Power BI report URL:

https://app.powerbi.com/groups/89b63c7c-e8ab-4322-b1e6-cabb581c1d94/reports/90983b81-7237-4b0d-902c-5b8c196c205e/93a0bdd07004584f8f3b?experience=power-bi

Breaking that down:

• Workspace ID: 89b63c7c-e8ab-4322-b1e6-cabb581c1d94 — the ID right after /groups/.
• Report ID: 90983b81-7237-4b0d-902c-5b8c196c205e — the ID right after /reports/. This is only the first ID segment.
• Page ID: 93a0bdd07004584f8f3b — the ID right after the Report ID, before ?experience=.... This is a separate value from the Report ID.

For dashboards, the process is the same, except the URL contains /dashboards/ instead of /reports/. Dashboards don't have pages, so there's no Page ID to worry about.

Setting up a Screenshot job? You'll also need the Page ID — the ID right after the Report ID in the URL. This is what tells Q-Play which specific page of the report to screenshot. Since dashboards don't have pages, this only applies to Report Screenshot jobs.

Step 8: Screenshot size and fitment

These settings only appear for Report Screenshot and Dashboard Screenshot job types.

Report/Dashboard Width & Height — this sets the resolution the screenshot is rendered at, like setting a virtual screen size for Power BI to render into. It doesn't need to exactly match your physical display's resolution, but it's a good starting point if you're not sure what to use.

For Dashboard Screenshot jobs specifically, there's an extra setting:

Dashboard fitment — controls how the dashboard is scaled into the screenshot:

• Fit to width — scales the dashboard to match the width you set.
• Actual size — renders the dashboard at its real size, with no scaling.

Power BI dashboards aren't dynamic like reports — they don't automatically reflow. If the dashboard's elements are large, Fit to width may make them look stretched or oddly proportioned. If that happens, try Actual size instead, or adjust the width/height to better match the dashboard's actual layout.

Step 9: Scheduling

Schedule type controls when the job actually runs:

• On-demand — the job only runs when it's actively being used (i.e. displayed), and only after the Resource timeout has passed since the last run.
• Scheduled — the job runs automatically on a set interval, regardless of whether it's currently being displayed.

Note: "Resource timeout" and "Refresh schedule" describe how often a new screenshot is generated. This wording applies to Report Screenshot and Dashboard Screenshot jobs specifically — for live Report/Dashboard jobs, there's nothing being "refreshed" since the content is already live, so Schedule type is the only setting that matters there.

Resource timeout (On-demand only) — the minimum time that must pass between screenshots. This prevents the job from re-running more often than necessary while it's actively in use.

Refresh schedule (Scheduled only) — how often a new screenshot should automatically be generated, e.g. every hour.

Step 10: Run a job

Jobs don't run automatically the moment the integration is set up — you need to trigger a run yourself to confirm the connection works and see a result.

You can do this in one of two ways:

From the Overview page: Click the ▶ (play) icon next to any job in the Jobs list.

From inside a specific job: Open the job, then click Run Job Now in the top-right corner.

Either way, the run will appear in Recent Runs once it's finished, showing whether it succeeded or failed. If it fails, see the troubleshooting section below.

What's next?

Once your job is set up and running successfully, the data itself is ready — but nothing will show on a screen yet. The integration only stores the connection; actually displaying the report or dashboard happens in the Q-Play app.

See Power Bi Enterprise app setup guide for how to add your job's output to a screen.

Troubleshooting failed jobs

If a job shows a Failed or Error status, you can check exactly what went wrong in the logs.

How to check the logs

Each job run has its own log.

• Click on a specific run in the Recent Runs table to open its individual log.
• Or click View logs to see logs across all runs.

The log will show a timestamped error message, usually including an HTTP status code and an error code — this tells you what actually went wrong.

Common errors and what they mean

If you run into an error that isn't listed here, contact support and include the full error message from the log — it'll help us identify the issue faster.