Skip to content

Dashboard Scripting

Subscription Tier Required

This feature requires the Premier subscription tier or higher.

Scripting Principles

In order to effectively make use of scripting in GS, you should be familiar with the following topics:

Scripts in GS run inside of a Web Worker, which allows access to a subset of available browser APIs. Scripts executed in GS will never be able to directly access the DOM.

Scripts in GS will execute once, from top to bottom, in the order which they are listed. Selected Library Scripts will be executed before any Inspection or Dashboard scripts.

GS makes heavy use of the async / await pattern. Prefer using async and await over .then(...) when writing code for GS to ensure the expected order of execution.

Scripts may be managed using the Scripts action in the Dashboard Editor, or by pressing Ctrl+Alt+C.

An image showing the location of the Script action in the Dashboard Editor

Dashboard API

All Dashboard-specific functions and objects are under gsApi.dashboard. This API contains a variety of events, functions, and access to other APIs.

For a full reference, see the Dashboard API.

Retrieval API

In order to access properties and functions for a specific Retrieval, a Retrieval API must be constructed. This is done by passing the Script ID of the Retrieval into the retrieval function:

gsApi.dashboard.retrieval('myScriptId');

This API may be stored in a variable for later use. For example, the following code:

const properties = await gsApi.dashboard.retrieval('myScriptId').getProperties();
await gsApi.dashboard.retrieval('myScriptId').updateProperties({
    maxRecords: properties.maxRecords + 10
});

Is equivalent to:

const myRetrieval = gsApi.dashboard.retrieval('myScriptId');
const properties = await myRetrieval.getProperties();
await myRetrieval.updateProperties({
    maxRecords: properties.maxRecords + 10
});

Dashboard Item APIs

In order to interact with Dashboard Items, a Dashboard Item API must be constructed. This is done by passing the Script ID of the Dasboard Item into the appropriate function on the dashboard API:

gsApi.dashboard.controlChart('myControlChart');

As with Retrievals, Dashboard Item APIs may be stored for later use:

const controlChart = gsApi.dashboard.controlChart('myControlChart');
await controlChart.updateProperties({
    ...
});

React To Events

Most Dashboard scripting functionality will happen in response to events. These events allow binding a function which is executed whenever the event occurs. For example, to execute code whenever a Button Dashboard Item is pressed, bind to the onClick event:

gsApi.dashboard.button('myButton').onClick(async () => {
    console.log('This will be logged whenever the button is clicked');
});

To wait until the Dashboard is fully loaded and ready to interact with, bind to the onReady event:

gsApi.dashboard.onReady(async () => {
    // It is now safe to interact with retrievals and dashboard items
});

To perform an action just before a Retrieval is used to fetch data, bind to the onBeforeRetrieved event:

gsApi.dashboard.retrieval('myRetrieval').onBeforeRetrieved(async () => {
});

To perform an action before a Dashboard Item is drawn, but after data has been retrieved for it, use the onBeforeDraw event:

gsApi.dashboard.controlChart('myControlChart').onBeforeDraw(async (e) => {
});

onBeforeDraw is a special event for Chart Dashboard items. Modifying the plotlyData object inside of the event's data object will change how the chart is drawn. See Modifying Existing Charts for more details.

Retrieve Extra Data

Although it is not possible to dynamically add new Retrievals to a Dashboard with scripting, existing Retrievals may be updated to include other data. This is done by creating an AlsoRetrieveApi using RetrievalApi.alsoRetrieveWhenRefreshed(), which allows accessing data that is not being fetched by any existing Dashboard Items:

const alsoRetrieveApi = await gsApi.dashboard.retrieval('myRetrieval').alsoRetrieveWhenRefreshed([{
    type: 'spcData',
    id: 'mySPCData',
    splitBy: ['characteristic']
}]);

alsoRetrieveApi.onRetrieved(async (e) => {
    e.data.response.spcData['mySPCData'].forEach((data) => {
        // Do something with the data detail
    });
});

Information

Unlike most other APIs, creating an AlsoRetrieveApi requires using the await keyword. This is due to asynchronously modifying the internal structure of the requested Retrieval.

Next Steps

Now that you're familiar with basic principles of Dashboard Scripting in GS, you are ready to walk through some specific scripting tasks: