IBM Support

EIF Slot Customization and the msg Slot

Question & Answer


Question

How can I use the EIF Slot Customization Editor to customize the msg slot for event forwarding

Answer


When using EIF forwarding, EIF slot customization is most often used to modify the msg slot value. The default msg slot values are often long and contain a very detailed message related to the situation formula. Customization allows the msg slot to be modified to better convey a user-friendly summary that can be specific to the person or tool receiving the event. A quick method to customize the msg slot is to use the EIF Slot Customization Editor.

Using the EIF Slot Customization Editor GUI


In the following example, the situation named “Test_CustomEIF_DiskSpace” samples the Logical Disk Space utilization using the Windows OS Agent.

First, edit the situation using the Situation Editor. Then, select the “EIF” tab to configure the Event Destination details and access the EIF Customization Slot Editor.




Confirm the Event Destination details and then select the button for EIF Slot Customization that appears on the lower right section (under the “Available EIF Receivers”) on the EIF Tab.



This will bring up the EIF Slot Customization Editor GUI. From here, select a class name based on the class names available in the GUI.

To change the class name, click on the icon to the right of the Event Class Name selection box to bring up a populated list of your available Event Classes.



By default, the classes for the base OS agents and a pre-selected group of common agents come preloaded in the GUI. If the agent selection that is needed does not appear in the pull down menu, there is a tool called TEDGEN that can be used to customize the list of agents and load the classes and attributes for additional agents. Here is a link to the ITM 6.2.3 Administrators Guide for the TEDGEN utility for more details: http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/topic/com.ibm.itm.doc_6.2.3/tec_eifslot_tedgen.htm

Here is an example window for the Windows OS agent Classes that will be used in the following examples:


For this example, find the class for the ITM_Logical_Disk and selected it.

Once selected, there will be two tables for the different slot names available for the event.



The “Base Slots” table includes the base slots for the event that are determined by default and provided for each event. This table includes the “msg” slot.

Below the “Base Slots” table is the “Extended Slots” table. This list of slot names will be specific to the class name selected and a subset of the slots may appear in the event details when using EIF forwarding. To get all of the extended slots included in the event that will be forwarded, select the checkbox to “Map all attributes” that appears directly under the “Extended Slots” table. However, this is not generally necessary and can easily cause issues if the event becomes too large when received at the event destination so it would be recommended to avoid using the “Map all Attributes” option outside of testing purposes.

To customize the msg slot, find the row in the table of “Base Slots” called “msg”. Edit the line under “Literal Value” to customize the value of the msg slot. The literal value will usually be a string of text and variables. There are a couple of options for the variable substitution for the msg slot including referencing other base slots or using variables that are derived from the attributes available for that class of events.

Per the ITM Installation Guide:
      When customizing the msg attribute slot, the Literal value column can be used to define a custom message template. The message template can consist of fixed message text and variable substitution references, or symbols. The symbol can be base or extended slot data, or a special reference to the situation formula. Base slots are those that are included in all forwarded events, such as situation_name. Extended slots are those specific to the attribute group used by the situation definition. See the following syntax:

      •For an extended slot, use the fully qualified attribute name ($Attribute_Table.Attribute_Name$).
      •For a base slot, use the variable name that is not fully qualified (no . periods) unless it is the situation formula symbol.
      •For a situation formula, use $formula$.

      These characters are not supported: less than, greater than, quotation mark, single quotation mark, and ampersand. The Literal value column cannot be used to define a message template if a value is selected in the Mapped attribute column.

In the case of using base slots, reference the names in the “Base Slots” tables or an event that have already been received.

In the case of the extended attribute names, determine the name of the class name and the attribute. The attribute name will not necessarily be the name in the “Extended Slots” table or the name of the slots in the EIF events that have been received. To find the fully qualified attribute names, reference the attribute file for that agent. In a later section of this document, more details are provided to assist in locating the attribute file and the attribute names.

As for the first example, the default msg slot, without any customization, would read like

msg='Test_CustomEIF_DiskSpace[(%_Free>5 ) ON Primary:MYNTAGENT:NT ON C: (%_Free=10 )]'

