Embed a quick report in a Power BI embedded analytics application for your organization

  • Article

Power BI Client APIs allow you to quickly create an interactive report and dataset from your application's data without your users ever needing to leave your app. By using this client-side library, you'll provide information about the data source, which Power BI will use to generate a dataset within the Power BI service. At the same time, Power BI will automatically generate a report with insights about the data for your users to explore and customize to meet their needs.

In this tutorial, you'll learn how to:

  • Set up your embedded environment
  • Configure an object to store information about your data source and customize your report
  • Pass this object to the API to add data exploration capabilities to your app

To use this experience, your users will need to sign into Power BI.

You'll use a configuration object to store information about your data source. Additionally, you can also use the configuration object to customize your report's appearance and behavior. For instance, you can adjust the theme, and location settings in the configuration object. When you create and embed the dataset, you then pass that object to the API.

Important

If you are embedding content for a national cloud, the first few steps of this tutorial are different. See Embed content for national clouds for details.

Prerequisites

Before you start this tutorial, verify that you have both the Power BI and code dependencies listed below:

Method

The following sections explain how to embed and configure Power BI content using your favorite text editor.

The IQuickCreateConfiguration interface displays properties that a configuration object can supply to the Power BI Client APIs about the dataset you want to create:

Example

interface IQuickCreateConfiguration { 
    type?: "quickCreate"; 
    accessToken: string; 
    settings?: ISettings; 
    tokenType?: TokenType; 
    theme?: IReportTheme; 
    embedUrl?: string; 
    datasetCreateConfig: IDatasetCreateConfiguration; 
    reportCreationMode?: ReportCreationMode; 
    eventHooks?: EventHooks; 
}

Access token permission to QuickCreate

QuickCreate only supports AAD tokens. Make sure your application has the following scopes:

  • Content.Create
  • Dataset.ReadWrite.All
  • Report.Read.All
  • Workspace.Read.All

See Register an app to embed Power BI content for more information.

Embed Url

Unique to this form of embedding, this experience has a special route /quickcreate. A typical embed Url for this experience looks like this: https://app.powerbi.com/quickcreate

Step 1.1 - Create a dataset without a data source

PowerBI provides a simple way to let developers include data directly in the request to Power BI if you are unable to set up a data source. We do limit the size of the request to 16MB. Note that, because there is no data source for Power BI to connect to, you can't refresh the dataset after creation.

  1. IDataTable

    IDataTable is essentially a wrapper of a 2D string array where you should fill in your data. Although data is an array, we only support 1 data table for now. The name can be set by you, but it needs to match the name in ITableSchema.

    In order for Power BI to parse your data in the correct format, your data values should be formatted following the M language value specification. The locale property defined in IQuickCreateConfiguration also affects the parsing of the values. See M Language values - PowerQuery M to learn more.

    Your data should be passed in in rows. Each row should contain the same number of columns defined in ITableSchema.  

    Note

    Data and tableSchemaList must come in pairs.

Example

const data: IDataTable = [
    { "name": "MyTableName", 
      "rows": [ 
              ["1", "1", "1991"], 
              ["1", "1", "1991"], 
        ]
    } 
]

Note

Currently, the name property can't be customized, so you can't name a table. The default name for the property is "Table".

  1. ITableSchema

    For Power BI to understand your data, you need to provide the schema for each column of the table. Each column schema needs to have a name and a type. The name will be used as the field list name after the dataset is created. The type is a subset of the M Language type specification. The supported types are conveniently listed in DataType. See M Language types - PowerQuery M to learn more.

    Similar to the data property, although tableSchemaList is defined as an array, we only support single table for now.

    export const enum DataType { 
    Number = "Number", 
    Currency = "Currency", 
    Int32 = "Int32", 
    Percentage = "Percentage", 
    DateTime = "DateTime", 
    DateTimeZone = "DateTimeZone", 
    Date = "Date", 
    Time = "Time", 
    Duration = "Duration", 
    Text = "Text", 
    Logical = "Logical", 
    Binary = "Binary",  
    }

    In addition to name and dataType, users can specify default aggregation on columns by providing an optional property aggregateFunction for each column. The number for supported aggregate functions are based on the AggregateFunction Enum type.

Example

