How to embed reports into third-party systems - Quick BI

Quick BI lets you embed reports, such as dashboards and workbooks, from a workspace into third-party systems for seamless business integration. This solution applies to Quick BI Pro and Quick BI Standard.

Limits

The basic solution supports embedding only dashboards and workbooks.
When you embed a workbook data entry page into a third-party environment, some system browsers may prevent cross-origin iframes from writing cookies. This can cause data submission to fail on complex workbook data entry pages. For example, if you open an embedded workbook data entry page in the built-in browser of WeCom on an iOS device, data submission fails after you fill in and submit the data.

Therefore, we recommend that you use the workbook data entry feature directly on the Quick BI platform.

Background information

To embed Quick BI reports in your system, you must configure report embedding.
- If you use Quick BI Pro, you cannot differentiate database permissions after embedding a report. Row-level permissions do not take effect for the embedded report, and the permissions are the same as those of the report author. The security enhancement solution is not supported.
- If you use Quick BI Standard, you can differentiate database permissions after embedding a report. This means that for the same report, different users see different data. The security enhancement solution is also supported. For more information, see Security Enhancement Solution for Embedded Data Permission Control and Parameter Transmission in Reports.
Alibaba Cloud International has five sites with the following domain names:
- Singapore: bi-ap-southeast-1.data.aliyun.com
- Hong Kong (China): bi-cn-hongkong.data.aliyun.com
- Malaysia (Kuala Lumpur): bi-ap-southeast-3.data.aliyun.com
- Germany (Frankfurt): bi-eu-central-1.data.aliyun.com
- Indonesia: bi-ap-southeast-5.data.aliyun.com

Note

This topic uses the domain name for the Hong Kong (China) site as an example for URL construction. When you use other sites, replace the domain name with the one that corresponds to your site.

Step 1: Enable embedding for the report

You can configure report embedding only for reports that are in the Published state.

You can enable report embedding from the Open Platform module:

On the Quick BI homepage, follow the steps in the figure to go to the Embed Report page.
On the Add Embedded Report page, select the target workspace and object type. In the list, select the desired report and click Enable Embedding. If the list is long, you can also search for a report by entering its name.

Note
To embed workbook data entry pages into a third-party environment, be aware that some system browsers prohibit cross-origin iframes from writing cookies. This can cause data submission to fail. Therefore, we recommend that you use the workbook data entry feature directly on the Quick BI platform.

Embedding configuration

The test feature for configuring report embedding applies only to the enhanced solution.

Important

The test feature is for trial purposes only. For actual use, you must complete Step 2: Obtain an accessTicket through an HTTPS interface and Step 3: Construct the login-free URL.

After you enable embedding, the basic and enhanced solutions offer different capabilities during integration:

Capability	Basic solution	Enhanced solution
Bound user	Report owner, cannot be modified	Customizable, allows for personalized views
Number of visits	Up to 100,000 times per ticket	Unlimited, supports custom settings
Watermark	Not supported	Support (unless the data screen itself does not support watermarks)
Validity period	Maximum 240 minutes	Customizable
Global parameters	Not supported	Support
Block embedding	Not supported	Supported
Number of jumps Note The target report for the jump must also have embedding enabled.	Only one jump is allowed. For example, after jumping from report A to report B, report B cannot jump to report C.	Supports an unlimited number of jumps. For example, after jumping from report A to report B, report B can jump to report C, and so on.

Step 2: Obtain an accessTicket through an HTTPS interface

The following example shows how to embed a dashboard from a workspace into a third-party system.

If the account that enables dashboard access has Developer or Analyst permissions, it can enable permissions only for dashboards created by that account.
If the account has Admin permissions, it can enable permissions for all reports in the workspace.
1. Follow the steps below to obtain an AccessKey ID and AccessKey secret. These correspond to accessId and accessKey.
  1. Log on to the Quick BI console.
  2. On the Quick BI homepage, follow the steps in the figure to obtain the AccessKey ID and AccessKey secret.
2. Obtain the Alibaba Cloud account ID. This corresponds to aliyunUid.
  
  Log on to your Alibaba Cloud account and click your profile picture in the upper-right corner to view your account ID.
