Notifications

273 views

Description

Description

A very convenient feature of the reporting system in the ServiceNow platform is the capability to create dynamic report filter conditions in the reporting module, directly from within the report criteria. These conditions can be created in JavaScript and configured as part of the report criteria filter, thus substituting a dynamic Javascript function for a specific value. This KB article will thus describe the process that can be used to create and configure such a dynamic filter in a report.

Procedure

To create a report using such a dynamic conditional statement, the procedure consists of basically placing a JavaScript URL in the conditional value statement of the filter. Technically the JavaScript command can be entered directly into the field, however, in most cases, for any script that is longer than one statement, this script should be placed in it's own record and then a call to a function in that record place into the value field of the report condition. This article will describe how to thus add a dynamic JavaScript statement for evaluation as part of a specific report's filter criteria.

To add such a dynamic JavaScript statement or function, first open the report for editing for which the statement is intended to be added. Alternatively, for a new report being created, dynamic JavaScript condition values can be set.

After configuring the other information for the report (such as data source, report type, etc), click the filter icon on the right side of the report view to open the filter conditions for editing.

Begin by selecting a filter condition corresponding to a supported field on the report target form and ensure to select a supported operator. Note that certain combinations of field types and operators will allow a dynamic Javascript statement to be specified and others will not. Currently the field types and operators that are known to allow this are the following:

 

Field TypeOperators Allowed Expected Return Data Type
Sys ID (GUID)"is", "is not", "is one of", "starts with", "ends with", "contains", "does not contain", "between", "greater than or is", "less than or is".

Textual representation of a complete or partial sys_id value.

For the "is one of" operator, the expected return type would be either a comma delimited list of sys_id values or an array containing each sys_id that should be included in the results.

Free Text String"is", "is not", "is one of", "starts with", "ends with", "contains", "does not contain", "between", "greater than or is", "less than or is".

One or more textual characters.

For the "is one of" operator, the expected result would be either a comma delimited list of string values or an array containing each of the values to include in the "is one of" search value field.

Reference"starts with", "ends with", "contains", "does not contain"One or more textual characters that may represent some value or portion of a a value found in this field in the table or data source.
String (referencing another table)"contains", "starts with", "ends with", "does not contain"One or more textual characters that may represent some value or portion of a value found in this field in the table or data source.
User Input"is", "is not"Textual characters that could represent the full value of some record for this field in the table or data source.
Table Name"is", "is not", "is one of", "starts with", "ends with", "contains", "does not contain", "between", "greater than or is", "less than or is"

Textual representation of a complete or partial Table Name in the system.

For the "is one of" operator, the expected return type would be either a comma delimited list of Table Name values or an array containing each Table Name that should be included in the results.

Template Value"is", "is not"Textual characters that will fulfill the value as per a Template found on the instance.
Domain ID"starts with", "ends with", "contains", "does not contain".

One or more textual characters that may represent some value or portion of a value found in the domain field in the table or data source.

User Roles"is", "is not"

Textual representation of a user role string value.

Domain Path"starts with", "ends with", "contains", "does not contain", "is", "is not", "is one of", "less than or is", "greater than or is", "between".

One or more textual characters that may represent some value or portion of a value found in this field in the table or data source.

For the "is one of" operator, either a comma delimited list of textual values or an array object containing each values that should be included.

Translated Text"is", "is not", "is one of", "starts with", "ends with", "contains", "does not contain", "between", "greater than or is", "less than or is"

Textual value.

For the "is one of" operator, the expected return type would be either a comma delimited list of textual values or an array of textual values.

Translated Field"is", "is not", "is one of", "starts with", "ends with", "contains", "does not contain", "between", "greater than or is", "less than or is"

Textual value.

For the "is one of" operator, the expected return type would be either a comma delimited list of textual values or an array of textual values.

HTML"contains", "does not contain"

Textual value which might correspond to data in the selected field in this report criteria.

HTML Template"contains", "does not contain"

Textual value which might correspond to data in the selected field in this report criteria.

Email Script"contains", "does not contain"Textual value representing a value that should (or should not) be in the Email Script field.
Script (Plain)"contains", "does not contain"Textual value representing a value that should (or should not) be in the Script field.
Script (server side)"contains", "does not contain"Textual value representing a value that should (or should not) be in the Script field.
Script"contains", "does not contain"Textual value representing a value that should (or should not) be in the compared Script field.
Short Table Name"is", "is not"

Textual value (under 40 characters).