Instead, I would like the msg slot to read like “C: is 90% used” so I want my msg slot to look like “<the drive name> is <value> % used”. To do this, I would need to include the fully qualified attribute names to substitute the value of the disk drive name and the percent (used) utilization. In this case, the “Literal Value” field would be:

$NT_Logical_Disk.Disk_Name$ is $NT_Logical_Disk.%_Used$ % used

When the event is forwarded via EIF the value of the $NT_Logical_Disk.Disk_Name$ attribute will be substituted with the Disk Name (ie “C:”) and the value of the $NT_Logical_Disk.%_Used$ attribute will be substituted with the value of the ‘percent used’ of the disk drive. The words “is” and “% used” will remain unchanged.

So the GUI will appear as follows:



At this point, save the changes by hitting “OK” on the bottom right corner of the screen.

The msg slot will now look like:

msg='C: is 24 % used';

A Second Example


Other base slot values can be used as variables in the msg slot. This example will use the “sub_source” slot which will reference the origin of the situation, such as the agent hostname, and the “sub_origin” slot which will resolve to the drive name. In this example, the $sub_origin$ and the $sub_source$ base slots are used to make the msg slot literal value:

"Drive $sub_origin$ on $sub_source$ is $NT_Logical_Disk.%_Used$ % used"




The msg slot will now look like:

msg='Drive C: on Primary:MyNTAgent:NT is 24 % used'

MSG Slot Mapping in EIF Events


The mapping of the msg slot occurs at the time the events are forwarded to an event destination from the Hub TEMS. There is a default mapping for each event that will be applied if no EIF Slot Customization mapping is saved for that situation. The Class name of the event will receive a default value along with the slots for the attributes associated with the event. In the case that a default class name cannot be identified, the class name will be Omegamon_Base.

In the situation example, the original event, without any custom mapping, appears as:
ITM_NT_Logical_Disk;source='ITM';sub_source='Primary:MYNTAGENT:NT';cms_hostname=‘HUBTEMS’;cms_port='3661';integration_type='N';master_reset_flag='';appl_label='';situation_name='Test_CustomEIF_DiskSpace';situation_type='S';situation_origin='Primary:MYNTAGENT:NT';situation_time=' 11:20:14.002';situation_status='Y';situation_thrunode='HUBTEMS';hostname='MYNTAGENT';origin='<ip_address>';adapter_host='MYNTAGENT';severity='WARNING';date='02/10/2012';msg='Test_CustomEIF_DiskSpace[(%_Free>5 ) ON Primary:MYNTAGENT:NT ON C: (%_Free=76 )]';situation_displayitem='C:';sub_origin='C:';avg_disk_queue_length='0.078';avg_disk_read_queue_length='0';avg_disk_write_queue_length='0.078';disk_bytes_per_sec='14182';disk_bytes_per_sec_64='14182';avg_disk_ms_per_read='0';disk_queue_length='3';disk_read_bytes_per_sec_64='0';disk_read_bytes_per_sec='0';disk_reads_per_sec='0';disk_transfers_per_sec='3';disk_write_bytes_per_sec_64='14182';disk_write_bytes_per_sec='14182';disk_writes_per_sec='3';free_megabytes='364393';disk_name='C:';disk_name_long='C:';server_name='Primary:MYNTAGENT:NT';pct__free='76';pct__disk_read_time='0';pct__disk_time='7';pct__disk_write_time='7';pct__used='24';physical_disk_number='0';timestamp='1120210112014868';total_size='476938';situation_eventdata='~';END


After mapping using the msg slot literal value of:
“$NT_Logical_Disk.Disk_Name$ is $NT_Logical_Disk.%_Used$ % used”

The event appears as:
ITM_NT_Logical_Disk;cms_hostname=‘HUBTEMS’;cms_port='3661';integration_type='N';master_reset_flag='';appl_label='';situation_name='Test_CustomEIF_DiskSpace';situation_type='S';situation_origin='Primary:MYNTAGENT:NT';situation_time='<date>14:13:26.001';situation_status='Y';situation_thrunode='HUBTEMS';situation_displayitem='C:';source='ITM';sub_source='Primary:MYNTAGENT:NT';hostname='MYNTAGENT';origin='<ip_address>';sub_origin='C:';adapter_host='MYNTAGENT';date='02/10/2012';severity='WARNING';msg='C: is 24 % used';situation_eventdata='~';END


