AWS Business Intelligence Blog

Build custom and interactive dashboards using new runtime capabilities in QuickSight Embedding SDK

Amazon QuickSight is a fully managed, cloud-native business intelligence (BI) service that you can use to connect to your data and create interactive dashboards that can be shared with tens of thousands of users. The dashboards can be used within QuickSight or embedded in software as a service (SaaS) apps.

Today, we’re launching a feature you can use to dynamically update the theme and filters of embedded dashboards and visuals at runtime through the QuickSight Embedding SDK. Runtime filtering and theming of embedded dashboards and visuals can help you seamlessly integrate your SaaS application with QuickSight embedded dashboards and visuals. You can now use the new methods available in the Embedding SDK to:

  • Use filter methods to take advantage of the power of QuickSight filters within your SaaS application at runtime and make integrations between your application and embedded QuickSight dashboards and visuals seamless. You can also create custom filter controls in your application, apply filter presets based on data from your application, and personalize filter configurations for users.
  • Synchronize the theme of your embedded content with the parent application and unlock personalized and accessible options for your users. With this new feature, you can apply preconfigured themes or users can update the default themes for their dashboard view at runtime.

Feature overview

To dynamically update theme and filter of embedded dashboard and visual you need to use QuickSight Embedding SDK version 2.5.0 or higher.

Runtime filtering

You can use the Embedding SDK to create, query, update, and remove QuickSight filters on an embedded dashboard or visual in your application. Create QuickSight filter objects in your application using the FilterGroup data model and apply them to embedded dashboards and visuals using the filter methods.

For setup:

  • getFilterGroupsForSheet(sheetId) – Return the FilterGroups that are currently scoped to the sheet supplied in the parameter.
  • getFilterGroupsForVisual(sheetId, visualId) – Return the FilterGroups that are scoped to the visual supplied in the parameter.
  • addFilterGroups(filterGroup[]) – Add and apply the supplied FilterGroups to the embedded dashboard or visual.
  • updateFilterGroups(filterGroup[]) – Update the FilterGroups on the embedded experience with the same FilterGroupId with the FilterGroup supplied in the parameter.
  • removeFilterGroups(filterGroup[] | filterGroupId[]) – Remove the supplied FilterGroups from the dashboard.

Runtime theming

You can make changes to the theming of your QuickSight embedded dashboards and visuals at runtime. These theme changes can be done at initialization and during the lifetime of your QuickSight embedded dashboards and visuals. When setting the theme Amazon Resource Name (ARN), the user must have access to the theme. This can be done from the share option in the analysis editor’s theme list, or with the UpdateThemePermissions API.

Setting methods

  • setTheme(themeArn: string) – Replace the active theme on a dashboard or visual with another theme, removing the theme override if one is currently set. This method sends an error message if the theme doesn’t exist or if the user doesn’t have access to it.
  • setThemeOverride(themeOverride: ThemeConfiguration) – Set a dynamic ThemeConfiguration on top of the currently active theme. Replaces the existing theme override if there is one. Any values not supplied will be defaulted to those on the currently active theme.

Initializing with a theme

Embedded QuickSight dashboards and visuals can be initialized with a theme other than the dashboard’s set theme by specifying the theme ARN to initialize within the theme property of DashboardContentOptions and VisualContentOptions.

const frameOptions = {
    url: '<YOUR_EMBED_URL>',
    container: '#your-container',
};

const contentOptions = {
    theme: 'arn:aws:quicksight::aws:theme/RAINIER',
};
const embeddedDashboardExperience = await embeddingContext.embedDashboard(frameOptions, 
contentOptions);

Use cases

AnyCompany, Inc. is a fictitious independent software vendor (ISV) that operates in various regions and has customers in all industry segments such as enterprise, startups, and small to medium sized businesses (SMBs). AnyCompany has thousands of users from these various customers accessing their application portal. AnyCompany wants to provide customized, personal, and accessible experiences including embedded analytics in the SaaS application to their users in North America and Europe. They have the following use cases related to embedded analytics content in the SaaS application. AnyCompany wants to dynamically personalize the user experience depending on who the user is and what information they’re going to view in their dashboard. This new feature also allows AnyCompany users to personalize their experience within the embedded dashboards by selecting and saving their preferred theme as the default, so when they sign in to an SaaS application with embedded dashboards, AnyCompany presents embedded content in that user’s preferred theme.

Runtime theming

