5 Working With Event Templates

Create Event Template

The Oracle Enterprise Manager Connector Framework invokes the createEvent operation whenever an event is generated in Oracle Enterprise Manager and a rule is configured to invoke the SCOM connector. createEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to SCOM alert format. Table 5-2 lists the default field mappings between the Microsoft SCOM alert and the Oracle Enterprise Manager event.

Update Event Template

The Oracle Enterprise Manager Connector Framework invokes the updateEvent operation whenever an event is generated in Oracle Enterprise Manager and a rule is configured to invoke the SCOM connector.

updateEvent_request.xsl is invoked during the process to transform the data from Oracle Enterprise Manager format to SCOM alert format. Table 5-3 lists the default field mappings between the Microsoft SCOM alert and the Oracle Enterprise Manager event.

Formatted Enterprise Manager Event Contents

Listed below is the format used by the templates for the Description fields. 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 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/TargetType>
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 will only be present if the event contains target property values. Listed below are some sample target property name/value pairs:

  Line of business: Finance

  Owner: Finance-DB Team

• The Event Context section will only be 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. Copy the URL to a browser to directly view the event in Enterprise Manager.

Edit a Template with Enterprise Manager

To edit an existing template:

1. Log in to Enterprise Manager Cloud Control.

2. From the Setup menu, select Extensibility, then Management Connectors.

3. On the Management Connectors page, select the Microsoft SCOM Connector. Click Configure.

4. On the Configure Management Connector page, click the Template tab.

5. Select a template and click Edit.

6. After you edit the Description or Template Contents fields, click Save. On the confirmation page, click Yes to complete the template save.

View Template Code in Enterprise Manager

To view template code:

1. Log in to Enterprise Manager Cloud Control.

2. From the Setup menu, select Extensibility, then Management Connectors.

3. On the Management Connectors page, select the Microsoft SCOM Connector. Click Configure.

4. On the Configure Management Connector page, click the Template tab.

5. Select a template and click View.

The event templates are in XSLT format. A basic knowledge of XSLT is required to understand the code.

Delete a Template with Enterprise Manager

To delete a template:

1. Log in to Enterprise Manager Cloud Control.

2. From the Setup menu, select Extensibility, then Management Connectors.

3. On the Management Connectors page, select the Microsoft SCOM Connector. Click Configure.

4. On the Configure Management Connector page, click the Template tab.

5. Select a template and click Delete.

6. Click Yes to confirm the delete operation.

Restore a Deleted Template with Enterprise Manager

To restore a deleted template:

1. Log in to Enterprise Manager Cloud Control.

2. From the Setup menu, select Extensibility, then Management Connectors.

3. On the Management Connectors page, select the Microsoft SCOM Connector. Click Configure.

4. On the Configure Management Connector page, click the Template tab.

5. Select a template and click Restore.

6. Click Yes in the confirmation page that appears in order to restore.

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, perform the following steps.

1. Determine the command required to export the adapter installation file. To do this, perform the following steps:

   • From the Enterprise Manager console, click Setup.

   • Select Extensibility in the pane.

   • Select Self Update, then click Management Connector.

   • Click the SCOM connector, then select Export from the Actions list.

   A popup window appears with the command required to export the file. See Figure 5-1 below for an example of the popup window.

2. Open a command window on the Management Server host machine and navigate to a temporary directory where the file can be copied.

3. Log into emcli using the following command. You will be asked to provide the password information for the sysman account.

   emcli login -username=sysman

4. Run the emcli export_update command from your system, changing <dirname> to the full path of the temporary directory.

   A zip file will be created. The file name will be comprised of the id value specified in the export_update command with a .zip extension.

