Event Filter String

The <link/> element in the eventLinks.xml file, and the <template/> element in the eventViewsTemplates.xml file, have at least one subordinate <filter/> element, that in turn contains a query attribute, which specifies a string value that is used to query the event collector database for events.

All events that satisfy the filter string specified in the query attribute are returned from the event collector database and displayed in the Event Viewer when the user displays an event list represented by the <link/> or <template/> element.

For more information about the <filter/> element and query attribute, see Specifying Pre-defined Filters.

This describes how to design the filter string in the query attribute.

In the following query attribute example, all events are returned that are associated with the application from which the currently selected work item is associated, and that are associated with the currently logged-in user:

query="applicationName='{AppName}' AND 
       principalName='{sessionResourceName}'"

The filter string can contain:

• Event attributes - These represent values in the events that you are filtering on. In the example above, applicationName and principalName are event attributes that contain the name of the application associated with the currently selected work item, and the name of the resource (user) associated with the currently selected work item, respectively.

  All available event attributes are listed in the eventAttributes.xml file. Note, however, that not all event attributes are applicable to all event types, and not all event attributes are filterable and sortable.

• Substitution tokens - These are replaced with attribute values when the link is executed. They provide the values to which you are comparing the values in the event attributes to determine which to return from the event collector database.

  Substitution tokens in the filter string must be enclosed in { } braces, as well as single quotes (see {AppName} and {sessionResourceName} in the example above).

  For more information about substitution tokens, see Substitution Tokens.

• Event Message IDs - These identify the specific event. The ID must be enclosed in single quotes. For example:

query="messageId='BRM_WORKITEM_EX_SCHEDULE*'"

For a complete list of the available event message IDs, see the messageId attributes in the eventDescriptions.xml file.

• Logical and comparative operators - You can include the following operators in the filter string:

  Operator	Description
  AND	Logical AND
  OR	Logical OR
  =	Equal to
  <>	Not equal to
  <	Less than
  <=	Less than or equal to
  >	Greater than
  >=	Greater than or equal to

  When using the comparative operators, the values being compared must be of the same type.

• Parentheses - You can group, in parentheses, attributes/tokens being compared to obtain the desired hierarchy in the filter string.
• Wildcards - The following wildcard characters can be used in the filter string:

  Wildcard	Description
  ?	Matches any single character.
  *	Matches any number of characters.

  Wildcard characters can also be escaped using the \ character, for example:

     ‘str\?ng’

  And the escape character can be escaped, for example:

     ‘str\\ng’

• Dynamic Time-Period / Point-in-Time Variables - These are special variables that define a date/time range or point-in-time relative to the current date/time at the point in time when the expression is evaluated.

  For instance, the ~TODAY~ dynamic time-period variable allows you to define a filter that always represents the current day.

  Dynamic time-period variables in the filter string must be enclosed in { } braces. The following is an example usage of the ~TODAY~ variable:

query="principalName='{sessionResourceName}' AND 
       creationTime = {~TODAY~}"

This variable evaluates to the current date when the filter string is evaluated.

The available dynamic time-period variables are:

• ~TODAY~ - The current day, from 12:00 A.M. to 12:00 P.M.
• ~THISWEEK~ - The current week, from 12:00 A.M. Sunday morning to 12:00 P.M. Saturday evening.
• ~THISMONTH~ - The current month, from the 1st through the last day of the month.
• ~THISQUARTER~ - The current 3-month quarterly period. The specific three months to which this refers depends on how the definition of a quarter is configured. As companies use different months on which to begin a quarter, this may be referring to:
• This month, and the next two months,
• last month, this month, and next month, or
• the previous two months, and this month.

  Which of these periods to use depends on the setting of the FilterMaskQuarterStart parameter in the application’s config.xml file. For more information, see First Quarter Month.

• ~THISYEAR~ - This current year, from January 1 through December 31.

~variable[+-]#~

• ~PERIOD-dd:hh:mm~ - A time period that includes the last dd days, hh hours and mm minutes, from the point in time the filter is invoked.
• ~PERIOD+dd:hh:mm~ - A time period that includes the coming dd days, hh hours, and mm minutes, from the point in time the filter is invoked.
• ~POINT-dd:hh:mm~ - A point in time dd days, hh hours, and mm minutes in the past.
• ~POINT+dd:hh:mm~ - A point in time dd days, hh hours, and mm minutes in the future.

  The place holder fields dd, hh and mm in the above variables can be assigned values greater than or equal to 0. The syntax must include all place holder fields.

• ~NOW~ - The current date and time.
  Note: For a usage example of the dynamic time-period / point-in-time variables, see the filter mask for date fields: