Asynchronous Loading

This page explains how async loading works, along with how and when to use two different methods for async loading.

About async loading

Asynchronous (async) loading can provide a better user experience by allowing users to interact with key elements of the interface while they are waiting for slower-loading components to display. By reducing the initial wait time, users experience a more responsive interface, keeping them engaged and productive. This is especially useful in dashboards and employee home pages.

There are two ways to enable async loading in your interfaces:

• Configure read-only grid, chart, and KPI components to load independently using the loadDataAsync parameter
• Use the a!asyncVariable() function to create an async variable. This allows you to load data asynchronously for use anywhere in your interface, including in more than one component.

In both cases, the components waiting on data will display placeholder skeletons, so users know they can expect content to display soon.

How async loading works

Normally, when an interface evaluates, it must wait for all of the components and data queries to load before it can display the whole interface, as in the following diagram:

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

Async loading allows the rest of the interface to display while it waits for the data to load in the background, which works like this:

1. All non-async components evaluate. The non-async components load as normal and the async component displays a placeholder skeleton.

2. After the async data loads, the whole interface reevaluates and all components display, including the async component.

   Tip:  For read-only grids that use the loadDataAsync parameter, the user filters load async as well as the data in the grid.

3. If you have more than one async component, they will load independently from each other and the interface will reevaluate after the data loads for each async component.

Scroll or drag to pan · ⌘+/⌘− to zoom · Esc to close

How to enable async loading

You can enable async loading in your interface using one of two methods: use the a!asyncVariable() function to create async variables, or use the loadDataAsync parameter (only for read-only grid, chart, or KPI components).

Choosing between a!asyncVariable and loadDataAsync

Read-only grid, chart, and KPI components offer two ways to load their data asynchronously. Use the following table to decide which method is best for your use case.

Create an async variable using the a!asyncVariable() function

You can create an async variable by using the a!asyncVariable() function to define a local variable. Any component that uses the async variable will wait for the data to load and display a placeholder in the meantime. See a!asyncVariable() for more information on how the placeholder behavior works.

This method allows you to load data asynchronously for use anywhere in an interface.

To use this method:

1. In an a!localVariables() function, wrap the expression for your data (such as a query) in the a!asyncVariable() function. For example:

   1
   2
   3
   4
   5
   6
   7
   a!localVariables(
     local!asyncData: a!asyncVariable(
       value: a!queryRecordType(
         ...
       )
     )
   )
   

2. Use the resulting local variable in one or more components.

See the a!asyncVariable() Function page for examples.

Use the loadDataAsync parameter on grids, charts, and KPIs

This method applies specifically to read-only grids, charts, and KPIs when they use a record type in the data parameter.

To enable async loading using loadDataAsync:

1. For the component's data parameter, use a record type reference.
2. Set the loadDataAsync parameter to true.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
a!gridField(
  labelPosition: "COLLAPSED",
  data: 'recordType!{SYSTEM_RECORD_TYPE_USER}User',
!  loadDataAsync: true,
  columns: {
    a!gridColumn(
      label: "First And Last Name",
      sortField: 'recordType!{SYSTEM_RECORD_TYPE_USER}User.fields.{SYSTEM_RECORD_TYPE_USER_FIELD_firstAndLastName}firstAndLastName',
      value: fv!row['recordType!{SYSTEM_RECORD_TYPE_USER}User.fields.{SYSTEM_RECORD_TYPE_USER_FIELD_firstAndLastName}firstAndLastName']
    ),
    a!gridColumn(
      label: "Title",
      sortField: 'recordType!{SYSTEM_RECORD_TYPE_USER}User.fields.{SYSTEM_RECORD_TYPE_USER_FIELD_title}title',
      value: fv!row['recordType!{SYSTEM_RECORD_TYPE_USER}User.fields.{SYSTEM_RECORD_TYPE_USER_FIELD_title}title']
    )
  }
)

When to enable async loading

Async loading is most beneficial for parts of an interface that are slow to load because they are waiting on data from a query or integration. This is especially helpful for integrating with slow external systems that you can't control. A good rule of thumb is to use async loading for any data that takes longer than 500 ms to retrieve.

Performance and resource considerations

To maintain application performance and scalability, use a!asyncVariable() strategically, not for every query. Each async variable requires additional server resources, so using them too often can negatively impact your environment's performance and the user experience.

As a best practice:

• Start with the slowest loading data. Focus your efforts on the parts of the interface that will provide the most noticeable improvement.
• Limit the number of async variables to 7 per interface for the best performance.
• Don't make a variable async if it's already fast. If a query consistently returns in under 500ms, the flash of a loading placeholder can feel more jarring to a user than a brief, synchronous load.

Identifying slow-loading components

Use the interface object's Performance Details to identify slow-loading components that could benefit from being loaded async.

To identify slow-loading components:

1. In the interface header, click Performance Details .
2. Run an interface evaluation.
   • To test the interface with certain rule input values, choose a test scenario or run an ad hoc test.
   • To test the interface with default rule input and local variable values, in the interface header, click the reset button .
3. Under Parameters and Direct Children, identify the slowest loading local variables or components.

When using the performance details, remember that performance in your development environment will likely be different from production. To get a more accurate assessment, you may need to mimic production-level data volumes in your testing environment. See Best Practices: Database Volume Testing for more information.

Feedback