Build a seamless interaction between your application and embedded Amazon QuickSight dashboards and visuals using embedded callback actions

Amazon QuickSight is a fully managed, cloud-native business intelligence (BI) service that makes it straightforward to connect to your data, create interactive dashboards, and share these with tens of thousands of users, either within the QuickSight interface or embedded in software as a service (SaaS) applications or web portals. With QuickSight providing insights to power daily decisions across the organization, end-users expect actionable insights that can flow seamlessly into their daily workflow in their application of choice. This allows you to make data-driven decisions and take action on these decisions without context switching between multiple platforms.

With this release, customers embedding QuickSight dashboards or visuals can now use new capabilities in the Embedding SDK to unlock use cases for end readers such as, but not limited to:

Flagging a record for secondary processing
Sending a notification to stakeholders on a key insight
Performing on-the-fly data updates through writebacks
Tracking user interactions to improve future design and adoption

In this post, we show how to build a seamless interaction between your application and embedded QuickSight dashboards and visuals using embedded callback actions.

Solution overview

Embedded callback actions enable developers to build tighter integration between your application and QuickSight embedded dashboards and visuals. To get started, developers can now write code in their application listening to end-user’s interactivity on visuals by registering data point callbacks on top of one or more visuals using new functions in the Embedding SDK. Once registered, when a reader clicks on data points such as a certain slice in a pie chart or a bar in a bar chart, the row of the data associated with the data point is sent to the third-party application. This data can then be captured, processed, restated, or passed into another part of the application.

The following are the new SDK actions and events that are added as part of the feature. With these new actions and events, application developers can invoke any of these action functions to list, get, add, or remove an action on a dashboard visual. Subsequently, after these actions are registered, they then use event callbacks to listen to events on user interactions like clicking a cell in a pivot table, a bar in a bar chart, and a slice of a pie chart as an event and capture those data points and invoke appropriate workflows to further process these data points.

The following are the new SDK actions:

getSheetVisuals – Returns a list of visuals for the specified sheet
getVisualActions and getActions – Return a list of actions for a visual on a dashboard
addVisualActions and addActions – Append an action to an existing list of actions for a visual on a dashboard
removeVisualActions and removeActions – Remove an action from a visual on a dashboard
setVisualActions and setActions – Override existing actions with a new list of actions for a visual on a dashboard

The following are the new SDK events:

GET_VISUAL_ACTIONS – Emitted after the response is received when calling GetVisualAction and contains the list of custom actions for the visual.
ADD_VISUAL_ACTIONS – Emitted after the response is received when calling AddVisualAction and contains the success or error when adding a custom action to a visual.
CALLBACK_OPERATION_INVOKED – Emitted when clicking on a visuals data point that has a custom action with the CallbackOperation. This contains the data point and some other event information.

All these actions support CRUD operations in the form of Set, Get, Add, and Remove. This helps with using existing actions, creating new actions, or sometimes removing actions that you don’t want to have enabled in an embedded dashboard.

Prerequisites

For this post, you must have the following prerequisites:

A QuickSight subscription to Enterprise edition
The latest version of the QuickSight Embedding SDK

Use case overview

Let’s consider a fictional company, AnyCompany, which is a leading fulfillment technology company that manages warehouses and provides a warehouse management system that can optimize operational efficiency. They are using QuickSight and its embedding capabilities to seamlessly integrate data-driven experiences into their software applications. These embedding capabilities bring the power of QuickSight to their end-users, where they can analyze and interact with data without leaving their application. Today, AnyCompany is using dashboard embedding for their end-users and would like to trigger multiple functional workflows based on user actions and events from within a QuickSight dashboard.

AnyCompany has the following key requirements for various workflows:

Email – AnyCompany wants to flag records to trigger emails from dashboards to keep end customers up to date on various milestones (data points), like inventory, order fulfillment, and shipment tracking
Writeback – AnyCompany wants to seamlessly provide mechanisms for their end-users to update shipments, inventory, and order fulfillment status from an embedded dashboard to a database
Usage analytics – AnyCompany wants to derive insights on click analytics by their warehouse users to measure adoption and engagement among their user base for continuous improvement and to improve their experience based on their usage patterns

In the following sections, we discuss each workflow in more detail.

Email workflow

The following figure shows the sequence of steps to flag records in the email workflow through the new events and actions feature in the QuickSight Embedding SDK.

The user accesses the dashboard from within an embedded application. During the dashboard embedding using the QuickSight Embedding SDK, the application developer registers an action using setVisualActions or setActions on a visual to listen to click events from the end-user. When the end-user interacts with a visual in the dashboard (for instance, by using a custom action named ‘Flag record‘), these events are emitted to the parent application and the data points can be captured by listening to these events using CALLBACK_OPERATION_INVOKED. The response of this emitted event includes all the event information along with the data points clicked by the user. Using these details from the emitted event, the application developer can trigger an email workflow and present the appropriate UI to further customize the email template. The following screenshots and code snippets show the art of the possible in an email workflow.

The following code snippet shows how application developers can dynamically enable an action while embedding a dashboard into a web application. In this example, the ‘Flag Record’ action is enabled in a table visual:

