EmbedAdditional embedding configurationsImplement inbound and outbound events in embeds

Outbound event reference

View as MarkdownOpen in Claude

Sigma supports the following outbound events that describe user interactions with embedded Sigma content. Each event includes specific properties about the interaction that allow the host application to process and respond accordingly.

action:outbound

This event occurs when a Generate iframe event workbook action is triggered. This event can be used to react to user actions taken in the workbook. See Create actions that trigger embed iframe events.

Event structure:

1{
2   type: 'action:outbound';
3   name: string;
4   values: Record<string,unknown>;
5}

Event properties:

nameA name for the event. Enter this name in the Event name field in the workbook action.
valuesOne or more event keys and values to pass to your host application. Enter the corresponding key-value pairs in the Event key fields in the workbook action.

document:element:nodata

This event occurs if there is no data in a table, pivot table, or chart in a workbook, report, or data model.

This event is useful to identify if there is no data in a given element and redirect to a different page or display relevant guidance in the host application.

Event structure:

1{
2   type: 'document:element:nodata',
3   elementId: string;
4}

Event properties:

elementIdThe ID of the document element.

url:onchange

This event occurs when the URL path changes, but not when URL search parameters change. This event returns the URL of the embed.

This event gives insight into when the user creates their own workbook that they can edit.

Event structure:

1{
2   type: 'url:onchange';
3   url: string;
4}

Event properties:

urlThe embed pathname without search or query parameters.

workbook:​bookmark:​onchange

This event occurs when a user selects or deselects a bookmark.

Event structure:

1{
2   type: 'workbook:bookmark:onchange', 
3   bookmarkName: string; 
4   workbookId: string;
5   versionTagName: string | null; 
6   bookmarkId: string;
7}

Event properties:

bookmarkNameThe name of the bookmark.
workbookIdThe ID of the workbook where the bookmark was created.
versionTagNameThe tag assigned to the workbook version. Always null in embeds.
bookmarkIdThe unique ID of the bookmark.

workbook:​bookmark:​oncreate

This event occurs when an embed user creates a bookmark using the embed UI.

This event is useful for analyzing when users create their bookmarks.

Event structure:

1{
2   type: 'workbook:bookmark:oncreate';
3   bookmarkName: string;
4   workbookId: string;
5   versionTagName: string | null;
6   bookmarkId: string;
7}

Event properties:

bookmarkNameThe name of the bookmark.
workbookIdThe ID of the workbook where the bookmark was created.
versionTagNameThe tag assigned to the workbook version.
bookmarkIdThe ID of the created bookmark.

workbook:​bookmark:​ondelete

This event occurs when an embed user deletes a bookmark using the embed UI.

Event structure:

1{  
2   type: 'workbook:bookmark:ondelete';  
3   bookmarkName: string;  
4   workbookId: string;  
5   versionTagName: string | null;  
6   bookmarkId: string;  
7 }

Event properties:

bookmarkNameThe name of the bookmark.
workbookIdThe ID of the workbook where the bookmark was deleted.
versionTagNameThe tag assigned to the workbook version.
bookmarkIdThe ID of the deleted bookmark.

workbook:​bookmark:​onupdate

This event occurs when an embed user updates a bookmark using the embed UI by either changing the name, setting or removing it as the default view, sharing the bookmark, or unsharing the bookmark by setting it as a personal view.

Event structure:

1{  
2   type: 'workbook:bookmark:onupdate';  
3   workbookId: string;  
4   versionTagName: string | null;  
5   bookmarkId: string;  
6   bookmarkName?: string;  
7   isShared?: boolean;  
8   isDefault?: boolean;  
9}

Event properties:

workbookIdThe ID of the workbook where the bookmark was updated.
versionTagNameThe tag assigned to the workbook version.
bookmarkIdThe ID of the updated bookmark.
bookmarkNameOptional. The name of the bookmark. Only defined in the event if updated by the user.
isSharedOptional. Whether or not the bookmark is shared. Only defined in the event if updated by the user.
isDefaultOptional. Whether or not the bookmark is set as the default view. Only defined in the event if updated by the user.

