Quick BI:Embed Reports Securely with Ticket-Based Authentication

Background information

Quick BI Professional Edition provides a ticket-based report embedding solution with comprehensive security controls for link access, data viewing, and user permissions. This enables low-cost integration with enterprise business systems while maintaining brand consistency.

Limits

Note the following limits for ticket-based report embedding:

• You can embed only dashboards, workbooks, data dashboards, ad hoc analysis reports, data entry reports, or reports from Downloads into other systems.

• To try the global parameters feature, contact the Quick BI operations owner.

• Quick BI Professional Edition supports the enhanced solution. The Pro edition supports only the basic solution.

  The basic solution and the enhanced solution differ as follows.

  Capability	Basic solution	Enhanced solution
  Attached user	Report owner. This value cannot be modified.	Customizable. This lets you provide different views to different users.
  Access count	Up to 100,000 times per ticket.	Unlimited. You can customize the access count.
  Watermark	Not supported.	Supported. (This does not apply if the large screen does not support watermarks.)
  Validity period	Up to 240 minutes.	Customizable.
  Global parameters	Not supported.	Supported.
  Block embedding	Not supported.	Supported.
  Number of redirects Note Embedding must also be enabled for the report to which you are redirected.	Only one redirect is allowed. For example, if Report A is redirected to Report B, Report B cannot be redirected to Report C.	An unlimited number of redirects are supported. For example, if Report A is redirected to Report B, Report B can be redirected to Report C, and Report C can be redirected to another report.

Step 1: Enable Embedding for a Report

You can configure the report embedding feature only when the report is in the Published state.

Step 2: Generate an AccessTicket

1. Call the CreateTicket API operation to generate the ticket required for report embedding.

   Note

   The following restrictions apply to accounts used to generate AccessTickets:

   • If the account is disabled in Tenant Management > User Management, you cannot generate new AccessTickets. However, existing AccessTickets remain usable.

   • If the account is deleted in Tenant Management > User Management, you cannot generate new AccessTickets, and existing AccessTickets become invalid.

   The following table describes the parameters that you can configure to generate an AccessTicket.

   Parameter name	Type	Description
   WorksId	String	The ID of the report for which embedding is enabled. Dashboards, workbooks, data dashboards, reports from Downloads, ad hoc analysis reports, and data entry reports are supported.
   CmptId	String	The ID of a widget in one of the preceding reports. To obtain the widget ID, call the QueryWorksBloodRelationship API operation.
   TicketNum	Integer	Number of tickets. Default value: 1. Recommended value: 1. Maximum value: 99999. Each time the ticket is used for access, the remaining number of times that the ticket can be used is reduced by one.
   UserId	String	The ID of the Quick BI user. This is not your Alibaba Cloud account ID. You can call the QueryUserInfoByAccount API operation to obtain the user ID. Example: fe67f61a35a94b7da1a34ba174a7****. Note Enter a value for either UserId or AccountName. If you leave both empty, the report owner is used by default. To configure row-level permissions, see Appendix 1: Configure Row-level Permissions.
   AccountName	String	The name of the user account. If the user uses an Alibaba Cloud account, such as wangwu, the format is [Alibaba Cloud account]. Example: wangwu. If the user uses a RAM user, such as zhangsan**@aliyun.cn, the format is [Alibaba Cloud account:RAM user]. Example: wangwu:zhangsan**. Note Enter a value for either UserId or AccountName. If you leave both empty, the report owner is used by default. To configure row-level permissions, see Appendix 1: Configure Row-level Permissions.
   AccountType	Integer	The type of the user account. 1: Alibaba Cloud account 3: Quick BI-specific account 5: RAM user Note If you specify AccountName, you must also specify AccountType.
   ExpireTime	Integer	Expiration time. Unit: minutes. Default value: 240. Maximum for page debugging is 240. Through the API, the maximum is the Integer upper limit.
   WatermarkParam	String	Watermark parameter for the report. Maximum length: 50 characters.
   GlobalParam	String	Global parameters for report filter conditions. Value: JSON string. Note To use the global parameters feature, contact the Quick BI operations owner.

   Note

   • To prevent link sharing, set TicketNum to 1. This setting means the generated third-party embedded link can be accessed only once.

   • When you embed a report, you can attach the WatermarkParam watermark parameter.

