This chapter explains how to change default mappings and default port numbers. This chapter discusses the following topics:
Although the default mappings are sufficient for most implementations, you can change them as needed. The following sections discuss:
Note:
It is assumed that you already have a good understanding of XSL.For reference information on the default mappings, see Appendix A, "Default Mappings."
Example 4-1 represents the format that the IBM Netcool/OMNIbus web service expects for creating new events in IBM Netcool/OMNIbus. The format for update requests is the same, except the root node would be update instead of create.
Example 4-1 Sample Format for IBM Netcool/OMNIbus Web Service
<iwaveaf:create xmlns:iwaveaf="http://iwavesoftware.com/services/
adapter-framework">
<event>
<description></description>
<severity></severity>
<status></status>
<repeatCount></repeatCount>
<createDate></createDate>
<eventClass>
<name>Host</name>
</eventClass>
<source>
<name>OracleEnterpriseManager</name>
<computerName>Host</computerName>
</source>
<object>
<displayName></displayName>
<computerName></computerName>
</object>
<repeatCount>0</repeatCount>
<createDate></createDate>
<group>
<name>PrimaryServer</name>
</group>
<extended-fields>
<string-field name="action_flag">CREATE</string-field>
<string-field name="ext_id"></string-field>
<string-field name="sub_source">OracleEnterpriseManager</string-field>
<string-field name="sub_origin">OracleEnterpriseManager</string-field>
</extended-fields>
</event>
</iwaveaf:create>
Table 4-1 identifies the mappings between the IBM Netcool/OMNIbus base event slot names and the XML format that the IBM Netcool/OMNIbus web services uses. The XML document presented to the IBM Netcool/OMNIbus web service must have the corresponding fields set. This must be handled in the appropriate translation file identified in Table A-1, "XSL Files that Perform Mappings".
Table 4-1 Event Attributes and XML Path Mappings
| IBM Netcool/OMNIbus Slot Names | XML Path |
|---|---|
|
Identifier |
|
|
Node |
|
|
NodeAlias |
|
|
AlertGroup |
|
|
AlertKey |
|
|
Severity |
|
|
Summary |
|
|
Type |
|
|
All other slot names |
See Extended Fields below. |
Extended fields pass information for slots that are not mapped. An extended field is defined as a <string-field/> element that is a child of the extended-fields node. The name of the slot is specified in the name attribute, and the value of the slot is specified in the value attribute.
Example 4-2 shows the format that the Oracle Enterprise Manager Connector Framework provides when an alert is created or updated in Oracle Enterprise Manager.
Example 4-2 XML Format of Alerts
<EMEvent>
<EventGuid/>
<ExternalEventId/>
<ViolationId/>
<TargetType/>
<TargetName/>
<MetricName/>
<MetricColumn/>
<KeyValues/>
<Message/>
<Severity/>
<SeverityCode/>
<CollectionTime/>
<EventPageURL/>
<EMUser/>
<NotificationRuleName/>
<TargetHost/>
<TargetTimezone/>
<Property>
<Name/>
<Value/>
</Property>
</EMEvent>
Table 4-2 provides a description of the fields shown in Example 4-2.
Table 4-2 Field Descriptions for XML Format
| Field | Description |
|---|---|
|
|
Unique identifier of the alert in Oracle Enterprise Manager. |
|
|
Unique identifier of the event in IBM Netcool/OMNIbus. This will only be set for updates. |
|
|
Time the alert was generated. |
|
|
Target type for which the alert was generated. |
|
|
Target name that is a unique instance of the target type. |
|
|
Name of the metric that was violated. |
|
|
Column under the metric that was violated. |
|
|
Key values associated with the metric column that was violated. |
|
|
Severity text assigned to the alert. |
|
|
Severity numeric code assigned to the alert. |
|
|
User that owns the rule that generated the alert. |
|
|
Name of the notification rule that caused the alert to be forwarded to IBM Netcool/OMNIbus. |
|
|
Link to the web page for the alert. |
|
|
Description of the alert. |
|
|
Host name of the system where the target resides. |
|
|
Time zone of the system where the target resides. |
|
|
Additional properties that do not have a specific field in the alert model. |
This section explains how to customize the mapping between Enterprise Manager and the IBM Netcool/OMNIbus web service. The procedure provides the steps required for changing a mapping. Following this procedure, an example is provided that shows how to change the mapping of the target type and target name fields.
Study the default mapping and determine the changes you want to make. See Appendix A for details about the default mappings and the files that define the mapping for the different Enterprise Manager operations.
Create a back-up copy of the XSL file you want to change.
Open the XSL file in a text editor or in an XSLT editor.
Change the file to map the fields as determined in step 1. You might need to study the information in XML Format of IBM Netcool/OMNIbus Events and Mappings Between XML Format and Event Field Names. These sections describe the data formats of the IBM Netcool/OMNIbus events and Oracle Enterprise Manager alerts.
Save your changes.
Rerun the register command for the template that was modified to pick up the changes. See Registering Templates for details.
The files are now ready for integration. You do not need to stop and start OMS. The changes will automatically be picked up.
By default, the origin slot in the IBM Netcool/OMNIbus event is set to the Oracle Enterprise Manager target type, and the sub_origin slot is set to the target name. The following example shows how to change the value where the target type and name information is placed in Netcool/OMNIbus. In this example, the target_type and target_name slots were added to the class definition to contain this information.
The changes made to the default mapping are as follows:
The origin slot is modified to use a hard-coded value of Oracle Enterprise Manager.
The sub_origin slot is not set to any value.
The new target_type slot is set to the Oracle Enterprise Manager target type.
The new target_name slot is set to the Oracle Enterprise Manager target name.
Make a back-up copy of the createEvent_request.xsl file and name it default_createEvent_request.xsl.
Make a backup copy of the updateEvent_request.xsl file and name it default_updateEvent_request.xsl.
Open the createEvent_request.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.
<source>
<!-- OMNIbus slot = source -->
<name>OracleEnterpriseManager</name>
<!-- OMNIbus slot = origin -->
<computerName>
<xsl:value-of select="a:TargetType"/>
</computerName>
</source>
…
<extended-fields>
<!-- OMNIbus fields that are not mapped to the common object model -->
<string-field name="action_flag">CREATE</string-field>
<string-field name="ext_id">
<xsl:value-of select="a:EventGuid"/>
</string-field>
<string-field name="sub_source">OracleEnterpriseManager</string-field>
<string-field name="sub_origin">
<xsl:value-of select="a:TargetName"/>
</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:
<source> <!-- OMNIbus slot = source --> <name>OracleEnterpriseManager</name> <!-- OMNIbus slot = origin --> <computerName>Oracle Enterprise Manager</computerName> </source> … <extended-fields> <!-- OMNIbus fields that are not mapped to the common object model --> <string-field name="action_flag">CREATE</string-field> <string-field name="ext_id"> <xsl:value-of select="a:EventGuid"/> </string-field> <string-field name="sub_source">OracleEnterpriseManager</string-field> <string-field name="target_type"> <xsl:value-of select="a:TargetType"/> </string-field> <string-field name="target_name"> <xsl:value-of select="a:TargetName"/> </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.
Run the following register command for the template that was modified to enable OMS to pick up the changes:
emctl register_template connector -t $OMS_HOME/sysman/connector/OMNIBUS_Connector/createEvent_request.xsl -repos_pwd testPass -ctname "OMNIBUS Connector" -cname "OMNIBUS Connector" -tname "Create Event Request" -iname "createEvent" -ttype 2 -d "This is the request xsl file for createEvent method"
In most cases, you can use the default port numbers that the IBM Netcool/OMNIbus web service uses. However, if there are any conflicts with existing applications, you need to change the port numbers.
8080 is the default port number for HTTP communication, and 8443 is the default port for HTTPS communication. To change the port number, perform the following steps on the system where the IBM Netcool/OMNIbus web services are installed. Replace
<OMNIBUSWS_INSTALL> with the directory where the IBM Netcool/OMNIbus web services are installed.
Open a command prompt window and change the working directory to:
<OMNIBUSWS_INSTALL>/adapters/conf
Enter the following command to configure the web service to connect to the IBM Netcool/OMNIbus Agent:
../bin/propertiesEditor.bat -p services.url=<prot>://localhost:<newPort>/ services framework.properties
Where <prot> is the protocol (HTTPS or HTTPS) and <newPort> is the new port number.
The propertiesEditor.bat script is specifically for the Windows platform. The equivalent script for Unix platforms is propertiesEditor.sh.
Make a backup copy of the framework.properties file.
Open the framework.properties file with a text editor and replace all references to the old port number with the new port number, then save the file.
Note:
If the old port number is 8443, you will not find any references to the old port number.Change the working directory to ../bin.
Enter the following command to restart the IBM Netcool/OMNIbus web service:
If the web service is installed on a Unix system:
./service.sh restart
If the web service is installed on a Windows system as a standalone application, close the window where the adapter was running, then run:
startAdapters.bat
If the web service is installed on a Windows system as a Windows service, enter the following commands:
net stop iWaveAdapters net start iWaveAdapters
Perform the following steps to change the URL the Netcool/OMNIbus connector is using:
Log in to the Oracle Enterprise Manager console by entering a user name with a "Super Administrator" role, entering the appropriate password, then clicking Login.
Click the Setup link at the top right part of the window. The Overview of Setup page appears.
Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.
Click on the Configure icon associated with the Netcool/OMNIbus Connector. This invokes edit mode, enabling you to configure the connector.
Change the URLs listed in the Web Service End Points section to use the new port number.
Click OK to save your changes.