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.
Instructions for parameter transmission embedding:
In embedded integration scenarios, you can create personalized data viewing experiences for the same report by combining global parameters with parameter injection.
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.
NoteThe 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
NoteThe 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:
From the Quick BI product home page, use the instructions below to access the embedded report page.
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.
If the report list is extensive, you can also enter the report name to quickly locate the desired report.
In the Report Embedding Configuration dialog box, you can configure the following settings.
ImportantThis 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.
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.
Click on the Copy button.
Step 2: Generate AccessTicket through API interface
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****
.NoteUserId 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**.
NoteUserId 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
NoteIf 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.
NoteIf you need to use the global parameter capability, please contact the Quick BI operations owner.
NoteFor 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.
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 }
NoteThe
result
represents the AccessTicket generated by this API call, which isfd138bcb-****-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 |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
| |
|
|
|
|
|
|
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
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.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.
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.
In this example, the Workbook ID is
d0****3ba88
.In the workbook editing page, locate the workbook ID in the address bar.
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.
In this example, the Downloads ID is
b2****47
.In the Downloads editing page, locate the Downloads pageId in the address bar.
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.
Data entry ID, in this example, is
29****53
In the data entry editing page, locate the data entry pageId in the address bar.
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.For 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 |
contain | String contains | SQL will automatically parse into |
start-with | String starts with | SQL will automatically parse into |
end-with | String ends with | SQL will automatically parse into |
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 |
The figures above represent the default limits for embedding reports in the Professional Edition.