2. Generate the AccessTicket.

   For sample code, see SDK example.

   The following code shows an example of a returned result:

   {
     "requestId" : "7D784AB0-5B77-077E-B628-E782B58D3898",
     "result" : "fd138bcb-****-4fde-b413-81bcee59bdb6",
     "success" : true
   }

   Note

   The value of the result field is the AccessTicket generated by this API call. In this example, the AccessTicket is fd138bcb-****-4fde-b413-81bcee59bdb6.

Step 3: Concatenate the Single Sign-on URL

https://bi-cn-hongkong.data.aliyun.com/token3rd/report/view.htm?id=<42****18ef6>&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6&cmptId=XXX

1. Obtain the Quick BI domain name.

   For example, the domain name for Quick BI in the China (Hong Kong) region is bi-cn-hongkong.data.aliyun.com. Use the domain name of your environment.

2. Obtain the report preview URL.

   Preview page URLs by report type:

   • Dashboard: token3rd/dashboard/view/pc.htm

   • Workbook: token3rd/report/view.htm

   • Data dashboard: token3rd/screen/view/pc.htm

   • Downloads: token3rd/offline/view/pc.htm

   • Ad hoc analysis: token3rd/analysis/view/pc.htm

   • Data entry: token3rd/dataform/view.htm

3. On the report editing page, obtain the report ID.

   • Dashboard ID. Example: d01****c5f.

     On the dashboard editing page, obtain the value of pageId from the address bar.

     

   • Workbook ID. Example: d0****3ba88.

     On the workbook editing page, obtain the workbook ID from the address bar.

   • Data dashboard ID. Example: 3c****26b.

     On the data dashboard editing page, obtain the value of pageId from the address bar.

     

   • The Downloads ID. For example: b2****47.

     On the Downloads editing page, obtain the value of pageId from the address bar.

     

   • Ad hoc analysis ID. Example: 7f****da.

     On the ad hoc analysis editing page, obtain the value of pageId from the address bar.

     

   • Data entry ID. Example: 29****53.

     On the data entry editing page, obtain the value of pageId from the address bar.

     

4. Concatenate the Quick BI domain name, report preview URL, report ID, and the AccessTicket from Step 2 to create the request URL.

   • Dashboard URL format: https://<Quick BI domain name>/<Report preview URL>?pageId=<Report ID>&accessTicket=<AccessTicket>

   • Workbook URL format: https://<Quick BI domain name>/<Report preview URL>?id=<Report ID>&accessTicket=<AccessTicket>

   • Data dashboard URL format: https://<Quick BI domain name>/<Report preview URL>?pageId=<Report ID>&accessTicket=<AccessTicket>

   • Downloads URL format: https://<Quick BI domain name>/<Report preview URL>?pageId=<Report ID>&accessTicket=<AccessTicket>

   • Ad hoc analysis URL format: https://<Quick BI domain name>/<Report preview URL>?id=<Report ID>&accessTicket=<AccessTicket

   • Data entry URL format: https://<Quick BI domain name>/<Report preview URL>?id=<Report ID>&accessTicket=<AccessTicket>

Appendix 1: Configure Row-level Permissions

If you do not specify UserId or accountName, the embedded report uses the report owner's permissions. To attach a specific user's permissions, configure row-level permissions as shown in the following figure, then set UserId or AccountName.Row- and column-level permissions.

Appendix 2: Global Parameter Generation

Configure global parameters in the target dashboard or workbook. These parameters are used when generating AccessTickets.

[
  {
    "paramKey": "price", // Global parameter key
    "joinType": "and",   // Join type. Use 'and'.
    "conditionList": [
      {
        "operate": "=", // Operator. See the description below.
        "value": "1"    // Value. For multiple values, use an array, such as ["1", "2"].
      },
      {
        "operate": "=", // Operator. See the description below.
        "value": "2"    // Value. For multiple values, use an array, such as ["1", "2"].
      }
    ]
  },
  {
    "paramKey": "area", // Global parameter key
    "joinType": "and",   // Join type. Use 'and'.
    "conditionList": [
      {
        "operate": "in",          // Operator
        "value": ["North China","South China"]    // Value. For multiple values, use an array.
      }
    ]
  }
]

Appendix 3: Number of Embeddable Reports