Notifications

44 views

Description

Although the out-of-box platform includes a large number of Date/Time filter options that should suit most Date or Time based Interactive filter requirements, there may arise the need for a specific such filter selection that is not found in the default list of selectable filter options.

Standard default filter selections

This article describes the steps needed to create such a custom Date/Time filter that can then be included in any Date/Time based interactive filter for use on a Dashboard or Homepage.

Resolution

There are several steps involved in adding such a custom filter, which will be covered in detail in this article describing the process.  In this article, as an example to illustrate the steps as described, we will be adding an example of a need to add a Date/Time filter consisting of the time period of the last fortnight (two weeks or 14 days).

The first step is to modify the list of selectable options to include this new option.

Thus, to begin, the user should first be logged in to the instance with an account which is a member of the admin role on the instance.

Once logged in, the user should browse to the following location: System Definition -> Business Rules.

The resulting list of Business Rules should be filtered to locate the Business Rule with the name "Get Date Filter Options for Date Filters".  This Business Rule should then be opened for editing.

This Business Rule opened is that which populates the list of selectable options in the Interactive Filter forms for new or existing Interactive Filters of type Date.

The next step is to then modify the Script field (found on the Advanced tab) to include the Javascript needed to add the new option.  As will be noticed from the current script found in this field, each answer.add() statement in the script consists of the addition of a new selectable option which would appear in the list of selectable options.

Thus, we will need to add a new option to this list using the answer.add() function corresponding to and formatted for, our new value.  The general format of the answer.add function as used in this Business Rule would be as follows:

answer.add('<Time_Period_Name>@javascript:<Beginning_Time_Period>@javascript:<Ending_Time_Period>', gs.getMessage('<Textual_Representation_Of_Time_Period>'));

In which:

<Time_Period_Name> is a unique textual representation of the time period selected.  This should be a value not used by any other such function in this Business Rule and is used internally by the system to identify this option and is usually set to something that can be descriptive of the time-period described.

For this example, thus, we will use the value "112_Last Fortnight" which is unique in this list and is descriptive of the time period actually represented.

<Beginning_Time_Period> is the specific date and time on which this filter to start.  Absolute or relative values can be used, although it is much more common to use a relative value (which uses the javascript URL syntax).  Thus, this will usually consist of a javascript statement specifying this starting date. 

For our example we will specify the following to indicate exactly two weeks ago gs.daysAgoStart(14) to indicate that the time interval for this selection should be exactly two weeks ago.

<Ending_Time_Period> is the specific date and time on which the time period for this filter option should end.  This can be either an absolute or relative value, although, similar to the Beginning_Time_Period this is usually a relative time period (which would thus include the javascript url syntax) that is specified through use of an applicable Javascript statement or function.

Thus, for our continuing example, we will specify the option gs.daysAgoStart(0) to specify the time period ends at the current date and time.

<Textual_Representation_Of_Time_Period> is a short text representation that will display in the list to indicate the Time Period that this particular selection will signify.  The text specified will also determine the ordering for which this option appears in the resulting lists on which it is displayed (the values are sorted in an ascending alphabetical order based on this field).  It is often possible (but not required) to use a value which will cause the option to appear in the logical place in the list based on the timespan the selection will cover.

For this example, we will use "Last Fortnight", to indicate that this selection will specify a time period from one fortnight previous to the current date and time.

Thus, in our example our complete statement might appear as the following:

answer.add('112_Last Fortnight@javascript:gs.daysAgoStart(14)@javascript:gs.daysAgoEnd(0)', gs.getMessage('Last Fortnight');

New timespan option added for use in Interactive Filters

Click the Update button on the Business Rule record to save the changes.

Once the Business Rule has been modified as necessary, this new timespan option will then appear within the allowable options for an Interactive List, however, it will not be included in any actual existing Interactive Lists on the system.  To include it in an actual Interactive List, it will need to be added to the options selected for that particular Interactive List.  The following additional steps will describe how this can be done.

New timespan option selectable

 

Ensure to still be logged into the instance with an account associated with the admin role in that instance.

Browse to the following location on the instance: Reports -> Administration -> Interactive Filters.

A list of Interactive Filters currently found on the instance will appear.  Locate the Interactive Filter for which you want to add the new option and open this Interactive Filter for editing. This new option can only be added to an Interactive Filter in which the Filter based on field is set to type Date.

In the Date Filter section, in the Available column, scroll to locate the new field (as per the Textual_Representation_Of_Time_Period value as used above) in this list and double click this new option in the list.  This will cause the option to then move to the Selected column.  The new value can also be selected for the Default value if wanted for this Interactive Filter.

Interactive Filter modified to include new option

Click the Update button to save the changes.

After making these changes, anywhere this particular Interactive Filter is used on the instance, this new option will also appear.  This option can then be selected in that filter to display the data as specified by that newly added option.

New filter option selectable

Additional Information

It should be noted that the command template and the examples used above use relative values for the date ranges.  In using these relative values, these are evaluated using the javascript URL format and a simple javascript function or statement.  However, if needed, a literal static value could also be used in place of each of the javascript URL statements.

Similarly, the date ranges may be more complex than might be provided by a simple Javascript statement.  In such cases, the javascript URL could actually call a function in which more involved date and time calculations might be performed and then passed back to the calling statement.

There are several resources which may be helpful in performing the steps described in this article.

The following link shows the various gs data and time-based functions which a user may find helpful in creating the necessary date and time ranges (Scoped and Legacy API links):

Article Information

Last Updated:2019-08-20 01:43:37
Published:2019-08-20