AWS Business Intelligence Blog

Deliver Amazon QuickSight pixel-perfect reports to non-QuickSight users

Amazon QuickSight Pixel-perfect Reports enables the creation and sharing of highly formatted, personalized reports containing business-critical data to hundreds of thousands of end-users without any infrastructure setup or maintenance, up-front licensing, or long-term commitments.

Customers who are using the unified business intelligence (BI) capability of Amazon QuickSight for creating pixel-perfect reports can now use the recently launched Snapshot Export APIs. These APIs allow programmatic access to export pixel-perfect reports in PDF and data from tables and pivot tables in CSV and Excel formats.

In this post, we will cover how to use QuickSight, a serverless and cloud-native BI service, and Amazon Simple Storage Service (Amazon S3), an object storage service, to generate reports with specific parameters and have these reports delivered to users in a custom application.

Feature overview

In this section, we discuss some of the features of the new APIs.

Snapshot Export APIs

You can use the following APIs to initiate, track, and describe the dashboard snapshot jobs:

  • StartDashboardSnapshotJob – Use this asynchronous API to start a dashboard snapshot job. When successful, it means that the job is successfully submitted.
  • DescribeDashboardSnapshotJob – Use this synchronous API to poll QuickSight and get the status of your job. When successful, this API call response will have status of the job along with other meta-data information. The possible job status values are RUNNING, FAILED, and COMPLETED.
  • DescribeDashboardSnapshotJobResult – Use this synchronous API to get details of a completed job. If the job failed, the response will have errors describing why the job failed. If the job completed successfully, the response will have the S3 bucket and key where the output file is stored.

Supported output formats

The APIs support the following output formats:

  • PDF – The input can be a single pixel-perfect report sheet of a published dashboard. The output can be a PDF file with maximum 1,000 pages.
  • CSV – In this case, the input can be up to five pivot or table visuals from a dashboard that are published in the dashboard.

Storage destination

By default, the generated snapshots are stored in the QuickSight S3 bucket. However, if you provide the destination path generated, you can optionally store snapshots in a custom S3 bucket. Storing generated content in a custom S3 bucket provides added flexibility of being able to define custom retention and security permissions, trigger subsequent workflows, and other use cases.

Permissions required

These APIs are available to users or roles with AWS Identity and Access Management (IAM) permissions to run these QuickSight APIs. The following IAM policy allows an IAM user to get access to these APIs. Apart from this, the execution role or the user must have access to write to the desired S3 bucket. If you use any encryption on the S3 bucket, then the role or the user must have the necessary AWS Key Management Service (AWS KMS) policy attached.


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [    
                "quicksight:StartDashboardSnapshotJob"
                "quicksight:DescribeDashboardSnapshotJob",      
                "quicksight:DescribeDashboardSnapshotJobResult"
            ],
            "Resource": "*"
        }
    ]
}

If the storage destination is a custom S3 bucket in your AWS account, then the role must have additional access to write to the S3 bucket.

Solution overview

Let’s consider a fictional software as a service (SaaS) startup company, AnyCompany, which provides a call center management service to organizations. The company has been using QuickSight to generate insights for their customers.

AnyCompany has the following key reporting requirements apart from the standard dashboards available to end-users:

  • Generate report snapshots for compliance – Provide users the ability to generate a snapshot of the dashboard in the form of a PDF and store it in a repository for the specific number of days. Each customer of AnyCompany must be able to generate this snapshot on demand.
  • Ad hoc data download by the customers – Provide the ability for users to download base customer details that the customer’s call center representatives can use to call the right customer. For example, as part of a marketing campaign, a product team can download a list of customers that are not at the risk of churn and are satisfied with their current service to cross-sell a product.

The following is the sequence of steps to generate a snapshot through the new anonymous QuickSight dashboard snapshot APIs. Note that all the calls to QuickSight happen from the server side of the application.

  1. Provide inputs and start the job.
  2. Check completion of the job periodically.
  3. Generate a downloadable link for the user to access the report.

The following diagram illustrates the sequence of calls you can make and resources that are produced. The implementation can change depending on your specific use case and constraints.

In the following sections, we explore the use case of AnyCompany. Here, for compliance purposes, the customer wants to select a specific month to create a snapshot in PDF format but keep all the other parameters as their default. We show the steps taken on both the browser side and server side.

On the browser side, the user enters the report inputs and sends the details to the server. This includes the input parameter or filter that the user wants to apply. In many cases, the parameter and filter depend on the dashboard and the row-level security that the user has. Therefore, in order to allow the user to select the values that are applicable, the dashboard is embedded using row-level security.

