This chapter provides information about the default event templates shipped with the IBM Tivoli Netcool/OMNIbus Connector.
Event templates are XML transformation style sheets that map Enterprise Manager event attributes to Netcool/OMNIbus alert attributes.
The Netcool/OMNIbus event connector contains predefined event templates for Create and Update event operations on the Netcool/OMNIbus system. You can customize these templates to fulfill your particular requirements. Oracle recommends that you back up these factory-built templates before customizing them.
This chapter discusses the following topics:
This section describes the default mappings between the Enterprise Manager event data fields and the Netcool/OMNIbus alert data fields.
XML Style Sheet (XSL) files contain the mappings between the two systems. These files are located in the Self Update archive that was installed in Installing the Connector in Enterprise Manager.
To obtain copies of the XSL files, perform the steps in Exporting the Template Files.
Table 5-1 lists the XSL files that perform the mappings and provides a summary of each.
Table 5-1 XSL Files That Perform Mappings
| File | Description |
|---|---|
|
|
Transforms the Oracle Enterprise Manager event data to the IBM Netcool/OMNIbus alert format for the createEvent operation. |
|
|
Transforms the Oracle Enterprise Manager event data to the IBM Netcool/OMNIbus alert format for the updateEvent operation. |
The following sections provide details about the default mappings in each of the files:
The Oracle Enterprise Manager Connector Framework invokes the createEvent operation whenever an event is generated in Oracle Enterprise Manager and there is a rule configured to invoke the Netcool/OMNIbus connector. createEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to Netcool/OMNIbus alert format. Table 5-2 lists the default field mappings between the IBM Tivoli Netcool/OMNIbus alert and the Oracle Enterprise Manager event.
Table 5-2 Netcool/OMNIbus Field Name
| Netcool/OMNIbus Field Name | Value |
|---|---|
|
Identifier |
Set to the event |
|
Node |
Set to the event |
|
NodeAlias |
Set to the event |
|
Manager |
Hard coded to "Oracle Enterprise Manager." |
|
Agent |
Set to the event |
|
Summary |
Set to the event |
|
Severity |
Set the severity based on the event severity as specified in Severity Mappings. |
|
AlertGroup |
Set to the event |
|
AlertKey |
Set to the |
|
LastOccurrence |
Set to the event |
|
URL |
Set to the event |
|
Details |
Set to the formatted contents of the event as specified in Details Mapping - Create. |
|
Type |
Problem |
|
Journal |
Set to the formatted contents of the event as specified in Journal Mapping. |
The Oracle Enterprise Manager Connector Framework invokes the updateEvent operation whenever an event is updated in Oracle Enterprise Manager and there is a rule configured to invoke the Netcool/OMNIbus connector. updateEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to Netcool/OMNIbus alert format. Table 5-3 lists the default field mappings between the IBM Netcool/OMNIbus alert and the Oracle Enterprise Manager event.
Table 5-3 Update Event Template Mapping
| Netcool/OMNIbus Field Name | Value |
|---|---|
|
Identifier |
Set to the event |
|
Severity |
Set the severity based on the event severity as specified in Severity Mappings. |
|
Summary |
Set to the event |
|
LastOccurrence |
Set to the event |
|
Details |
Set to the formatted contents of the event as specified in Details Mapping - Update. |
|
Journal |
Set to the formatted contents of the event as specified in Journal Mapping. |
This section identifies the format of the information that will be placed in the details table whenever an alert is created in Netcool/OMNIbus. The format the template uses for the details table is shown below. Text delimited by angle brackets (< and >) designates an Enterprise Manager Event field name that will be replaced by the actual field contents. Lines marked with double-asterisks indicate they will only be present if the designated event field contains data. The Notes section below the format contains information about some of the fields.
Occurred Date: <OccurredDate> ReportedDate: <ReportedDate> Event Class: <EventClass> Event Name: <EventName> Target Type: <SourceInfo/TargetInfo/TargetTypeLabel> Target Name: <SourceInfo/TargetInfo/TargetName> Severity: <Severity> Message: <Message> URL: <EventURL> <TargetProperty/Name[1]>: <TargetProperty/Value[1]>** <TargetProperty/Name[2]>: <TargetProperty/Value[2]>** <TargetProperty/Name[3]>: <TargetProperty/Value[3]>** <TargetProperty/Name[4]>: <TargetProperty/Value[4]>** <TargetProperty/Name[5]>: <TargetProperty/Value[5]>** <TargetProperty/Name[6]>: <TargetProperty/Value[6]>** <TargetProperty/Name[7]>: <TargetProperty/Value[7]>** <TargetProperty/Name[8]>: <TargetProperty/Value[8]>** <TargetProperty/Name[9]>: <TargetProperty/Value[9]>** <TargetProperty/Name[10]>: <TargetProperty/Value[10]>** <TargetProperty/Name[11]>: <TargetProperty/Value[11]>** <TargetProperty/Name[12]>: <TargetProperty/Value[12]>** <TargetProperty/Name[13]>: <TargetProperty/Value[13]>** <TargetProperty/Name[14]>: <TargetProperty/Value[14]>** <TargetProperty/Name[15]>: <TargetProperty/Value[15]>** <TargetProperty/Name[16]>: <TargetProperty/Value[16]>** <TargetProperty/Name[17]>: <TargetProperty/Value[17]>** <TargetProperty/Name[18]>: <TargetProperty/Value[18]>** <TargetProperty/Name[19]>: <TargetProperty/Value[19]>** <TargetProperty/Name[20]>: <TargetProperty/Value[20]>**
The Target Properties information is only present if the event contains target property values. Listed below are a couple of sample target property name/value pairs:
Line of business: Finance Owner: Finance-DB Team
URL is set to the URL of the Event Details page in Enterprise Manager. The URL must be copied into a browser to view the event in Enterprise Manager.
This section identifies the format of the information that will be updated in the details table whenever an alert is updated in Netcool/OMNIbus. Text delimited by angle brackets (< and >) designates an Enterprise Manager Event field name that will be replaced by the actual field contents.
Severity: <Severity> Message: <Message>
This section identifies the format of journal entries that are added whenever an alert is created or update in Netcool/OMNIbus. Text delimited by angle brackets (< and >) designates an Enterprise Manager Event field name that will be replaced by the actual field contents.
Severity: <SeverityCode> Reported Date: <ReportedDate> <Message>
The Netcool/OMNIbus alert severity is set based on the Enterprise Manager event severity value. Table 5-4 shows the values used when creating the alert in Netcool/OMNIbus.
Although the default mappings are sufficient for most implementations, you can change them as needed. The following sections discuss:
Managing Templates in Oracle Enterprise Manager 12c (recommended)
It is assumed that you already have a good understanding of XSL.
For reference information on the Netcool/OMNIbus mappings, see Appendix A, "Web Service for Netcool/OMNIbus Details."
Example 5-1 shows the format that the Oracle Enterprise Manager Connector Framework provides when an event is created or updated in Oracle Enterprise Manager.
For more information about Oracle Enterprise Manager events, see the Using Incident Management chapter of the Oracle Enterprise Manager Cloud Control Administrator's Guide.
Example 5-1 XML Format of Events
<EMEvent xmlns="http://xmlns.oracle.com/sysman/connector">
<ExternalEventID/>
<SystemAttributes>
<EventClass/>
<OccurredDate/>
<ReportedDate/>
<EventName/>
<Severity/>
<SeverityCode/>
<SourceInfo>
<TargetInfo>
<TargetName/>
<TargetTypeLabel/>
<TargetProperty>
<Name/>
<Value/>
</TargetProperty>
</TargetInfo>
</SourceInfo>
<Message/>
<EventURL/>
</SystemAttributes>
<EventContextAttributes>
<NumberAttribute>
<Name/>
<Value/>
</NumberAttribute>
<StringAttribute>
<Name/>
<Value/>
</StringAttribute>
</EventContextAttributes>
</EMEvent>
Table 5-5 provides a description of the fields shown in Example 5-1.
Table 5-5 Field Descriptions for XML Format
| Field | Description |
|---|---|
|
ExternalEventID |
Unique identifier of the alert in IBM Netcool/OMNIbus. This will only be set for updates. |
|
EventClass |
Identifies the type of event. |
|
OccurredDate |
In cases where the event information is mined from a log, this field contains the date and time when the event occurred based on the entry in the log. |
|
ReportedDate |
Date/time the event was reported by Enterprise Manager. |
|
EventName |
Descriptive name of the event. |
|
Severity |
Severity of the event: Fatal, Critical, Warning, Minor_Warning, Informational, or Clear. |
|
SeverityCode |
Severity code for the event: FATAL, CRITICAL, WARNING, MINOR_WARNING, INFORMATIONAL, or CLEAR. |
|
TargetName |
Target name that is a unique instance of the target type. |
|
TargetTypeLabel |
Display name of the target type for which the event was generated. |
|
TargetProperty |
Additional target properties that do not have a specific field in the event model (name:value pair). |
|
Message |
Description of the event. |
|
EventURL |
Link to the web page for the event. |
|
EventContextAttributes |
Additional event properties that do not have a specific field in the event model (name:value pair). |
Oracle Enterprise Manager 12c (Release 12.1.0.2 and later) includes the functionality to allow you to manage templates within Cloud Control. Templates, which are included as part of the connector installation, are automatically registered and are shown within Enterprise Manager.
If you need to use new a template that is not included as part of the connector installation, then you will need to register it using the emctl command. See Manually Changing a Mapping for more information. Once you have registered the template, you will be able to manage it through Enterprise Manager.
Using Enterprise Manager, you can edit a template, view the XML code, delete a template, and restore a deleted template.
To begin:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the IBM Tivoli Netcool/OMNIbus Connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Note:
This feature is available on Oracle Enterprise Manager Release 12.1.0.2.0 or later only. To verify your installed release version:Log in to Enterprise Manager.
From the Help menu, select About Cloud Control.
The pop-up window displays the installed version of Oracle Enterprise Manager.
To edit an existing template:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the IBM Tivoli Netcool/OMNIbus Connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click Edit.
After you edit the Description or Template Contents fields, click Save. On the confirmation page, click Yes to complete the template save.
To view template code:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the IBM Tivoli Netcool/OMNIbus Connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click View.
The event templates are in XSLT format. A basic knowledge of XSLT is required to understand the code.
To delete a template:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the IBM Tivoli Netcool/OMNIbus Connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click Delete.
Click Yes to confirm the delete operation.
To restore a deleted template:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the IBM Tivoli Netcool/OMNIbus Connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click Restore.
Click Yes in the confirmation page that appears in order to restore.
Note:
You can restore out-of-box templates that you have may edited or customized to their default values. You cannot restore new templates that you have created (using the emctl register_template command) described in Manually Changing a Mapping.The following procedure provides the steps required to change a mapping.
Export the default template XSLT files from Enterprise Manager to use as a baseline. Follow the instructions in Exporting the Template Files to obtain copies of the default template files.
Create a custom template file by copying the XSL file you want to change to a new file with a unique name.
Make the desired mapping changes to the template file. See Modifying Templates for guidance on mapping changes.
Register the new template with Enterprise Manager as specified in Registering Templates.
See Template Customization Example for an example of how to customize templates.
The connector installation jar file is included in the Self Update archive that was installed in Installing the Connector in Enterprise Manager.
To extract the installation file:
Copy the omnibus_connector.jar file from the Management Server host system to a temporary directory. The file is located in the archives directory that was extracted in Exporting the Installation Files.
Extract the templates from the connector jar file using the following command:
$JAVA_HOME/bin/jar xf omnibus_connector.jar createEvent_request.xsl updateEvent_request.xsl
Note:
If the system where the connector file is located does not have the JDK installed, you cannot extract the jar file contents. You must copy the jar file to a system that has the JDK installed and transfer the template files after they have been extracted.A template is an XSLT file that transforms an input XML format to an output XML format. To make the mapping changes, you need to understand the input XML format being transformed and the output XML the template generates. The input document is the XML document that contains the Enterprise Manager event information. The output document is the request being sent to the web service for Netcool/OMNIbus. The output XML document must conform to the data format specified in the Netcool/OMNIbus EventService WSDL as shown in Appendix C.
Appendix B contains details on the format of the event data generated by Enterprise Manager. Appendix C contains details on the XML format required by the web service for Netcool/OMNIbus EventService. Mappings Between XML Format and Message Field Names in Appendix A provides the mapping between the web service for Netcool/OMNIbus EventService fields and the field names in Netcool/OMNIbus. Listed below are the steps you should follow to modify the template file.
To modify a template:
Review Mappings Between XML Format and Message Field Names in Appendix A and Appendix C to identify the names of the fields in the web service for Netcool/OMNIbus that you are planning to modify. For example, if you want to populate the Node field in Netcool/OMNIbus, look up the field in Appendix A and observe that the web service for Netcool/OMNIbus expects the data in the /create/event/source/displayName XML path.
If you are planning on using data from the event, review Appendix B to identify the field(s) you want to use in the mapping. Appendix D provides sample transactions that could be very helpful in identifying what data is present in the XML document from Enterprise Manager.
Open the custom template file in a text editor or a utility that can be used to build XSLT files.
Make the necessary changes to the custom template file and save it.
Unless the change is very basic, you should test the changes that you have made using the sample data from Appendix D. This requires a utility that performs XSLT translations.
You need to reregister your customized templates before they are recognized in Enterprise Manager.
For each customized template, run the following emctl register_template connector command. The command must be run as a user that has execute privileges on emctl and read privileges on the template:
$ORACLE_HOME/bin/emctl register_template connector -t <template.xsl> -repos_pwd <reposPassword> -cname <connectorName> -iname <internalName> -tname <templateName> -ttype 2 [-d <description>]
Where:
<template.xsl> is the full path name of the custom template file.
<reposPassword> is the Enterprise Manager root password.
<connectorName> is the name of the connector instance installed in step 5 of Creating a Connector Instance.
<internalName> is the internal name to use for the template.
<templateName> is the name to display for the template.
<description> is the description of the template.
For example, the following command updates the createEvent template for the connector instance with the name of "Netcool/OMNIbus:"
emctl register_template connector -t /home/oracle/templates/createEvent_custom_request.xsl -repos_pwd sysmanpass -cname "Netcool/OMNIbus" -iname "createEvent" -tname "Create Event Request" -ttype 2 -d "Demo template"
In this scenario, the customer has determined that the default mapping does not work for their environment. Instead of placing target name information in the Node field, the customer would like to place target type information in the Node field. The customer would also like to set the Location field if the target properties have location information specified. They have created a temporary directory on the OMS server system at /home/oracle/customized_templates to contain the templates.
The following steps explain how the customer would customize the templates to meet their requirements.
Open a command window on the OMS server system and change the working directory to the temporary directory:
cd /home/oracle/customized_templates
Copy the omnibus_connector.jar file from the archives directory from Exporting the Installation Files to the temporary directory:
cp $exported_dir/archives/omnibus_connector.jar .
Extract the template files from the jar file. This command extracts the createEvent and updateEvent template files:
$JAVA_HOME/bin/jar xf omnibus_connector.jar createEvent_request.xsl updateEvent_request.xsl
Make a working copy of the template files for modification:
cp createEvent_request.xsl createEvent_request_custom.xsl
Open the createEvent_request_custom.xsl file in a text editor.
Change the mapping for the Node field as shown below.
Before Changes
The following code shows the Node mapping in the file before the changes:
<source>
<name>
<!-- Sets the Netcool/OMNIbus NodeAlias field -->
<xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetName"/>:<xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetProperty[a:Name='Target_Host']/a:Value"/>
</name>
<displayName>
<!-- Sets the Netcool/OMNIbus Node field -->
<xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetName"/>
</displayName>
</source>
After Changes
The following code shows the Node mapping after the changes. The changes are shown in bold:
<source>
<name>
<!-- Sets the Netcool/OMNIbus NodeAlias field -->
<xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetName"/>:<xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetProperty[a:Name='Target_Host']/a:Value"/>
</name>
<displayName>
<!-- Sets the Netcool/OMNIbus Node field -->
<xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetTypeLabel"/>
</displayName>
</source>
Add logic to populate the Location field if the target properties contain location information.
Before Changes
The following code shows the extended fields mapping in the file before the changes:
<extended-fields>
<!-- Sets the Netcool/OMNIbus Manager field -->
<string-field name="Manager">Oracle Enterprise Manager</string-field>
...
</extended-fields>
After Changes
The following code shows the extended fields mapping after the changes. The changes are shown in bold:
<extended-fields> <xsl:variable name="location"> <xsl:for-each select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetProperty"> <xsl:if test="a:Name = 'Location'"> <xsl:value-of select="a:Value"/> </xsl:if> </xsl:for-each> </xsl:variable> <!-- Sets the Netcool/OMNIbus Location field if specified in the target properties --> <xsl:if test="$location != ''"> <string-field name="Location"><xsl:value-of select="$location"/> </string-field> </xsl:if> <!-- Sets the Netcool/OMNIbus Manager field --> <string-field name="Manager">Oracle Enterprise Manager</string-field> ... </extended-fields>
Save your changes after making the updates.
To set up for testing, create an empty create.xml file and open in a text editor.
Copy the contents of the XML document in the Create Example section of Appendix D into the create.xml file and save it.
Test the new templates using a utility that performs XSLT translations using the create.xml file as the input XML document.
Note:
There are a variety of off-the-shelf testing utilities that are available. Use the utility that works best for your environment.Examine the output XML document and verify that the results are correct.
Note:
You can also use an XML client to send the XML output document to the web service for Netcool/OMNIbus to verify that it is a format accepted by the web service.If the XML document has problems, make any necessary corrections and repeat steps 11 and 12.
At the OMS server system, run the following command to re-register your customized createEvent template:
emctl register_template connector -t /home/oracle/customized_templates/createEvent_request_custom.xsl -repos_pwd sysmanpass -cname "Netcool/OMNIbus" -iname "createEvent" -tname "Create Event Request" -ttype 2 -d "This is the customized request xsl file for the createEvent method"