5.4 Customizing Event Mappings

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 Customizing Microsoft HP Operations Manager.

5.4.1 XML Format of Oracle Enterprise Manager Events

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).

5.4.2 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 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.

5.4.2.1 Exporting the Template Files

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:
1. From the Setup menu in the Enterprise Manager console, select Extensibility, then Self Update.
2. Click on the Management Connector link.
3. 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.
  
  Figure 5-1 Export Command Example
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.

5.4.2.2 Modifying Templates

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.

Enterprise Manager Event Format contains details on the format of the event data generated by Enterprise Manager. OMU Web Service WSDL Format 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 OMU Web Service WSDL Format 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 Enterprise Manager Event Format to identify the field(s) you want to use in the mapping. Enterprise Manager Event Examples 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.

5.4.2.3 Registering Templates

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"

5.4.2.4 Template Customization Example

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 Enterprise Manager Event Examples into the create.xml file and save it.
Copy the contents of the XML document in the "Update Example" section of Enterprise Manager Event Examples 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