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 adapter 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 Appendix E, "SCOM 2007 Connector".This section describes the default mappings between the Enterprise Manager event data fields and the Microsoft SCOM alert data fields.
This section discusses the following topics:
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 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 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 |
|---|---|
|
|
Transforms the Oracle Enterprise Manager event data to the Microsoft SCOM 2012 alert format for the |
|
|
Transforms the Oracle Enterprise Manager event data to the Microsoft SCOM 2012 alert format for the updateEvent operation. |
|
|
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:
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 Appendix E.
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. |
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 Appendix E.
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.
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. |
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 |
|
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. See Priority Mapping for details. |
|
Severity |
Yes |
Set the severity based on the event severity. See Severity 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. |
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>**
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.
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 Notes 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>**
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.
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: <ReportedDate> Message: <Message> Severity: <Severity>
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.
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 |
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 |
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 Appendix A, "Customizing Microsoft SCOM".
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">
<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>
Table 5-7 provides a description of the key fields shown in Example 5-1 that are used in the default mappings.
Table 5-7 Field Descriptions for XML Format
| 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) |
Oracle Enterprise Manager 12c (Release 12.1.0.2 and later) 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.
If you need to use new a template that is not included as part of the connector installation, then you will need to register it using the emctl command. See Changing a Mapping for more information. Once you have registered the template, you will be able to manage it through Enterprise Manager.
Using Enterprise Manager, you can edit a template, view the XML code, delete a template, and restore a deleted template.
To begin:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the appropriate Microsoft SCOM connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Note:
This feature is available on Oracle Enterprise Manager Release 12.1.0.2.0 or later only. To verify your installed release version:Log in to Enterprise Manager.
From the Help menu, select About Cloud Control.
The pop-up window displays the installed version of Oracle Enterprise Manager.
To edit an existing template:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the appropriate Microsoft SCOM connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click Edit.
After you edit the Description or Template Contents fields, click Save. On the confirmation page, click Yes to complete the template save.
To view template code:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the appropriate SCOM connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click View.
The event templates are in XSLT format. A basic knowledge of XSLT is required to understand the code.
To delete a template:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the appropriate SCOM connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click Delete.
Click Yes to confirm the delete operation.
To restore a deleted template:
Log in to Enterprise Manager Cloud Control.
From the Setup menu, select Extensibility, then Management Connectors.
On the Management Connectors page, select the appropriate SCOM connector. Click Configure.
On the Configure Management Connector page, click the Template tab.
Select a template and click Restore.
Click Yes in the confirmation page that appears in order to restore.
Note:
You can restore out-of-box templates that you may have edited or customized to their default values. You cannot restore new templates that you have created (using theemctl register_template command) described in Registering Templates.This section explains how to customize the mapping between Enterprise Manager and the Microsoft SCOM adapter web service. The procedure provides the steps required for changing 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.
Copy the XSL file you want to change to a new file to hold the custom template.
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.
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 Appendix A, "Customizing Microsoft SCOM".
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 adapter EventService web service. Mappings Between XML Format and Alert Field Names in Appendix A provides the mapping between the SCOM adapter EventService web service fields and the field names in SCOM. Listed below are the steps you should follow to modify the template file.
Review Mappings Between XML Format and Alert Field Names in Appendix A and SCOM Web Service WSDL Format in Appendix D 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.
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 are 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.
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.
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 (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 updates 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"
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.
Navigate to the Management Connector Updates page and export the SCOM 2012 Connector. Copy the first emcli 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 machine and change the working directory to the temporary directory.
cd /home/oracle/customized_templates
Log into emcli.
emcli login -username=<Super Administrator>
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
Extract the connector jar file from the zip file.
unzip *.zip archives/*connector.jar
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_2012.xsl updateEvent_request_2012.xsl updateEvent_request_2012_alt.xsl
Make a copy of the createEvent_request_2012.xsl file and name it custom_createEvent_request_2012.xsl.
Make a copy of the updateEvent_request_2012.xsl file and name it custom_updateEvent_request_2012.xsl
Open the custom_createEvent_request_2012.xsl file in your text editor.
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>
Save your changes after making the updates.
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.
Save your changes after making the updates.
To set up for testing, create the empty files named create.xml and update.xml and open in a text editor.
Copy the contents of the XML document in Section B.1, "Create Sample" into the create.xml file and save.
Copy the contents of the XML document in Section B.2, "Update Sample" into the update.xml file and save.
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 the results are correct.
Note:
You can also use an XML client to send the XML output document to the SCOM adapter 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 17 and 18.
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_2012.xsl -repos_pwd <Super Administrator>pass -cname "SCOM 2012" -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 reregister your customized updateEvent template.
emctl register_template connector -t /home/oracle/customized_templates/custom_updateEvent_request_2012.xsl -repos_pwd <Super Administrator>pass -cname "SCOM 2012" -iname "updateEvent" -tname "Update Event Request" -ttype 2 -d " This is the customized request xsl file for the updateEvent method"