Skip to content

Transforming events

To modify events as they arrive, create an event map through the user interface:

  1. Create an event class.

  2. Go to the event console and create an event mapping in this class from the existing event.

  3. Edit the map.

  4. In the Transform area, update the event with detail data. The entry field allows you to insert Python scripts. The event is provided as "evt" and the device as "device." In this case, extract the sysLocation event detail and make it the summary with the following:

    evt.summary = evt.sysLocation
    
  5. Save the event mapping.

If you move the event to the event archive and resend the trap, the summary for the trap should now read the device name in the location you assigned.

Event transforms based on event class

When an event arrives in the system, you can change values (such as severity). For example, you can make the summary more informative, or change severity according to text within the summary.

Each event class allows for a short Python script to be executed when an event arrives.

For example, a user may want full file system threshold events on /data to be critical. Add the following Python script in the Threshold Transform of /Events/Perf/Filesystem:

if evt.component == '/data' and evt.severity != 0: evt.severity = 5

Like event mappings for event class keys, the "evt," "device," and "component" objects are available in the script of the transform.

Event mapping and transforms

You can map or transform events to perform a wide range of operations, from altering the severity of certain events to altering nearly every field on an event, based on complex rules.

You cannot alter the following fields through event transformation. (This is because they are set after transformation has been performed.)

  • evid
  • firstTime
  • lastTime
  • count

The following illustration shows the path followed by an incoming event in the event mapping system.

The process begins with the "eventClass field exists" decision. This also is one of the more important differentiators in how you must handle a particular type of event.

Event class mappings

To view event class mappings, select EVENTS > EVENT CLASSES, and then select Mapping Instances in the drop-down list. This allows you to see all event class mappings in a single location. The ID column shows the mapping's event class.

You can create event class mappings directly from the event classes, but this requires that you know the event class key. A simpler way to create event class mappings is through the event console:

  1. Select an event that you want to match in the event console.
  2. Click the Reclassify an Event icon. The Classify Events dialog appears.
  3. Select the event class to which you want to map the event, and then click Submit. This creates the event class mapping with the correct event class key, and example text against which you can develop your regular expression.

When editing an event class mapping, you can control which events it will match, as well as other properties:

  • Matching tab
    • Event Class Key - Must match the incoming event's Event Class Key field for this mapping to be considered as a match for events.
    • Rule - Provides a programmatic secondary match requirement. It takes a Python expression. If the expression evaluates to True for an event, this mapping is applied.
    • Regex - The regular expression match is used only in cases where the rule property is blank. It takes a Perl Compatible Regular Expression (PCRE). If the regex matches an event's message field, then this mapping is applied.
    • Explanation - Free-form text field that can be used to add an explanation field to any event that matches this mapping.
    • Resolution - Free-form text field that can be used to add a resolution field to any event that matches this mapping.
  • Transforms tab - Takes Python code that will be executed on the event only if it matches this mapping. For more details on transforms, see the section titled "Event Class Transform."
  • Configuration Properties tab - Listing of Configuration Properties defined for this event class.
  • Sequence tab - Sequence number of this mapping. This number determines the order in which mappings with the same event class key are evaluated.

Mappings have the same configuration properties as event classes. Any configuration property set locally on a mapping will override the same property set on the event class. This works in the same hierarchical, most specific match, concept that device class and device configuration properties work.

When a captured event occurs, it will not have a pre-defined event class. For this type of event, you must create an event class mapping if you want to affect the event. If a captured event occurs and none of the event class mappings in the system match it, its event class will be set to /Unknown, and it will retain all of the default properties with which it began.

The next step of evaluation for events without an event class is to check the Event Class Key field. This controls which event class mapping the event will match. If the event has a blank event class key, or its event class key does not match any event class mappings in the system, the special "defaultmapping" event class key is searched for instead. This provides for a way to map events even if they have a blank or unpredictable event class key.

Event class mapping sequence

The sequence area of an event class mapping (select Sequence in the left panel) allows you to provide more than one mapping for the same event class key. In this case, the sequence is evaluated in ascending order until a full (rule or regex) match is found.

For example, suppose a router is sending in unclassified events that need to be mapped to two event classes:

  • /Events/Router/fanDown
  • /Events/Router/fanUnknown

The event class key for both has been sent to "router", but one has a message of "Fan Down" and the other has no message at all. The mapping on /Events/Router/fanDown has an event class key of "router" and a regex of "Fan Down." The mapping on /Events/Router/fanUnknown has only an event class key of "router" and (in this example) no regex. Because the fanUnknown mapping matches the fanDown events, the evaluation of fanDown needs to occur first.

You can modify the evaluation of mappings with the same event class key in the Sequence area of any of those event class mappings. In the previous example, you could go to either mapping, select Sequence, and both mappings would be displayed. You can set one to 0, and the other to 1. (You can enter other values, but they will be changed to the shortest list of integers, starting with 0.) Setting fanDown to 0 and fanUnknown to 1 will ensure that the events will be mapped properly.

Event class transform

When a generated event occurs, it has an event class assigned to it. This causes the event class mapping step to be skipped. The only way to affect the fields of one of these events is through the configuration properties and transform of the event class.

To access the transform for an event class:

  1. Navigate to the event class from Events > Event Classes.
  2. From the drop-down list, select Transforms.
  3. Enter information into the dialog box (as Python code), and then click the Save button in the upper-right corner. As you develop your transform, you can revert back to the last saved state by clicking the Revert this Transform button.

During transform execution, certain Python objects are available for evaluation and alteration.

Object Description
evt The event, itself.
device If the event matches a device that exists in the system, a device object is provided.
component If the event matches a component that exists in the system, a component object is provided.

The following example shows how you can validate that a device object exists before using it to drop events from a particular location.

if device and "Hawaii" in device.getLocationName(): evt._action = "drop"

Tip

Transforms on an event class are executed after any transforms on that classes parent class. Transforms on event class mappings are executed after any transforms in the target event class path.

More information on event transforms can be viewed here: