1. Microsoft Systems Center Operations Manager (SCOM) Connector Installation and Configuration Guide
  2. Working With Event Templates

5 Working With Event Templates

This chapter provides details on the default event templates shipped along with the SCOM connectors. The event templates specify the mappings between an Enterprise Manager event attributes and SCOM web service attributes:

Note:

Unless otherwise noted, these instructions apply to the SCOM 2012 connector and to the SCOM 2007 connectors. Instructions specific to the SCOM 2007 connectors are available in Microsoft SCOM 2007 Connector.

Familiarization with Event Templates

This section describes the default mappings between the Enterprise Manager event data fields and the Microsoft SCOM alert data fields.

Topics

Default Templates

The event templates 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 Microsoft SCOM Event Connector. To extract the installation file, perform the steps in Exporting the Template Files.

Table 5-1 lists the XSL files that perform the mappings for the SCOM 2012 connector and provides a summary of each. Table E-1 lists the XSL files that perform the mappings for the SCOM 2007 connectors and provides a summary of each.

Table 5-1 XSL Files that Perform SCOM 2012 Mappings

File Description

createEvent_request_2012.xsl

Transforms the Oracle Enterprise Manager event data to the Microsoft SCOM 2012 alert format for the createEvent operation.

updateEvent_request_2012.xsl

Transforms the Oracle Enterprise Manager event data to the Microsoft SCOM 2012 alert format for the updateEvent operation.

updateEvent_request_2012_alt.xsl

Alternate template that transforms the Oracle Enterprise Manager event data to the Microsoft SCOM 2012 alert format for the updateEvent operation. This template causes the connector to create a new alert in SCOM 2012 each time a status change occurs in Enterprise Manager.

The following sections provide details about the default templates:

Create Event Template

This section identifies the default create mappings for the SCOM 2012 connector. To see the default create mappings for the SCOM 2007 connectors, refer to section Create Event 2007 Template in Microsoft SCOM 2007 Connector.

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 2012 connector. The createEvent_request_2012.xsl template is invoked during the process to transform the data from Oracle Enterprise Manager format to SCOM 2012 alert format.Table 5-2 lists the default field mappings between the Microsoft SCOM alert and the Oracle Enterprise Manager event and the Microsoft SCOM 2012 alert.

Table 5-2 Create Event Template Mappings

SCOM Field Name Required Value

Name

Yes

Set to the event EventName field.

Description

Yes

Set to the formatted contents of the event as specified in Formatted Enterprise Manager Description Contents.

Priority

Yes

Set the priority based on the event priority. See Priority Mapping for details.

Severity

Yes

Set the severity based on the event severity. See Severity Mapping for details.

Alert History

No

Set to the formatted contents of the event as specified in Formatted Alert History Create Contents.

Update Event Template

This section identifies the default update mappings for the SCOM 2012 connector. To see the default update mappings for the SCOM 2007 connectors, refer to Update Event 2007 Template in Microsoft SCOM 2007 Connector.

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 2012 connector.

Example 5-1 Default Template

If the updateEvent operation is configured to use the default template, the updateEvent_request_2102.xsl template is invoked during the process to transform the data from Oracle Enterprise Manager format to SCOM 2012 alert format.Table 5-3 lists the default field mappings between the Microsoft SCOM alert and the Oracle Enterprise Manager event and the Microsoft SCOM 2012 alert.

Table 5-3 Update Event Template Mappings

SCOM Field Name Required Value

ID

Yes

Set to the event ExternalEventId field.

Resolution State

Yes

Set to 255 (Closed) if the event severity is Clear. Otherwise, set to 0 (New).

Alert History

No

Set to "Oracle Enterprise Manager cleared alert" if the event severity is Clear.

Set to "Oracle Enterprise Manager changed alert severity to warning" if the event severity is Warning.

Set to "Oracle Enterprise Manager changed alert severity to critical" if the event severity is Critical.

Not set for other severity values.

Example 5-2 Alternate Template

