Selector file

The BMC Impact Integration Web Services APIs use the selector file to define groups of criteria (called selectors ) that are used to identify and select events that propagate from BMC Impact Manager cells. Events that match all the criteria in a selector file become available to the publish-subscribe and polling mechanisms of the BMC Impact Integration Web Services clients.

The selector file is required for the BMC Impact Integration Web Services clients that receive events from BMC Impact Manager cells. It is a case-insensitive text file.

The selector file is crucial in determining which events the subscribing clients receive. The default selector file, iiws.selector, is stored under the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc sub directory.

The selector file will be looked up from the directory $IIWS_HOME/TOmcat/webapps/imws/WEB-INF/etc. The default filename is iiws.selector, and can be modified in the ImWebServices.conf file, as shown in the following example:

svci:IIAPISelectorFile="C:\Program Files\BMC Software\Impact
	Integration Web Services/mcell/iiws.selector"

The default selector file provides the selector name Always matches for the $ClassName "Event". Using the default selector, your client receives all events propagating from the BMC Impact Manager cells.

The BMC Impact Integration Web Services server loads this selector file at start.

Selector File characteristics

Selector set files have the following characteristics:

• Selector set file criteria are not case-sensitive.
• The naming convention for selector set files is integrationName.selector.
• Selector set file syntax is checked when the selector set file is loaded. If the selector set file contains problematic syntax, the BMC Impact Integration Web Services API bmcii_loadSelectorSet() function will fail.
• The contents of a selector set file comprise a selector set. The selector set can contain one or more selectors. However, a selector set file can contain only one selector set.
• Each selector in a selector set must have a unique name. However, different selector sets can have selectors with identical names.
• When a selector set file is called by the BMC Impact Integration Web Services API bmcii_matchSelectorSet() function, it is scanned from beginning to end. The selection process for the selector stops the first time that a parameter in a selector is matched to a parameter value in a selector. After a match is made, the remaining selectors in a set are ignored.
  
  If the bmcii_matchSelectorSetAll() function is called, the function continues to scan after a matching selector is identified.
• Because the selector sets are scanned from beginning to end, the order of selectors in a set and in the lines within a selector are important to optimizing the matching process.
• The $doselector function allows you to include selectors and subselectors within a selector set. Selectors and subselectors further refine the selector criteria.
• The $doselector function invokes subselectors.
• The relationship between the criteria described in successive lines of a single stanza in a message selector is AND, unless otherwise indicated.
• The selector file supports the logical operators OR, AND, &&, and ||.
• A selector set can contain multiple stanzas of selector criteria, nested one level deep. These multiple stanzas of selector criteria are referred to as selector groups. The logical relation between the groups can be expressed through an AND, OR, &&, or || connector.
• Each line in a selector contains only one selector criterion.
• The selector file supports the following comparison operators:
  • Greater-than (>)
  • Greater-than or equal to (>=)
  • Less-than (<)
  • Less-than or equal to (<=)
    The selector file supports these comparison operators for numerals only.
• The selector file supports the metaslot feature, which enables you to include information about the message. For example, you can use the metaslot to indicate the source of a message. You must specify a metaslot by using the keyword metaslot, followed by a dot (.), to prefix the slot name: metaslot.classname="EVENT".
• The selector file supports required slots. A required slot keyword determines the required slot or slots in the selector criteria. The message must have the specific required slot for it to match the selector criteria.
  
  The required slot keyword consists of the term reqdslot, followed by a dot (.), both of which you can add as a prefix to the specific slot name: for example, reqdslot.msg="TEXT". To illustrate, if the selector criteria specified that the slot message is required ( reqdslot.msg="TEXT"), then a message that did not have the slot message would fail the matching test.
  
  The reqdslot keyword overrides the FailOnMissingSlot parameter when the latter is set equal to FALSE. That is, a message that does not have the designated required slot fails to meet the selector criteria.
  
  When the FailOnMissingSlot parameter is set to TRUE, the BMC II C APIs ignore the reqdslot keyword when they process the message to determine whether it meets the selector criteria.
