<script custom-tag="" type="application/ld+json">{"@context":"https://schema.org","@type":"TechArticle","headline":"Create a custom interactive filter widget","image":"http://support.servicenow.com/29f1d2661baf6010cafa53d8624bcb43.iix","author":{"name":"ServiceNow Support","url":"http://support.servicenow.com/now"},"keywords":"ServiceNow, NowSupport public Knowledge Base articles, Product Documentation: Washington DC,KB1623350,","wordcount":"4375","publisher":"ServiceNow","url":"https://support.servicenow.com/kb?id=kb_article_view&sysparm_article=KB1623350","datePublished":"2025-04-07","dateCreated":"2024-02-01","dateModified":"2024-02-01","description":"<h2>Create a custom interactive filter widget</h2><br/><div style=\"overflow-x:auto\">\n\n<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"><head><meta content=\"text/html; charset=UTF","articleBody":"<h2>Create a custom interactive filter widget</h2><br/><div style=\"overflow-x:auto\">\n\n<html xmlns=\"http://www.w3.org/1999/xhtml\" xml:lang=\"en\" lang=\"en\"><head><meta content=\"text/html; charset=UTF-8\" /><meta name=\"copyright\" content=\"(C) Copyright 2025\" /><meta name=\"DC.rights.owner\" content=\"(C) Copyright 2025\" /><meta name=\"generator\" content=\"DITA-OT\" /><meta name=\"DC.type\" content=\"reference\" /><meta name=\"DC.title\" content=\"Custom interactive filter examples\" /><meta name=\"abstract\" content=\"As an administrator, you can create custom interactive filter widgets to provide advanced filtering options on dashboards.\" /><meta name=\"description\" content=\"As an administrator, you can create custom interactive filter widgets to provide advanced filtering options on dashboards.\" /><meta name=\"DC.subject\" content=\"Interactive filters, Custom filter example\" /><meta name=\"keywords\" content=\"Interactive filters, Custom filter example\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../../../use/dashboards/concept/c_CustomPublishers.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../../../use/performance-analytics/concept/c_performanceAnalyticsAndReporting.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../../../use/reporting/concept/classic-vis-overview.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../../../use/dashboards/concept/c_HomepagePublishers.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../administer/content-management/task/t_CreateAContentBlock.dita/t_CreateAContentBlock.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../script/client-scripts/concept/c_UIScripts.dita/c_UIScripts.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../script/general-scripting/reference/r_JellyTags.dita/r_JellyTags.html\" /><meta name=\"DC.relation\" scheme=\"URI\" content=\"../../../app-store/dev_portal/API_reference/DashboardMessageHandler/concept/c_DashboardMessageHandler.html\" /><meta name=\"DC.contributor\" content=\"joe.silber\" /><meta name=\"DC.contributor\" content=\"courtney.bradwell\" /><meta name=\"DC.creator\" content=\"ServiceNow\" /><meta name=\"DC.date.created\" content=\"2023-08-03\" /><meta name=\"DC.date.modified\" content=\"2024-02-01\" /><meta name=\"DC.format\" content=\"XHTML\" /><meta name=\"DC.identifier\" content=\"r_CustomPublisherExample\" /><link rel=\"stylesheet\" type=\"text/css\" href=\"../../../CSS/commonltr.css\" /><title>Custom interactive filter examples</title></head><body>\n<div class=\"nested0\" id=\"r_CustomPublisherExample\">\n <h1 class=\"title topictitle1\" id=\"ariaid-title1\">Custom interactive filter examples</h1>\n\n \n \n <div class=\"body refbody\"><p class=\"shortdesc\">As an administrator, you can create custom interactive filter widgets to provide\n advanced filtering options on dashboards.</p>\n\n <div class=\"section\"><h2 class=\"title sectiontitle\">Use case</h2>\n \n <p class=\"p\">This example details how to create a custom filter to filter reports on the Task table, or its\n child tables. The filter only shows records where the current user is the caller. The filter\n exposes two buttons to the user, one button to add the filter and one to remove the\n filter.</p>\n\n </div>\n\n </div>\n\n <div class=\"related-links\">\n<div class=\"familylinks\">\n<div class=\"parentlink\"><strong>Parent Topic:</strong> <a class=\"link\" href=\"../../../use/dashboards/concept/c_CustomPublishers.html\" title=\"As an administrator, you can create scripted interactive filter widgets to provide advanced filtering options on dashboard reports.\">Custom interactive filters</a></div>\n</div>\n\n<div class=\"linklist relinfo relconcepts\"><strong>Related concepts</strong><br />\n<ul class=\"linklist\"><li class=\"linklist\"><a class=\"link\" href=\"../../../app-store/dev_portal/API_reference/DashboardMessageHandler/concept/c_DashboardMessageHandler.html\" title=\"Provides methods to define custom filtering logic for interactive filters.\">DashboardMessageHandler</a></li></ul></div>\n\n<div class=\"linklist relinfo\"><strong>Related topics</strong><br />\n<ul class=\"linklist\"><li class=\"linklist\"><a class=\"link\" href=\"../administer/content-management/task/t_CreateAContentBlock.dita/t_CreateAContentBlock.html\" target=\"_blank\" rel=\"noopener noreferrer\">Configure a content block</a></li><li class=\"linklist\"><a class=\"link\" href=\"../script/client-scripts/concept/c_UIScripts.dita/c_UIScripts.html\" target=\"_blank\" rel=\"noopener noreferrer\">UI scripts</a></li><li class=\"linklist\"><a class=\"link\" href=\"../script/general-scripting/reference/r_JellyTags.dita/r_JellyTags.html\" target=\"_blank\" rel=\"noopener noreferrer\">Jelly tags</a></li></ul></div>\n</div>\n<div class=\"topic task nested1\" id=\"create-custom-if-widget\">\n <h2 class=\"title topictitle2\" id=\"ariaid-title2\">Create a custom interactive filter widget</h2>\n\n \n \n <div class=\"body taskbody\"><p class=\"shortdesc\">Create custom interactive filter widgets to provide advanced filtering options on\n dashboards.</p>\n\n <div class=\"section prereq p\">\n <p class=\"p\">Role required: admin</p>\n\n </div>\n\n <ol class=\"ol steps\"><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Open a dashboard that you want to add the custom interactive filter to.</span>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Click the add content icon (<img class=\"image icon\" id=\"create-custom-if-widget__image_qrq_mm5_trb\" height=\"20\" src=\"../image/icon-add-user-db.png\" alt=\"\" />).</span>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">From the <span class=\"ph uicontrol\">Widget Category</span> list, select Content\n Blocks.</span>\n <div class=\"itemgroup info\">\n <img class=\"image\" id=\"create-custom-if-widget__image_zt4_gn5_trb\" src=\"../image/add-content-block-db-polaris.png\" alt=\"Widget category menu with Content Blocks selected\" />\n </div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">From the list of content blocks, select New Dynamic\n Content.</span>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">In the New Dynamic Content panel, click <span class=\"ph uicontrol\">Add</span>.</span>\n <div class=\"itemgroup info\">\n <img class=\"image\" id=\"create-custom-if-widget__image_e2z_sn5_trb\" src=\"../image/add-new-dynamic-content.png\" alt=\"New Dynamic Content widget option\" />\n </div>\n <div class=\"itemgroup stepresult\">A new Dynamic Content block is added to the dashboard.</div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">On the dashboard, click the link that says <span class=\"ph uicontrol\">Click here to configure\n this reusable Dynamic Content block</span>.</span>\n <div class=\"itemgroup info\">\n <img class=\"image\" id=\"create-custom-if-widget__image_s2g_np5_trb\" src=\"../image/add-new-dynamic-content-config.png\" alt=\"New Dynamic Content widget option\" />\n </div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Define the filtering logic in the <span class=\"ph uicontrol\">Dynamic content</span> field.</span>\n <div class=\"itemgroup info\">\n <img class=\"image\" id=\"create-custom-if-widget__image_zcc_plp_h2b\" src=\"../image/db-custom-interactive-filter-ex.png\" alt=\"Dynamic content - New record\" />\n </div>\n </li></ol>\n\n <div class=\"section postreq\" id=\"create-custom-if-widget__postreq_fhy_hr5_trb\">\n <p class=\"p\">Define the filtering logic.</p>\n\n </div>\n\n </div>\n\n</div>\n<div class=\"topic task nested1\" id=\"create-custom-date-time-filter\">\n <h2 class=\"title topictitle2\" id=\"ariaid-title3\">Create a custom date/time filter option</h2>\n\n \n \n <div class=\"body taskbody\"><p class=\"shortdesc\">When the standard selection of date/time filter options doesn't meet your needs, you\n can create a custom option.</p>\n\n <div class=\"section prereq p\">\n <p class=\"p\">Follow these steps to create a custom Date/Time filter option that can then be\n included in any Date/Time-based interactive filter for use on a Dashboard. In this\n example, you create a filter option for the period of a two weeks, a fortnight.</p>\n\n <p class=\"p\">Role required: admin.</p>\n\n </div>\n\n <ol class=\"ol steps\"><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Navigate to <span class=\"ph menucascade\"><span class=\"ph uicontrol\">All</span> > <span class=\"ph uicontrol\">System Definition</span> > <span class=\"ph uicontrol\">Business Rules</span></span>.</span>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Open the business rule Get Date Filter Options for Date Filters.</span>\n <div class=\"itemgroup info\">This rule populates the list of selectable options in forms for new or\n existing date type interactive filters.</div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">On the <span class=\"ph uicontrol\">Advanced</span> tab, modify the\n <span class=\"ph uicontrol\">Script</span> field to include the JavaScript needed to add\n the new option.</span>\n <div class=\"itemgroup info\">Add the following line:\n <pre class=\"pre codeblock\"><code>answer.add('<Time_Period_Name>@javascript:<Beginning_Time_Period>@javascript:<Ending_Time_Period>', gs.getMessage('<Textual_Representation_Of_Time_Period>'));</code></pre>\n </div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">In the line you added, make the following substitutions.</span>\n \n<table border=\"1\" frame=\"hsides\" rules=\"rows\" cellpadding=\"4\" cellspacing=\"0\" summary=\"\" class=\"simpletable choicetable choicetableborder\" id=\"create-custom-date-time-filter__choicetable_qnn_gnq_bvb\"><colgroup><col style=\"width:50%\" /><col style=\"width:50%\" /><table><thead><tr class=\"sthead chhead\"><th class=\"stentry choptionhd\" style=\"vertical-align:bottom;text-align:left;\" id=\"d33868e414-option\">Option</th><th class=\"stentry chdeschd\" style=\"vertical-align:bottom;text-align:left;\" id=\"d33868e414-desc\">Description</th></tr></thead><tbody><tr class=\"strow chrow\"><th style=\"vertical-align:top;\" headers=\"d33868e414-option\" id=\"d33868e418\" class=\"stentry choption\"><Time_Period_Name></th><td style=\"vertical-align:top;\" headers=\"d33868e414-desc d33868e418\" class=\"stentry chdesc\">A unique name for the time period selected. This string is used\n internally by the system to identify the option and is set to something\n that can be descriptive of the time period described.<p class=\"p\">Enter the value\n 112_Last Fortnight.</p>\n\n </td></tr><tr class=\"strow chrow\"><th style=\"vertical-align:top;\" headers=\"d33868e414-option\" id=\"d33868e433\" class=\"stentry choption\"><Beginning_Time_Period></th><td style=\"vertical-align:top;\" headers=\"d33868e414-desc d33868e433\" class=\"stentry chdesc\">The specific date and time on which this filter starts. This value\n can use absolute or relative values. It’s much more common to use a\n relative value that uses the JavaScript URL syntax.<p class=\"p\">Enter the value\n gs.daysAgoStart(14) to indicate that the\n time interval for this selection should be exactly two weeks\n ago.</p>\n\n </td></tr><tr class=\"strow chrow\"><th style=\"vertical-align:top;\" headers=\"d33868e414-option\" id=\"d33868e448\" class=\"stentry choption\"><Ending_Time_Period></th><td style=\"vertical-align:top;\" headers=\"d33868e414-desc d33868e448\" class=\"stentry chdesc\">The specific date and time on which the time period for this filter\n option should end. This value can also use absolute or relative values.\n Similar to the <span class=\"keyword parmname\">Beginning_Time_Period</span> this value is\n usually a relative time period to use the JavaScript URL syntax.<p class=\"p\">Enter\n the value gs.daysAgoStart(0) to indicate that\n the time period ends at the current date and time.</p>\n\n </td></tr><tr class=\"strow chrow\"><th style=\"vertical-align:top;\" headers=\"d33868e414-option\" id=\"d33868e466\" class=\"stentry choption\"><Textual_Representation_Of_Time_Period></th><td style=\"vertical-align:top;\" headers=\"d33868e414-desc d33868e466\" class=\"stentry chdesc\">A short text string that displays in the list of Date/Time filter\n options, which appear in ascending alphabetical order.<p class=\"p\">Enter\n Last fortnight, to indicate that this\n selection specifies a time period from one fortnight before the\n current date and time.</p>\n\n </td></tr></tbody></table></colgroup></table><div class=\"itemgroup stepresult\">The complete statement now\n reads:<pre class=\"pre codeblock\"><code>answer.add('112_Last Fortnight@javascript:gs.daysAgoStart(14)@javascript:gs.daysAgoEnd(0)', gs.getMessage('Last fortnight'));</code></pre>\n </div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Select <span class=\"ph uicontrol\">Update</span> to save your changes to the business\n rule.</span>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Check that the new option is available when you edit or create a Date/Time\n filter.</span>\n <ol type=\"a\" class=\"ol substeps\" id=\"create-custom-date-time-filter__substeps_z15_dsq_bvb\"><li class=\"li substep substepexpand\">\n <span class=\"ph cmd\">Navigate to <span class=\"ph menucascade\"><span class=\"ph uicontrol\">All</span> > <span class=\"ph uicontrol\">Reports</span> > <span class=\"ph uicontrol\">Administration</span> > <span class=\"ph uicontrol\">Interactive Filters</span></span>.</span>\n </li><li class=\"li substep substepexpand\">\n <span class=\"ph cmd\">Select a Date filter.</span><div class=\"itemgroup info\">The available filters include <span class=\"ph uicontrol\">Last\n fortnight</span>.<br /><img class=\"image\" id=\"create-custom-date-time-filter__image_n3d_k5q_bvb\" src=\"../image/available-date-time-filter-options-fortnight.png\" alt=\"Available date filter options including last fortnight\" /><br /></div></li></ol>\n\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Edit a date filter to include the new value and add the filter to a\n dashboard.<br /><img class=\"image\" id=\"create-custom-date-time-filter__image_ibt_y1r_bvb\" src=\"../image/date-filter-new-option.png\" alt=\"A date filter with the last fortnight option available\" /><br /></span>\n </li></ol>\n\n </div>\n\n</div>\n<div class=\"topic task nested1\" id=\"define-cif-filtering-logic\">\n <h2 class=\"title topictitle2\" id=\"ariaid-title4\">Define filtering logic - example</h2>\n\n \n \n <div class=\"body taskbody\"><p class=\"shortdesc\">After you create the interactive filter, add the filtering logic.</p>\n\n <div class=\"section prereq p\">\n <p class=\"p\">Role required: admin</p>\n\n <div class=\"p\">Filters use the <span class=\"keyword apiname\">DashboardMessageHandler</span> class to manage active\n filters. Instantiate <span class=\"keyword apiname\">DashboardMessageHandler</span> with a unique value.\n <div class=\"note\"><span class=\"notetitle\">Note:</span> The ID of the custom interactive filter must be unique. If it has the same\n ID as another interactive filter or custom interactive filter, the filtering\n logic does work properly.</div>\n</div>\n\n </div>\n\n <ol class=\"ol steps\"><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">In the dynamic content record, add the filtering logic to the Dynamic content\n XML block.</span>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">The <span class=\"ph uicontrol\">Only mine</span> button publishes a filter on Task table\n reports using the encoded query\n <code class=\"ph codeph\">caller_idDYNAMIC90d1921e5f510100a9ad2572f2b477fe</code>.</span><div class=\"itemgroup info\">The\n <span class=\"ph uicontrol\">All tasks</span> button removes the filter.</div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">You can then add buttons or other interface elements to the dynamic content.\n In this example, the code for the <code class=\"ph codeph\">clearFilter()</code>\n function and the buttons in the filter are added below the\n <code class=\"ph codeph\">publishFilter()</code> function.</span>\n <div class=\"itemgroup info\">\n <pre class=\"pre codeblock\"><code><?xml version="1.0" encoding="utf-8" ?>\n<j:jelly trim="false" xmlns:j="jelly:core" xmlns:g="glide" xmlns:j2="null" xmlns:g2="null">\n <script>\n var my_dashboardMessageHandler = new DashboardMessageHandler("my_unique_id");\n \n function publishFilter () {\n var filter_message = {};\n filter_message.id = "my_unique_id";\n filter_message.table = "task";\n \n <!-- Add your own filter query logic here -->\n filter_message.filter = "assigned_toDYNAMIC90d1921e5f510100a9ad2572f2b477fe";\n SNC.canvas.interactiveFilters.setDefaultValue({\n id: filter_message.id,\n filters: [filter_message]\n }, false);\n my_dashboardMessageHandler.publishFilter(filter_message.table, filter_message.filter);\n }\n \n function clearFilter() {\n var filter_message = {};\n filter_message.id = "my_unique_id";\n filter_message.table = "task";\n filter_message.filter = "";\n SNC.canvas.interactiveFilters.setDefaultValue({\n id: filter_message.id,\n filters: [filter_message]\n }, false);\n my_dashboardMessageHandler.removeFilter();\n }\n </script> \n \nExample of a filter that generates a static filter on 'task' table reports, or removes it <br/>\n <input id="allTasks" type="button" value="All tasks" onclick="clearFilter();" />\n <input id="onlyMine" type="button" value="Only mine" onclick="publishFilter();" />\n \n</j:jelly></code></pre>\n </div>\n </li><li class=\"li step stepexpand\">\n <span class=\"ph cmd\">Select <span class=\"ph uicontrol\">Submit</span>.</span>\n </li></ol>\n\n <div class=\"section result\" id=\"define-cif-filtering-logic__result_xvj_2s5_trb\">\n <p class=\"p\">The custom interactive filter appears on the dashboard you added the dynamic content\n block to. It is also in the list of content blocks in the <span class=\"ph uicontrol\">Add\n Widgets</span> panel.</p>\n\n </div>\n\n </div>\n\n</div>\n<div class=\"topic reference nested1\" id=\"custom-interactive-filter-multiple-reports\">\n <h2 class=\"title topictitle2\" id=\"ariaid-title5\">Custom interactive filter example - Multiple reports</h2>\n\n \n \n <div class=\"body refbody\"><p class=\"shortdesc\">You can use a custom interactive filter to filter multiple reports using different\n tables. There are two different APIs to publish an interactive filter for a single table or\n multiple tables. This example filters a report on the incident and problem tables by assignment\n group using a custom interactive filter.</p>\n\n <div class=\"section\" id=\"custom-interactive-filter-multiple-reports__section_zpd_jrp_zlb\"><h3 class=\"title sectiontitle\">About custom interactive filters on multiple tables</h3>\n \n <div class=\"p\" id=\"custom-interactive-filter-multiple-reports__prereq_e4f_4mp_zlb\">Keep the following in mind when you create a custom interactive\n filter:<ul class=\"ul\" id=\"custom-interactive-filter-multiple-reports__ul_rsb_tmp_zlb\"><li class=\"li\">Custom interactive filters that apply to only one table use the function\n <span class=\"keyword apiname\">DashboardMessageHandler.publishFilter()</span>.</li><li class=\"li\">Custom interactive filters that apply to multiple tables use the function\n <span class=\"keyword apiname\">DashboardMessageHandler.publishMessage()</span>.</li><li class=\"li\">Before you publish, an interactive filter call to the\n <span class=\"keyword apiname\">SNC.canvas.interactiveFilters.setDefaultValue()</span> function is\n required.</li><li class=\"li\">A call to either the\n <span class=\"keyword apiname\">SNC.canvas.interactiveFilters.removeDefaultValue()</span> or the\n <span class=\"keyword apiname\">DashboardMessageHandler.removeFilter()</span> function is required before\n you reset the filter.</li></ul>\n</div>\n\n <p class=\"p\" id=\"custom-interactive-filter-multiple-reports__context_dw5_4qp_zlb\">A custom interactive filter that calls the\n <span class=\"keyword apiname\">publishFilter()</span> method multiple times refreshes the associated report\n the same number of times. Repeated calls to this method can cause performance issues.</p>\n\n </div>\n\n <div class=\"section\" id=\"custom-interactive-filter-multiple-reports__section_rv4_lrp_zlb\"><h3 class=\"title sectiontitle\">How to apply Custom Interactive Filter to multiple tables</h3>\n \n <p class=\"p\">The following example filters the report by assignment group on the Incident [incident] and\n Problem [problem] tables.</p>\n\n <p class=\"p\"><span class=\"keyword apiname\">DashboardMessageHandler.publishMessage()</span> accepts multiple filters as an\n array. Construct the filter array and then create a single instance of\n <span class=\"keyword apiname\">DashboardMessageHandler</span> which calls\n <span class=\"keyword apiname\">DashboardMessageHandler.publishMessage([filters])</span>. This method\n refreshes the widget only once.</p>\n\n </div>\n\n <div class=\"example\">\n <pre class=\"pre codeblock\"><code><?xml version="1.0" encoding="UTF-8"?>\n<j:jelly xmlns:j="jelly:core" xmlns:g="glide" xmlns:g2="null" xmlns:j2="null" trim="false">\n <script>\n var my_dashboardMessageHandler = new DashboardMessageHandler("my_unique_id");\n\nfunction publishMultipleFilter() {\n <!-- Mutliple filters can be passed as an array -->\n var finalFilter = [{"table":"incident","filter":"assignment_group=6fcd3b573b331300ad3cc9bb34efc447"}, {"table":"problem","filter":"assignment_group=6fcd3b573b331300ad3cc9bb34efc447"}];\n <!-- call setDefaultValue first -->\n SNC.canvas.interactiveFilters.setDefaultValue({\nid: my_dashboardMessageHandler._unique_id,\nfilters: finalFilter,\n}, false);\n <!-- then call Publishmessage to publish filters-->\n my_dashboardMessageHandler.publishMessage(finalFilter);\n}\n\nfunction clearFilter() {\nSNC.canvas.interactiveFilters.removeDefaultValue(my_dashboardMessageHandler._unique_id, false);\nmy_dashboardMessageHandler.removeFilter();\n}\n </script>\n \nExample of a filter that filters incident and problem table where the assignment group is Problem solving\n <input id="allTasks" type="button" value="All" onclick="clearFilter();" />\n <input id="onlyMine" type="button" value="Assignment group is [Problem solving]" onclick="publishMultipleFilter();" />\n</j:jelly></code></pre>\n </div>\n\n </div>\n\n</div>\n</div>\n</body></html></div>"}</script>