If the updateEvent operation has been reconfigured to use the alternate template, the updateEvent_request_2012_alt.xsl template is invoked during the process to transform the data from Oracle Enterprise Manager format to SCOM 2012 alert format.

Table 5-4 lists the default field mappings between the Oracle Enterprise Manager event and the Microsoft SCOM 2012 alert when the status is clear.

Table 5-5 lists the default field mappings between the Oracle Enterprise Manager event and the Microsoft SCOM 2012 alert for all other status values.

Table 5-4 Clear Event Alternate Template Mappings

SCOM Field Name Required Value

ID

Yes

Set to the event ExternalEventId field.

Resolution State

Yes

Set to 255 (Closed).

Alert History

No

Set to "Oracle Enterprise Manager cleared alert"

Table 5-5 Update Event Alternate Template Mappings

SCOM Field Name Required Value

Name

Yes

Set to the event EventName field.

Description

Yes

Set to the formatted contents of the event as specified in Formatted Enterprise Manager Description Contents.

Priority

Yes

Set the priority based on the event priority. SeePriority Mapping for details.

Severity

Yes

Set the severity based on the event severity. SeeSeverity Mapping for details.

Alert History

No

If the synchronization feature is enabled, entries will be added to the history log for all events leading up to and including the update. The original create entry will be formatted as specified in Formatted Alert History Create Contents. Each update entry will be formatted as specified in Formatted Alert History Update Contents.

If the synchronization feature is disabled, an entry will be added to the alert history log that is formatted as specified in Formatted Alert History Update Contents.

Formatted Enterprise Manager Description 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>
Event 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.

  • Event 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.

Formatted Alert History Create Contents

Listed below is the format used by the templates for the Alert History field for createEvent operations. 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 Note section below contains information about some of the fields. 

Oracle Enterprise Manager created an event with the following attributes:
Message: <Message>
Severity: <Severity>
Reported Date: <ReportedDate>
Occurred Date: <OccurredDate>
Target Name: <SourceInfo/TargetInfo/TargetName>
Target Type: <SourceInfo/TargetInfo/TargetType>
Event Class: <EventClass>
Event Name: <EventName>
Event URL: <EventURL>

Target Properties:**
    <TargetProperty/Name>: <TargetProperty/Value>**

Event Context:**
    <EventContextAttributes/StringAttribute/Name>: < EventContextAttributes/StringAttribute /Value>**

Note:

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

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

Formatted Alert History Update Contents

Listed below is the format used by the templates for the Alert History field for updateEvent operations. The Title used is specified in Alert History Title. Text delimited by angle brackets (< and >) designates an Enterprise Manager Event field name that will be replaced by the actual field contents. 

Title
Reported Date: <ReportDate>
Message: <Message>
Severity: <Severity>
Alert History Title

Table 5-6 shows the title that is specified for the Alert History field for updateEvent operations. The value used is based on the severity specified in the Enterprise Manager event information.

Table 5-6 Alert History Titles

Event Severity Title

Clear

Oracle Enterprise Manager cleared event.

Warning

Oracle Enterprise Manager changed event severity to Warning.

Critical

Oracle Enterprise Manager changed event severity to Critical.

All Others

No title is specified.

Severity Mapping

The SCOM alert severity is set based on the Enterprise Manager event severity value. The following table shows the values used when creating the alert in SCOM.

When the event severity is … Set the alert severity to …

Fatal

Error

Critical

Error

Warning

Warning

Minor Warning

Warning

Informational

Information

Clear

Information

Priority Mapping

The SCOM alert priority is set based on the Enterprise Manager event priority value. The following table shows the values used when creating the alert in SCOM.

When the event priority is ... Set the alert priority to …
Fatal High
Critical High
Warning Normal
Minor Warning Normal
Informational Low
Clear Low

Customizing Event Templates

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 SCOM mappings, see Customizing Microsoft SCOM.

XML Format of Oracle Enterprise Manager Events

The sample below shows the format that the Oracle Enterprise Manager Connector Framework provides when an event is created or updated in Oracle Enterprise Manager. For a description of the fields, see Field Descriptions for XML Format of Events.

Example 5-3 XML Format of Events

