4 Changing Default Configurations

This chapter explains how to change default mappings and default port numbers. This chapter discusses the following topics:

Customizing Mappings

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

  • XML Format of Microsoft SCOM Alerts

  • 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 Microsoft SCOM Alerts

Example 4–1 represents the format that the Microsoft SCOM web service expects for creating new alerts in Microsoft SCOM. Example 4–2 represents the format that the Microsoft SCOM web service expects for updating alerts in Microsoft SCOM.

Example 4-1 Sample Create Format for Microsoft SCOM Web Service

<iwaveaf:create xmlns:iwaveaf="http://iwavesoftware.com/services/   adapter-framework">
  <event>
    <summary></summary>
    <description></description>
    <severity></severity>
    <priority></priority>
    <extended-fields>
      <string-field name="CustomField1"></string-field>
      ...
      <string-field name="CustomField10"></string-field>
    </extended-fields>
  </event>
</iwaveaf:create>

Example 4-2 Sample Update Format for Microsoft SCOM Web Service

<iwaveaf:update xmlns:iwaveaf="http://iwavesoftware.com/services/ adapter-framework">
  <event>
    <identifier></identifier>
    <status></status>
    <extended-fields>
      <string-field name="AlertHistory"></string-field>
      <string-field name="CustomField1"></string-field>
      …
      <string-field name="CustomField10"></string-field>
    </extended-fields>
  </event>
</iwaveaf:update>

Mappings Between XML Format and Alert Field Names

Table 4–1 identifies the mappings between the Microsoft SCOM alert field names and the XML format that the Microsoft SCOM web services uses when creating an alert in SCOM. Table 4–2 identifies the mappings between the Microsoft SCOM alert field names and the XML format that the Microsoft SCOM web services uses when updating an alert in SCOM.

The XML document presented to the Microsoft SCOM web service must have the corresponding fields set. Fields denoted with an asterisk ( * ) are optional. This must be handled in the appropriate translation file identified in Table A–1.

Table 4-1 Create Alert Attributes and XML Path Mappings

Microsoft SCOM Slot Names XML Path Attribute Name Attribute Value

Name

/create/event/summary

    

Description

/create/event/severity

    

Priority

/create/event/priority

    

* Custom Field 1

/create/event/extended-fields/string-field

name

CustomField1

* Custom Field 2

/create/event/extended-fields/string-field

name

CustomField2

* Custom Field 3

/create/event/extended-fields/string-field

name

CustomField3

* Custom Field 4

/create/event/extended-fields/string-field

name

CustomField4

* Custom Field 5

/create/event/extended-fields/string-field

name

CustomField5

* Custom Field 6

/create/event/extended-fields/string-field

name

CustomField6

* Custom Field 7

/create/event/extended-fields/string-field

name

CustomField7

* Custom Field 8

/create/event/extended-fields/string-field

name

CustomField8

* Custom Field 9

/create/event/extended-fields/string-field

name

CustomField9

* Custom Field 10

/create/event/extended-fields/string-field

name

CustomField10

Table 4-2 Update Alert Attributes and XML Path Mappings

Microsoft SCOM Slot Names XML Path Attribute Name Attribute Value

Id

/create/event/identifier

    

Resolution State

/create/event/status

    

* Custom Field 1

/create/event/extended-fields/string-field

name

CustomField1

* Custom Field 2

/create/event/extended-fields/string-field

name

CustomField2

* Custom Field 3

/create/event/extended-fields/string-field

name

CustomField3

* Custom Field 4

/create/event/extended-fields/string-field

name

CustomField4

* Custom Field 5

/create/event/extended-fields/string-field

name

CustomField5

* Custom Field 6

/create/event/extended-fields/string-field

name

CustomField6

* Custom Field 7

/create/event/extended-fields/string-field

name

CustomField7

* Custom Field 8

/create/event/extended-fields/string-field

name

CustomField8

* Custom Field 9

/create/event/extended-fields/string-field

name

CustomField9

* Custom Field 10

/create/event/extended-fields/string-field

name

CustomField10

* Alert History

/create/event/extended-fields/string-field

name

AlertHistory

Extended Fields

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.

XML Format of Oracle Enterprise Manager Alerts

Example 4–3 shows the fields for the XML format.

Example 4-3 XML Format of Alerts

<EMAlert>
  <AlertGuid/>
  <ExternalAlertId/>
  <ViolationId/>
  <TargetType/>
  <TargetName/>
  <MetricName/>
  <MetricColumn/>
  <KeyValues/>
  <Message/>
  <Severity/>
  <SeverityCode/>
  <CollectionTime/>
  <AlertPageURL/>
  <EMUser/>
  <NotificationRuleName/>
  <TargetHost/>
  <TargetTimezone/>
  <Property>
    <Name/>
    <Value/>
  </Property>
</EMAlert>

Table 4–3 provides a description of the fields shown in Example 4–3.

Table 4-3 Field Descriptions for XML Format

Field Description