ISVs have a variety of customers who want to have the look and feel of any SaaS applications they use to blend seamlessly with their applications, including matching their company’s color scheme and themes. AnyCompany has a similar requirement to meet their customers’ needs when embedding dashboards from QuickSight into their SaaS application. They have a variety of options for styling and theming. In many cases, AnyCompany develops a single dashboard that must rendered in a variety of themes, colors, and fonts.

Light and dark modes

AnyCompany’s SaaS application ships with a variety of themes and color schemes that are readily available for their users to choose from, the most common use of this pattern is toggling between light and dark modes on the portal. When the toggle between light and dark modes is at the SaaS application level, AnyCompany wants the embedded content to be in sync with the parent application.

For example, when the application loads in the default mode, the site is loaded with the Classic (default or light) theme as shown in the following figure.

And when the user switches to the Midnight theme, the whole experience changes to dark mode.

To achieve this, AnyCompany is now using the latest runtime theming functionality and can load the theme depending on the user’s selection at runtime.

function UpdateTheme(themeId){
awsData.embeddedDashboardExperience.setTheme('arn:aws:quicksight::aws:theme/'+themeId);
}

Preferred theme

AnyCompany allows users of its SaaS application to customize their user experience at the user level. This means that each user can select and save their preference of theme to load each time they sign in. Theme preference is stored by AnyCompany and is passed to the Embedded SDK at runtime.

The following figure shows that NorthUser has a preferred theme, which is automatically loaded when NorthUser signs in to the portal.

let themeArn = "arn:aws:quicksight::aws:theme/CLASSIC"; 
        if(userName == 'NorthUser')
          themeArn = "arn:aws:quicksight::aws:theme/RAINIER";
        }  
        const frameOptions = {
                url: embedUrl,
                container: "#dashboardContainer",
                width:"100%",
                height:"100%",
                withIframePlaceholder: true,
                onChange: function(event){ LogEvent('DASHBOARD-CHANGE-EVENT', event) },
                Dummy:'dummy'
        };
        
        const contentOptions = {
                locale: "en-US",
                toolbarOptions: {
                    export: false,
                    undoRedo: false,
                    reset: false
                },
                themeArn: themeArn,
                //themeArn: "arn:aws:quicksight:us-west-2:xxxxxxxxxx:theme/592294ed-bdcf-4fb9-ba97-e672460b0c6a",
                onMessage: function(event){ LogEvent('DASHBOARD-MESSAGE-EVENT', event) }
        }

Font customization

AnyCompany wants to be able to load and change fonts from within the fonts offered by QuickSight based on a per customer or per user basis. To achieve this, AnyCompany is using the themeOverride option to override font settings. By using this option, AnyCompany can update and customize the font settings of the current theme.

The following figures shows that AnyCompany is now able to change the font, background, and data colors on the embedded dashboard using the themeOverride option.

function UpdateFont(fontId){     awsData.embeddedDashboardExperience.setThemeOverride(JSON.parse('{"Typography":{"FontFamilies":[{"FontFamily":"'+fontId+'"}]}}'));
    }
    
    function UpdateColorScheme(colorId){
      console.log('In UpdateFont func');
      console.log(colorId);
      if(colorId == 'Teal')
        colorId = '{"DataColorPalette": {"Colors": ["#117A8B","#22D475","#8A50B3","#7FD4B9","#F65D6A","#4263A6","#3D993D","#E673C9"],"MinMaxGradient": ["#CCF0FF","#29A8DD"],"EmptyFillColor": "#F6F7F8"}}';
      else if(colorId == 'Navy')
        colorId = '{"DataColorPalette": {"Colors": ["#00558C","#F9B218","#8A50B3","#7FD4B9","#F65D6A","#4263A6","#3D993D","#E673C9"],"MinMaxGradient": ["#CCF0FF","#29A8DD"],"EmptyFillColor": "#F6F7F8"}}';
      else
        colorId = '{"DataColorPalette": {"Colors": ["#FF5050","#FF743A","#FF9014","#FFC301","#FAFF01","#FBFF77","#FDFFC3","#FEFFF9"],"MinMaxGradient": ["#FF0000","#FF7C00"],"EmptyFillColor": "#F6F7F8"}}';
      awsData.embeddedDashboardExperience.setThemeOverride(JSON.parse(colorId));
    }

Runtime filtering