workbook:​chart:​error

This event occurs when a chart produces an error.

This event is useful for detecting errors and taking action in response.

Event structure:

1{
2   type: 'workbook:chart:error';
3   nodeId: string;
4   message: string | undefined;
5   code: string;
6}

Event properties:

nodeIdThe element ID of the chart.
messageThe error message.
codeThe error code.

workbook:​chart:​onvalueselect

This event is specifically designed for user interactions with embedded visualization elements, like clicking data points in a bar chart. This event extends beyond the basic interaction details and includes a values object that provides insight about the specific chart component selected.

This event is crucial for applications that must respond to precise user interactions within embedded visualization elements. It offers a nuanced understanding of the chart component a user focuses on and analyzes.

Event structure:

1{
2   type: 'workbook:chart:onvalueselect';
3   nodeId: string;
4   title: string;
5   values: valuesObject;
6}

Event properties:

nodeIdThe element ID of the chart.
titleThe title of the chart.
valuesContains key-value pairs representing any selected field column value, including color, axis, and value of the selected chart component. For example, the category label and corresponding value of a specific data point.

Example scenario:

A user clicks on a specific bar in a bar chart. The event returns detailed information about that bar, including its category label and value. This enables the host application to provide context-specific responses or further data insights related to that precise interaction.

workbook:dataloaded

This event occurs when a workbook finishes loading its data.

This event is useful for signaling when an iframe finishes loading a Sigma embed.

Event structure:

1{  
2   type: 'workbook:dataloaded' 
3}

Example scenario: When a user exports the workbook as PDF via API immediately after accessing a workbook, they might see in the PDF that the embed element hasn’t finished loading. Developers can add a check for iframe elements and check that the iframe contents are fully loaded before exporting.

workbook:error

This event occurs when a workbook produces an error. Common error codes and messages that might occur that you might catch and handle with this event are listed in Common embed error codes and messages.

This event is useful for detecting errors and taking action in response.

Event structure:

1{
2   type: 'workbook:error';
3   message: string | undefined;
4   code: string;
5}

Event properties:

messageThe error message.
codeThe error code.

workbook:exploreKey:onchange

This event occurs when a new exploration is created on an embed.

Event structure:

1{
2   type: 'workbook:exploreKey:onchange', 
3   exploreKey: string;
4}

Event properties:

exploreKeyThe unique ID associated with the exploration.

workbook:fullscreen:onchange

This event occurs when the user minimizes or maximizes an element.

This event is useful for taking an action in response to an element being minimized or maximized.

Event structure:

1{
2   type: 'workbook:fullscreen:onchange';
3   fullScreen: boolean;
4}

Event properties:

fullScreenIf true, the element was maximized; if false, the element was minimized.

workbook:​id:​onchange

This event occurs when the ID of the displayed workbook changes.

This event gives insight into when the user creates their own workbook that they can edit.

Event structure:

1{ 
2   type: 'workbook:id:onchange'; 
3   id: string 
4}

Event properties:

idThe workbook ID.

workbook:loaded

This event occurs when a workbook’s metadata has loaded, but the elements haven’t been evaluated.

This event is crucial for scenarios in which an initial setup or a pre-processing step is required before the workbook becomes interactive. It provides an opportunity to implement any preparatory actions in the host application based on the workbook’s metadata.

Event structure:

1{
2  type: 'workbook:loaded',
3  workbook: {
4    variables: encodedVariables // Contains workbook metadata
5  },
6}

workbook:ondelete

This event occurs when a user clicks Delete in the embed menu and a workbook is successfully deleted.

Event structure:

1{
2   type: 'workbook:ondelete';
3   id: string;
4}

Event properties:

idThe workbook ID.

workbook:pageheight:onchange

This event communicates the document height to the parent whenever it changes.

