How to apply background filters in the dashboard programmatically [Linux]
Introduction
This article explains how to programmatically apply background filters to Sisense dashboards using JavaScript. Background filters allow you to set filter criteria that are not visible or directly editable by end users, but still affect the data displayed in widgets. This approach is useful for enforcing business logic or default data scoping behind the scenes. The solution described here is tested on Sisense L2026.1 and is compatible with both cloud and on-premises deployments.
Step-by-Step Guide
Prepare Your Environment
Create a new dashboard or go to an existing dashboard with at least 1 widget. Apply a filter with “Include all” option for the value you want to apply the background filter to.
Apply the code
Go to three dots menu in the dashboard, Edit Script, and paste the following code:
var filterValue = 'ABC'
function setFilter(value) {
// Getting specifically the existing Brand filter to apply a background filter on it. Change it to get the filter you want.
// Note in this context the Brand filter must already exist in your dashboard, even if with "Include all" applied.
var filter = prism.activeDashboard.filters.$$items.find(function(f){
return f.jaql && f.jaql.title === 'Brand';
});
if (filter) {
filter.jaql.filter = { // This is the main filter
explicit: false,
multiSelection: false,
all: true,
filter: { // This is the background filter
contains: value,
isBetween: false
}
// You can also change the main filter value here if you want, defining a contains or members array for example.
};
<br>
prism.activeDashboard.filters.update(filter, {save: true, refresh: true});
}
}
<br>
dashboard.on('widgetready', function(scope, args) {
setFilter(filterValue);
});Code Explanation
filterValue: The value you want to apply as a background filter.
setFilter(value): This function searches for the specified dashboard filter (by title, e.g., "Brand"). It then updates the filter’s JAQL object, nesting the background filter criteria inside the main filter object.
filter.jaql.filter: The main filter object. The nested filter property sets the background filter criteria (e.g., contains: value).
prism.activeDashboard.filters.update: Applies the updated filter to the dashboard, saving and refreshing widgets.
dashboard.on('widgetready', ...): Ensures the filter is applied after all widgets are loaded, preventing timing issues.
This is just a basic example, feel free to use it as a base to create a custom code that will apply the background filters under some specific conditions or action trigger. As a result, you should see something similar as the following screenshot, the black funnel icon suggesting there is a background filter applied, then if you go to the three dots, Edit background filter, you will see the exact filter and values applied programmatically in the UI.
Note: The filter must already exist in the dashboard for this script to work. If you need to dynamically add filters, use the Sisense JavaScript API methods for creating filters.
Conclusion
Applying background filters programmatically in Sisense dashboards empowers developers and administrators to tailor data visibility and enforce business logic without exposing filter controls to end users. This approach enables advanced scenarios such as dynamic data segmentation, automated contextual filtering, and compliance-driven data access—all managed seamlessly behind the scenes. By leveraging JavaScript, you can respond to user actions, external events, or custom logic to adjust dashboard filters in real time, unlocking new levels of flexibility and automation in your analytics environment. This capability is especially valuable for creating personalized dashboards, implementing security rules, or integrating Sisense with external systems, making your dashboards smarter and more responsive to business needs.
References/Related Content
Disclaimer:This post outlines a potential custom workaround for a specific use case or provides instructions regarding a specific task. The solution may not work in all scenarios or Sisense versions, so we strongly recommend testing it in your environment before deployment. If you need further assistance with this, please let us know.
