This appendix describes the Netcool/OMNIbus mappings and various other configuration defaults in the following sections:
Sample Create Format for the Web Service for Netcool/OMNIbus represents the format that the web service for Netcool/OMNIbus expects for creating new alerts in Netcool/OMNIbus. The format for update requests is the same, except that the root node would be update instead of create.
<iwaveaf:create xmlns:iwaveaf="http://iwavesoftware.com/services/adapter-framework">
<event>
<identifier></identifier>
<source>
<name></name>
<displayName></displayName>
</source>
<metric>
<category></category>
</metric>
<object>
<identifier></identifier>
</object>
<severity></severity>
<description></description>
<type></type>
<logs>
<log>
<extended-fields>
<string-field name="1"></xsl:text></string-field>
<string-field name="2"></xsl:text></string-field>
<string-field name="3"></xsl:text></string-field>
<string-field name="4"></xsl:text></string-field>
<string-field name="5"></xsl:text></string-field>
<string-field name="6"></xsl:text></string-field>
<string-field name="7"></xsl:text></string-field>
<string-field name="8"></xsl:text></string-field>
<string-field name="9"></xsl:text></string-field>
<string-field name="10"></xsl:text></string-field>
<string-field name="11"></xsl:text></string-field>
<string-field name="12"></xsl:text></string-field>
<string-field name="13"></xsl:text></string-field>
<string-field name="14"></xsl:text></string-field>
<string-field name="15"></xsl:text></string-field>
<string-field name="16"></xsl:text></string-field>
</extended-fields>
</log>
</logs>
<extended-fields>
<string-field name="Manager"> </string-field>
<string-field name="Agent"></string-field>
<date-field name="LastOccurrence"></date-field>
<string-field name="URL"></string-field>
<string-field name="Detail_1_Name"> </string-field>
<string-field name="Detail_1_Value"> </string-field>
<string-field name="Detail_2_Name"></string-field>
<string-field name="Detail_2_Value"></string-field>
<string-field name="Detail_3_Name"></string-field>
<string-field name="Detail_3_Value"> </string-field>
<string-field name="Detail_4_Name"></string-field>
<string-field name="Detail_4_Value"> </string-field>
<string-field name="Detail_5_Name"></string-field>
<string-field name="Detail_5_Value"></string-field>
<string-field name="Detail_6_Name"></string-field>
<string-field name="Detail_6_Value"></string-field>
<string-field name="Detail_7_Name"></string-field>
<string-field name="Detail_7_Value"> </string-field>
<string-field name="Detail_8_Name"></string-field>
<string-field name="Detail_8_Value"></string-field>
<string-field name="Detail_9_Name"></string-field>
<string-field name="Detail_9_Value"></string-field>
<string-field name="Detail_10_Name"></string-field>
<string-field name="Detail_10_Value"></string-field>
<string-field name="Detail_11_Name"></string-field>
<string-field name="Detail_11_Value"></string-field>
<string-field name="Detail_12_Name"></string-field>
<string-field name="Detail_12_Value"></string-field>
<string-field name="Detail_13_Name"></string-field>
<string-field name="Detail_13_Value"></string-field>
<string-field name="Detail_14_Name"></string-field>
<string-field name="Detail_14_Value"></string-field>
<string-field name="Detail_15_Name"></string-field>
<string-field name="Detail_15_Value"></string-field>
<string-field name="Detail_16_Name"></string-field>
<string-field name="Detail_16_Value"></string-field>
<string-field name="Detail_17_Name"></string-field>
<string-field name="Detail_17_Value"></string-field>
<string-field name="Detail_18_Name"></string-field>
<string-field name="Detail_18_Value"></string-field>
<string-field name="Detail_19_Name"></string-field>
<string-field name="Detail_19_Value"></string-field>
<string-field name="Detail_20_Name"></string-field>
<string-field name="Detail_20_Value"></string-field>
</extended-fields>
</event>
</iwaveaf:create>
Table A-1 identifies the mappings between the IBM Tivoli Netcool/OMNIbus alert field names (from the alerts.status table) and the XML format that the web service uses. To set the IBM Tivoli Netcool/OMNIbus alert fields, the XML document presented to the web service must have the corresponding fields set. This must be handled in the appropriate translation file identified in Table 5-1.
Note:
The XML paths specified in this table are for create requests. To determine the XML path for update requests, replace the create node in the path with update.For example, the XML path for the Identifier field on an update operation would be:
/update/event/identifier
Table A-1 Event Fields and XML Path Mappings
| Netcool/OMNIbus Event Field | Web Service XML Path |
|---|---|
|
Identifier |
|
|
NodeAlias |
|
|
Node |
|
|
AlertGroup |
|
|
AlertKey |
|
|
Severity |
|
|
Summary |
|
|
Type |
|
|
Journal |
See Log Entries below |
|
Manager |
See Extended Fields below |
|
Agent |
See Extended Fields below |
|
LastOccurrence |
See Extended Fields below |
|
URL |
See Extended Fields below |
The alerts.journal table is populated from data passed in the <logs> element. An entry is added to the journal table for each <log> element that is a child of the <logs> element. The text for the journal entry is passed in <string-field/> elements that are children of <extended-fields> elements within the <log> element.
The name attribute in the <string-field/> element must be set to an integer from 1 to 16. A journal entry has 16 columns that can contain text, and the name attribute determines what column in the journal table to populate. The column is 255 characters in length; so, strings longer than 255 characters will be truncated.
An extended field is defined as a <string-field/> or <date-field/> element that is a child of the <extended-fields> node. Fields that contain date information are passed as a date-field element and all other fields are passed as a string-field element. The name of the extended field is specified in the name attribute, and the value of this field is specified as the element value. The name must be the name of a database column in the alerts.status table or a special reserved name used to populate the alert.details table.
The web service allows up to 20 entries to be populated in the alerts.details table. To populate an entry, you must specify 2 elements. The Detail_n_Name element populates the Name field of the alerts.details table and the Detail_n_Value element populates the Detail field. For both elements, the n would be replaced by an integer between 1 and 20. The number identifies the position where the information would appear on the Alert Details tab of the Event Information window.
Listed below is an example that shows how to populate fields in the alerts.status, alerts.details, and alerts.journal database tables. In the example, the Manager and LastOccurrence fields would be populated in the alerts.status table for the row with an identifier of TESTYA3F17890220E040020A78012524. The lines that start with Detail would cause the first two rows of the alerts.details table to be populated for the alert with an identifier of TESTYA3F17890220E040020A78012524. The log entry will cause a journal entry to be added to the alerts.journal table for the alert with an ID of TESTYA3F17890220E040020A78012524.
Example A-1 How to Populate Fields
<event>
<identifier>TESTYA3F17890220E040020A78012524</identifier>
<logs>
<log>
<extended-fields>
<string-field name="1">This creates an entry in the journal</xsl:text></string-field>
</extended-fields>
</log>
</logs>
<extended-fields>
<string-field name="Manager">Oracle Enterprise Manager</string-field>
<date-field name="LastOccurrence">2012-01-13T16:08:45.000-06:00</date-field>
<string-field name="Detail_1_Name">Reported Date:</string-field>
<date-field name="Detail_1_Value">2012-05-03T00:00:00.0-00:00</date-field>
<string-field name="Detail_2_Name"> Event Class:</string-field>
<string-field name="Detail_2_Value">metric_alert</string-field>
</extended-fields>
</event>
In most cases, you can use the default port numbers that the 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:
The web service for Netcool/OMNIbus 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:
Identify a new port number to use for the web service. You must verify that the new port number is not in use on the system where the web service is installed.
Change the web service to use the new port number:
At the system where the web service is installed, navigate to the adapters/conf directory and open the framework.properties file in a text editor.
Change the port number from 8080 to the new port number for the following properties:
services.url
client.url
notification.url
acquisitionevent.url
Save and close the framework.properties file.
Stop and then start the web service as instructed in Section 2.6.3, "Running the Web Service on Unix" and Section 2.7.3, "Running the Web Service on Windows."
Change the configuration of the IBM Tivoli Netcool/OMNIbus Connector to use the new port number:
From the Setup menu of Oracle Enterprise Manager Cloud Control, select Extensibility, then Management Connectors.
Click on the name of the Netcool/OMNIbus Connector.
The General tab of the Configure Management Connector page appears.
Change the URLs listed in the Web Service End Points section to use the new port number.
Click OK to save your changes.
Change the agent scripts to send alert information to the new port number:
Navigate to the directory where the Oracle Agent for Netcool/OMNIbus is installed.
Open the oracle_error.cmd (Windows) or oracle_error.sh (Unix) script file in a text editor.
Change the port number in the OMNIBUS_ADAPTER_URL variable from 8080 to the new port number and save.
Open the oracle_send.cmd (Windows) or oracle_send.sh (Unix) script file in a text editor.
Change the port number in the OMNIBUS_ADAPTER_URL variable from 8080 to the new port number and save.
Contact Oracle Support for assistance in switching the default SSL port 8443 to a different port.
Occasionally, problems occur when accessing the web service for Netcool/OMNIbus, 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.
To reset the web service credentials:
Open a command prompt window and change the working directory to the web service adapters/conf directory using the following command:
cd <OMNIWS_INSTALL>/adapters/conf
Replace <OMNIWS_INSTALL> with the directory where the web service is installed.
Enter the following command to change the user name and password for accessing the web service:
../bin/propertiesEditor.sh -e framework.username="<username>" -h 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.
Stop and then start the web service as instructed in Section 2.6.3, "Running the Web Service on Unix" and Section 2.7.3, "Running the Web Service on Windows."