const tableSchemaList: ITableSchema = [{ 
    name: "MyTableName",  
    columns: [ 
        { 
            name: "createdby", 
            dataType: DataType.Text
             aggregateFunction: 6 // Count 
        }, 
        { 
            name: "createdon", 
            dataType: DataType.DateTime 
        }, 
        { 
            name: "size", 
            dataType: DataType.Number 
        } 
    ]     
}];   
const data: IDataTable = [
    { 
        "name": "MyTableName", 
        "rows": [ 
                ["1", "1", "1991"],
                ["1", "1", "1991"],
        ]
    }
] 
const datasetCreateConfig: IDatasetCreateConfiguration = {
    "modelName": "my model", 
    "locale": "en_US", 
    "tableSchemaList": tableSchemaList,
    "data": data
}

Step 1.2 - Create a dataset with your existing data source

IDatasetCreateConfiguration is a configuration that lets Power BI know how to create the dataset. This includes the Mashup document, the locale of the dataset, and the connection information that tells Power BI how to connect to your data source.

Mashup document

Mashup documents, or M documents, have their own language specifications. For the purposes of this embed experience, the easiest way to start is to connect to the data source of your choice in Power BI Desktop and then copy the resulting mashup query out of the query editor view. Read the Query Editor documentation for Power BI Desktop for details.

Example

Let Source = Csv.Document(Web.Contents("https://yourdomain.com/sample.csv"), [Delimiter=",", QuoteStyle=QuoteStyle.None]), #"Promoted Headers" = Table.PromoteHeader(Source, [PromoteAllScalars=true]) in #"Promoted Headers";"

To turn the source code above into a mashup document, you just need to add a section. A section includes:

  • section-name;
  • shared section-member-name = expression;
  • where expression will be your mashup query,
  • and section-member-name will show up in Power BI as table/entity name.

For the sample mashup query provided above, here is a corresponding mashup document example:

"section Section1; shared #"Table" = let Source = Csv.Document(Web.Contents("https://yourdomain.com/sample.csv"), [Delimiter=",", QuoteStyle=QuoteStyle.None]), #"Promoted Headers" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]) in #"Promoted Headers";"

  Once you have your mashup document, you can identify which parts will be static and which parts will be dynamic and can be filled in programmatically. In the example above, we have some adjustable variables, the web content domain, the delimiter, the quote style, and if you want to promote the headers or not. Therefore, the query can be turned into a template and populated with the appropriate parameters on the hosting application side, depending on data the user is consuming at the time.

Locale

PowerBI will use the locale information provided in this configuration to evaluate the mashup document and parse values if raw data is provided.

Data source configuration

Authorization to the data source

Currently, we only support anonymous connection to data sources. This means Power BI needs to be able to connect to your data source without requiring authentication.

Note

If you include the data directly in the request, you should omit the dataSourceConnection property.

DataCacheMode

For most data sources, Import mode should suit your needs. However, in some cases where data changes quickly or when data sources are very big, you can also use the DirectQuery mode. If you think this might apply to you, read learn more about DirectQuery in Power BI.

Note

If you include raw data in the request, the DataCacheMode must be imported.

Sample

const datasetCreateConfig: IDatasetCreateConfiguration = { 
    "modelName": "temp model", 
    "locale": "en_US", 
    "mashupDocument": "section Section1; shared Table = let Source = Csv.Document(Web.Contents(\"https://yourdomain.com/sample.csv\"),[Delimiter=\",\", QuoteStyle=QuoteStyle.None]), #\"Promoted Headers\" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]) in #\"Promoted Headers\";", 
    "dataSourceConnection": { 
        "credentialType": CredentialType.Anonymous, // =1 
        "dataCacheMode": DataCacheMode.Import // =1 
    } 
}

Step 2 - Create a dataset and auto-generate report

Now with the datasetCreateConfig set, you're ready to generate the dataset and embed an auto-generated report. This is similar to the createReport method that allows you to create in report embed, the quickCreate method that takes in an iframe container, and the quickCreateConfig method that helps you embed the report.

Example

const powerbi = window.powerbi; 
const iframeContainer = document.getElementById("myIframeContainer"); 
const quickCreateConfig: IQuickCreateConfiguration = { 
    type: "quickCreate", 
    accessToken: "ey.....",  
    tokenType: TokenType.Aad, // Aad token only 
    embedUrl: "https://app.powerbi.com/quickcreate", // see below for generating the embed url 
    datasetCreateConfig: datasetCreateConfig, 
    reportCreationMode: ReportCreationMode.QuickExplore, // QuickExplore for auto-generated visual,    
    settings: { 
        localeSettings: { 
            language: "en_US" // this should match the current locale of your window/product. It will be used to localize the UI. 
        } 
    } 
}; 
const quickCreateReport = powerbi.quickCreate(iframeContainer, quickCreateConfig);

Next Steps

Understanding the different embedding solutions

Embed a report in Power BI embedded analytics