This event is useful for avoiding situations where the body of a frame might scroll due to dynamic sizing. Use this function to calculate the height of the iframe.

To use this event, the responsive_height parameter must be set to true. See Embed URL parameters.

Event structure:

1{
2   type: 'workbook:pageheight:onchange';
3   pageHeight: number;
4}

Event properties:

pageHeightThe height of the page, in pixels.

workbook:pivottable:oncellselect

This event occurs when a user selects a cell or multiple cells in an embedded pivot table. This event provides an array of selected cells and their properties.

This event is crucial for applications that require responsive interaction with pivot table data within Sigma, allowing the host application to tailor its response based on user selection in the embedded workbook.

Event structure:

1{
2   type: 'workbook:pivottable:oncellselect';
3   nodeId: string;
4   title: string;
5   cells: cellsObject;
6}

Event properties:

nodeIdThe element ID of the pivot table.
titleThe title of the pivot table.
cells

A collection of objects for each cell, including the following:

  • type: ‘valueCell’ to identify the cell as a standard value cell.
  • value: Value to identify the actual cell data.
  • columnName: String to name the column containing the cell.

workbook:published

This event occurs in secure embeds when a user saves and publishes a workbook.

This event is useful for taking some action in the host application when a workbook is published and for tracking when changes are made to a workbook.

Event structure:

1{
2   type: 'workbook:published';
3   workbookId: string;
4}

Event properties:

workbookIdThe ID of the published workbook.

workbook:saveas

This event occurs when a user successfully saves a workbook using the Save as option on the embed menu of the workbook.

Event structure:

1{
2   type: 'workbook:saveas';
3   workbookId: string;
4   saveWorkbookId: string;
5}

Event properties:

workbookIdThe ID of the original workbook.
savedWorkbookIDThe ID of the newly saved workbook.

workbook:table:oncellselect

This event occurs when a user selects a cell or multiple cells in an embedded table. This event provides an array of selected cells and their properties.

This event is crucial for applications that require responsive interaction with table data within Sigma, allowing the host application to tailor its response based on user selection in the embedded workbook.

Event structure:

1{
2   type: 'workbook:table:oncellselect';
3   nodeId: string;
4   title: string;
5   cells: cellsObject;
6}

Event properties:

nodeIdThe element ID of the table.
titleThe title of the table.
cells

A collection of objects for each cell, including the following:

  • type: ‘valueCell’ to identify the cell as a standard value cell.
  • value: Value to identify the actual cell data.
  • columnName: String to name the column containing the cell.
  • underlyingData: An array of rows contributing to the aggregate value. The data is subject to size limitations. A truncation flag indicates when the data exceeds the limit.

Example scenario:

When a user selects a specific cell (for example, in the Sum of Revenue column) for a particular order, the event returns detailed information about the cell, including its value, column name, and any underlying data (if it’s an aggregate value).

workbook:variables:onchange

This event occurs when a user- or system-initiated update is applied to a control element within the embedded Sigma content. The event also triggers when a user clicks an element on the page that updates a control value, such as clicking a chart mark or data point that applies a cross-filter.

This event is essential for situations where the host application needs to respond to changes within the embedded Sigma content. This event provides information about user interactions with the embedded content, allowing for a dynamic and responsive integration within the host application.

For detailed examples on how values are encoded for URLs, refer to Add query string parameters to a URL.

Event structure:

1{
2  type: 'workbook:variables:onchange',
3  workbook: {
4    variables: { 'Variable1': 'value1', 'Variable 2': 'value2' } // Updated variable values
5  },
6}

Event properties:

workbook.variablesContains the controls and their values updated within the workbook. The format follows the structure { 'control-ID': 'value' }, with URL-encoded values.

Example scenario:

If you have a multi-select list values control configured with a control ID of store-region and a user selects two regions, East and Midwest, the event emitted is of the following format:

1{
2  type: 'workbook:variables:onchange',
3  workbook: {
4    variables: { 'store-region': "East,Midwest" }
5  },
6}