Use Pause Refresh Options and APIs

At design time, you can configure data refresh and interaction settings of specific charts or tables in the Builder panel or via script APIs to improve the efficiency of retrieving and updating data after the widgets are initially loaded in application runtime.

Note

Currently, R visualization widgets aren't supported for the settings.

Data Refresh Settings in Builder Panel

Under Data Refresh in the Builder panel, three modes are available:

Always Refresh (default)
Refresh Active Widgets Only
Under this mode, you can avoid unnecessary data refresh. Visible widgets will refresh, while invisible widgets' data refresh will be automatically paused except when they’re called by the following fetch data script APIs:

DataSource.getResultSet, DataSource.getData, DataSource.isResultEmpty, DataSource.getResultMember, DataSource.getDataSelections, DataSource.expandNode, DataSource.refreshData

Table.getColumnCount, Table.getRowCount

Query will be sent by tables even if the latest data’s been fetched, but won’t be sent by charts.

Note

Widgets in inactive popup dialogs, tabs in tab strips and pages in page books will be treated as invisible ones.

In addition, onResultChanged event will still be triggered when the result set from an invisible widget is updated by script APIs such as setDimensionFilter and setVariableValue.

When invisible widgets become visible, any previously paused operations that result in data refresh will impact them again and update their data. Query will be sent by tables whether data will be changed or not.
Always Pause
No data refresh will take place in runtime. We recommend checking Disable Interaction as well as most of the interactions won’t take effect.

Later when you disable this mode, DataSource.refreshData and other refresh activities can be automatically resumed except for planning activities, which needs to be manually triggered.

Data Refresh Settings by Script APIs

After defining default settings above, you can further leverage RefreshPaused APIs to allow end users to start or stop data refresh:

Code Syntax

// Set data refresh mode.
DataSource.setRefreshPaused(paused: PauseMode | boolean): void

// Get data refresh mode, which returns On, Off or Auto.
DataSource.getRefreshPaused(): PauseMode

The modes defined in script APIs correspond to the options in the Builder panel as follows:

In Script APIs	In Builder Panel
`PauseMode.On`	Always Pause
`PauseMode.Off`	Always Refresh
`PauseMode.Auto`	Refresh Active Widgets Only

If you set data refresh mode for the same widget in both Builder panel and script editor, scripting will overwrite the settings in the panel.

Influence on Other Functionalities When Widgets are in Paused Mode

Refresh in the toolbar during application runtime won’t work on this widget.
All context menus (including right-click menu and quick action menu) will be disabled.
All data related actions that can trigger query will be disabled.
Planning will be automatically disabled, which means:
- The planning Properties in the widget’s Builder panel and planning menu item in the toolbar during application runtime will be automatically disabled.
- If application user change to another planning model, planning will still be automatically disabled.
- Changing planning data in another table from the same planning model won’t trigger data refresh in the table in paused status.
- All planning APIs (including ones that enable planning) won’t take effect or return default value according to its return type declaration (except for submitData, setUserInput and setPlanningEnabled. They return false instead).
- Application users can enable planning for tables in paused mode in runtime. However, they will receive a warning message that they can't change to PauseMode.On or PauseMode.Auto again once planning is enabled. To prevent them from enabling planning and losing planning data they input, we recommend application designers to disable planning before enabling widgets to pause.
Changing script variables used in calculated measure won’t result in the refresh of related widgets.
PDF exporting is based on currently rendered result.
All modifications of time series forecast, smart grouping and navigation panel will be applied to the widget’s existing state.
All APIs can be called, but won’t trigger data refresh of the widget, which means:
- Application.refresh and DataSource.refreshData won’t work on the widget.
- All Getter APIs will return results based on the widget’s existing state.
- All Setter APIs will apply to the widget’s existing state and no data refresh will be triggered.
  
  Note
  
  However, some local property and styling setting APIs such as DataSource.setMemberDisplay will cause the widget to re-render.
- Open Explorer API and Smart Insights will use the current state of the widget.
  
  Note
  
  However, paused mode doesn’t work on this widget in Explorer.
- Prompt APIs can be called but the widget won’t refresh after prompt values are set.
- SearchToInsight result API can be called but the widget won’t refresh.
If no values are defined for mandatory variables in a widget’s data source, the variable dialog will pop up, for example, when the table in paused mode is called by setModel API.

Exceptional Cases When Widgets are in Paused Mode

There’re exceptional cases where some queries would still be triggered even when widgets don't always refresh:

APIs	Queries (first time query without cache)
`DataSource.getMembers`	Query remote dimension members.
`DataSource.setDimensionFilter`	Fetch member information if no `MemberInfo` object is specified in the API. Note Therefore, we recommend you set `MemberInfo` if possible as the example below: Chart_1.getDataSource().setDimensionFilter("Location_4nm2e04531", { dimensionId: "Location_4nm2e04531", id: "[Location_4nm2e04531].[State_47acc246_4m5x6u3k6s].&[SA1]", description: "California", displayId: "California" });
`DataSource.setVariableValue`	For application-level variable in BW model, five queries are triggered by `submitStoryVariable` action: `reInitVariablesAfterSubmit` `reInitVariablesAfterSubmit` `submitVariables` `updatePromptDescriptions` `processSynchronization` For widget-level variable in BW model: Two queries are triggered in chart: `submitVariables` `reInitVariablesAfterSubmits` One query is triggered in table: `submitVariables` Note This is applicable when variable is set via scripting during application runtime or initial value is set in design time.
`DataSource.setHierarchy`	For BW model, two queries are triggered: `ProcessHierarchyCatalogManagerCreation` `getHierarchiesFromCatalog`
`DataSource.expandNode`	For BW model, two queries are triggered: `submitVariable` `fetchMembersWithDescription`
`DataSource.collapseNode`	For chart in BW model, two queries are triggered: `submitVariable` `processSynchronization`
`Table.setModel` `Table.openSelectModelDialog`	For BW model, five queries are triggered: `turnOffBatchAndShutdownQueryManager` `buildquerymanager` `activateVariableVariant` `submitVariables` `submitVariables` For other models, two queries are triggered: `turnOffBatchAndShutdownQueryManager` `processMemberHelp` (to fetch members of Account)
Initial loading of application with BW model and variables	Two queries are triggered: `fetchStoryVariableDetail` `submitBWVariableforActivePage` For table, extra four queries are triggered: `submitVariable` `processSynchronization` `processSynchronization` `processSynchronization`

Code Example

Let’s say you want to turn on or off data refresh and interaction of Chart_1 and Table_1 via two switches, Switch_Refresh and Switch_Interaction.

Leave the options Always Refresh checked and Disable Interaction unchecked in the Builder panel of both Chart_1 and Table_1. Meanwhile, both the two switches’ default status is on.

Write the scripts below for Switch_Refresh:

Sample Code

if (Switch_1.isOn()) {
    Chart_1.getDataSource().setRefreshPaused(PauseMode.Off);
    Table_1.getDataSource().setRefreshPaused(PauseMode.Off);
} else {
    Chart_1.getDataSource().setRefreshPaused(PauseMode.On);
    Table_1.getDataSource().setRefreshPaused(PauseMode.On);
}

Write the scripts below for Switch_Interaction:

Sample Code

Chart_1.setEnabled(!Chart_1.isEnabled());
Table_1.setEnabled(!Table_1.isEnabled());

After that, when you turn off the two switches, the chart and table won’t refresh when you perform various activities such as adding filters to and setting hierarchy level of the chart and table, setting the variable value used by the reference line in the chart and collapsing the parent node in the table.

Later once you turn on the two switches again, the chart and table will automatically refresh and display the latest results.