<EMEvent xmlns="http://xmlns.oracle.com/sysman/connector">
   <ConnectorGUID/>
   <ExternalEventID/>
   <NotificationRuleOwner/>
   <NotificationRuleName/>
   <ConnectorVariable>
      <VariableName/>
      <VariableValue/>
   </ConnectorVariable>
   <ConnectorVariable>
      <VariableName/>
      <VariableValue/>
   </ConnectorVariable>
   <Property>
      <Name/>
      <Value/>
   </Property>
   <Property>
      <Name/>
      <Value/>
   </Property>
   <SystemAttributes>
      <EventClass/>
      <EventID/>
      <SequenceID/>
      <OccurredDate/>
      <ReportedDate/>
      <DisplayTZ/>
      <EventName/>
      <Severity/>
      <SeverityCode/>
      <SourceInfo>
         <SourceObjInfo>
            <ObjID/>
            <ObjName/>
            <ObjOwner/>
            <SourceObjType/>
            <SourceObjSubType/>
         </SourceObjInfo>
         <TargetInfo>
            <TargetGUID/>
            <TargetName/>
            <TargetType/>
            <TargetTypeLabel/>
            <TargetURL/>
            <TargetProperty>
               <Name/>
               <Value/>
            </TargetProperty>
            <TargetProperty>
               <Name/>
               <Value/>
            </TargetProperty>
         </TargetInfo>
      </SourceInfo>
      <Message/>
      <ActionMessage/>
      <EventURL/>
      <AutoClose/>
      <EventCategory/>
      <EventCategory/>
   </SystemAttributes>
   <EventClassSpecificAttributes>
      <RawAttribute>
         <Name/>
         <Value/>
      </RawAttribute>
      <StringAttribute>
         <Name/>
         <Value/>
      </StringAttribute>
   </EventClassSpecificAttributes>
   <EventContextAttributes>
      <NumberAttribute>
         <Name/>
         <Value/>
      </NumberAttribute>
      <NumberAttribute>
         <Name/>
         <Value/>
      </NumberAttribute>
   </EventContextAttributes>
</EMEvent>

Field Descriptions for XML Format of Events

Table 5-7 provides a description of the key fields shown in XML Format of Oracle Enterprise Manager Events that are used in the default mappings:

Table 5-7 Field Descriptions for XML Format of Events

Field Description

ExternalEventId

Unique identifier of the message in Microsoft SCOM. 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

TargetName

Target name that is a unique instance of the target type

TargetType

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)

Managing Templates in Oracle Enterprise Manager

Oracle Enterprise Manager 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.

Using Enterprise Manager, you can edit a template, view the XML code, delete a template, and restore a deleted template.

To begin:

  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 appropriate Microsoft SCOM connector. Click Configure.
  4. On the Configure Management Connector page, click the Template tab.
Edit a Template with Enterprise Manager
To edit an existing template:
  1. Select a template and click Edit.
  2. After you edit the Description or Template Contents fields, click Save. On the confirmation page, click Yes to complete the template save.
Viewing Template Code in Enterprise Manager
To view template code, select a template and click View.
The event templates are in XSLT format. A basic knowledge of XSLT is required to understand the code.
Deleting a Template with Enterprise Manager
To delete a template:
  1. Select a template and click Delete.
  2. Click Yes to confirm the delete operation.
WARNING! Once you delete a default template you will no longer be able to restore to the default settings. Once deleted, the only way to reregister a template is using the emctl command as specified in Registering Templates.
Restoring an Updated Template with Enterprise Manager
To restore an updated template:
  1. Select a template and click Restore.
  2. Click Yes in the confirmation page that appears in order to restore.

Changing a Mapping

This section explains how to customize the mapping between Enterprise Manager and the Microsoft SCOM web service. The procedure provides the steps required for changing a mapping.

