This chapter explains how to change default mappings and default port numbers. This chapter discusses the following topics:
Customizing Mappings
Changing Default Port Numbers
Although the default mappings are sufficient for most implementations, you can change them as needed. The following sections discuss:
XML Format of HP OpenView Operations Messages
XML Format of Oracle Enterprise Manager Alerts
Changing a Mapping
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 HP OpenView Operations web service expects for creating new messages in HP OpenView Operations. The format for update requests is the same, except the root node would be update instead of create.
Example 4-1 Sample Format for HP OpenView Operations Web Service
<iwaveaf:create xmlns:iwaveaf="http://iwavesoftware.com/services/ adapter-framework">
<event>
<summary></summary>
<urgency></urgency>
<resolvedBy></resolvedBy>
<identifier></identifier>
<group>
<name></name>
</group>
<object>
<displayName></displayName>
</object>
<source>
<computerName></computerName>
</source>
<extended-fields>
<string-field value="Oracle Enterprise Manager" name="application"/>
<string-field value="NONE" name="ovo_ts_field"/>
<!-- CMA fields go here -->
<!-- The name attribute should be set to the name of the CMA field to <!-- populate -->
<!-- The value attribute should be set to the value to place in the CMA <!-- field -->
<!-- <string-field value="" name=""/> -->
</extended-fields>
</event>
</iwaveaf:create>
Table 4–1 identifies the mappings between the HP OpenView Operations message field names and the XML format that the HP OpenView Operations web services uses. To set the HP OpenView Operations message attributes, the XML document presented to the HP OpenView Operations web service must have the corresponding fields set. This must be handled in the appropriate translation file identified in Table A–1.
Table 4-1 Message Attributes and XML Path Mappings
| HP OpenView Operations Message Attributes | XML Path |
|---|---|
|
Identifier |
/create/event/identifier |
|
Message Text |
/create/event/summary |
|
Severity |
/create/event/urgency |
|
Message Group |
/create/event/group/name |
|
Object |
/create/event/object/displayName |
|
Node |
/create/event/source/computerName |
|
Application |
See "Extended Fields" below. |
|
ResolvedBy |
/create/event/resolvedBy |
|
CMA Fields |
See "Extended Fields" below. |
An extended field is defined as a <string-field/> element that is a child of the extended-fields node. The name of the extended field is specified in the name attribute, and the value of this field is specified in the value attribute.
Some reserved extended field names are handled differently. The reserved field names are listed below along with a description of how they are handled.
application — Reserved for the HP OpenView Operations application attribute. The specified value for this field is used to set the application field when creating or updating an HP OpenView Operations message.
disown — Used to change the behavior of the HP OpenView Operations Agent. By default, the HP OpenView Operations account used to create the message is left as the owner. By setting this field to true, the message is disowned after it is created.
ovo_ts_field — Used to prevent transaction loopback, and should always be set to NONE.
Any other extended field name you specify adds a Custom Message Attribute (CMA) field to the message. You specify the name of the CMA field for the Name attribute, and you specify the value for the Value attribute.
Note:
Adding CMA fields causes overhead. Attempting to add a large number of CMA fields can affect performance somewhat.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 |
|---|---|
|
EventGuid |
Unique identifier of the alert in Oracle Enterprise Manager. |
|
ExternalEventId |
Unique identifier of the message in HP OpenView Operations. This will only be set for updates. |
|
CollectionTime |
Time the alert was generated. |
|
TargetType |
Target type for which the alert was generated. |
|
TargetName |
Target name that is a unique instance of the target type. |
|
MetricName |
Name of the metric that was violated. |
|
MetricColumn |
Column under the metric that was violated. |
|
KeyValues |
Key values associated with the metric column that was violated. |
|
Severity |
Severity text assigned to the alert. |
|
SeverityCode |
Severity numeric code assigned to he alert. |
|
EMUser |
User that owns the rule that generated the alert. |
|
NotificationRuleName |
Name of the notification rule that caused the alert to be forwarded to HP OpenView Operations. |
|
EventPageURL |
Link to the web page for the alert. |
|
Message |
Description of the alert. |
|
TargetHost |
Host name of the system where the target resides. |
|
TargetTimezone |
Time zone of the system where the target resides. |
|
Property |
Additional properties that do not have a specific field in the alert model. |
The following procedure provides the steps required for changing a mapping. Following this procedure below, an example is provided to more fully illustrate the procedure.
Study the default mapping and determine the changes you want to make.
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 Section 4.1.1 and Section 4.1.2. These sections describe the data formats of the HP OpenView Operations messages and Oracle Enterprise Manager alerts.
Save your changes.
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 Application field in the HP OpenView Operations message is set to the Oracle Enterprise Manager target type, and no CMA fields are defined. The example procedure below shows how to change the value assigned to the Application field to a different value. The example also shows how to add a CMA field.
The changes made to the default mapping are as follows:
The Application field is modified to use a hard-coded value of Oracle Enterprise Manager.
A new CMA field named TargetType is added to contain the TargetType associated with the Oracle Enterprise Manager alert.
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 Extended Fields section to reflect the new mapping.
Before Changes
The code below shows the Extended Fields section in the file before the changes.
<extended-fields>
<!-- The extended fields section contains any fields that are not <!-- defined in the event model -->
<!-- BEGIN RESERVED FIELDS SECTION -->
<!-- The fields defined in this section are reserved and have <!-- special meaning -->
<!-- The application field is mapped to the OVO Application <!-- field -->
<string-field name="application">
<xsl:attribute name="value">
<xsl:value-of select="a:TargetType"/>
</xsl:attribute>
</string-field>
<!-- The ovo_ts_field node must always be set to NONE -->
<string-field value="NONE" name="ovo_ts_field"/>
<!-- The following extended field is used to disown the alert in <!-- OVO after it is created -->
<!-- By default, the ovo user account used to create the alert <!-- will be left as the owner -->
<!-- To force it to disown it after it is created, uncomment the <!-- following line and comment out the next line -->
<!-- <string-field value="true" name="disown"/> -->
<string-field value="true" name="own"/>
<!-- END RESERVED FIELDS SECTION -->
<!-- BEGIN CMA FIELDS SECTION -->
<!-- All of the fields that follow will be added as CMA fields <!-- in OVO -->
<!-- CMA field names do not have to be predefined in OVO -->
<!-- To add a CMA field, copy the following line and set the <!-- name and value attributes -->
<!-- Set the name attribute to the name of the CMA field <!-- to add -->
<!-- Set the value attribute to the value to assign <!-- the CMA field -->
<!--
<string-field value="" name=""/>
-->
<!-- END CMA FIELDS SECTION -->
</extended-fields>
After Changes
The code below shows the Extended Fields section in the file after the changes. The changes are shown in bold italics.
<extended-fields>
<!-- The extended fields section contains any fields that are not <!-- defined in the event model -->
<!-- BEGIN RESERVED FIELDS SECTION -->
<!-- The fields defined in this section are reserved and have <!-- special meaning -->
<!-- The application field is mapped to the OVO Application <!-- field -->
<string-field value=”Oracle Enterprise Manager” name="application"/>
<!-- The ovo_ts_field node must always be set to NONE -->
<string-field value="NONE" name="ovo_ts_field"/>
<!-- The following extended field is used to disown the alert in <!-- OVO after it is created -->
<!-- By default, the ovo user account used to create the alert <!-- will be left as the owner -->
<!-- To force it to disown it after it is created, uncomment the <!-- following line and comment out the next -->line
<!-- out the next line -->
<!-- <string-field value="true" name="disown"/> -->
<string-field value="true" name="own"/>
<!-- END RESERVED FIELDS SECTION -->
<!-- BEGIN CMA FIELDS SECTION -->
<!-- All of the fields that follow will be added as CMA fields <!-- in OVO -->
<!-- CMA field names do not have to be predefined in OVO -->
<!-- To add a CMA field, copy the following line and set the <!-- name and value attributes -->
<!-- Set the name attribute to the name of the CMA field <!-- to add -->
<!-- Set the value attribute to the value to assign <!-- the CMA field -->
<!--
<string-field value="" name=""/>
-->
<string-field name="TargetType">
<xsl:attribute name="value">
<xsl:value-of select="a:TargetType"/>
</xsl:attribute>
</string-field>
<!-- END CMA FIELDS SECTION -->
</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.
In most cases, you can use the default port numbers that the HP OpenView Operations web service uses. However, if there are any conflicts with existing applications, you need to change the port numbers.
The following sections provide procedures on how to change these default port numbers.
9099 is the default port number that the HP OpenView Operations server system uses internally. To change this port number, perform the following steps on the server where you installed the OVOU Agent.
Replace <OVOA_INSTALL> with the directory where the HP OpenView Operations Agent is installed.
Open a command prompt window and change the working directory to:
<OVOA_INSTALL>/ovo-agent/scripts
Enter the following command to stop the HP OpenView Operations Agent:
./stopallbb
You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent. See Section 2.2, "Installing and Running the HP OpenView Operations Agent" on page 2-2 for information about the account that is authorized to stop the Oracle OVO Agent.
Make a backup copy of the following file:
<OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini
Open the file above in a text editor.
Search for the line containing the string ManagementPort=9099.
Change 9099 to the new port number.
Save the file and exit.
Open the following file in a text editor:
<OVOA_INSTALL>/ovo-agent/scripts/setenvbb
Search for the line containing the string export IW_MGMTPORT=9099.
Change 9099 to the new port number.
Enter the following command to start the HP OpenView Operations Agent.
./startallbb
The Oracle OVO Agent will pick up the configuration changes and use the new port number.
9007 is the default port number used for communication between the HP OpenView Operations Agent and the HP OpenView Operations web service. To change this port number, perform the following steps at the HP OpenView Operations server system.
Replace <OVOA_INSTALL> with the directory where the HP OpenView Operations Agent is installed.
Open a command prompt window and change the working directory to:
<OVOA_INSTALL>/ovo-agent/scripts
Enter the following command to stop the HP OpenView Operations Agent. You will be prompted for the credentials to stop the Oracle OVO Agent.
./stopallbb
You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent. See Section 2.2, "Installing and Running the HP OpenView Operations Agent" for information about the account that is authorized to stop the Oracle OVO Agent.
Make a backup copy of the following file:
<OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini
Open the file above in a text editor.
Search for the line containing the AGENTADDR= string.
Change 9007 to the new port number.
Save the file and exit.
Enter the following command to start the HP OpenView Operations Agent.
./startallbb
The Oracle OVO Agent will pick up the configuration changes and use the new port number.
Perform the following steps at the system where the HP OpenView Operations web services are installed. Replace <OVOWS_INSTALL> with the directory where the HP OpenView Operations web services are installed.
Open a command prompt window and change the working directory to:
<OVOWS_INSTALL>/iwave-af-1.1.1/conf
Enter the following command to configure the web service to connect to the HP OpenView Operations Agent ...
../bin/propertiesEditor.bat -p hpovou.xmlagent=<prot>://<OVOserver>:<newPort> spring.properties
... where <prot> is the protocol (HTTP or HTTPS), <OVOserver> is the host name or IP address of the HP OpenView Operations server, 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.
Change the working directory to ../bin.
If the web service is installed on a UNIX system, enter the following command to restart the HP OpenView Operations web service:
./service.sh restart
If the web service is installed on a Windows system, press Ctrl-C in the window where the adapter was running and run the following command to restart the HP OpenView Operations web service:
startAdapters.bat
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 Oracle OVO Agent is installed.
Replace <OVOA_INSTALL> with the directory where the HP OpenView Operations Agent is installed.
Open a command prompt window and change the working directory to:
<OVOA_INSTALL>/ovo-agent/scripts
Enter the following command to stop the HP OpenView Operations Agent. You will be prompted for the credentials to stop the Oracle OVO Agent.
./stopallbb
You must specify the user name and password for the account that is authorized to stop the Oracle OVO Agent. See Section 2.2, "Installing and Running the HP OpenView Operations Agent" on page 2-2 for information about the account that is authorized to stop the Oracle OVO Agent.
Make a backup copy of the following file:
<OVOA_INSTALL>/ovo-agent/bin/sdserverbb.ini
Open the file above in a text editor.
Search for and replace the old port number with the new port number. If the old port number is 8443, you will not find any references to the old port number.
Save the file and exit.
Enter the following command to start the HP OpenView Operations Agent.
./startallbb
The Oracle OVO Agent will pick up the configuration changes and use the new port number.
Perform the following steps at the system where the HP OpenView Operations web services are installed. Replace <OVOWS_INSTALL> with the directory where the HP OVOU web services are installed.
Open a command prompt window and change the working directory to:
<OVOWS_INSTALL>/iwave-af-1.1.1/conf
Enter the following command to configure the web service to connect to the HP OpenView Operations Agent ...
../bin/propertiesEditor.bat -p services.url=<prot>://<hostname>:<newPort>/services spring.properties
... where <prot> is the protocol (HTTP or HTTPS), <hostname> is the host name or IP address of the HP OpenView Operations server, 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 back-up copy of the spring.properties file.
Open the spring.properties file with a text editor and replace all references to the old port number the new port number, then save the file.
Change the working directory to ../bin.
Enter the following command to restart the HP OpenView Operations 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, press Ctrl-C in the window where the adapter was running, then run:
startAdapters.bat
Perform the following steps to change the URL being used by the OVOU connector:
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 HP OVOU 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.