PowerBI Component - Complete Documentation

Table of Contents

• Overview
• Installation
• Basic Usage
• Inputs
• Outputs
• Usage Examples
• Best Practices

Overview

The ngx-powerbi-component embeds Microsoft Power BI reports, dashboards, and tiles in your Angular application. Features include:

• Embed Power BI Reports
• Embed Power BI Dashboards
• Embed Power BI Tiles
• AAD and Embed token support
• Configurable settings
• Event handling

Installation

npm install ngx-st-powerbi powerbi-client powerbi-models

Import the module:

import { NgxStPowerBiModule } from 'ngx-st-powerbi';

@NgModule({
  imports: [NgxStPowerBiModule]
})
export class AppModule { }

Basic Usage

// Component
@Component({
  selector: 'app-report',
  template: `
    <ngx-powerbi-component
      [accessToken]="accessToken"
      [tokenType]="tokenType"
      [embedUrl]="embedUrl"
      [id]="reportId"
      [type]="reportType"
      (embedded)="onEmbedded($event)">
    </ngx-powerbi-component>
  `,
  styles: [`
    ngx-powerbi-component {
      display: block;
      height: 600px;
    }
  `]
})
export class ReportComponent {
  accessToken = 'your-access-token';
  tokenType = TokenType.Embed;
  embedUrl = 'https://app.powerbi.com/reportEmbed';
  reportId = 'report-guid';
  reportType = ReportType.Report;
  
  onEmbedded(result: number): void {
    console.log('Report embedded');
  }
}

Inputs

accessToken

• Type: string
• Required: Yes
• Description: Power BI access token (AAD or Embed token).
• Example:

  [accessToken]="myAccessToken"

tokenType ⭐ (Required)

• Type: TokenType ('Aad' | 'Embed')
• Required: Yes
• Description: Type of authentication token being used.
• Example:

  import { TokenType } from 'ngx-st-powerbi';
    
  tokenType = TokenType.Embed;  // or TokenType.Aad

embedUrl

• Type: string
• Required: Yes
• Description: The embed URL for the Power BI content.
• Example:

  embedUrl="https://app.powerbi.com/reportEmbed?reportId=xxx&groupId=xxx"

id

• Type: string
• Required: Yes
• Description: The unique identifier (GUID) of the report, dashboard, or tile.
• Example:

  [id]="reportId"

type

• Type: ReportType ('Report' | 'Dashboard' | 'Tile')
• Required: Yes
• Description: Type of Power BI content to embed.
• Example:

  import { ReportType } from 'ngx-st-powerbi';
    
  type = ReportType.Report;      // For reports
  type = ReportType.Dashboard;   // For dashboards
  type = ReportType.Tile;        // For tiles

name

• Type: string
• Required: No
• Description: Display name for the embedded content.
• Example:

  name="Sales Report"

options

• Type: models.ISettings
• Required: No
• Description: Power BI embed configuration settings.
• Example:

  options: models.ISettings = {
    filterPaneEnabled: false,
    navContentPaneEnabled: true,
    background: models.BackgroundType.Transparent
  };

Outputs

embedded

• Type: number
• Description: Emitted when the Power BI content is successfully embedded.
• Example:

  (embedded)="onEmbedded($event)"
    
  onEmbedded(result: number): void {
    console.log('Power BI content embedded');
  }

Usage Examples

Example 1: Basic Report Embed

// Component
import { TokenType, ReportType } from 'ngx-st-powerbi';

@Component({
  selector: 'app-sales-report',
  template: `
    <div class="report-container">
      <h2>Sales Report</h2>
      <ngx-powerbi-component
        [accessToken]="accessToken"
        [tokenType]="tokenType"
        [embedUrl]="embedUrl"
        [id]="reportId"
        [type]="reportType"
        name="Sales Report"
        (embedded)="onReportEmbedded()">
      </ngx-powerbi-component>
    </div>
  `,
  styles: [`
    .report-container {
      height: 100vh;
      display: flex;
      flex-direction: column;
    }
    ngx-powerbi-component {
      flex: 1;
      display: block;
    }
  `]
})
export class SalesReportComponent implements OnInit {
  accessToken: string;
  tokenType = TokenType.Embed;
  embedUrl: string;
  reportId: string;
  reportType = ReportType.Report;
  