Custom filter controls: AnyCompany uses this capability to create customized filter controls in their SaaS application, apply filter presets based on data from the application, and personalize filter configurations for individual users. For example, they present different filter controls for different personas and want to add additional dynamic controls to interact with the dashboard and underlying dataset.

Filter presets and personalized configuration:

AnyCompany’s SaaS application presents financial data relevant to the users in their geographic region filtered by country and state. AnyCompany wants to use preset filters to present additional embedded content in context with each user’s location based on their country and state. Based on each user’s selections and preferences in other parts of the SaaS app, AnyCompany wants to personalize the embedded content view. Presets allow AnyCompany to add multiple presets with filters using different values and controls.

The following example shows that when PowerUser signs in to the application, they have a filter control on the page outside of the embedded content. They can interact with the control to filter data in the dashboard. This filter wasn’t created by the author but was created dynamically when the application was loaded. This allows developers to present custom user experiences based on each user’s needs and access level.

Whereas when NorthUser signs in to the application, they don’t see the region filter and cannot further interact with data.

const customer_region_filtergroup_id = 'customer_region_filtergroup_id';
         // Get the currently selected sheet ID
         const selectedSheetId = await awsData.embeddedDashboardExperience.getSelectedSheetId();
         // Get the current visuals for the selected sheet
         const visualsForSelectedSheet = await awsData.embeddedDashboardExperience.getSheetVisuals(selectedSheetId);
         
         console.log(visualsForSelectedSheet);
         
         
         var visuals = new Array();
         visualsForSelectedSheet.forEach((element) => visuals.push(element["VisualId"]));
         
         // Get the currently selected options in the select element
          const selectedValues = event;
          var arr = new Array(); 
          arr.push(selectedValues);
          const categoryValues  = arr; 
         // Check if the FilterGroup with our ID already exists in the dashboard
          const sheetFilterGroups = await awsData.embeddedDashboardExperience.getFilterGroupsForSheet(selectedSheetId);
          const existingCategoryFilterGroup = sheetFilterGroups.find((filterGroup) => {
              return filterGroup.FilterGroupId === customer_region_filtergroup_id;
          });
          
          // If the FilterGroup does not exist, create and add a new one to the dashboard
          if (!existingCategoryFilterGroup) {
              const categoryFilterGroup = {
                  Status: 'ENABLED',
                  Filters: [
                      {
                          CategoryFilter: {
                              Configuration: {
                                  CustomFilterListConfiguration: {
                                      NullOption: 'NON_NULLS_ONLY',
                                      MatchOperator: 'CONTAINS',
                                      CategoryValues: categoryValues,
                                  },
                              },
                              Column: {
                                  ColumnName: 'Customer Region',
                                  DataSetIdentifier: 'Business Review',
                              },
                              FilterId: 'customer_region_filter_id',
                          },
                      },
                  ],
                  CrossDataset: 'SINGLE_DATASET',
                  ScopeConfiguration: {
                      SelectedSheets: {
                          SheetVisualScopingConfigurations: [
                              {
                                  Scope: 'SELECTED_VISUALS',
                                  SheetId: selectedSheetId,
                                  VisualIds: visuals,
                              },
                          ],
                      },
                  },
                  FilterGroupId: customer_region_filtergroup_id,
              };
             // Add the FilterGroup to the dashboard
              awsData.embeddedDashboardExperience.addFilterGroups([categoryFilterGroup]);
          } else {
         // Get the existing FilterGroup and update the CategoryFilter with the newly selected values
          const updatedCategoryFilter = {
              ...existingCategoryFilterGroup,
              Filters: [
                  {
                      CategoryFilter: {
                          ...existingCategoryFilterGroup.Filters[0].CategoryFilter,
                          Configuration: {
                              CustomFilterListConfiguration: {
                                  NullOption: 'NON_NULLS_ONLY',
                                  MatchOperator: 'CONTAINS',
                                  CategoryValues: categoryValues,
                              },
                          },
                      },
                  },
              ],
          };
          // Update the existing FilterGroup on the dashboard
          await awsData.embeddedDashboardExperience.updateFilterGroups([updatedCategoryFilter]);
          }

Conclusion

Runtime filtering and theming of embedded dashboards and visuals can help you seamlessly integrate your SaaS application with QuickSight embedded dashboards and visuals. This post illustrated some of the ways you can apply these new methods for seamless integration using embedded SDK.

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

Join the Quicksight Community to ask, answer, and learn with others and explore additional resources.

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 Principal 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.