4 Changing Default Configurations

This chapter explains how to change default mappings and change other common configurations. This chapter discusses the following topics:

• Customizing Mappings

• Changing Default Port Numbers

• Changing Web Service Credentials

Customizing Mappings

Although the default mappings are sufficient for most implementations, you can change them as needed. The following sections discuss:

• XML Format of HP Operations Manager 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".

XML Format of HP Operations Manager Messages

Example 4–1 represents the format that the HP Operations Manager web service expects for creating new messages in HP Operations Manager. 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 Operations Manager 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>
          <!-- OMU Application -->
          <string-field name="application">
            <xsl:value-of select="a:TargetType"/>
          </string-field>
          <!-- Do not add CMA data -->
          <string-field name="ovo_ts_field">NONE</string-field>
          <!-- Own the event after it is created -->
          <string-field name="own">true</string-field>
        </extended-fields>

Mappings Between XML Format and Message Field Names

Table 4–1 identifies the mappings between the HP Operations Manager message field names and the XML format that the HP Operations Manager web services uses. To set the HP Operations Manager message attributes, the XML document presented to the HP Operations Manager 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 Operations Manager 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.

Extended Fields

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 as the element value.

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 Operations Manager application attribute. The specified value for this field is used to set the application field when creating or updating an HP Operations Manager message.

• disown — Used to change the behavior of the HP Operations Manager Agent. By default, the HP Operations Manager 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 in the element.

Note: Adding CMA fields causes overhead. Attempting to add a large number of CMA fields can affect performance somewhat.

XML Format of Oracle Enterprise Manager Alerts

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 Operations Manager. 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 Operations Manager.
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.

Changing a Mapping

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.

1. Study the default mapping and determine the changes you want to make.

2. Create a back-up copy of the XSL file you want to change.

3. Open the XSL file in a text editor or in an XSLT editor.

4. 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 Operations Manager messages and Oracle Enterprise Manager alerts.

5. Save your changes.

6. Rerun the register command for the template that was modified to pick up the changes. See Section 2.5, "Registering Templates" for details.

Example of Changing a Mapping

By default, the Application field in the HP Operations Manager 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.

1. Make a back-up copy of the createEvent_request.xsl file and name it default_createEvent_request.xsl.

2. Make a back-up copy of the updateEvent_request.xsl file and name it default_updateEvent_request.xsl.

3. Open the createEvent_request.xsl file in your text editor.

4. 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>
       <!-- OMU Application -->
       <string-field name="application">
         <xsl:value-of select="a:TargetType"/>
       </string-field>
       <!-- Do not add CMA data -->
       <string-field name="ovo_ts_field">NONE</string-field>
       <!-- Own the event after it is created -->
       <string-field name="own">true</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 italics.

     <extended-fields>
       <!-- OMU Application -->
       <string-field name="application">Oracle Enterprise Manager</string-field>
       <!-- Do not add CMA data -->
       <string-field name="ovo_ts_field">NONE</string-field>
       <!-- Own the event after it is created -->
       <string-field name="own">true</string-field>
       <string-field name="TargetType">
         <xsl:value-of select="a:TargetType"/>
       </string-field>
     </extended-fields>
     

5. Save your changes after making the updates.

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

7. Save your changes after making the updates.

8. 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/HP_OMU_Connector/createEvent_request.xsl 
   -repos_pwd testPass -ctname "HP OMU Connector" -cname "HP OMU Connector" 
   -tname "Create Event Request" -iname "createEvent" -ttype 2 -d "This is the 
   request xsl file for createEvent method"
   

Changing Default Port Numbers

In most cases, you can use the default port numbers that the HP Operations Manager 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.

Changing the Agent Listener Port (9007)

9007 is the default port number used for communication between the HP Operations Manager Agent and the HP Operations Manager web service. To change this port number, perform the following steps at the HP Operations Manager server system.

Replace <OMUA_INSTALL> with the directory where the HP Operations Manager Agent is installed.

1. Open a command prompt window and change the working directory to:

   <OMUA_INSTALL>/ovo-agent/scripts
   

2. Enter the following command to stop the HP Operations Manager Agent. You will be prompted for the credentials to stop the Oracle OMU Agent.

   ./stop.sh
   

   
   

   Note: You must specify the user name and password for the account that is authorized to stop the Oracle OMU Agent. See Section 2.2, "Installing and Running the Oracle Agent for HP Operations Manager" for information about the account that is authorized to stop the Oracle OMU Agent.

   
   

3. Make a back-up copy of the following file:

   <OMUA_INSTALL>/ovo-agent/conf/ovooper.txt
   

4. Open the file above in a text editor.

5. Search for the line containing the ListenPort=string.

6. Change 9007 to the new port number.

7. Save the file and exit.

8. Enter the following command to start the HP Operations Manager Agent.

   ./start.sh
   

   The Oracle OMU Agent will pick up the configuration changes and use the new port number.

Perform the following steps at the system where the HP Operations Manager web services are installed. Replace <OMUWS_INSTALL> with the directory where the HP Operations Manager web service is installed.

1. Open a command prompt window and change the working directory to:

   <OMUWS_INSTALL>/adapters/conf
   

2. Make a back-up copy of the framework.properties file.

3. Open the framework.properties file in a text editor.

4. Search for the line containing the hpovou.xmlagent property. Change the port number from 9007 to the new port number.

5. Save the file and exit.