  constructor(private powerBiService: PowerBiService) {}
  
  ngOnInit(): void {
    this.loadReportConfig();
  }
  
  loadReportConfig(): void {
    this.powerBiService.getReportConfig().subscribe(config => {
      this.accessToken = config.accessToken;
      this.embedUrl = config.embedUrl;
      this.reportId = config.reportId;
    });
  }
  
  onReportEmbedded(): void {
    console.log('Sales report loaded successfully');
  }
}

Example 2: Dashboard Embed with Settings

// Component
import { TokenType, ReportType } from 'ngx-st-powerbi';
import * as models from 'powerbi-models';

@Component({
  selector: 'app-dashboard',
  template: `
    <ngx-powerbi-component
      [accessToken]="accessToken"
      [tokenType]="tokenType"
      [embedUrl]="embedUrl"
      [id]="dashboardId"
      [type]="dashboardType"
      [options]="dashboardOptions"
      (embedded)="onDashboardEmbedded()">
    </ngx-powerbi-component>
  `,
  styles: [`
    ngx-powerbi-component {
      display: block;
      height: 800px;
    }
  `]
})
export class DashboardComponent {
  accessToken = 'your-token';
  tokenType = TokenType.Embed;
  embedUrl = 'https://app.powerbi.com/dashboardEmbed?dashboardId=xxx';
  dashboardId = 'dashboard-guid';
  dashboardType = ReportType.Dashboard;
  
  dashboardOptions: models.ISettings = {
    filterPaneEnabled: false,
    navContentPaneEnabled: false,
    background: models.BackgroundType.Transparent
  };
  
  onDashboardEmbedded(): void {
    console.log('Dashboard embedded');
  }
}

Example 3: Multiple Reports with Tab Selection

// Component
@Component({
  selector: 'app-multi-report',
  template: `
    <mat-tab-group>
      <mat-tab label="Sales">
        <ngx-powerbi-component
          [accessToken]="accessToken"
          [tokenType]="tokenType"
          [embedUrl]="salesReport.embedUrl"
          [id]="salesReport.id"
          [type]="reportType">
        </ngx-powerbi-component>
      </mat-tab>
      
      <mat-tab label="Marketing">
        <ngx-powerbi-component
          [accessToken]="accessToken"
          [tokenType]="tokenType"
          [embedUrl]="marketingReport.embedUrl"
          [id]="marketingReport.id"
          [type]="reportType">
        </ngx-powerbi-component>
      </mat-tab>
      
      <mat-tab label="Finance">
        <ngx-powerbi-component
          [accessToken]="accessToken"
          [tokenType]="tokenType"
          [embedUrl]="financeReport.embedUrl"
          [id]="financeReport.id"
          [type]="reportType">
        </ngx-powerbi-component>
      </mat-tab>
    </mat-tab-group>
  `,
  styles: [`
    ngx-powerbi-component {
      display: block;
      height: 600px;
    }
  `]
})
export class MultiReportComponent {
  accessToken: string;
  tokenType = TokenType.Embed;
  reportType = ReportType.Report;
  
  salesReport = {
    id: 'sales-report-guid',
    embedUrl: 'https://app.powerbi.com/reportEmbed?reportId=sales...'
  };
  
  marketingReport = {
    id: 'marketing-report-guid',
    embedUrl: 'https://app.powerbi.com/reportEmbed?reportId=marketing...'
  };
  
  financeReport = {
    id: 'finance-report-guid',
    embedUrl: 'https://app.powerbi.com/reportEmbed?reportId=finance...'
  };
}

Example 4: With Loading State

