Notification Filters

The option to use Check and Change selectors as well as Service Hours in Notification Actions directly reduces the need to define Filter Lists tremendously. Even more, the usage of selectors provides a tremendous performance improvement.

Filter Lists are available for Check and CCMS Alert Notification Actions.

Avantra offers advanced filtering options for Notifications. A filter can be either certain Service Hours (in other words the definition of some time periods), or Service Hours combined with a filter expression.

The option to build Filters only on Service Hours is first of all provided for backward compatibility. You are encouraged to define Service Hours directly on the corresponding Notification Action instead.

A Filter List is a list consisting of one or multiple filters. In this context, they are also called Filter List Entries.

Filters are meant to be "positive", i.e. you define exactly which Notifications are supposed to "pass" the filter. If there are multiple filters defined in a Filter List, the list is processed until a filter is found that permits the Notification to "pass".

Only if no such filter is found the Notification is "blocked". In other words, multiple Filter List Entries are combined by a Boolean OR operator. Filter Lists are processed in the order of their definition, i.e. the top-most one of the list is processed first.

The reason why these OR-combined expressions are represented by an ordered list is that the Service Hours mentioned above can be defined as overlapping.

There are the following options available for Filters:

Simple Filter Lists

It is possible to restrict passing Notifications to certain Customers, System Roles, Checks, check status, Notification numbers, or a combination of these using simple select boxes. See Defining Simple Filter Lists.

Advanced Filter Lists

In addition to the Simple Filter List, you can define virtually any expression in an Expression Editor to define which Notifications to pass. See Defining Advanced Filter Lists.

If you are working with Filter Lists and Output Channels and you are working with Macros, you will find a button Convert to FTL that allows you to convert them into Interpolations.

Defining Simple Filter Lists

Perform the following steps in order to create a Simple Filter List:

Simple Filter Lists are useful in conjunction with Notifications for CCMS Alerts.

If you notify Checks, almost any function of the simple Filter List can be implemented by means of a selector, which is a far better choice from a performance perspective. However, see the end of this section for a general discussion about Filters and Selectors.
Procedure: Defining Simple Filter Lists

  1. Choose one of the following options:

    Creating a Simple Filter List from scratch

    1. Fill in a Name and optionally a Description. The name of the Filter List has to be unique. If you do not want the Filter List to be active immediately, clear the Active flag.

    2. Press the Next button.

    3. Fill in a Name for the Filter List Entry and choose a value for Service Hours and push the Next.

      Unless you are sure you need multiple Filter List Entries, you most likely want to choose the 7 x 24 hours Service Hours.
    Adding a Simple Filter List Entry to an existing Filter List

    1. Select Configuration  Notifications from the top-level menu. Select the Filter Lists tab.

    2. Choose the appropriate Filter List

    3. Push the New … button in the Entries section.

    4. Fill in a Name and choose a Service Hours record. Press the Next button.

  2. Select appropriate values for at least one of the following lists: Customer, System Role, Monitored System, Check, Check Status. Push the Next button.

  3. You may also choose an Escalation Type, i.e. define the number(s) or number ranges of Notifications you want to pass. Select the appropriate item from the checkboxes and fill in values in the field Notification Number(s).

    Escalation only works for Notification Actions having resending defined, i.e. in Notification Actions for RealTime Monitoring Checks.

  4. Push the Finish button.

Example 1. Simple Filter List

Consider defining one or more CCMS Custom Checks and choosing to report the CCMS Alerts to Avantra. If you only want to notify these CCMS Alerts for e.g. dedicated Customers or System Roles, a Simple Filter is a good choice.

Defining Advanced Filter Lists

We provide a slightly more complex example that cannot be accomplished with a Simple Filter List. Assume you want to forward RealTime Monitoring Check Notifications for every Critical Check Result, but only once. And you have a couple of Checks you consider important for immediate Notification. And the remaining Checks you want only be forwarded if they stay in Critical status for more than 15 minutes. In this case, you need an Advanced Filter List:

Example 2. Example for a complex Filter expression
(
  InList('${check.name}','AgentConnect','RFCCONNECT','SystemAlive',
    'PI_CONNECT', 'J2EECONNECT','TREX Connect','DBCONNECT',
    'WD_Connect','AGENTALIVE')

  and
    ${notification.number}==1
)
or
(
  (
    not InList('${check.name}','AgentConnect','RFCCONNECT','SystemAlive',
            'PI_CONNECT','J2EECONNECT','TREX Connect','DBCONNECT','WD_Connect',
            'AGENTALIVE')
    )
    and ${check.statusAgeInSeconds?c}>900
    and ${notification.lastCheck.status}!=${check.status}
)

The meaning of this expression is:

For a formal description of the Advanced Filter syntax, see Reference: Advanced Filter Syntax.

Advanced Filters can be created by converting them from Simple Filters:

