All Products
Search
Document Center

:Security Enhancement Solution for Embedded Data Permission Control and Parameter Transmission in Reports

Last Updated:Jan 20, 2025

This topic describes the use of the ticket report embedding solution for seamless integration with third-party systems. It details how to manage permissions for Quick BI reports embedded in third-party systems and effectively prevent data breaches through ticket management. This solution is designed for the Professional Edition.

Note

Instructions for parameter transmission embedding:

  1. In embedded integration scenarios, you can create personalized data viewing experiences for the same report by combining global parameters with parameter injection.

  2. Parameter transmission embedding is exclusively available to enterprise customers with 100 or more general users in the Professional Edition.

Background information

Quick BI has introduced a new security-enhanced embedding analysis solution known as the ticket report embedding solution. With the Professional Edition of Quick BI, you can implement comprehensive security control over link sharing, access, and data viewing across various scenarios. This enables seamless integration with enterprise business systems, cost-effective development, and the creation of distinctive data products that align with your brand's identity.

Precautions

When utilizing the ticket report embedding solution, consider the following:

  • Currently, only dashboards, workbooks, data dashboards, Downloads, ad hoc analysis, and data entry reports are embeddable into other systems.

  • To trial the global parameter feature, please reach out to the Quick BI operations owner.

  • The enhanced solution for the international site is currently available only for the Singapore and Hong Kong (China) regions.

    Note

    The domain names for the Singapore and Hong Kong (China) sites are as follows:

    • Singapore: bi-ap-southeast-1.data.aliyun.com

    • Hong Kong (China): bi-cn-hongkong.data.aliyun.com

    This topic uses the Hong Kong (China) domain as an example for link concatenation. Replace it with the corresponding site domain when using other sites.

  • Quick BI Professional Edition offers an enhanced solution, whereas the Pro version provides a basic solution.

    The basic solution and the enhanced solution offer different capabilities. Refer to the table below for details:

    Capability

    Basic solution

    Enhanced solution

    Bind user

    Report owner, cannot be modified

    Supports customization, personalized

    Access requests

    Up to 100,000 times per ticket

    Unlimited, supports custom settings

    Watermark

    Not supported

    Supported

    (except for dashboards that do not support watermarks)

    Validity period

    Maximum 240 minutes

    Supports customization

    Global parameter

    Not supported

    Supported

    Block embedding

    Not supported

    Supported

    Number of redirects

    Note

    The redirected report also needs to be enabled for embedding.

    Only one redirect is allowed

    For example: After report A redirects to report B, report B cannot redirect to report C.

    Supports unlimited redirects

    For example: After report A redirects to report B, report B can still redirect to report C, and C can continue to redirect further, and so on.

Step 1: Enable the report to be embedded

You can configure the report embedding feature only when the report is in published status.

To enable report embedding, navigate through the open platform module:

  1. From the Quick BI product home page, use the instructions below to access the embedded report page.

    image

  2. On the Add Embedded Report page, first select the desired workspace and data object type. Then choose the data object name from the list and click Enable Embedding to proceed.image.png

    If the report list is extensive, you can also enter the report name to quickly locate the desired report.

  3. In the Report Embedding Configuration dialog box, you can configure the following settings.

    Important

    This debugging process is intended solely for experiencing the feature. For practical application, ensure to complete Step 2: Generate AccessTicket through the API interface and Step 3: Concatenate the Seamless Login URL.

    Parameter name

    Description

    Embedded Object

    Select the object to embed.

    • Select Entire Page, then the embedded object is the current dashboard.

    • Select a specific component, then the embedded object is a specific component under the current dashboard.

    Display Configuration

    After embedding, whether to carry the title of the current dashboard.

    Security Authentication Type and Ticket Link

    Select ticket authentication and generate a ticket link.

    You can manually enter the ticket link or click Quick Generate to generate a ticket.

    image

    In the ticket generation interface, you can set the bound user, validity period, watermark parameter, access requests, and global parameter.

    Obtain Embedding Code

    Supports generating URL Link and Iframe Code.

  4. Click on the Copy button.

