Oracle® Enterprise Manager HP Operations Manager Connector Installation and Configuration Guide Release 12 (12.1.0.2.0) Part Number E28302-03 |
|
|
PDF · Mobi · ePub |
This chapter provides information about the default event templates shipped with the OMU Connector. The event templates specify the mappings between Enterprise Manager event attributes and OMU web service attributes.
This chapter discusses the following topics:
Default Templates
Formatted Enterprise Manager Event Contents
Severity Mappings
Customizing Event Mappings
This section describes the default mappings between the Enterprise Manager event data fields and the OMU message 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 Section 2.3, "Installing the Connector". To extract the installation file, perform the steps in Section 4.1.3.1, "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 |
---|---|
createEvent_request.xsl |
Transforms the Oracle Enterprise Manager event data to the HP Operations Manager message format for the createEvent operation. |
updateEvent_request.xsl |
Transforms the Oracle Enterprise Manager event data to the HP Operations Manager message 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 OMU connector. createEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to OMU message format. Table 5–2 lists the default field mappings between the HP Operations Manager message and the Oracle Enterprise Manager event.
Table 5-2 Create Event Template Mapping
Operations Manager Field Name | Value |
---|---|
Message Text |
Set to the formatted contents of the incident as specified in Formatted Enterprise Manager Event Contents. |
Severity |
Set the severity based on the event severity as specified in the section below entitled Formatted Enterprise Manager Event Contents. |
Message Group |
Hard-coded to "OracleEnterpriseManager." |
Object |
Set to the event TargetName field. |
Node |
Hard-coded to "OracleEnterpriseManager." |
Application |
Set to the event TargetTypeLabel field. |
The Oracle Enterprise Manager Connector Framework invokes the updateEvent operation whenever an event is generated in Oracle Enterprise Manager and there is a rule configured to invoke the OMU connector. updateEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to OMU message format. Table 5–3 lists the default field mappings between the HP Operations Manager message and the Oracle Enterprise Manager event.
Table 5-3 Update Event Template Mapping
Operations Manager Field Name | Value |
---|---|
Message No. |
Set to the event ExternalEventId field. |
Message Text |
Set to the formatted contents of the incident as specified in Formatted Enterprise Manager Event Contents |
Severity |
Set the severity based on the event severity. See Severity Mappings for details. |
Message Group |
Hard-coded to "OracleEnterpriseManager." |
Object |
Set to the event TargetName field. |
Node |
Hard-coded to "OracleEnterpriseManager." |
Application |
Set to the event TargetTypeLabel field. |
The format the templates use for the Description fields 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.
Received event reported by Oracle Enterprise Manager: 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> Target Properties:** <TargetProperty/Name>: <TargetProperty/Value>** Event Context:** <EventContextAttributes/StringAttribute/Name>: < EventContextAttributes/StringAttribute /Value>**
The Target Properties section 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
The Event Context section is only present if the event contains event context attribute values. There can be StringAttribute or NumberAttribute values that contain a name/value pair.
URL is set to the URL of the Event Details page in Enterprise Manager. The URL is set up as a link that you can click directly to view the event in Enterprise Manager.
The OMU message severity is set based on the Enterprise Manager event severity value. Table 5–4shows the values used when creating the message in OMU.
Although the default mappings are sufficient for most implementations, you can change them as needed. The following sections discuss:
It is assumed that you already have a good understanding of XSL.
For reference information on the OMU mappings, see Appendix A, "Customizing Microsoft HP Operations Manager".
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.
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 message in HP Operations Manager. This will only be set for updates. |
EventClass |
Identifies the type of event. |
OccurredDate |
Date/time the event occurred. |
ReportedDate |
Date/time the event was reported by OMS. |
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. |
TargetType |
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). |
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 back-up copy of the XSL file you want to change.
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:
Determine the command required to export the adapter installation file. To do this, perform the following steps:
From the Setup menu in the Enterprise Manager console, select Extensibility, then Self Update.
Click on the Management Connector link.
Click on the OMU connector and then select Export from the Actions list.
A pop-up window appears with the command required to export the file. Figure 5-1 shows an example of the window.
Open a command window on the Management Server host system and navigate to a temporary directory where you can copy the file.
Log into EM CLI using the following command. You are asked to provide the password information for the sysman account.
emcli login -username=sysman
Note:
You must execute EM CLI from the OMS host. See the Oracle Enterprise Manager Command Line Interface for information about setting up EM CLI.Run the EM CLI export_update command from your system, changing <dirname> to the full path of the temporary directory.
This creates a zip file. The file name is comprised of the id value specified in the export_update command with a .zip extension. In the example command in Figure 5-1, the zip file name would be:
E9F684312AE7A18E98340715D079E58D.zip
Extract the adapter installation jar file from the zip file using the following command:
unzip *.zip archives/*connector.jar
Extract the templates from the connector jar file using the following command:
$JAVA_HOME/bin/jar xf archives/*.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 OMU Web service. The output XML document must conform to the data format specified in the OMU EventService WSDL.
Appendix C contains details on the format of the event data generated by Enterprise Manager. Appendix D contains details on the XML format required by the OMU EventService Web service. Mappings Between XML Format and Message Field Names provides the mapping between the OMU EventService Web service fields and the field names in OMU. 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 and Appendix D to identify the names of the fields in the OMU Web service that you are planning to modify. For example, if you want to populate the Source field in OMU, look up the field in Mappings Between XML Format and Message Field Names and observe that the OMU Web service expects the data in the /create/event/source/name XML path.
If you are planning on using data from the event, review Appendix C to identify the field(s) you want to use in the mapping. Appendix E 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 E. 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 as a user with execute privilege on emctl and the ability to read 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 template file.
<reposPassword> is the Enterprise Manager root (SYSMAN) password.
<connectorName> is the name of the connector instance installed in step 5 of section 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 "OMU:"
emctl register_template connector -t /home/oracle/customized_templates/createEvent_request.xml -repos_pwd sysmanpass -cname "OMU" -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 the target type information in the application field, the customer would like to hard-code the application field to "Oracle Enterprise Manager". The customer would also like to place the target type information in a CMA field named TargetType. 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.
Navigate to the Management Connector Updates page and export the OMU Connector. Copy the first EM CLI command listed in the Export Steps window for later use:
emcli export_update -id=DD4E9161C5E7129F9641447FB4F0497B -omslocal -dir=<dirname>
Open a command window on the OMS server system and change the working directory to the temporary directory:
cd /home/oracle/customized_templates
Log into EM CLI:
emcli login -username=sysman
Run the EM CLI command from step 1 to export the zip file to the temporary directory.
emcli export_update -id=DD4E9161C5E7129F9641447FB4F0497B -omslocal -dir=/home/oracle/customized_templates
Extract the connector jar file from the zip file:
unzip *.zip archives/*connector.jar
Extract the template files from the jar file. This command extracts the createEvent and updateEvent template files:
$JAVA_HOME/bin/jar xf archives/*.jar createEvent_request.xsl updateEvent_request.xsl
Make a back-up copy of the template files for modification:
cp createEvent_request.xsl createEvent_request.xsl.orig cp updateEvent_request.xsl updateEvent_request.xsl.orig
Open the createEvent_request.xsl file in a text editor.
Change the Extended Fields section to reflect the new mapping.
Before Changes
The following code shows the Extended Fields section in the file before the changes.
<extended-fields> <!-- OMU Application --> <string-field name="application"> <xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetTypeLabel"/> </string-field> <!-- Do not add CMA data --> <string-field name="ovo_ts_field">NONE</string-field> <!-- Own the event after it is created --> <string-field name="own">true</string-field> </extended-fields>
After Changes
The following code shows the Extended Fields section in the file after the changes. The changes are shown in bold italics.
<extended-fields> <!-- OMU Application --> <string-field name="application">Oracle Enterprise Manager</string-field> <!-- Do not add CMA data --> <string-field name="ovo_ts_field">NONE</string-field> <!-- Own the event after it is created --> <string-field name="own">true</string-field> <string-field name="TargetType"> <xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetTypeLabel"/> </string-field> </extended-fields>
Save your changes after making the updates.
Open the updateEvent_request.xsl file and make the same changes. In this case, you cannot just cut and paste the Extended Fields section, because there are some differences between the create and update translations. You will need to edit them separately.
Save your changes after making the updates.
To set up for testing, create the create.xml and update.xml files and open them in a text editor.
Copy the contents of the XML document in the "Create Example" section of Appendix E into the create.xml file and save it.
Copy the contents of the XML document in the "Update Example" section of Appendix E into the update.xml file and save it.
Test the new templates using a utility that performs XSLT translations using each of the create.xml and update.xml files as the input XML document.
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 OMU Web service 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 16 and 17.
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.xsl -repos_pwd sysmanpass -cname "OMU" -iname "createEvent" -tname "Create Event Request" -ttype 2 -d " This is the customized request xsl file for the createEvent method"
At the OMS server system, run the following command to re-register your customized updateEvent template:
emctl register_template connector -t /home/oracle/customized_templates/updateEvent_request.xsl -repos_pwd sysmanpass -cname "OMU" -iname "updateEvent" -tname "Update Event Request" -ttype 2 -d " This is the customized request xsl file for the updateEvent method"6