On the server side, you authenticate the user by attaching the following inputs in addition to the parameter values that the user submitted. Then you run the StartDashboardSnapshotJob API call and stores the following details in the application:

  • Row-level security session tags
  • S3 bucket and object prefix

QuickSight will push the output generated in the location mentioned. If the status code is 202, then the job is successfully submitted for execution.

You use the following code to send the response back to the client that the job is successfully submitted:

snapShortConfigurationTemplate = {
                                                "FileGroups": [
                                                  {
                                                    "Files": [
                                                      {
                                                        "SheetSelections": [
                                                          {
                                                            "SheetId": sheetId,
                                                            "SelectionScope": "ALL_VISUALS" if outputFormat =='PDF' else "SELECTED_VISUALS"  ,
                                                            
                                                          }
                                                        ],
                                                        "FormatType": outputFormat
                                                      }
                                                    ]
                                                  }
                                                ],
                                                "DestinationConfiguration": {
                                                  "S3Destinations": [
                                                    {
                                                      "BucketConfiguration": outputDestination
                                                    }
                                                  ]
                                                }
                                            }
 quickSight = boto3.client('quicksight', region_name=dashboardRegion);
 response = quickSight.start_dashboard_snapshot_job(
                     AwsAccountId = awsAccountId,
                     DashboardId = dashboardId,
                     SnapshotJobId = snapshotJobId,
                     SnapshotConfiguration = snapShortConfigurationTemplate,
                     UserConfiguration = {
                                            "AnonymousUsers": [
                                              {
                                                "RowLevelPermissionTags": [
                                                  {
                                                    "Key": "Tag1",
                                                    "Value": "123"
                                                  }
                                                ]
                                              }
                                            ]
                                          }
                 )

On the server side, you can periodically poll QuickSight to check the status of the job using DescribeDashboardSnapshotJob. When the job is complete, the output is stored in the location specified in the bucket configuration.

quickSight = boto3.client('quicksight', region_name=dashboardRegion);
response = quickSight.describe_dashboard_snapshot_job(
                     AwsAccountId = awsAccountId,
                     DashboardId = dashboardId,
                     SnapshotJobId = snapshotJobId
                     
                 )

The output of the snapshot contains some metadata and the job status. For example, in the following screenshot, you see that the job has the details of when the job was actually started and when it was last updated. Also, the job status is RUNNING. This means that the DescribeDashboardSnapshotJob API has to be called again.

The browser shows the updated status of the job based on the response. If the job started successfully, the status shows as RUNNING.

Generate a downloadable link

When the jobStatus response to DescribeDashboardSnapshotJob is COMPLETED, the download option becomes available in the browser. The user can choose the download icon to download the reports in CSV or PDF format.

On the server side, you run the DescribeDashboardSnapshotJobResult API call for the report and get the Amazon S3 location of the report. You use the API call to generate a pre-signed URL and send it to the browser for the user to download the content:

quickSight = boto3.client('quicksight', region_name=dashboardRegion);
response = quickSight.describe_dashboard_snapshot_job_result(
            AwsAccountId = awsAccountId,
            DashboardId = dashboardId,
            SnapshotJobId = snapshotJobId
            
        )

The following screenshot shows a sample response. You can fetch the Amazon S3 URI from the response and use the API GeneratePresignedUrl to generate the URL that can be shared to the user in a browser for download.

When the URL is received, it’s opened in a new tab in the browser. The user must have pop-ups enabled in their browser.

Conclusion

QuickSight Snapshot Export APIs provide a new means to deliver insights to users who are not managed in QuickSight. This provides a lot more flexibility for you to democratize insights to your end-users and provides more control over the content being generated. For more information, refer to Amazon QuickSight and the What’s New Feed for QuickSight.

If you have any questions or feedback, please leave a comment.

For additional discussions and help getting answers to your questions, check out the QuickSight Community.

About the authors

Rahul Easwar is a Senior Product Manager with Amazon QuickSight. He is the product leader for Amazon QuickSight Pixel-perfect Reporting responsible for the product launch in 2022 and continues to focus on new product innovations. Rahul has over 15 years of experience implementing and leading global Analytics programs for organizations across various industry verticals.

Vetri Natarajan is a Specialist Solutions Architect for Amazon QuickSight. Vetri has 16 years of experience implementing enterprise business intelligence (BI) solutions and greenfield data products. Vetri specializes in integration of BI solutions with business applications and enable data-driven decisions.