// Component
@Component({
  selector: 'app-report-with-loader',
  template: `
    <div class="report-wrapper">
      <mat-spinner *ngIf="loading"></mat-spinner>
      
      <ngx-powerbi-component
        *ngIf="!loading"
        [accessToken]="accessToken"
        [tokenType]="tokenType"
        [embedUrl]="embedUrl"
        [id]="reportId"
        [type]="reportType"
        (embedded)="onEmbedded()">
      </ngx-powerbi-component>
    </div>
  `
})
export class ReportWithLoaderComponent implements OnInit {
  loading = true;
  accessToken: string;
  tokenType = TokenType.Embed;
  embedUrl: string;
  reportId: string;
  reportType = ReportType.Report;
  
  constructor(private powerBiService: PowerBiService) {}
  
  ngOnInit(): void {
    this.loadReport();
  }
  
  loadReport(): void {
    this.powerBiService.getEmbedToken(this.reportId).subscribe(
      config => {
        this.accessToken = config.token;
        this.embedUrl = config.embedUrl;
        this.loading = false;
      },
      error => {
        console.error('Failed to load report', error);
        this.loading = false;
      }
    );
  }
  
  onEmbedded(): void {
    console.log('Report ready');
  }
}

Example 5: Custom Report Settings

// Component
import * as models from 'powerbi-models';

@Component({
  selector: 'app-custom-report',
  template: `
    <ngx-powerbi-component
      [accessToken]="accessToken"
      [tokenType]="tokenType"
      [embedUrl]="embedUrl"
      [id]="reportId"
      [type]="reportType"
      [options]="reportSettings">
    </ngx-powerbi-component>
  `
})
export class CustomReportComponent {
  accessToken = 'token';
  tokenType = TokenType.Embed;
  embedUrl = 'embed-url';
  reportId = 'report-id';
  reportType = ReportType.Report;
  
  reportSettings: models.ISettings = {
    filterPaneEnabled: true,
    navContentPaneEnabled: true,
    background: models.BackgroundType.Default,
    layoutType: models.LayoutType.MobilePortrait,
    useCustomSaveAsDialog: false,
    visualSettings: {
      visualHeaders: [
        {
          settings: {
            visible: true
          }
        }
      ]
    }
  };
}

Best Practices

1. Manage tokens securely:

   // Get tokens from backend, never hardcode
   this.powerBiService.getEmbedToken().subscribe(token => {
     this.accessToken = token;
   });

2. Set appropriate height:

   ngx-powerbi-component {
     display: block;
     height: 600px;  /* Or 100vh for full screen */
   }

3. Handle token expiration:

   // Refresh token before expiration
   setInterval(() => {
     this.refreshToken();
   }, 55 * 60 * 1000);  // Refresh every 55 minutes

4. Use appropriate token type:

   // Use Embed tokens for end users
   tokenType = TokenType.Embed;
      
   // Use AAD tokens for authenticated users with Power BI licenses
   tokenType = TokenType.Aad;

5. Configure visibility options:

   options: models.ISettings = {
     filterPaneEnabled: false,  // Hide filters for end users
     navContentPaneEnabled: true  // Show page navigation
   };

Token Types

Embed Token

• For users without Power BI licenses
• Generated on backend using Power BI REST API
• Time-limited (typically 1 hour)
• Recommended for most scenarios

AAD Token

• For users with Power BI licenses
• Azure Active Directory authentication
• Uses user's permissions
• For authenticated organizational users

Report Types

Report

• Interactive Power BI reports
• Multiple pages
• Filters and slicers
• Export capabilities

Dashboard

• Collection of tiles
• Overview of key metrics
• Links to underlying reports

Tile

• Single visualization from dashboard
• Embedded individually
• Lightweight

Common Use Cases

1. Analytics Dashboard: Embed company dashboards
2. Customer Reports: Embed reports for external customers
3. Multi-tenant Apps: Embed different reports per tenant
4. Mobile Apps: Embed reports in mobile views
5. Admin Portals: Embed administrative reports

Troubleshooting

Report not loading

• Verify access token is valid
• Check embed URL is correct
• Ensure report ID is correct
• Verify network connectivity to Power BI

Authentication errors

• Check token type matches authentication method
• Verify token hasn't expired
• Ensure proper permissions on Power BI content

This documentation covers all inputs, outputs, and usage patterns for the PowerBI component.