Skip to content

Dynamic Filters

Subscription Tier Required

This feature requires the Premier subscription tier or higher.

Sometimes, you may want to dynamically change the data displayed in a Dashboard, such as filtering by the current shift or a specific work center.

In this guide, you will use scripting and Button Items to dynamically update a Retrieval's filter at runtime.

You should be familiar with the principles of Dashboard Scripting before getting started.

Prerequisites

This guide assumes that you have:

  • At least one Process with SPC and DMS data.
  • Data collected across multiple Traceability values (such as different shifts or work centers).

This guide uses the Final Inspection Process and the Shift Traceability.

Create the Dashboard

To begin, create a new Dashboard. The fastest way to create a new Dashboard is to navigate to the Quick Chart menu entry, which acts as a shortcut for a new Dashboard.

Add a Retrieval

Next, add a Retrieval:

  1. Press the Add Retrieval button. An image showing the location of the Add Retrieval button on the Dashboard
  2. Fill in the Retrieval Name with Filter Demo.
  3. Change the Script ID to filterDemo. An image showing the Name and Script ID fields
  4. Modify the Date field to a range which includes data for your Process. An image showing the date field
  5. Select your Process in the Processes field. An image showing the process field
  6. (Optional) Update the Maximum Records to Retrieve per Standard to include more data.
  7. Press Confirm. An image showing the confirm button

Add Buttons

Add four Button items and resize them to each take up a quarter of the Dashboard's width. Set the Label and Script ID of the Buttons to:

  • Shift 1, with Script ID shift1
  • Shift 2, with Script ID shift2
  • Shift 3, with Script ID shift3
  • Reset, with Script ID reset

An image showing the buttons

Add Charts

Add a Control Chart and a Pareto Chart to the Dashboard. Select the previously-created Retrieval (Filter Demo) for both.

An image showing the charts and buttons

Scripting

Now that the Dashboard has been set up, you can begin scripting. Create a new Dashboard Script and give it a memorable name. If this interface is unfamiliar, review the Dashboard Scripting Principles and Code Editor articles.

An image showing the location of the Dashboard Script action

An image showing the location of the add button in the Dashboard Script overlay

The tasks we will use scripting to accomplish are:

  1. Listening to the Button onClick() events.
  2. Changing the Retrieval's filter property.
  3. Resetting the Retrieval's filter when Reset is clicked.

Listen to the Button Click Events

In the newly created Dashboard scipt, add onClick event handlers for the Buttons:

gsApi.dashboard.button('shift1').onClick(async () => {

});
gsApi.dashboard.button('shift2').onClick(async () => {

});
gsApi.dashboard.button('shift3').onClick(async () => {

});
gsApi.dashboard.button('reset').onClick(async () => {

});

These events will fire when the associated Button is clicked.

Change the Retrieval's Filter

At the top of the script, add a reference to the Retrieval and a promise which will resolve to the ID of the Shift Traceability:

const retrieval = gsApi.dashboard.retrieval('filterDemo');
const shiftPromise = gsApi.entity.getTraceabilityIdByName('Shift');

gsApi.dashboard.button('shift1').onClick(async () => {

Note that this does not use the await keyword. Instead, we are issuing a request to retrieve the Traceability's ID as soon as the script is loaded, and storing the resulting Promise for later use. This will allow us to begin fetching as soon as the script loads, but ensure that it has finished loading when the Traceability ID is actually needed.

At the bottom of the script, define a function that will update the Retrieval's filter and refresh the Retrieval:

gsApi.dashboard.button('reset').onClick(async () => {

});

/**
 * @param {string} newShift The Shift name to filter by
 */
async function updateShift(newShift) {
    await retrieval.updateProperties({
        filter: {
            grouping: 'all',
            nodes: [{
                filterBy: 'trace',
                entityId: await shiftPromise,
                operationId: 'textIs',
                value: newShift
            }]
        }
    });
    await retrieval.refresh();
}

This script makes use of a Retrieval's Quick Filter by setting the filter property to a FilterExpression.

Now call this function inside of the existing onClick() handlers:

gsApi.dashboard.button('shift1').onClick(async () => {
    await updateShift('Shift 1');
});
gsApi.dashboard.button('shift2').onClick(async () => {
    await updateShift('Shift 2');
});
gsApi.dashboard.button('shift3').onClick(async () => {
    await updateShift('Shift 3');
});

Reset the Retrieval

When the Reset button is clicked, reset the Retrieval's Filter and refresh it. Add the following code to the button's onClick() handler:

gsApi.dashboard.button('reset').onClick(async () => {
    await retrieval.updateProperties({ filter: null });
    await retrieval.refresh();
});

Tip

null is used to set optional properties to their unset state.

Test the Dashboard

Save and View the Dashboard. If you have not previously saved the Dashboard, fill in the Name overlay with Dynamic Filtering. Try clicking each shift button to filter the data, then click Reset to clear the filter.

An image showing the final dashboard

Additional Exercises

On your own, attempt to:

  • Use the Buttons to modify the Retrieval's datePeriod to Today, Last Week, and Last Year.
  • Add a second Retrieval and update both Retrievals when a Button is clicked.
  • Highlight the selected Button by changing its backgroundColor.

Final Code

const retrieval = gsApi.dashboard.retrieval('filterDemo');
const shiftPromise = gsApi.entity.getTraceabilityIdByName('Shift');

gsApi.dashboard.button('shift1').onClick(async () => {
    await updateShift('Shift 1');
});
gsApi.dashboard.button('shift2').onClick(async () => {
    await updateShift('Shift 2');
});
gsApi.dashboard.button('shift3').onClick(async () => {
    await updateShift('Shift 3');
});
gsApi.dashboard.button('reset').onClick(async () => {
    await retrieval.updateProperties({ filter: null });
    await retrieval.refresh();
});

/**
 * @param {string} newShift The Shift name to filter by
 */
async function updateShift(newShift) {
    await retrieval.updateProperties({
        filter: {
            grouping: 'all',
            nodes: [{
                filterBy: 'trace',
                entityId: await shiftPromise,
                operationId: 'textIs',
                value: newShift
            }]
        }
    });
    await retrieval.refresh();
}