For the "is one of" operator, the expected return type would be either a comma delimited list of textual values or an array containing each such textual characters that would represent a short table name.

Field Name"is", "is not", "is one of", "starts with", "ends with", "contains", "does not contain", "between", "greater than or is", "less than or is".

Textual representation of a complete or partial field name value.

For the "is one of" operator, the expected return type would be either a comma-delimited list of field name values or an array containing each field name that should be included in the results.

Notes:

  • With the "between" operator, two fields are provided that can each support a different (or the same) JavaScript URL.
  • The return value for the "is" operator can also be an array of data elements of the expected type, and the system will treat this operator as it would the "is one of" operator.

Thus, as can be seen from this chart, certain data field types combined with certain operators will allow inclusion of a JavaScript URL and thus custom search function to be used in that filter criteria.

After selecting the appropriate criteria and operator, the JavaScript URL should be typed in the comparison value field.

For a single line JavaScript statement, the JavaScript URL should be typed into the value field in a manner similar to the following:

javascript:<JavaScript_Statement>;

Where <JavaScript_Statement> is a valid JavaScript statement that will return the expected results.

As a very very common example of a single statement JavaScript URL condition that might be used for filtering many record types is the following:

javascript:gs.getUserName();

This would return, for the selected field (Updated by in the example below), in which the value is equal to the user name of the user currently logged into the instance and running the report.

JavaScript statement condition

As mentioned, however, if this JavaScript is anything more than a very simple script which might consist of one line, the best option would normally be to first create the script in its own record. In these cases, a Script Include record should be created which contains the script. An existing Script Include record could also be used as long as it represents a function that returns the appropriate data type and format.

Thus, in the case of a function, a Script Include record should first be created that will return the correct format and data type, and will conform to the specific data that the report should filter for. To create a new Script Include record, browse to the following location on the instance: System Definition -> Script Includes.

The Client callable checkbox must be selected in the Script Include record or the filter will not be able to make a call to the record. Provide a descriptive Name value for the Script Include record. This name will also be used in access to the function. The format of the actual text in the Script field of record might be something similar to the following:

var <Record_Name> = Class.create();
<Record_Name>.prototype = Object.extendsObject(AbstractAjaxProcessor, {
<Function_Name>: function(){
// Function Body
// Function Body
// Function Body
return <Some_Value>;
},
type: '<Record_Name>'
});

In this script template, <Record_Name> would correspond to the name of the Script Include record itself, <Function_Name> would be your choice of function name, and <Some_Value> would be the specific value or values which would be substituted into the search criteria in the report. The Function Body would thence, using any number of JavaScript objects, glide object record queries, and other statements and objects calculate the specific dynamic value for which the target report should filter.

FindGroups Script Include record

Since any Script commands found in these filter fields (as well as any Object functions that are invoked and executed), are performed before the report is loaded, these statements would be executed at Server-Side and thus have access to the Server Side scripting objects (such as gs and gliderecord).

After the Script Include record has been created and is ready for use, the next step is to add the JavaScript URL in the value field for the appropriate step. To call a function declared in a specific Script Include, the value field might appear similar to the following:

javascript:new <Record_Name>().<Function_Name>();

With <Record_Name> again corresponding to the Script Include record name which contains the object and function we intend to instantiate and <Function_Name> the specific function in that Script Include record which returns the actual value to be compared in that filter criteria in the report.

Dynamic JavaScript in report conditions

Note that the Javascript URL could also include one or more parameters passed to the function which will perform the calculation and return a result. For example, a Javascript function which passes two parameters to the Script Include record could be written as javascript:new TextJSFilter().getGroupIDs("Professional Services","Sales");. Of course, the target function in the Script Include record would also need to be modified to accept these parameters (as an example the function declaration within the Script Include might be modified as getGroupIDs: function(primaryGroup,secondaryGroup).

The specific operator used and field type selected will determine what the return type or output type of the JavaScript statement should be.

For example, if the field type is a sys_id and the operator which was select is "is", "is not", "greater than or is", or "less than or is" you would want a statement that would provide a single sys_id.

Similarly, if the field was a standard free text String type or a Reference field, you would want to provide a JavaScript statement that returned a String that returned a textual value which should be used in the comparison.

After adding the necessary JavaScript statements and conditions and configuring the remainder of the report, the report should be saved and tested to ensure it does return and display the expected results.

Javascript filtered report

Article Information

Last Updated:2019-08-02 20:46:29
Published:2019-04-25