AlertGuid

Unique identifier of the alert in Oracle Enterprise Manager.

ExternalAlertId

Unique identifier of the alert in Microsoft SCOM. 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 the 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 Microsoft SCOM.

AlertPageURL

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

This section explains how to customize the mapping between Enterprise Manager and the Microsoft SCOM 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.

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

  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 Microsoft SCOM alerts and Oracle Enterprise Manager alerts.

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

Example of Changing a Mapping

By default, the alert name in the Microsoft SCOM 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 Alert From Oracle Enterprise Manager.

  • Custom field 1 is set to the Target Type.

  • Custom field 2 is set to the Target Name.

  • Custom field 3 is set to the Metric Name.

  • Custom field 4 is set to the Metric Column.

  1. Make a back-up copy of the createalert_request.xsl file and name it default_createalert_request.xsl.

  2. Make a backup copy of the updatealert_request.xsl file and name it default_updatealert_request.xsl.

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

  4. Change the appropriate sections to reflect the new mapping.

    • Before Changes

      The code below shows the impacted sections in the file before the changes.

       <xsl:value-of select="a:MetricColumn"/>
     </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>
    <!-- SCOM alert title -->
     <summary>
        Alert 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:TargetType"/>
       </string-field>
       <string-field name="CustomField2">
         <xsl:value-of select="a:TargetName"/>
       </string-field>
       <string-field name="CustomField3">
         <xsl:value-of select="a:MetricName"/>
       </string-field>
       <string-field name="CustomField4">
         <xsl:value-of select="a:MetricColumn"/>
       </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>

  5. Save your changes after making the updates.

  6. Open the updateAlert_request.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.

  7. Save your changes after making the updates.

Changing Default Port Numbers

In most cases, you can use the default port numbers that the Microsoft SCOM 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 Microsoft SCOM web services are installed. Replace <SCOMWS_INSTALL> with the directory where the Microsoft SCOM web services are installed.

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

    <SCOMWS_INSTALL>\adapters\conf

  2. Make a backup copy of the framework.properties file.

  3. Enter the following command to configure the web service to connect to the Microsoft SCOM 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.

  4. Change the working directory to ..\bin.

  5. Enter the following command to restart the Microsoft SCOM 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 SCOM 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 SCOM 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 Default Custom Field

The SCOM Agent requires that a custom field be set aside for its exclusive use. By default, alerts that the SCOM Agent creates will have custom field 10 set to the Guid of the event that triggered the alert. If this presents a problem, perform the following steps to change the SCOM Agent to use a different custom field.

  1. Change the OracleEnterpriseManager.Alert.Creator.xml management pack file to place the event Guid in a different custom field:

    1. On the system where the SCOM Agent is installed, navigate to the directory where the OracleEnterpriseManager.Alert.Creator.xml file is located.

    2. Open the file with a text editor and search for Custom10. You should find the following line in the file:

      <Custom10>$Data/EventOriginId$</Custom10>

    3. Change “$Data/EventOriginId$” to “$Data/Params/Param[20]$”.

    4. Locate the tag for the custom field that the SCOM Agent will use, and change the contents to “$Data/EventOriginId$”.

    5. Save the file and exit the editor.

  2. Import the updated management pack into SCOM as described in Installing the Alert Creator Management Pack on page 2-5.

  3. Change the SCOM Web Service configuration to search for the event Guid in a different custom field:

    1. On the system where the SCOM Web Service is installed, navigate to the adapters/conf directory in the SCOM Web Service installation directory.

    2. Open the framework.properties file with a text editor and search for the scom2007.connector.response.query property.

    3. Change CustomField10 in the search string to the custom field number the management pack is setting.

    4. Save the file and exit the editor.

  4. Stop and start the SCOM Web Service.

    Refer to the appropriate section in Chapter 2 based on the platform where the SCOM Web Service is installed. For Unix platforms, see Running the Web Service on Unix on page 2-8. For Windows platforms, see Running the Web Service on Windows on page 2-10.

Changing SCOM API Connection Parameters

When installing the SCOM Agent, you must configure the connection parameters used for accessing the SCOM API. The installation includes the SCOMAgentConfig utility you can use to change the Agent configuration parameters.

Perform the following steps to change the connection parameters:

  1. Open Windows Explorer on the system where the SCOM Agent is installed.

  2. Navigate to the bin directory in the SCOM Agent installation directory.

  3. Run the SCOMAgentConfig.exe utility. This action starts the SCOM Agent Configuration Tool.

  4. Click Load. This action opens a directory navigation window.

  5. Navigate to the SCOM Agent installation directory and open the SCOMAgent.cfg file.

  6. Click the Management Groups tab and click Edit. This action displays the Edit Management Group window.

  7. Change the desired information in the following fields listed, then click Update:

    Name Server Domain Username Password

  8. Click Save to save the changes to the configuration file.

  9. Click Exit to exit the utility.

  10. Stop and restart the SCOM Agent in IIS.