Using Pause Refresh APIs

As an application designer, you can pause the refresh of a chart or table until application users have completed corresponding actions or necessary initial loading activities. This can improve the efficiency of retrieving and updating a table or chart when running an application.

Once you trigger the pause refresh of a chart or table, no data refresh will take place. Later when you disable the pause refresh status, dataSource.refreshData() APIs and other refresh activities can be automatically triggered again, except for planning activities, which needs to be manually triggered.

Note

Currently, R visualization widget doesn’t support pause refresh.

You can define whether you want to pause the refresh data or disable interaction both in a widget’s Builder panel and via Script API.

In the Builder panel, two options are available:

  • Pause Data Refresh

  • Disable Interaction

We recommend you disable user interactions of the widget while you pause data refresh, as most of the interactions won’t take effect.

After defining a default setting above, you can further leverage scripts APIs to allow end users start or stop data refresh and user interactions via corresponding RefreshPaused APIs. Noted that for now, in one event if you set pause refresh API for multiple charts to false, each chart will render one after another. For more information, refer to the Analytics Designer API Reference.

Influence on other functionality when RefreshPaused=true

After you set a widget to pause refresh status:

  • Application’s refresh toolbar 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 widget’s toolbar during application runtime are automatically disabled.

    • If application user change to another planning model, planning is still automatically disabled for that model.

    • If another table is bond to the same planning model as this widget, changing that table’s planning data won’t trigger the widget to refresh.

    • 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).

    • During the application runtime, the widget can’t be refreshed. However, application users might still have the option to enable planning again. Once planning is enabled, end users won’t be able to set RefreshPaused to “true” with a warning message. To prevent them from enabling planning and losing planning data they input, we recommend application designers explicitly disable planning before enabling pause refresh status.

  • Changing script variables used in Calculated Measure won’t result in related widget refreshing.

  • 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 trigger the widget to re-render.

    • OpenExplorer API and Smart Insights will use current state of the widget.

      Note

      However, PauseRefresh doesn’t work on this widget in Explorer.

    • Prompt APIs can be called but the widget won’t be refreshed after setting prompt values.

    • SearchToInsights result API can be called but the widget won’t be refreshed according to the new viz definition .

Later if you set the widget’s RefreshPaused to false, the widget will be automatically refreshed. But planning is not, so you need to manually enable planning again.

Exceptional Cases When RefreshPaused=true

However, there’re some exceptional cases that some queries would still be triggered when you set a widget to pause refresh status:

APIs Queries (first time query without cache) Comment
DataSource.getMembers() Query dimension members from remote  
DataSource.setDimensionFilter() Fetch member information if no MemberInfo object is specified in the API

Therefore, we recommend you set MemberInfo if possible. For example as below:

Chart_1.getDataSource().setDimensionFilter("Location_4nm2e04531", {

dimensionId: "Location_4nm2e04531",

id: "[Location_4nm2e04531].[State_47acc246_4m5x6u3k6s].&[SA1]",

description: "California",

displayId: "California"

});
DataSource.setVariableValue()

Application level variable in BW Model:

5 queries are triggered by submitStoryVariable action:

  • reInitVariablesAfterSubmit

  • reInitVariablesAfterSubmit

  • submitVariables

  • updatePromptDescriptions

  • processSynchronization

 This is applicable when variable is set via triggering scripting during application runtime or having initial value set when designing an application.

Widget level variable in BW Model:

2 queries are triggered in Chart:

  • submitVariables

  • reInitVariablesAfterSubmits

1 query is triggered in Table:

  • submitVariables
DataSource.setHierarchy()

For BW Model:

2 queries are triggered:

  • ProcessHierarchyCatalogManagerCreation

  • getHierarchiesFromCatalog

  
DataSource.expandNode()

For BW Model:

2 queries are triggered:

  • submitVariable

  • fetchMembersWithDescription

  
DataSource.collapseNode()

For BW Model in Chart:

2 queries are triggered:

  • submitVariable

  • processSynchronization

  

Table.setModel()

Table.openSelectModelDialog()

For BW Model:

5 queries are triggered:

  • turnOffBatchAndShutdownQueryManager

  • build query manager

  • activateVariableVariant

  • submitVariables

  • submitVariables

For other Model:

2 queries are triggered:

  • turnOffBatchAndShutdownQueryManager

  • processMemberHelp (to fetch members of Account)

  
Application initial loading BW model with BW variables

Besides 2 queries:

  • fetchStoryVariableDetail

  • submitBWVariableforActivePage

For Table, extra 4 queries are triggered:

  • submitVariable

  • processSynchronization

  • processSynchronization

  • processSynchronization

  
Code Example

Let’s say you want to enable or disable the pause refresh and interaction of Chart_1 and Table_1 via two switches:

  • Switch_Refresh, controls the pause refresh activities

  • Switch_Interaction, controls the interaction of widgets

Leave the options Pause Data Refresh and Disable Interaction in the Builder panel of Chart_1 and Table_1 uncheck. Meanwhile, both the two switches’ default status is On.

Write the script below for Switch_Refresh:

Sample Code
Chart_1.getDataSource().setRefreshPaused(!Chart_1.getDataSource().isRefreshPaused());
Table_1.getDataSource().setRefreshPaused(!Table_1.getDataSource().isRefreshPaused());

Write the script 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 chart reference line and collapsing the parent node in table.

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