# Power BI Integration Power BI Integration allows administrators and content designers to embed Microsoft Power BI reports and dashboards directly inside OtisEd.Nimble portal pages. Users see live, interactive Power BI content without leaving the portal, while the portal handles all authentication in the background. ## Table of Contents * [Overview](#overview) * [How Embedded Reports Work](#how-embedded-reports-work) * [Administrator Setup](#administrator-setup) * [Configuring Power BI Connection Settings](#configuring-power-bi-connection-settings) * [Adding a Power BI Report to a Dashboard](#adding-a-power-bi-report-to-a-dashboard) * [Required Properties](#required-properties) * [Optional Display Properties](#optional-display-properties) * [Viewing and Interacting with Embedded Reports](#viewing-and-interacting-with-embedded-reports) * [Report Types](#report-types) * [Troubleshooting](#troubleshooting) *** ## Overview The Power BI Integration connects the portal to your organization's Microsoft Power BI service. Once an administrator provides the necessary Azure app registration credentials, any report or paginated report published to a Power BI workspace can be surfaced on a portal dashboard as a card. Viewers interact with the report — filtering data, navigating pages, and exploring bookmarks — entirely within the portal. Key capabilities: * Embed standard Power BI reports and paginated reports (RDL) * Display inside the Container Designer as a "Power BI" card * Per-card control over filters, page navigation, bookmarks, status bar, and background * Optional workspace override per card, or a shared default workspace for the whole site * Automatic token management — access tokens are cached and refreshed transparently *** ## How Embedded Reports Work When a user views a page that contains a Power BI card, the portal: 1. Authenticates to Microsoft Entra ID (Azure AD) using the service account credentials stored in Site Settings. 2. Retrieves the target report's embed URL from the Power BI REST API. 3. Generates a short-lived, read-only embed token scoped to that specific report. 4. Passes the embed URL and token to the browser, where the Power BI JavaScript SDK renders the report inside the card. The user's browser never holds an Azure credential. The embed token grants read-only access to that single report. Tokens are cached on the server for up to one hour (with a five-minute safety buffer) to avoid a new API call on every page load. *** ## Administrator Setup ### Configuring Power BI Connection Settings Before any Power BI card can display content, a system administrator must configure the Azure app registration that the portal uses to communicate with Power BI. **Where to find these settings:** Administration menu > Site Settings > Power BI Settings section **Fields to complete:** | Field | Description | | -------------------- | ---------------------------------------------------------------------------------------------- | | Entra Application ID | The Application (client) ID from your Azure app registration | | Entra Tenant ID | The Directory (tenant) ID of your Azure AD organization | | Default Workspace ID | The Power BI workspace (group) GUID used when a card does not specify its own workspace | | Client Secret | The client secret generated for the app registration — stored securely and masked after saving | **Prerequisites in Azure and Power BI:** 1. Create an app registration in Azure Entra ID (Azure AD). The app needs the `Power BI Service > Report.Read.All` API permission (application permission, not delegated). 2. Grant admin consent for the permission in Azure. 3. In Power BI Admin Portal, enable "Allow service principals to use Power BI APIs" and add the app registration's service principal to the workspace (or to an Entra security group that has workspace access). 4. Copy the Application ID, Tenant ID, and a client secret into Site Settings. Once saved, the portal validates credentials when a report card first loads. If credentials are missing or incorrect, the card displays an error message. **To update or rotate the client secret:** Enter the new secret value in the Client Secret field and save. The portal always uses the value most recently saved. To remove the secret entirely, use the "Clear existing client secret" button that appears after a secret has been saved. *** ## Adding a Power BI Report to a Dashboard Power BI reports are added to dashboards using the Container Designer. The card type is listed under the "Data Visualization" category as "Power BI." For general instructions on adding cards and editing dashboards, see the Container Designer guide. ### Required Properties **Report ID** The GUID that identifies the specific Power BI report to embed. Find this ID in the report's URL in the Power BI service: `https://app.powerbi.com/groups/{workspace-id}/reports/{report-id}/...` Copy the segment labeled `{report-id}` and paste it into the Report ID field. The field accepts the standard GUID format: `00000000-0000-0000-0000-000000000000`. ### Optional Display Properties **Workspace ID** The GUID of the Power BI workspace that contains the report. If left blank, the card uses the Default Workspace ID configured in Site Settings. Provide a workspace ID here when the report lives in a different workspace from the default. **Title and Description** A card-level title and optional description that appear above the embedded report. The title alignment can be set to left, center, or right. **Hide Title** When enabled, the title area is removed entirely and the embed fills the full card height. The following settings fall under the **Report Display** group in the card properties panel: | Property | Default | Effect | | ---------------------- | ------- | ---------------------------------------------------------------------------------------------------- | | Show Filters | Off | Shows or hides the report's filter pane | | Show Page Navigation | Off | Shows or hides the page navigation control | | Transparent Background | On | Report background inherits the card's styling instead of using white | | Default Page | (empty) | Load a specific report page first (e.g., `ReportSection3`). Leave empty for the report's own default | | Show Status Bar | Off | Shows or hides the zoom/status bar at the bottom of the report | | Show Bookmarks | Off | Shows or hides the bookmarks pane | | Hide Border | Off | Removes the card border | Note: Filter pane, page navigation, bookmarks, status bar, and default page settings apply to standard Power BI reports only. Paginated reports (RDL) use their own built-in rendering and these settings are not applied. *** ## Viewing and Interacting with Embedded Reports When a page containing a Power BI card loads, the report appears inside the card after a brief loading indicator. The report is fully interactive within its card boundaries. **What users can do:** * Click on visuals to apply cross-filtering across the report * Use the filter pane (if enabled by the card configuration) to apply or clear filters * Navigate between report pages using the page navigation bar (if enabled) * Apply and navigate bookmarks (if enabled) * Zoom and use status bar controls (if enabled) * Hover over visuals for tooltips **What users cannot do:** * Edit or publish back to Power BI (all embeds are read-only) * Export report data (export capability is controlled by the Power BI workspace settings, not the portal) The card automatically sizes itself to fill the available space and adjusts the embedded report height when the browser window or dashboard layout changes. *** ## Report Types The integration supports two types of Power BI content: **Standard Reports** Interactive reports built in Power BI Desktop. All display options (filters, page navigation, bookmarks, status bar, background, default page) are available. **Paginated Reports (RDL)** Print-optimized, pixel-perfect reports. These render with their own layout controls built in. The portal correctly detects this type and skips the standard report display settings, which do not apply to paginated reports. The report type is detected automatically from the Power BI API response. No additional configuration is needed. *** ## Troubleshooting **"Could not get Power BI embed token. Please check the report configuration."** The portal connected to the Power BI API but could not generate an embed token for the specified report. Common causes: * The Report ID in the card properties is incorrect or belongs to a different workspace than the one specified. * The service principal (app registration) does not have access to the workspace containing the report. Add the service principal or its security group as a workspace member in Power BI. * The Workspace ID in the card does not match the workspace containing the report. **"Failed to load Power BI report. Please check the report ID."** The portal could not retrieve report details from the Power BI API. Common causes: * The Report ID GUID is malformed or belongs to a workspace the service principal cannot access. * The Azure app registration credentials in Site Settings are incomplete or incorrect. * The Power BI API service is temporarily unavailable. **"Please configure a Report ID in the card properties."** No Report ID has been entered in the card's properties. Open the card in the Container Designer and enter a valid Power BI report GUID. **Report appears blank or shows a Power BI error screen** * Confirm the report is published (not in Draft) in the Power BI service. * Confirm the report is in the workspace indicated by either the Workspace ID card property or the Default Workspace ID in Site Settings. * Verify the service principal has at least Viewer access to the workspace. **Site Settings credentials** If no Power BI credentials are configured in Site Settings, every Power BI card on every page will fail to load. An administrator must supply the Entra Application ID, Entra Tenant ID, Client Secret, and Default Workspace ID before cards can function. --- # Agent Instructions: 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: ``` GET https://nimble.docs.otised.com/guides/powerbi-integration.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.