onMessage: async (messageEvent) => {
                        const {eventName, message} = messageEvent;
                        switch (eventName) {
                            case 'CONTENT_LOADED':
                                await visualFrame.addActions([
                                    CustomActionId: 'flag-record-action',
                                    Name: 'Flag record',
                                    Trigger: 'DATA_POINT_MENU',
                                    Status: 'ENABLED',
                                    ActionOperations: [{
                                        CallbackOperation: {
                                            EmbeddingMessage: {}
                                        }
                                    }]
                                ]);

After the action is enabled on a visual using the preceding code, when the user starts interacting with the record, the menu option on a record shows the newly added “Flag record” option, as shown in the following screenshot.

When the user triggers the flag record, the event can be handled through the QuickSight Embedding SDK, as shown in the following code snippet:

case 'CALLBACK_OPERATION_INVOKED':
 const { Datapoints: [Datapoint], VisualId } = message;

  const aggregatedData = Datapoint.Columns.reduce((aggregatedRawData, column, index)=> 
    {
        const columnType = Object.keys(column)[0];

        if (columnType) {
            const valueType = Object.keys(column?.[columnType])[0];

            if (valueType) {
                const columnMetadata = column[columnType][valueType]?.Column;
                const rawValue = Datapoint.RawValues[index][valueType];
                const formattedValue = Datapoint.FormattedValues[index];

                return {
                    ...aggregatedRawData,
                    [columnMetadata.ColumnName]: rawValue
                }
            }
        }
       return aggregatedRawData;
    }, {});
   // Send data to backend server to send email
    await fetch('<REPLACE_WITH_BACKEND_SERVER_ENDPOINT>', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({ data: aggregatedRawData })
    });

Based on the data returned, the response can further be processed to trigger an email flow, as shown in the following screenshot.

Writeback workflow

The following figure shows the sequence of steps in the writeback workflow through the new events and actions capabilities in the QuickSight Embedding SDK.

This works exactly the same way as the previous example, but instead of triggering an email workflow, data can be directly processed and loaded into a database.

The code snippet is as follows:


onMessage: async (messageEvent) => {
    const {eventName, message} = messageEvent;
    switch (eventName) {
    case 'CONTENT_LOADED':
        await visualFrame.addActions([
            CustomActionId: 'write-back-action',
            Name: 'write to database',
            Trigger: 'DATA_POINT_MENU',
            Status: 'ENABLED',
            ActionOperations: [{
                CallbackOperation: {
                    EmbeddingMessage: {}
                }
            }]
        ]);
        break;
    case 'CALLBACK_OPERATION_INVOKED':
        const { Datapoints: [Datapoint], VisualId } = message;

        const aggregatedData = Datapoint.Columns.reduce((aggregatedRawData, column, index) => {
            const columnType = Object.keys(column)[0];

            if (columnType) {
                const valueType = Object.keys(column?.[columnType])[0];

                if (valueType) {
                    const columnMetadata = column[columnType][valueType]?.Column;
                    const rawValue = Datapoint.RawValues[index][valueType];
                    const formattedValue = Datapoint.FormattedValues[index];

                    return {
                        ...aggregatedRawData,
                        [columnMetadata.ColumnName]: rawValue
                    }
                }
            }

            return aggregatedRawData;
        }, {});

        // Send data to backend server to write to database
        await fetch('<REPLACE_WITH_API_ENDPOINT>', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({ data: aggregatedRawData })
        });

        break;
    default:
        console.warn(`Unhandled event: ${eventName}`);
        break;
    }
    }
    }

Usage analytics workflow

The following figure shows the sequence of steps for capturing usage analytics through the new events and actions feature in the QuickSight Embedding SDK.

In this workflow, all user interactions with visuals can be enabled on the click basis and all the data points can then be written to the database along with user identity, role, department, and so on. This data can further be analyzed to generate insights on end-user adoption and engagement. Additionally, you can use this data to improve dashboards or run campaigns within your organization to spread awareness and increase adoption. For example, if a specific department is interacting with a bar chart and drilling down two layers every single time they load a dashboard, you can improve the view of the dashboard for that department by surfacing those metrics to the top level.

Conclusion

Embedded callback actions provide methods to subscribe to specific visual interactions and listen to the events when these are triggered by end-users in an embedded dashboard. This post illustrated various use cases on the possible application of these actions and events. For more information, refer to Amazon QuickSight now supports embedded callback actions and Add embedded callback actions at runtime in Amazon QuickSight.

If you have any questions or feedback, please leave a comment. For additional discussions and help getting answers to your questions, check the QuickSight Community.

About the Authors

Mayank Agarwal is a product manager for Amazon QuickSight, AWS’ cloud-native, fully managed BI service. He focuses on embedded analytics and developer experience. He started his career as an embedded software engineer developing handheld devices. Prior to QuickSight he was leading engineering teams at Credence ID, developing custom mobile embedded device and web solutions using AWS services that make biometric enrollment and identification fast, intuitive, and cost-effective for Government sector, healthcare and transaction security applications.

Srikanth Baheti is a Specialized World Wide Principal Solution Architect for Amazon QuickSight. He started his career as a consultant and worked for multiple private and government organizations. Later he worked for PerkinElmer Health and Sciences & eResearch Technology Inc, where he was responsible for designing and developing high traffic web applications, highly scalable and maintainable data pipelines for reporting platforms using AWS services and Serverless computing.

Raji Sivasubramaniam is a Sr. Solutions Architect at AWS, focusing on Analytics. Raji is specialized in architecting end-to-end Enterprise Data Management, Business Intelligence and Analytics solutions for Fortune 500 and Fortune 100 companies across the globe. She has in-depth experience in integrated healthcare data and analytics with wide variety of healthcare datasets including managed market, physician targeting and patient analytics.

AWS Business Intelligence Blog