To change a mapping:
  1. 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.
  2. Create a file that holds the customized template:

    • If the template being customized is available in the Enterprise Manager Cloud Control console, then perform the following steps to get the template data:

      1. Follow the steps in Viewing Template Code in Enterprise Manager to view the data for the template being customized.

      2. Select the template contents and copy.

      3. Create an empty text file to hold the template contents.

      4. Paste the template contents into the file and save.

    • If the template you want to customize is not available from the console, you will need to perform the following steps to export the template data. You will need to do this if you are using the alternate template:

      1. Follow the instructions inExporting the Template Files to obtain copies of the default template files.

      2. Copy the template XSL file being customized to a new file name.

  3. Make the desired mapping changes to the custom file. See Modifying Templates for guidance on mapping changes.
  4. Update the existing template using the contents of the custom template file. Perform the following steps to update the template:
    1. Follow the steps in Edit a Template with Enterprise Manager to edit the data for the template being customized.
    2. Open the custom template file in a text editor.
    3. Copy the contents of the file.
    4. Paste the contents over the existing template contents in the Enterprise Manager Cloud Control console and save.
The files are now ready for integration. You do not need to stop and start OMS. The changes will automatically be picked up.

See Template Customization Example for an example of how to customize templates.

For information on customizing SCOM, see Customizing Microsoft SCOM.

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 web service. The output XML document must conform to the data format specified in the SCOM EventService WSDL.

Enterprise Manager Event Format contains details on the format of the event data generated by Enterprise Manager. Microsoft 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 Microsoft SCOM Web Service WSDL Format to identify the names of the fields in the SCOM web service 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 web service 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 Enterprise Manager Event Format to identify the field(s) you want to use in the mapping. Enterprise Manager Event Samples has sample transactions that are 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 Enterprise Manager Event Samples. This will require a utility that performs XSLT translations.
Registering Templates

This section documents how to register connectors using the emctl command line command. Since new templates cannot be defined for event connectors, the only reason you would need this command is to reregister a default connector that was deleted from the Enterprise Manager Cloud Control console.

This command can also be used to update an existing template, but the recommended method of updating a template is through the Cloud Control console as specified in Edit a Template with Enterprise Manager.

To register a 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 (Super Administrator) 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: This command could be used to reregister the createEvent template for the connector instance with the name of SCOM 2012:
emctl register_template connector -t /home/oracle/customized_templates/createEvent_request.xml -repos_pwd <password> -cname "SCOM 2012" -iname "createEvent" -tname "Create Event Request" -ttype 2 -d "Demo template"
Template Customization Example

By default, the alert name in the Microsoft SCOM 2012 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.

  1. Navigate to the SCOM 2012 connector configuration page.
  2. Go to the Template tab.
  3. Select the Create Event Request template and click View.
  4. Select the template contents and copy.
  5. Click OK.
  6. Create an empty file named custom_createEvent_request_2012.xsl.
  7. Open the file in a text editor then paste the template contents and save.
  8. At the Cloud Control console, select the Update Event Request template and click View.
  9. Select the template contents and copy.
  10. Create an empty file named custom_updateEvent_request_2012.xsl.
  11. Open the file in a text editor then paste the template contents and save.
  12. Open the custom_createEvent_request_2012.xsl file in your text editor.
  13. 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:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetType"/>
       </string-field>
       <string-field name="CustomField2">
         <xsl:value-of select="a:SystemAttributes/a:SourceInfo/a:TargetInfo/a:TargetName"/>
       </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>
  14. Save your changes after making the updates.
  15. Open the custom_updateEvent_request_2012.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.
  16. Save your changes after making the updates.
  17. To set up for testing, create the empty files named create.xml and update.xml and open in a text editor.
  18. Copy the contents of the XML document in Create Sample into the create.xml file and save.
  19. Copy the contents of the XML document in Update Sample into the update.xml file and save.
  20. 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.
  21. 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.

  22. If the XML document has problems, make any necessary corrections and repeat steps 17 and 18.
  23. At the Cloud Control console, edit the Create Event Request template.
  24. Copy the contents of the custom_createEvent_request_2012.xsl file over the existing template and save.
  25. At the Cloud Control console, edit the Update Event Request template.
  26. Copy the contents of the custom_updateEvent_request_2012.xsl file over the existing template and save.