Step 2: Generate AccessTicket through API interface

  1. Invoke the CreateTicket interface to generate the necessary ticket for report embedding.

    The parameters for generating accessTicket are described below:

    Parameter name

    Type

    Description

    WorksId

    String

    The ID of the report for which embedding is enabled.

    Currently supports dashboards, workbooks, data dashboards, Downloads, ad hoc analysis, and data entry.

    CmptId

    String

    The component ID. It is the ID of a specific component in the above reports.

    For the interface to obtain the component ID, see QueryWorksBloodRelationship.

    TicketNum

    Integer

    The number of tickets.

    • Default value: 1.

    • Recommended value: 1.

    • Maximum value: 99,999.

    Each time the ticket is used for access, the number of tickets decreases by 1.

    UserId

    String

    The UserId of Quick BI, not your Alibaba Cloud account ID.

    You can call the QueryUserInfoByAccount interface to obtain the UserId. A sample UserId is fe67f61a35a94b7da1a34ba174a7****.

    Note

    UserId and AccountName only need to fill in one. If not filled, the default is to bind the report's owner. If you need to configure row-level permissions, see Appendix 1: Configure row-level permissions.

    AccountName

    String

    The account name of the user.

    • If the user is an Alibaba Cloud account wangwu, the format is [main account], for example, wangwu.

    • If the user is a RAM account zhangsan**@aliyun.cn, the format is [main account: sub-account], for example, wangwu:zhangsan**.

    Note

    UserId and AccountName only need to fill in one. If not filled, the default is to bind the report's owner. If you need to configure row-level permissions, see Appendix 1: Configure row-level permissions.

    AccountType

    Integer

    The account type of the user.

    • 1: Alibaba Cloud account

    • 3: Quick BI self-built account

    • 5: RAM user

    Note

    If AccountName is not empty, then AccountType cannot be empty.

    ExpireTime

    Integer

    Expiration time.

    • Unit: minutes

    • Default value: 240 (This value is the upper limit for page debugging. It can be customized through the interface, with the maximum limit being the maximum value of the integer field type)

    WatermarkParam

    String

    The watermark parameter of the report.

    Must not exceed 50 characters.

    GlobalParam

    String

    The global parameter for the report filter condition.

    The value is a JSON string.

    Note

    If you need to use the global parameter capability, please contact the Quick BI operations owner.

    Note
    • For link anti-sharing control, it is recommended to set TicketNum to 1, indicating the generated third-party embedded link can be accessed only once.

    • When you embed a report, you can bind it to the WatermarkParam watermark parameter.

  2. Generate the AccessTicket.

    For sample code, please refer to the SDK example.

    The API call returns the following result:

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

    The result represents the AccessTicket generated by this API call, which is fd138bcb-****-4fde-b413-81bcee59bdb6.

Step 3: Concatenate seamless login URL

The process and examples for URL concatenation are shown in the following table.

Process

Dashboard example

Workbook example

Downloads example

Data dashboard example

Ad hoc analysis example

Data entry example

1. Obtain Quick BI domain name

bi-cn-hongkong.data.aliyun.com

bi-cn-hongkong.data.aliyun.com

bi-cn-hongkong.data.aliyun.com

bi-cn-hongkong.data.aliyun.com

bi-cn-hongkong.data.aliyun.com

bi-cn-hongkong.data.aliyun.com

2. Obtain preview report URL

token3rd/dashboard/view/pc.htm

token3rd/report/view.htm

token3rd/offline/view/pc.htm

token3rd/screen/view/pc.htm

token3rd/analysis/view/pc.htm

token3rd/dataform/view.htm

3. Obtain report ID

dd0****83f

42****18ef6

22****9pek0

27****an79d

7f****5dda

29****df453

4. Obtain AccessTicket

fd138bcb-****-4fde-b413-81bcee59bdb6

fd138bcb-****-4fde-b413-81bcee59bdb6

fd138bcb-****-4fde-b413-81bcee59bdb6

fd138bcb-****-4fde-b413-81bcee59bdb6

fd138bcb-****-4fde-b413-81bcee59bdb6

fd138bcb-****-4fde-b413-81bcee59bdb6

The format and report URL for concatenation are as follows:

  • The format for concatenating dashboard URLs is https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>. Here is the resulting URL:

    https://bi-cn-hongkong.data.aliyun.com/token3rd/dashboard/view/pc.htm?pageId=dd0****83f&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6
  • The format for concatenating workbook URLs is https://<Quick BI domain name>/<preview report URL>?id=<report ID>&accessTicket=<AccessTicket>. Here is the resulting URL:

    https://bi-cn-hongkong.data.aliyun.com/token3rd/report/view.htm?id=<42****18ef6>&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6
  • The format for concatenating Downloads URLs is https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>. For instance, for the Hong Kong (China) site, the resulting URL would be:

    https://bi-cn-hongkong.data.aliyun.com/token3rd/offline/view/pc.htm?pageId=<42****18ef6>&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6
  • The format for concatenating data dashboard URLs is https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>. For instance, the URL for the China (Hong Kong) site would be:

    https://bi-cn-hongkong.data.aliyun.com/token3rd/screen/view/pc.htm?pageId=<42****18ef6>&accessTicket=fd138bcb-****-4fde-b413-81bcee59bdb6
  • The format for concatenating URLs for ad hoc analysis in Quick BI is https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>. For instance, the URL generated for the China (Hong Kong) site would be:

    https://bi-cn-hongkong.data.com/token3rd/analysis/view.htm?id=<xxx>&accessTicket=<xxx> 
  • To enter data, use the URL format https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>. For instance, the URL for the Hong Kong (China) site would be:

    http://bi-cn-hongkong.data.com/token3rd/dataform/view.htm?id=<xxx>&accessTicket=<xxx>

