Delen via


Create, edit, and save an embedded report

Power BI embedded analytics allows you to create, edit, and save embedded reports. A report can be created based on an existing dataset, or you can edit an existing report. You can also save the report after it was created or edited.

How to create a report

Learn how to create a new, blank report from an existing data set.

Required access token permissions for creating a report

Generate an embed token with access to the dataset. If you use the master user authentication method, make sure your application has the following scopes: Dataset.Read.All, Content.Create, and Workspaces.ReadWrite.all. See Embed Token - Generate Token for more information.

Required client-side permissions for creating a report

The following client-side permissions are required for creating a report:

  • Create - Users can create a new report.

  • All - Users can create, view, edit, save, and save a copy of the report.

Create a new report

Create a new, blank report from an existing dataset. You will need a dataset ID and the embed URL. For example, you can use the getDatasetsInGroup REST API and retrieve the CreateReportEmbedURL. See Datasets - Get Datasets In Group for more information.

Note

You must have build or write permissions on the dataset to create a new report.

let embedCreateConfiguration = {
    tokenType: tokenType,
    accessToken: accessToken,
    embedUrl: embedURL,
    datasetId: datasetId,
    settings: settings,
    theme: theme, // optional
};

// Grab the reference to the div HTML element that will host the report
let embedContainer = $('#embedContainer')[0];

// Create report
let report = powerbi.createReport(embedContainer, embedCreateConfiguration);

You also have the option to create a report with a theme applied to it. New visuals added to the report will respect the theme style. See Apply report themes for more information.

How to edit a report

Learn how to edit an existing report and switch between View and Edit modes.

Required access token permissions for editing

Generate an embed token with access to the report. If you use the master user authentication method, make sure your application has the following scopes: Dataset.ReadWrite.All and Report.ReadWrite.All. You must also set the allowEdit: true flag for each report that the end-user needs to edit. See Embed Token - Generate Token for more information.

Required client-side permissions for editing

The following client-side permissions are required for editing a report:

  • Copy - Users can save a copy of the report by using Save As.

  • ReadWrite - Users can view, edit, and save the report.

  • All - Users can create, view, edit, save, and save a copy of the report.

Edit the report

Load your existing report in Edit mode. The report must be embedded in the same way the application embeds a regular report, and the view mode must be in Edit. Make sure that you set the viewMode parameter to models.ViewMode.Edit, and that you have the right client permissions.

let config = {
    type: 'report',
    tokenType: models.TokenType.Aad or models.TokenType.Embed,
    accessToken: YourAccessToken,
    embedUrl: YourEmbedUrl,
    id: YourEmbedReportId,
    permissions: models.Permissions.All,
    viewMode: models.ViewMode.Edit,
};

// Grab the reference to the div HTML element that will host the report
let embedContainer = $('#embedContainer')[0];

// Embed report
let report = powerbi.embed(embedContainer, config);

Your user can now edit the report based on the permissions that have been enabled.

You can also switch between the Edit and View modes after the report is loaded.

report.switchMode("view");

To switch to edit mode:

report.switchMode("edit");

How to save a report

Learn how to save a report, including additional options like saving a copy of a report and saving a report to another workspace.

Required access token permissions for saving

Generate an embed token with access to the report and dataset. If you want to save the report to another workspace, the token needs to have access to the target workspace. If you use the master user authentication method, make sure your application has the following scopes: Report.ReadWrite.All, and Workspaces.ReadWrite.all. You must also set the allowEdit: true flag for each report that the customer needs to edit. See Embed Token - Generate Token for more information.

Required client-side permissions for saving

The following client-side permissions are required for saving a report:

  • ReadWrite - Users can view, edit, and save the report.

  • Create - Users can create a new report.

  • Copy - Users can save a copy of the report by using Save As.

  • All - Users can create, view, edit, save, and save a copy of the report.

Save a report

When creating a report, the report is not saved until you call the save operation from the file menu or JavaScript.

report.save();

Save a copy of a report

Save an additional copy with a different name. The copy of the report will be saved to the same workspace as the report's dataset.

let saveAsParameters = {
    name: "newReport"
};

report.saveAs(saveAsParameters);

You can also save your report to another workspace. Make sure you have the right permissions for the target workspace.

let saveAsParameters = {
    name: "newReport"
    targetWorkspaceId: "13bbf317-fe2b-4b15-a081-94b0921c28e5"
};

report.saveAs(saveAsParameters);

Verify that the report is saved

Call report.isSaved to make sure the report is saved. This method can help prevent losing unsaved changes.

let isReportSaved = await report.isSaved();

Create a custom saveAs experience

You can create a custom saveAs dialog by adding the useCustomSaveAsDialog: true report setting to the configuration object. This setting hides the default UI dialog.

The saveAsTriggered event is raised when a user clicks on Save As in the UI. Use this information to show your custom dialog.

report.on("saveAsTriggered", function (event) {
    console.log(event);
});

To perform a save as operation, you can call report.saveAs from your custom dialog. See Save a copy of a report for more information.

let saveAsParameters = {
    name: "newReport"
    targetWorkspaceId: "13bbf317-fe2b-4b15-a081-94b0921c28e5"
};

report.saveAs(saveAsParameters);

Listen to the save and saveAs events

The saved event is raised when a save is triggered by a save or saveAs action in the UI or by using the APIs. See How to handle events for more information.

report.on("saved", function (event) {
    console.log(event);
});