3. On the report editing page, obtain the report ID. This corresponds to worksId:
4. Obtain the accessTicket.
  
  Append the accessId, accessKey, aliyunUid, and worksId parameters that you obtained in the previous steps to the following request URL. Then, send a GET request to obtain the accessTicket.
  
  https://bi-cn-hongkong.data.aliyun.com/openapi/ac3rd/ticket/create?worksId=xx&aliyunUid=xx&accessKey=xx&accessId=xx&validityTime=xx
  Note
  
  The account used to obtain the accessTicket has the following restrictions:
  
  If the account is disabled in Organization Management > User Management, you cannot generate new accessTickets, but you can continue to use existing ones.
  
  If the account is deleted from Organization Management > User Management, you cannot generate new accessTickets, and you cannot continue to use existing ones.
  
  The aliyunUid is used only to verify whether the current role has permission to enable login-free access for organization reports when you generate an accessTicket. It is not used for identity binding in third-party embedded reports.
  
  validityTime is an optional parameter. The value can range from 1 to 240. The default value is 240. The unit is minutes.
  
  To immediately invalidate an accessTicket, send a POST request with the corresponding values for aliyunUid, accessId, accessKey, and accessTicket.
  
  http://bi-cn-hongkong.data.aliyun.com/openapi/ac3rd/ticket/invalid?aliyunUid=xx&accessId=xx&accessKey=xx&accessTicket=xx

Step 3: Construct the login-free URL

Note

This solution does not support authentication for bound users. By default, the login-free report is accessed with the identity of the report owner.

The following table shows the construction process and examples.

Process	Dashboard example	Sample Workbook
1. Obtain the Quick BI domain name	`bi-cn-hongkong.data.aliyun.com/`	`bi-cn-hongkong.data.aliyun.com/`
2. Obtain the report preview URL	`token3rd/dashboard/view/pc.htm`	`token3rd/report/view.htm`
3. Obtain the report ID	`dd0****83f`	`42****18ef6`
4. Obtain the AccessTicket	`fd138bcb-****-4fde-b413-81bcee59bdb6`	`fd138bcb-****-4fde-b413-81bcee59bdb6`

The construction format and report URLs are as follows.

The format for a dashboard is https://<Quick BI domain name>/<Report preview URL>?pageId=<Report ID>&accessTicket=<AccessTicket>. The generated URL is:
```
https://bi-cn-hongkong.data.aliyun.com/token3rd/dashboard/view/pc.htm?pageId=dd0****83f&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6
```
The format for a workbook is https://<Quick BI domain name>/<Report preview URL>?id=<Report ID>&accessTicket=<AccessTicket>. The generated URL is:
```
https://bi-cn-hongkong.data.aliyun.com/token3rd/report/view.htm?id=<42****18ef6>&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6
```

Obtain the Quick BI domain name.

For example, the domain name for the Quick BI site in Hong Kong (China) is bi-cn-hongkong.data.aliyun.com/. You must use the domain name for your specific environment.
Obtain the report preview URL.

The preview page URLs for reports are as follows. Select the one that you need.
- Dashboard: token3rd/dashboard/view/pc.htm
- Workbook: token3rd/report/view.htm
On the report editing page, obtain the report ID.
- Dashboard ID
  
  On the dashboard editing page, obtain the value of pageId from the address bar.
- Workbook ID
  
  On the workbook editing page, obtain the value of the workbook ID from the address bar.
Append the Quick BI domain name, report preview URL, report ID, and the AccessTicket that you obtained in Step 2 to the request URL.
- Dashboard format: https://<Quick BI domain name>/<Report preview URL>?pageId=<Report ID>&accessTicket=<AccessTicket>
- Workbook format: https://<Quick BI domain name>/<Report preview URL>?id=<Report ID>&accessTicket=<AccessTicket>

Manage embedded reports

You can perform the following operations on embedded reports:

Query embedded reports: In the search box on the report list page, enter a keyword from the report name and click the icon to search for the report.

You can narrow the search by selecting the workspace or type of the report.
View the number of embedded reports. For more information, see View the number of embedded reports.
Delete an embedded report: Click the icon next to the report to delete it.

View the number of embedded reports

On the Quick BI homepage, click Open Platform.
In the navigation pane on the left, click Embedded Analytics.

On the Report Embedding page, you can view the number of reports that are embedded in third-party systems.

How to resolve the "access report_tree unauthorized" error during report embedding

Problem description

