This QuickStart demonstrates filter synchronization between a host application and Sigma embeds. It uses Store Region and Date Range filters in the host application that stay in sync with matching controls in the embedded Sigma workbook—creating a seamless experience where filter changes instantly update the embedded content.
REST API Usage 01: Getting Started
For more information on Sigma's product release strategy, see Sigma product releases
If something doesn't work as expected, here's how to contact Sigma support
Target Audience
Developers who want to use Sigma's REST API to programmatically control Sigma in an embedded context.
Prerequisites
- Any modern browser will work.
- Access to your Sigma environment.
- Some familiarity with Sigma is assumed. Not all steps are shown, as the basics are assumed understood.
- Microsoft VSCode or other suitable development tool.
Start the Express server in terminal from the embedding_qs_series_2_api_use_cases folder and enable debugging:
DEBUG=true npm start
The server is ready when it displays: Server listening at http://localhost:3000.
Browse to the landing page:
http://localhost:3000
Select the Custom Filters page and click Go.
Select the Embed_API_QuickStart workbook:
The embed will load once a Current User is selected.
Before using the sample application, we need to add the corresponding filter controls to the Embed_API_QuickStart workbook. These controls will allow the workbook to process inbound events from the host application when the user changes filters.
In Sigma, open the Embed_API_QuickStart workbook.
List control
Add a List control and configure it as shown:
Set the Target to both elements in the embed, referencing the Store Region column.
Date range control
Add a Date range control to the page and configure it as shown. Set both elements in the embed as targets:
Publish the workbook.
Now our embed will display the Sigma controls:
In the host application, select Current users, choose the Embed_API_QuickStart workbook, and test the filters by selecting different Store Regions and Date Ranges.
For example, you can select multiple regions, and the list control will display them as a comma‑delimited list:
The date picker provides all the common ranges, along with a custom range option:
This implementation uses an open‑source jQuery date range picker from jsdelivr's free CDN.
It also incorporates a custom loading indicator, as described in the QuickStart, REST API Usage 07: Custom Loading Indicators
Now that the host controls are confirmed to work, you can move them to a hidden page so embed users will not see or interact with them.
In Sigma, select both controls and Move them to a new page.
Rename the new page Controls and hide it:
Publish the workbook.
With the controls hidden, they no longer appear in the embed, but the host application filters continue to function as expected:
In this QuickStart, you learned how to synchronize filters between a host application and an embedded Sigma workbook.
We covered:
- Starting the sample Express server and loading the Custom Filters workbook
- Adding matching filter controls (List and Date Range) in Sigma to respond to host‑side filter changes
- Testing host‑controlled filters for multi‑selection and date range picking
- Using an open‑source jQuery date range picker and integrating a custom loading indicator
- Hiding filter controls on a separate, hidden workbook page while retaining full host application control
This pattern provides a seamless, user‑friendly way to manage embedded content while keeping filter logic centralized in the host application.
Additional Resource Links
Blog
Community
Help Center
QuickStarts
Be sure to check out all the latest developments at Sigma's First Friday Feature page!