One observation is that the default mapping causes the forwarded event to include some additional slots that are not directly relevant to the event once the msg slot was customized. Which slots are included by default will be directly dependent upon the Class Name of the event and the default mapping.

In addition, the variables were successfully substituted into the msg slot when the situation becomes true in the example. It is important to note that variable substitutions for agent based attributes referenced in EIF slot customizations are not resolved to a new value for non-true events. This would include events generated for the situations going false or the situation being stopped or started. In the example above, the slot of situation_status=’Y’ confirms that this event was raised for a situation going true and it is expected that the attribute values, if available, will be substituted in place of the variables in the msg slot. If the situation status is another value, such as ‘N’, the variables values will not be substituted. For instance, if the variables are not substituted, you will see “msg='Drive on is % used'”

Viewing the EIF mapping using tacmd viewsit


EIF slot customizations, when done via the EIF Slot Customization Editor, will be saved internally on the Hub TEMS and can be viewed using the ‘tacmd viewsit’ command. The MAP value will include any mappings saved using the EIF Slot Customization GUI.

Login into the tacmd interface using ‘tacmd login’ and locate the situation. In this case, I named the situation “Test_CustomEIF_DiskSpace.

Example:
tacmd listsit | grep EIF
Test_CustomEIF_DiskSpace Windows OS


To get the mapping details, export the XML output to a file using
“tacmd viewsit -s <sitname> -e <filename>” and view the output file.


Here is the MAP parameter after making the customizations in the first example using full attribute names:


The mapping for the second example using base slot variables will appear as:


Note: Prior to making any mapping changes, there will be no <MAP> parameters in the file. Once the EIF Slot Customization changes are saved, the output will include the mapping values in the tacmd output.

Determining the Full Name of an Attribute


To determine the list of attribute names available for a specific class, reference the attribute file for the agent that was loaded with the application support installation on the Hub TEMS.

For Windows, the default directory for the attribute files is:
c:\IBM\ITM\CMS\ATTRLIB

For Unix/Linux, the default directory for the attribute files is:
/opt/IBM/ITM/tables/<tems-name>/ATTRLIB

Search the <agent product code>.atr file for the class name and then look for the full attribute name that can be referenced in the EIF Slot Customization Editor.

For instance, for the Windows OS agent (NT product code) used in the example, the knt.atr file is the attribute file and small subset of the attribute names may include:

c:\IBM\ITM\CMS\ATTRLIB>grep name knt.atr | grep name | grep <class name>
name NT_Logical_Disk.Disk_Name
name NT_Logical_Disk.Free_Megabytes
name NT_Logical_Disk.Total_Size
name NT_Logical_Disk.%_Used
name NT_Logical_Disk.%_Free
name NT_Logical_Disk.Disk_Name_Long
name NT_Physical_Disk.Server_Name
name NT_Physical_Disk.Timestamp
name NT_Physical_Disk.Disk_Name

Another option is to use the situation event editor itself and refer to the attribute names used when you write the attributes out to a command using the situation action as a tool for determining the attribute names available.

Deleting the EIF Slot Customization Map


If you need to remove the mapping and return to the default mapping for the event, return to the EIF Slot Customization Editor GUI for the situation and hit the “delete map” button on the lower-right corner of the screen. This will delete the mapping entry in the TEMS database.


Mapping enumerated slots to msg slot


In the case that you need to add an enumerated value into the msg slot, you will need to use a map file rather than the EIF slot customization editor.

Please refer to the following technote:
http://www-01.ibm.com/support/docview.wss?uid=swg21515055

    [{"Product":{"code":"SSTFXA","label":"Tivoli Monitoring"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"ITM Tivoli Enterprise Mgmt Server V6","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"6.2.2;6.2.3;6.3","Edition":"","Line of Business":{"code":"LOB45","label":"Automation"}}]

    Document Information

    Modified date:
    17 June 2018

    UID

    swg21591295