• You can use the full range of regular expressions as values for selector criteria. You can include any slots within the regular expression. The BMC II C APIs return the values of the slots at run time. Within a regular expression, you can specify a slot with the keyword slot, followed by a dot (.): slot.host. The BMC II C APIs will return the value of host before sending the regular expression to the library.

Format

The following figure depicts the structure of the selector set file:

Structure of selector set file

Selector set files must contain header information that describes the selector set. The header information consists of following selectors:

• Selector set headers, described in Selector set header.
• Selector headers, described in Selector header.
• Selector criteria are described in Selector criteria.

Selector set header

The selector set header provides the entire set of selectors in the file with identifying information and indicates whether the selector set is enabled for use. A single selector set header must precede all selectors and their selector groups in the selector set.

The following table describes the required and optional selector set header parameters that precede the selectors in a set:

Selector set header contents

Sample selector set header

SelectorSetName=testselector
FormatVersion=2
Version=7.1
ChangeDate=November 14, 2007
Description=This file contains the event selector tests
Enable=TRUE

Selector header

A selector header performs following actions:

• Provides each set of selector criteria in the file with identifying information.
• Indicates how some selector features will be implemented.
• Indicates whether the specific selector criteria, including any selector groups included within it, are enabled for use.

A selector header must precede each collection of selector criteria in the selector set.

The following table describes the required and optional selector header parameters that precede each selector:

Selector header contents

Sample selector set header

SelectorName=EVENT_SELECTOR
Description=Selectors for all events of class EVENT
FailOnMissingSlot=false
IsSubSelector=true
Enable=TRUE

Selector criteria

Each selector in a message selector set is constructed of successive lines of comparison criteria. Each criterion is composed of a comparison expressed as an equation. Equation operators are listed in the following table.

Each line contains one criterion with an AND relationship implied between lines (unless otherwise indicated).

In addition, the selector can consist of multiple groups of comparison criteria, each group related to the other through an AND, OR, ||, or && connector.

Format issues

Selector functions, which are internal to the selector file, are described in the following table. Operators are described in the following table.

• Each message selector in a set is enclosed in curly braces ({ } ).
• Message selector groups within a message selector are nested one level deep and also enclosed in curly braces. Do not nest message selector groups more than one level deep.
• To the right of the operator is a slot, static text, or a function. On the left is a slot, regular expression, static text, or a function.
• Explicit text that is used as a matching criterion must be enclosed in double quotation marks (" " ).
• If a criterion fails but has an OR relationship with the following criterion, and that criterion is a match, then that criterion pair is a match.
• The selector function scans each successive selector group in a message selector until it finds a match. After it finds a match, it stops searching.

• The # symbol is used to comment out the rest of a line in a file. This symbol can be used to alter selector functions and conceal developer comments. When a line in a selector is commented out, the selection function ignores it.
  Do not comment out whole selectors or selector sets. Instead, set the Enable parameter of the selector set header or the selector header to FALSE to disable the selector set or selector.

  Example

  The $functionName resolves a specified function and compares the results of that operation to a slot in the event. For example,
  $ClassName = "SECURITY_ALERT"
  
  The $ClassName function returns the class name of the event. The returned value is compared to the value to the right of the operator (in this case, the string, SECURITY_ALERT). If the event class name is SECURITY_ALERT, then the test is successful.

Selector functions

The following table describes the operators used for comparison in a selector set file:

Selector operators

The following table describes selector keywords that are prefixed to specific slots to indicate their function: metadata, required, or readable value. Remember to include the trailing dot (.) when prefixing the keyword to the slot name.

Keyword descriptions

Editing the selector file

1. If necessary, copy the iiws.selector file from the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory to the working directory of your BMC Impact Integration Web Services server installation.
2. In a text editor, open the iiws.selector file.
3. Modify the different file components — selector set header, selector header, selector content, and operators — as needed.
4. Save the file by using a file name of your choice and the file extension .selector. If you change the name of the selector file, modify the server instance parameter SelectorFileName in the ImWebServices.conf file accordingly.
5. Ensure that the selector file can be read by the user under whose permissions the web services server is running.

If the BMC Impact Integration Web Services server is running, restart it to initialize the changes.