Procedure: Defining Advanced Filter Lists

  1. Create a Simple Filter List as described in Procedure: Defining Simple Filter Lists.

  2. Open the newly created Filter List Entry and push the Convert button. Push Yes on the pop-up.

  3. Open the converted Filter List Entry.

  4. Modify your expression. There is a Content Assist available hitting Ctrl-Space.

    The editor verifies your expression on the fly.

  5. Push the Save button.

Converting an Advanced Filter into a Simple Filter is not possible.
Example 3. Example for an Advanced Filter Entry

We implement the Filter outlined in Example for a complex Filter expression.

  1. Create a Simple Filter List as described in Procedure: Defining Simple Filter Lists.

    Flag the following Checks:

    AgentConnect, RFCConnect, SystemAlive, PI_CONNECT, J2EECONNECT, TREX Connect, DBCONNECT, WD_Connect, and AGENTALIVE

    Select filtering of a single Notification and enter 1 in the filed Notification Number.

  2. Open the newly created Filter List Entry and push the Convert button. Push Yes on the pop-up.

  3. Open the converted Filter List Entry. It should look like:

    InList('${check.name}','AgentConnect','RFCCONNECT','SystemAlive','PI_CONNECT',
  'J2EECONNECT','TREX Connect','DBCONNECT','WD_Connect','AGENTALIVE')

  and
  ${notification.number}==1

  4. Extend the expression as shown in Example for a complex Filter expression and push the Save button.

Include the recently created Filter List in a Notification Action that selects e.g. all Critical RealTime Monitoring Checks, notifies all Critical check status, and resends every 10 minutes Critical check status.

You may use the testing facility to verify your filter.

Reference: Advanced Filter Syntax

The following list describes the elements available in an Advanced Filter expression:

  • The filter should be surrounded by brackets ().

  • The filter may contain any of the provided Interpolations.

  • Macros of type String must be quoted by use of the single quote '.

  • Any other string used in a comparison or in the InList or in the Like function must be quoted as well.

  • A filter can be created by logically grouping conditional expressions. The following conditional operators are available: and, or, not.

  • The most simple conditional expressions are:

    • The number 0. This expression is always false.

    • Any positive or negative number. This expression is always true.

    • The empty string ''. This expression is always false.

    • Any other string. This expression is always true.

  • A string expression has the format string <op> string with <op> one of the operators

    • lt : string-wise less than

    • gt : string-wise greater than

    • le : string-wise less than or equal

    • ge : string-wise greater than or equal

    • eq : string-wise equal

    • ne : string-wise not equal

  • A conditional numerical expression has the format number <op> number _ with _<op> one of the operators

    • < : numerically less than

    • > : numerically greater than

    • ⇐ : numerically less than or equal

    • >= : numerically greater than or equal

    • == : numerically equal

    • != : numerically not equal

  • For strings as well as numbers, there is a InList function with syntax: InList(<macro>, <item 1 >, …​, <item n >). This expression evaluates true if the <macro> is equal to one of the list items from <item 1 > to <item n >

  • For strings, there is a Like function with syntax Like(<macro>, <pattern>) where <pattern> is a string that may contain the wildcards ? and *. This expression evaluates true if the <macro> matches the <pattern>. Matching is performed always at the beginning and the end of the string, so you may want to use * at the beginning and/or end of the <pattern> for in-string matches.

  • Basic arithmetic expressions can be used as well within filters. The arithmetic operators comprise +, -, *, /, % (the modulus operator).

Using Global Expressions

Global Expressions are available to re-use certain parts of a Filter. Assume you have a certain expression you use in many of your Filters. Whenever you need to change this expression, you have to adapt all Filters. But you can also define the common parts in Global Expressions and include this one in your Filters.

Procedure: Define a Global Expression

  1. Select Configuration  Notifications from the top-level menu. Select the Global Expressions tab. Push the New button.

  2. Fill in a Name.

  3. Fill in an expression.

  4. Push the Create button.

If you create a Global Expressions with name globalExpression, you would reference it as <@globalExpression />. (If you have defined the Global Expression in the previous version of Avantra already, you can still reference it as %%globalExpression%%. However, this syntax is deprecated.)

Example 4. Using Global Expressions

If you define a Global Expressions isImportantCheck with value

InList('${check.name}','AgentConnect','RFCCONNECT','SystemAlive','PI_CONNECT',
                    'J2EECONNECT','TREX Connect','DBCONNECT','WD_Connect','AGENTALIVE')

and a Global Expressions firstNotificationAfter15Minutes with value

(${check.statusAgeInSeconds?c}>900 and ${notification.lastCheck.status}!=${check.status})

you can simplify Example for an Advanced Filter Entry to

(<@isImportantCheck /> and ${notification.number}==1)
    or
(not <@isImportantCheck /> and <@firstNotificationAfter15Minutes />)