6. Restart the web service as instructed in Section 2.3.1.2, "Running the Web Service on Unix" and Section 2.3.2.3, "Running the Web Service on Windows".

Changing the Agent Shutdown Ports (9008, 9009)

The OMU Agent has two components that you must shut down whenever the Agent is stopped. The default port numbers these components use are 9008 and 9009. To change these port numbers, perform the following steps at the HP Operations Manager server system.

Replace <OMUA_INSTALL> with the directory where the HP Operations Manager Agent is installed as follows:

1. Open a command prompt window and change the working directory to:

   <OMUA_INSTALL>/ovo-agent/scripts
   

2. Enter the following command to stop the HP Operations Manager Agent. You will be prompted for the credentials to stop the Oracle OMU Agent.

   ./stop.sh
   

   You must specify the user name and password for the account that is authorized to stop the Oracle OMU Agent. See Section 2.2, "Installing and Running the Oracle Agent for HP Operations Manager" for information about the account that is authorized to stop the Oracle OMU Agent.

3. Make a back-up copy of the ovooper.txt file, then open the file in a text editor.

4. Search for the line containing the ShutdownPort= string.

5. Change the default port number from 9008 to the new port number.

6. Save the file and exit.

7. If the ovoacq.txt file exits, perform the following steps. Otherwise skip to step 8.

   1. Make a back-up copy of the ovoacq.txt file, then open the file in a text editor.

   2. Search for the line containing the ShutdownPort= string.

   3. Change the default port number from 9009 to the new port number.

   4. Save the file and exit.

8. Enter the following command to start the HP Operations Manager Agent:

   ./start.sh
   

   The Oracle OMU Agent will pick up the configuration changes and use the new port numbers.

9. Change the working directory to the scripts directory by entering the following command:

   cd ../scripts
   

10. Make a back-up of the stop.sh script file, then open the file in a text editor.

11. Change the SEND_SHUTDOWN_PORT and RCV_SHUTDOWN_PORT variables from 9008/9009 to the new port numbers.

12. Save the file and exit.

Changing the Web Service Port (8080)

The OMU web service uses port 8080 as the default port for communication when the web service is configured at installation to use HTTP (no SSL). To change the port number to a different value, perform the following steps on the system where the Oracle OMU Agent is installed.

Replace <OMUA_INSTALL> with the directory where the HP Operations Manager Agent is installed.

1. Open a command prompt window and change the working directory to:

   <OMUA_INSTALL>/ovo-agent/conf

2. Verify that the ovoacq.txt file exits. If the file exists, perform the following steps. If it does not exist, skip to the next procedure that begins with "Open a command prompt window ..."

   1. Make a back-up copy of the ovoacq.txt file, then open the file in a text editor.

   2. Search for the line containing the URL= string.

   3. Change the default port number from 8080 to the new port number.

   4. Save the file and exit.

   5. Change the working directory to the scripts directory by entering the following command:

      cd ../scripts
      

   6. Stop the Agent by entering the following command:

      ./stop.sh
      

      
      

      Note: You must specify the user name and password for the account that is authorized to stop the Oracle OMU Agent. See Section 2.2, "Installing and Running the Oracle Agent for HP Operations Manager" for information about the account that is authorized to stop the Oracle OMU Agent.

      
      

   7. Start the Agent by entering the following command:

      ./start.sh
      

Perform the following steps at the system where the HP Operations Manager web services are installed. Replace <OMUWS_INSTALL> with the directory where the HP OMU web services are installed.

1. Open a command prompt window and change the working directory to:

   <OMUWS_INSTALL>/adapters/conf
   

2. Make a back-up copy of the framework.properties file, then open the file with a text editor.

3. Replace all references to the old port number with the new port number, then save the file.

4. Restart the web service as instructed in Section 2.3.1.2, "Running the Web Service on Unix" and Section 2.3.2.3, "Running the Web Service on Windows".

Perform the following steps to change the URL the OMU connector is using:

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

2. Click the Setup link at the top right part of the window. The Overview of Setup page appears.

3. Click the Management Connectors link on the left side of the window. The Management Connectors page appears, which shows the installed connectors.

4. Click on the Configure icon associated with the HP OMU Connector. This invokes edit mode, enabling you to configure the connector.

5. Change the URLs listed in the Web Service End Points section to use the new port number.

6. Click OK to save your changes.

Changing the Web Service Port (8443)

Contact Oracle support for assistance in switching the default SSL port 8443 to a different port.

Changing Web Service Credentials

Sometimes problems occur when accessing the web service, because the credentials provided are incorrect. Whenever this happens, you receive an HTTP 403 error from the web service. You first want to check the specified credentials and verify that you entered the correct information. If the credentials you have specified appear to be correct, but you still receive the 403 error, the best option is to reset the web service credentials.

Perform the following steps to reset the web service credentials:

1. Open a command prompt window and change the working directory to:

   <OMUWS_INSTALL>/adapters/conf
   

2. Enter the following command to change the user name and password for accessing the OMU web service:

   ../bin/propertiesEditor.sh –h 
   framework.username=”<username>” –e 
   framework.password=“<password>” framework.properties
   

   … where <username> is the user name to specify for the web service and <password> is the password.

   The propertiesEditor.sh script is specifically for the UNIX platform. The equivalent script for Windows platforms is propertiesEditor.bat.

3. Stop and then start the web service as instructed in Section 2.3.1.2, "Running the Web Service on Unix" and Section 2.3.2.3, "Running the Web Service on Windows".