When you use the third-party report embedding feature, the error message that is shown in the following figure appears.

Causes

Report permissions are not enabled in the corresponding workspace.

Solution

You can follow these steps to enable report permissions.

How to make an embedded Quick BI report auto-adjust its height (PC)

Problem description

When a third-party system uses an iframe to embed a Quick BI dashboard, the dashboard may display a scroll bar because cross-domain security restrictions prevent the system from obtaining the iframe content height.

Solution

When Quick BI loads a dashboard, it sends the dashboard height to the parent page through postMessage. The parent page can retrieve the height and ID by using an event listener.

You can do this in one of the following two ways:

Pass the iframe content height to the parent page.

// The Quick BI URL. You can add other URLs as needed.
const quickBIURL = ['https://bi-cn-hongkong.data.aliyun.com/'];
function messageListener(event) {
  if (quickBIURL.includes(event.origin)) {
    // The height passed by postMessage
    console.log('Quick BI Dashboard Height:', event.data.height);
    // The dashboard page ID passed by postMessage
    console.log('Quick BI Dashboard Id:', event.data.pageId);
  }
}
// Add the listener before the dashboard loads
window.addEventListener('message', messageListener);

The parent page sends a postMessage to the iframe page to obtain the dashboard height.

Note:

The iframe is the one that embeds the Quick BI dashboard.
The data passed in the message must include { getDashboardHeight: true }.

The following code block provides an example.

// The Quick BI URL. You can add other URLs as needed.
const quickBIURL = ['https://bi-cn-hongkong.data.aliyun.com/'];
function messageListener(event) {
  if (quickBIURL.includes(event.origin)) {
    // The height passed by postMessage
    console.log('Quick BI Dashboard Height:', event.data.height);
    // The dashboard page ID passed by postMessage
    console.log('Quick BI Dashboard Id:', event.data.pageId);
  }
}
// Add the listener before the dashboard loads
window.addEventListener('message', messageListener);
// Actively request the Quick BI dashboard height
// The iframe that embeds the Quick BI dashboard
const iframe = document.querySelector('iframe');
// The data passed in the message must include { getDashboardHeight: true }
iframe.contentWindow.postMessage({getDashboardHeight: true}, '*');

Note

A Quick BI dashboard automatically adjusts its width to the outer container, which eliminates the vertical scroll bar and the need for manual width adjustment.

Complete example

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    </head>
    <body>
        <iframe 
        class="quickbi-iframe-demo"
    src="https://bi-cn-hongkong.data.aliyun.com//token3rd/dashboard/view/pc.htm?pageId=dd0****83f&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6"
      scrolling="no"
     frameborder="0" 
      width="100%" 
      height="600">
    </iframe>
   <!-- <useBodyAutoHeight=true> makes the page body height adaptive. <page_Id> is the dashboard page ID. accessTicket is the token for accessing the dashboard. -->
        <script>
      // The Quick BI URL. You can add other URLs as needed.
      const quickBIURL = ['https://bi-cn-hongkong.data.aliyun.com'];
      function messageListener(event) {
        if (quickBIURL.includes(event.origin)) {
          // The height passed by postMessage
          console.log('Quick BI Dashboard Height:', event.data.height);
          // The dashboard page ID passed by postMessage
          console.log('Quick BI Dashboard Id:', event.data.pageId);
        }
      }
      // Add the listener before the dashboard loads
      window.addEventListener('message', messageListener);
      // The iframe that embeds the Quick BI dashboard
      const iframe = document.querySelector('iframe');
       // Actively request the Quick BI dashboard height
      // The data passed in the message must include { getDashboardHeight: true }
      iframe.contentWindow.postMessage({getDashboardHeight: true}, '*');
        </script>
    </body>
</html>

How to set the width for a mobile page embedded in a third-party application using an iframe

Problem description

Due to iframe compatibility issues on earlier versions of iOS, the iframe width may overflow. This can cause the dashboard to scroll horizontally, fixed-list tables to stop scrolling, charts to be truncated, or query control pop-ups to be misplaced.

Solution

Modify the iframe style.

Strictly follow the example code below:

iframe {
    border-width: 0;
    min-width: 100%;
    width: 0;
    *width: 100%;
    height: 667px; /* The height must be a fixed value. You can set it dynamically after getting the screen height. height: 100% has compatibility issues. */
}