5. Extract the connector installation jar file from the zip file using the following command.

   unzip *.zip archives/*connector.jar

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

   Figure 5-1 Export Steps

   
   

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 being generated by the template. The input document is the XML document that contains the Enterprise Manager event information. The output document is the request being sent to the SCOM adapter. The output XML document must conform to the data format specified in the SCOM EventService WSDL.

Appendix C, "Enterprise Manager Event Format" contains details on the format of the event data generated by Enterprise Manager. Appendix D, "SCOM Web Service WSDL Format" contains details on the XML format required by the SCOM EventService web service. Mappings Between XML Format and Alert Field Names provides the mapping between the SCOM EventService web service fields and the field names in SCOM. Listed below are the steps you should follow to modify the template file.

1. Review Mappings Between XML Format and Alert Field Names and Appendix D, "SCOM Web Service WSDL Format" to identify the names of the fields in the SCOM adapter that you are planning to modify. For example if you wanted to populate the Custom1 field in SCOM, look the field up in Mappings Between XML Format and Alert Field Names and you would see that the SCOM adapter expects the data in the /create/event/extended-fields/string-field XML path

2. If you are planning on using data from the event, review Appendix C, "Enterprise Manager Event Format" to identify the field(s) you want to use in the mapping. Appendix B, "Enterprise Manager Event Samples" has sample transactions that could be very helpful in identifying what data is present in the XML document from Enterprise Manager.

3. Open the custom template file in a text editor or a utility that can be used to build XSLT files.

4. Make the necessary changes to the custom template file and save.

5. Unless the change is very simple, you should test the changes that you have made using the sample data from Appendix B. This will require a utility that performs XSLT translations.

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 pathname 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 3.1 “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: This command updates the createEvent template for the connector instance with the name of “SCOM R2”:
emctl register_template connector
-t /home/oracle/customized_templates/createEvent_request.xml
-repos_pwd sysmanpass
-cname "SCOM R2"
-iname "createEvent"
-tname "Create Event Request"
-ttype 2
-d "Demo template"

Template Customization Example

By default, the alert name in the Microsoft SCOM alert is set to the Oracle Enterprise Manager metric column, and no custom fields are mapped. The following example shows how to change the alert name and add mappings for custom fields. The changes made to the default mapping are:

The alert name is modified to use a hard-coded value of Event From Oracle Enterprise Manager.Custom field 1 is set to the Target Type.Custom field 2 is set to the Target Name.Custom field 3 is set to the Metric Name.Custom field 4 is set to the Metric Column.

1. Navigate to the Management Connector Updates page and export the SCOM Connector. Copy the first emcli command listed in the Export Steps window for later use.

   emcli export_update -id=DD4E9161C5E7129F9641447FB4F0497B -omslocal -dir=<dirname>

2. Open a command window on the OMS server machine and change the working directory to the temporary directory.

   cd /home/oracle/customized_templates

3. Log into emcli.

   emcli login -username=sysman

4. Run the emcli command from step 1 to export the zip file to the temporary directory.

   emcli export_update -id=DD4E9161C5E7129F9641447FB4F0497B -omslocal -dir=/home/oracle/customized_templates

5. Extract the connector jar file from the zip file.

   unzip *.zip archives/*connector.jar

6. Extract the template files from the jar file. This command will extract the createEvent and updateEvent template files.

   $JAVA_HOME/bin/jar xf archives/*.jar createEvent_request.xsl updateEvent_request.xsl

7. Make a copy of the createEvent_request.xsl file and name it custom_createEvent_request.xsl.

8. Make a copy of the updateEvent_request.xsl file and name it custom_updateEvent_request.xsl

9. Open the custom_createEvent_request.xsl file in your text editor.

10. Change the appropriate sections to reflect the new mapping.

    Before Changes

    The code below shows the impacted sections in the file before the changes.

    <summary>
           <xsl:value-of select="a:SystemAttributes/a:EventName"/>
         </summary>
         ...
         <extended-fields>
           <!-- SCOM alert custom fields -->
           <!-- Uncomment fields to be set and replace "VALUE" with the actual
            value -->
           <!--
           <string-field name="CustomField1">VALUE</string-field>
           <string-field name="CustomField2">VALUE</string-field>
           <string-field name="CustomField3">VALUE</string-field>
           <string-field name="CustomField4">VALUE</string-field>
           <string-field name="CustomField5">VALUE</string-field>
           <string-field name="CustomField6">VALUE</string-field>
           <string-field name="CustomField7">VALUE</string-field>
           <string-field name="CustomField8">VALUE</string-field>
           <string-field name="CustomField9">VALUE</string-field>
           <string-field name="CustomField10">VALUE</string-field>
           -->
         </extended-fields>
    

    After Changes

    The code below shows the Extended Fields section in the file after the changes. The changes are shown in bold.

    <!-- SCOM alert title -->
         <summary>Event From Oracle Enterprise Manager</summary>
         ...
         <extended-fields>
           <!-- SCOM alert custom fields -->
           <!-- Uncomment fields to be set and replace "VALUE" with the actual
            value -->
           <string-field name="CustomField1">
             <xsl:value-of select="a:TargetType"/>
           </string-field>
           <string-field name="CustomField2">
             <xsl:value-of select="a:TargetName"/>
           </string-field>
           <string-field name="CustomField3">
             <xsl:value-of select="a:MetricName"/>
           </string-field>
           <string-field name="CustomField4">
             <xsl:value-of select="a:MetricColumn"/>
           </string-field>
           <!--
           <string-field name="CustomField5">VALUE</string-field>
           <string-field name="CustomField6">VALUE</string-field>
           <string-field name="CustomField7">VALUE</string-field>
           <string-field name="CustomField8">VALUE</string-field>
           <string-field name="CustomField9">VALUE</string-field>
           <string-field name="CustomField10">VALUE</string-field>
           -->
         </extended-fields>
    

11. Save your changes after making the updates.

12. Open the custom_updateEvent_request.xsl file and make the same changes for the custom fields. In this case, you cannot set the alert name because it is only valid for creates.

13. Save your changes after making the updates.

14. To set up for testing, create the create.xml and update.xml files and open in a text editor.

15. Copy the contents of the XML document in the “Create Sample” section of Appendix B into the create.xml file and save.

16. Copy the contents of the XML document in the “Update Sample” section of Appendix B into the update.xml file and save.

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

18. Examine the output XML document and verify the results are correct.

    Note:

    You can also use an XML client to send the XML output document to the SCOM web service to verify that it is a format accepted by the web service.

19. If the XML document has problems, make any necessary corrections and repeat steps 17 and 18.

20. At the OMS server system, run the following command to reregister your customized createEvent template.

    emctl register_template connector
    -t /home/oracle/customized_templates/custom_createEvent_request.xsl
    -repos_pwd sysmanpass
    -cname "SCOM R2"
    -iname "createEvent"
    -tname "Create Event Request"
    -ttype 2
    -d " This is the customized request xsl file for the createEvent method"
    

21. At the OMS server system, run the following command to reregister your customized updateEvent template.

    emctl register_template connector
    -t /home/oracle/customized_templates/custom_updateEvent_request.xsl
    -repos_pwd sysmanpass
    -cname "SCOM R2"
    -iname "updateEvent"
    -tname "Update Event Request"
    -ttype 2
    -d " This is the customized request xsl file for the updateEvent method"