5 Working With Event Templates

Event templates are XML transformation style sheets that map Enterprise Manager event attributes to OMU alert attributes.

The OMU event connector contains predefined event templates for Create and Update event operations on the OMU 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 provides information about the default event templates shipped with the OMU Connector.

This chapter discusses the following topics:

5.1 Default Templates

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 Installing the Connector in Enterprise Manager. To extract the installation file, 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
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.

5.1.1 Create Event Template

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.

5.1.2 Update Event Template

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.

5.2 Formatted Enterprise Manager Event Contents

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>**

Notes

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.

5.3 Severity Mappings

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.

Table 5-4 OMU Message Severity Mappings

When the incident severity is ...	Set the ticket severity to …
Fatal	Critical
Critical	Critical
Warning	Warning
Minor Warning	Warning
Information	Normal

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