To embed a block in a report, append &cmptId=XXX to the end of the report URL. For instance, when embedding a block into a workbook, the resulting URL would be:

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

    For instance, the domain name for the Quick BI China (Hong Kong) site is bi-cn-hongkong.data.aliyun.com. Always use the domain name of the specific environment as the standard.

  2. Acquire the preview report URL.

    The preview page URL corresponding to the report type is listed below. Select according to your requirements.

    • Dashboard: Access your dashboard at token3rd/dashboard/view/pc.htm.

    • Workbook: token3rd/report/view.htm

    • Data dashboard: Access it at token3rd/screen/view/pc.htm.

    • Downloads: To retrieve the file, navigate to token3rd/offline/view/pc.htm.

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

    • Data Entry: Navigate to token3rd/dataform/view.htm for form submission.

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

    • In this example, the Dashboard ID is d01****c5f.

      In the dashboard editing page, find the dashboard pageId in the address bar.

      image

    • In this example, the Workbook ID is d0****3ba88.

      In the workbook editing page, locate the workbook ID in the address bar.电子表格ID

    • In this example, the data dashboard ID is 3c****26b.

      In the data dashboard editing page, find the data dashboard pageId in the address bar.

      image.png

    • In this example, the Downloads ID is b2****47.

      In the Downloads editing page, locate the Downloads pageId in the address bar.

      image.png

    • Ad hoc analysis ID, in this example, is 7f****da

      In the ad hoc analysis editing page, find the ad hoc analysis pageId in the address bar.

      image

    • Data entry ID, in this example, is 29****53

      In the data entry editing page, locate the data entry pageId in the address bar.

      image

  4. Concatenate the Quick BI domain name, preview report URL, report ID, and Step 2 Obtain AccessTicket parameter obtained in the above steps into the following request address.

    • The concatenation format for dashboards https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>

    • The concatenation format for workbooks https://<Quick BI domain name>/<preview report URL>?id=<report ID>&accessTicket=<AccessTicket>

    • The concatenation format for data dashboards https://<Quick BI domain name>/<preview report URL>?pageId=<report ID>&accessTicket=<AccessTicket>

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

    • The concatenation format for ad hoc analysis https://<Quick BI domain name>/<preview report URL>?id=<report ID>&accessTicket=<AccessTicket

    • The concatenation format for data entry https://<Quick BI domain name>/<preview report URL>?id=<report ID>&accessTicket=<AccessTicket>

Appendix 1: Configure row-level permissions

If UserId and accountName are not filled, the viewing permissions for the embedded report will default to follow the report owner. You can follow the instructions in the figure below to configure row-level permissions and set the UserId or AccountName parameter to bind the target user's permissions.imageFor detailed operations, see Row and column permissions.

Appendix 2: Generate global parameter description

In the target dashboard or workbook, set the appropriate global parameters. These parameters are crucial for binding reports and generating AccessTickets.

The parameter name for global parameters is GlobalParam, and the parameter value for global parameters is a JSON array:

[
  {
    "paramKey": "price", // Global parameter key
    "joinType": "and",   // Connection method, use and
    "conditionList": [
      {
        "operate": "=", // Operator, see the following description
        "value": "1"    // Operation value, use an array ["1", "2"] in the case of multiple values
      },
      {
        "operate": "=", // Operator, see the following description
        "value": "2"    // Operation value, use an array ["1", "2"] in the case of multiple values
      }
    ]
  },
  {
    "paramKey": "area", // Global parameter key
    "joinType": "and",   // Connection method, use and
    "conditionList": [
      {
        "operate": "in",          // Operator
        "value": ["North China","South China"]    // Operation value, use an array in the case of multiple values
      }
    ]
  }
]

The common descriptions for the global parameter operate field are as follows:

Operator (operate)

Description

Remarks

=

Equal to

-

!=

Not equal to

-

>

Greater than

-

>=

Greater than or equal to

-

<

Less than

-

<=

Less than or equal to

-

in

in

The parameter value must be an array

not-in

not in

The parameter value must be an array

like

like

Keyword fuzzy match.

SQL will automatically parse into like '%{parameter value}%'

contain

String contains

SQL will automatically parse into like '%{parameter value}%'

start-with

String starts with

SQL will automatically parse into like '{parameter value}%'

end-with

String ends with

SQL will automatically parse into like '%{parameter value}'

Appendix 3: Description of the number of embeddable reports

Number of purchased users

Number of third-party embeddings

50

100

100

200

200

500

300

1,000

Note

The figures above represent the default limits for embedding reports in the Professional Edition.