9 Customizing Incident Manager

This chapter describes how to customize the event details page to provide more diagnostic information about the event and to facilitate quicker resolution of the underlying issue. Details pages on the Incident Manager UI allow users to view the details of an event. The content of such pages helps the user understand the basic nature of the underlying issue and provides additional contextual details (such as text, links to diagnostic or resolution pages) to resolve the issue quickly.

For incidents that have only one event, the customizations applied to the event details page are automatically applied to the Incident Details page.

Note:

For information about Incident Management, see the "Using Incident Management" chapter of the Oracle Enterprise Manager Cloud Control Administrator's Guide.

http://www.oracle.com/pls/em121/homepage

This chapter contains the following sections:

Introduction to Customizing Incident Manager
Understanding Supported Customizations
Creating Event-Specific Customization XML
Adding Customized Details About the Event
Providing Content in the Guided Resolution Region
Defining a Search String for My Oracle Support Knowledge
Defining Conditions for Customization
Registering Customizations
Testing Incident Manager After Customization

9.1 Introduction to Customizing Incident Manager

As a plug-in developer, you are responsible for the following steps within customizing Incident Manager:

Determine what customizations you require for your Incident Manager UI. For fine-grained access, use conditions. For more information, see Section 9.2, "Understanding Supported Customizations".
Construct the customization XML according to the XSD. For more information, see Section 9.3, "Creating Event-Specific Customization XML".
Register your customization. For more information, see Section 9.8, "Registering Customizations".
Test the UI by publishing an event that matches the condition. For more information, see Section 9.9, "Testing Incident Manager After Customization".

9.2 Understanding Supported Customizations

Figure 9-1 displays the General tab for a selected incident from the Incident Manager page.

Figure 9-1 Incident Manager

General tab of the Incident Manager UI page

The following customizations are supported for this page:

Adding name-value pairs to the Incident Details region.

For more information, see Section 9.4, "Adding Customized Details About the Event".
Customizing Action and Diagnostic links in the Guided Resolution region.

For more information, see Section 9.5, "Providing Content in the Guided Resolution Region".
Adding recommendations to the Guided Resolution region.

For more information, see Section 9.5.1, "Adding Recommendations using XML".
Specifying the default search phrase for My Oracle Support Knowledge.

For more information, see Section 9.6, "Defining a Search String for My Oracle Support Knowledge".

Each customization specification has two parts:

Condition

This is the criteria used to identify an event for which the customized content will be rendered. For example, consider a scenario where you want to show a diagnostic link for metric alerts on a database. The condition would be "event class is metric_alert and target type is oracle_database". Another example is where you to show the region containing a metric chart. This condition would be "event class is metric_alert and metric_type is numeric".

Note:
Any target type name is supported. While matching an event, you match the target type in the condition with the target type of the event
Action

The actions specify the customized content. For example, the specification of the diagnostic link (that is, the label and the URL to be shown under it).

9.3 Creating Event-Specific Customization XML

Oracle provides an event-specific customization XSD so that you can write XML to describe customizations for a specific event for display on the Incident Manager UI.

Note:

For a complete event-specific customization XML Schema Definitions (XSD), see the Extensibility Development Kit (EDK).

The event-specific customization XSD defines how the Incident Manager UI supports UI customization.

You can define fine-grained conditions to customize the Event Details or Incident Details pages.

Example 9-1 Sample Metadata File

<evt:CustomUI AppliesTo="EVENT" EventClass ="metric_alert" TargetType =host">
    <evt:ConditionDetails>
       <evt:Condition>
         <evt:Attrib Name="metric_name" Value="Load"/>
         <evt:Attrib Name="metricColumn" Value="cpuUtil"/> </evt:Condition>
     </evt:ConditionDetails>
</evt:CustomUI>

Oracle recommends the following naming conventions for your metadata XML:

event_class_description.xml

In the preceding file name:
- event_class represents the name of the event class
  
  Event customization supports the following event classes:
  - metric_alert
  - target_availability
  - job_status_change
  - cs_rule_violation
  - cs_score
  - sla_alert
  - metric_error
- description represents a short description of the event customization
For example, job_status_change_recommendation.xml
event_class_target_type_description.xml

In the preceding file name:
- event_class represents the name of the event class
- target_type represents the name of the target type for which this event is generated
- description represents a short description of the event customization
For example, host_metric_alert_diaglinks.xml

Note:

The maximum length of the file name is 255 characters.

For information about the directory location for the metadata XML, see Section 9.8, "Registering Customizations".

Note:

Use the empdk validate_plugin command to validate the XML metadata file. For more information about the empdk validate_plugin command, see Chapter 13, "Validating, Packaging, and Deploying the Plug-in".

9.3.1 Overview of Event-Specific Customization Metadata Elements

Table 9-1 describes the key elements that define the event-specific customization XML.

Table 9-1 Key Elements in Event-Specific Customization XML

Element	Description
`evt:CustomUI`	This is the root element of the XML. It defines the customization. It includes the following attributes: `AppliesTo`: Applicable to event customizations. The only valid value is EVENT. `EventClass`: Specifies the internal event class name and is applicable only when the customization applies to an event. `TargetType`: Internal name of the target type. The customization applies to events from all targets of this target type.
`evt:ConditionDetails`	Specifies the criteria on which the customizations are to be applied.
`evt:Condition`	Specifies a condition for the customization. Note: Oracle supports one condition only within the `evt:ConditionDetails` tag.
`evt:DetailUI`	Specifies that you are customizing the Details region of the Incident Manager UI page. For more information, see Section 9.4, "Adding Customized Details About the Event".
`evt:GuidedResolutionDetails`	Specifies that you are customizing the Guided Resolution region of the Incident Manager UI page. Using this element, you can add action links, diagnostic links, and recommendations. For more information, see Section 9.5.1, "Adding Recommendations using XML".

9.3.2 About Events

This section provides common event attributes and the definition of the two most commonly-used event types:

Common Event Attributes
Target Availability Event
Metric Alert Event

9.3.2.1 Common Event Attributes

All events have the following common attributes:

Table 9-2 Common Event Attributes

Attribute	Description
sys_event_class	Event type Possible values: target_availability: Target Availability events metric_alert: Metric Alert events
sys_event_name	Event name to identify the nature of the event uniquely
sys_event_key	Name of a subcomponent within the event source object to which this event is related. This is optional. Examples include a disk name on a host, name of a tablespace, and so on
sys_event_msg	Event message
sys_action_msg	Action message
sys_source_obj_type	Source object type. For example, JOBS for job-based events.
sys_source_obj_id	Unique internal identifier of a Source object
sys_target_guid	Unique internal identifier of a target
sys_target_name	Target name
sys_target_owner	Target owner
sys_target_version	Target version
sys_target_lifecycle_status	Lifecycle status
sys_incident_id	Incident ID
sys_severity	Severity of the event Possible values: 32: Fatal 16: Critical 8: Warning 4: Minor Warning
sys_category	Event category. Possible values: Availability: 1 Configuration: 2 Capacity: 4 Fault: 8 Load: 16 Performance: 32 Security: 64 Jobs: 128 Diagnostics: 256 Error: 512 Business: 1024

9.3.2.2 Target Availability Event

The Target Availability Event represents a target's availability status.

Example 9-2 shows the event attributes defined by the target availability XML file. Table 9-3 provides a list of all the event attributes for target availability.

Example 9-2 target_availability.xml

<evt:EventClass Name="target_availability" 
          NLSID="TARGET_AVAILABILITY" 
          ResourceBundle="oracle.sysman.core.common.events.classes.rsc.availability.AvailabilityEventsMsg" 
          TargetAware="ALWAYS" 
          SourceObjectType="TARGET"
          Version="1.0" 
          xmlns:evt="http://www.oracle.com/EnterpriseGridControl/eventclass_model"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/eventclass_model EventClass.xsd">

    <evt:DescriptionNLSID>TARGET_AVAILABILITY_DESC</evt:DescriptionNLSID> 

    <evt:AttributeDef>

        <!--This attribute is used to store the availability status of a target-->
        <evt:Attrib Name="target_status" 
                    DataType="STRING" 
                    isReferenced="false" 
                    NLSID="TARGET_STATUS" 
                    isValueTranslatable="true">
             <evt:DescriptionNLSID>TARGET_STATUS_DESC</evt:DescriptionNLSID> 
        </evt:Attrib>

        <!--The guid of the severity record associated with this availability record-->
        <evt:Attrib Name="severity_guid" 
                    DataType="RAW" 
                    isReferenced="false" 
                    NLSID="SEVERITY_GUID" 
                    isValueTranslatable="false">
             <evt:DescriptionNLSID>SEVERITY_GUID_DESC</evt:DescriptionNLSID> 
        </evt:Attrib>

        <!--The cycle guid of the severity record associated with this availability record-->
        <evt:Attrib Name="cycle_guid" 
                    DataType="RAW" 
                    isReferenced="true" 
                    NLSID="CYCLE_GUID" 
                    isValueTranslatable="false">
             <evt:DescriptionNLSID>CYCLE_GUID_DESC</evt:DescriptionNLSID> 
        </evt:Attrib>

        <!--The below attributes specifies the metric guid of response metric -->
        <evt:Attrib Name="metric_guid" 
                    DataType="RAW" 
                    isReferenced="true" 
                    NLSID="METRIC_GUID" 
                    isValueTranslatable="false">
             <evt:DescriptionNLSID>METRIC_GUID_DESC</evt:DescriptionNLSID> 
        </evt:Attrib>

        <!--The below attribute represents a sub-state for availability states like Status pending, Agent Unreachable and Blackout.
        TARGET STATUS        CODE     SUB_STATE

        Any                  0        None (Default)
        Agent unreachable    1        Normal
        Agent unreachable    2        Host Down
        Agent unreachable    3        Disk Full
        Status Pending       10       Normal
        Status Pending       11       Stuck
        -->
        <evt:Attrib Name="avail_sub_state" 
                    DataType="NUMBER" 
                    isReferenced="false" 
                    NLSID="AVAILABILITY_SUB_STATE" 
                    isValueTranslatable="false">
             <evt:DescriptionNLSID>AVAILABILITY_SUB_STATE_DESC</evt:DescriptionNLSID> 
        </evt:Attrib>

        <!--The below attributes specifies the availability transition severity 
        that resulted in the target availability status that is specified by
        target_status attribute -->
        <evt:Attrib Name="avail_severity" 
                    DataType="NUMBER" 
                    isReferenced="false" 
                    NLSID="AVAILABILITY_SEVERITY" 
                    isValueTranslatable="false">
             <evt:DescriptionNLSID>AVAILABILITY_SEVERITY_DESC</evt:DescriptionNLSID>
        </evt:Attrib>
    </evt:AttributeDef>

    <evt:RefAttribSource><![CDATA[ mgmt_avail.get_target_avail_ref_attribs]]></evt:RefAttribSource>

    <!-- For availibility we don't have any identifier attribute list. -->
    <!-- So system will use target_guid, event_class name to generate the identifier attribute. -->

    <evt:RuleAttribs>
        <evt:RuleAttrib Name="target_status" /></evt:RuleAttrib>
        <evt:RuleAttrib Name="avail_sub_state" /></evt:RuleAttrib> 
        <evt:RuleAttrib Name="avail_severity" /></evt:RuleAttrib> 
    </evt:RuleAttribs>

    <evt:NotifAttribs>
        <evt:NotifAttrib Name="target_status" /> 
        <evt:NotifAttrib Name="severity_guid" />
        <evt:NotifAttrib Name="avail_sub_state" /> 
        <evt:NotifAttrib Name="avail_severity" /> 
        <evt:NotifAttrib Name="metric_guid" /> 
        <evt:NotifAttrib Name="cycle_guid" /> 
    </evt:NotifAttribs>

    <evt:Severities>
        <evt:Severity>FATAL</evt:Severity>
        <evt:Severity>CRITICAL</evt:Severity>
        <evt:Severity>WARNING</evt:Severity>
        <evt:Severity>MINOR_WARNING</evt:Severity> 
        <evt:Severity>INFORMATIONAL</evt:Severity> 
    </evt:Severities>
</evt:EventClass>

Table 9-3 Event Attributes for Target Availability

Attribute	Description
TARGET_STATUS	Availability status
AVAILABILITY_SUB_STATE	Availability substatus
AVAILABILITY_SEVERITY	Transition severity

9.3.2.3 Metric Alert Event

A metric alert event is generated when an alert occurs for a metric on a specific target (for example, CPU utilization for a host target) or metric on a target and object combination (for example, space usage on a specific tablespace of a database target)

Example 9-3 shows the event attributes defined by the metric alert XML file. Table 9-4 provides a list of all the event attributes for the metric alert event.

Example 9-3 metric_alert.xml

<evt:EventClass Name="metric_alert" 
          NLSID="METRIC_ALERT_EVENT" 
          TargetAware="ALWAYS" 
          SourceObjectType="TARGET" 
          ResourceBundle="oracle.sysman.core.common.events.classes.rsc.metrics.MetricEventsMsg"
          Version="1.1"
          xmlns:evt="http://www.oracle.com/EnterpriseGridControl/eventclass_model"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.oracle.com/EnterpriseGridControl/eventclass_model EventClass.xsd">
    <evt:DescriptionNLSID>METRIC_ALERT_DESC</evt:DescriptionNLSID>
    <evt:AttributeDef> 
         <evt:Attrib Name="metric_guid" DataType="RAW" isReferenced="false"
                     NLSID="METRIC_GUID_NLSID" isValueTranslatable="false">
             <evt:DescriptionNLSID>METRIC_GUID_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_value" DataType="STRING" isReferenced="false" 
                     NLSID="KEY_VALUE_NLSID" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="severity_guid" DataType="RAW" isReferenced="false" 
                     NLSID="SEVERITY_GUID_NLSID" isValueTranslatable="false">
             <evt:DescriptionNLSID>SEVERITY_GUID_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="cycle_guid" DataType="RAW" isReferenced="true" 
                     NLSID="CYCLE_GUID_NLSID" isValueTranslatable="false">
             <evt:DescriptionNLSID>CYCLE_GUID_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="value" DataType="STRING" isReferenced="true" 
                     NLSID="VALUE_NLSID" isValueTranslatable="false">
             <evt:DescriptionNLSID>VALUE_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="metric_group" DataType="STRING" isReferenced="true"
                     NLSID="METRIC_GROUP_NLSID" isValueTranslatable="true">
             <evt:DescriptionNLSID>METRIC_GROUP_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="metric_column" DataType="STRING" isReferenced="true" 
                     NLSID="METRIC_COLUMN_NLSID" isValueTranslatable="true">
             <evt:DescriptionNLSID>METRIC_COLUMN_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="metric_description" DataType="STRING" isReferenced="true"
                     NLSID="METRIC_DESCRIPTION_NLSID" isValueTranslatable="true">
             <evt:DescriptionNLSID>METRIC_DESCRIPTION_DESC_NLID</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="coll_name" DataType="STRING" isReferenced="true" 
                     NLSID="COLL_NAME_NLSID" isValueTranslatable="true">
             <evt:DescriptionNLSID>COLL_NAME_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_1" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_1" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_1</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_2" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_2" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_2</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_3" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_3" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_3</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_4" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_4" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_4</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_5" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_5" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_5</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_6" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_6" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_6</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_7" DataType="STRING" isReferenced="true"
                     NLSID="ALERT_KEY_COL_NLSID_7" isValueTranslatable="true">
             <evt:DescriptionNLSID>ALERT_KEY_COL_DESC_7</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_1_value" DataType="STRING" isReferenced="true" 
                     NLSID="KEY_VALUE_PART_NLSID_1" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_1</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_2_value" DataType="STRING" isReferenced="true"
                     NLSID="KEY_VALUE_PART_NLSID_2" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_2</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_3_value" DataType="STRING" isReferenced="true"
                     NLSID="KEY_VALUE_PART_NLSID_3" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_3</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_4_value" DataType="STRING" isReferenced="true"
                     NLSID="KEY_VALUE_PART_NLSID_4" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_4</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_5_value" DataType="STRING" isReferenced="true"
                     NLSID="KEY_VALUE_PART_NLSID_5" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_5</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_6_value" DataType="STRING" isReferenced="true"
                     NLSID="KEY_VALUE_PART_NLSID_6" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_6</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="key_column_7_value" DataType="STRING" isReferenced="true"
                     NLSID="KEY_VALUE_PART_NLSID_7" isValueTranslatable="false">
             <evt:DescriptionNLSID>KEY_VALUE_PART_DESC_7</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="metric_type" DataType="NUMBER" isReferenced="true"
                     NLSID="METRIC_TYPE" isValueTranslatable="false">
             <evt:DescriptionNLSID>METRIC_TYPE_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="num_keys" DataType="NUMBER" isReferenced="true"
                     NLSID="NUM_KEYS" isValueTranslatable="false">
             <evt:DescriptionNLSID>NUM_KEYS_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="unit" DataType="STRING" isReferenced="true"
                     NLSID="UNIT_NLSID" isValueTranslatable="true">
             <evt:DescriptionNLSID>UNIT_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="is_thresholdable" DataType="NUMBER" isReferenced="true"
                     NLSID="IS_THRESHOLDABLE" isValueTranslatable="false">
             <evt:DescriptionNLSID>IS_THRESHOLDABLE_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="is_remote" DataType="NUMBER" isReferenced="true"
                     NLSID="IS_REMOTE" isValueTranslatable="false">
             <evt:DescriptionNLSID>IS_REMOTE_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="is_long_running" DataType="NUMBER" isReferenced="true"
                     NLSID="IS_LONG_RUNNING" isValueTranslatable="false">
             <evt:DescriptionNLSID>IS_LONG_RUNNING_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="is_udm" DataType="NUMBER" isReferenced="true"
                     NLSID="IS_UDM" isValueTranslatable="false">
             <evt:DescriptionNLSID>IS_UDM_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
         <evt:Attrib Name="is_metric_extension" DataType="NUMBER" isReferenced="true"
                     NLSID="IS_METRIC_EXTENSION" isValueTranslatable="false">
             <evt:DescriptionNLSID>IS_METRIC_EXTENSION_DESC</evt:DescriptionNLSID>
         </evt:Attrib>
    </evt:AttributeDef>

    <evt:RefAttribSource><![CDATA[sysman.em_severity.get_metric_alert_ref_attribs]]></evt:RefAttribSource>

    <evt:SignatureAttribs>
         <evt:SignaturePart>metric_guid</evt:SignaturePart>
         <evt:SignaturePart>key_value</evt:SignaturePart>
    </evt:SignatureAttribs>
    
    <evt:RuleAttribs>
         <evt:RuleAttrib Name="metric_group"/>
         <evt:RuleAttrib Name="metric_column"/>
         <evt:RuleAttrib Name="key_value"/>
         <evt:RuleAttrib Name="key_column_1_value"/>
         <evt:RuleAttrib Name="key_column_2_value"/>
         <evt:RuleAttrib Name="key_column_3_value"/>
         <evt:RuleAttrib Name="key_column_4_value"/>
         <evt:RuleAttrib Name="key_column_5_value"/>
         <evt:RuleAttrib Name="key_column_6_value"/>
         <evt:RuleAttrib Name="key_column_7_value"/>
    </evt:RuleAttribs>

    <evt:NotifAttribs>
         <evt:NotifAttrib Name="metric_guid"/>
         <evt:NotifAttrib Name="severity_guid"/>
         <evt:NotifAttrib Name="cycle_guid"/>
         <evt:NotifAttrib Name="coll_name"/>
         <evt:NotifAttrib Name="metric_group"/>
         <evt:NotifAttrib Name="metric_column"/>
         <evt:NotifAttrib Name="metric_description"/>
         <evt:NotifAttrib Name="value"/>
         <evt:NotifAttrib Name="key_value"/>
         <evt:NotifAttrib Name="key_column_1"/>
         <evt:NotifAttrib Name="key_column_1_value"/>
         <evt:NotifAttrib Name="key_column_2"/>
         <evt:NotifAttrib Name="key_column_2_value"/>
         <evt:NotifAttrib Name="key_column_3"/>
         <evt:NotifAttrib Name="key_column_3_value"/>
         <evt:NotifAttrib Name="key_column_4"/>
         <evt:NotifAttrib Name="key_column_4_value"/>
         <evt:NotifAttrib Name="key_column_5"/>
         <evt:NotifAttrib Name="key_column_5_value"/>
         <evt:NotifAttrib Name="key_column_6"/>
         <evt:NotifAttrib Name="key_column_6_value"/>
         <evt:NotifAttrib Name="key_column_7"/>
         <evt:NotifAttrib Name="key_column_7_value"/>
         <evt:NotifAttrib Name="num_keys"/>
    </evt:NotifAttribs>

    <evt:Severities>
         <evt:Severity>CRITICAL</evt:Severity>
         <evt:Severity>WARNING</evt:Severity>
    </evt:Severities>

</evt:EventClass>

Table 9-4 Event Class Attributes for Metric Alerts

Attribute	Description
KEY_VALUE_DESC	Monitored object for the metric corresponding to the Metric Alert event
VALUE_DESC	Value of the metric when the event triggered
METRIC_GROUP_DESC	The name of the metric
METRIC_COLUMN_DESC	The name of the metric column
KEY_COLUMN_1_VALUE	Value of Key Column 1
KEY_COLUMN_2_VALUE	Value of Key Column 2
KEY_COLUMN_3_VALUE	Value of Key Column 3
KEY_COLUMN_4_VALUE	Value of Key Column 4
KEY_COLUMN_5_VALUE	Value of Key Column 5
KEY_COLUMN_6_VALUE	Value of Key Column 6
KEY__COLUMN_7_VALUE	Value of Key Column 7
IS_METRIC_EXTENSION_DESC	Flag to indicate if the metric is metric extension

9.4 Adding Customized Details About the Event

The Incident Details region shows information about the event. It consists of system attributes (such as the message, target name, and when the event was reported) and the class attributes. You can customize the name-value pairs for the class attributes.

Through the event-specific customization XML, you can choose which attributes to show, such as the labels for the name part, and whether you require a link under the value. For more information, see Section 9.3, "Creating Event-Specific Customization XML".

Example 9-4 Constructing a Name-Value Pair

<evt:DetailUI>
  <evt:UIAttributeList>
    <evt:UIAttrib Name="metric_name">
      <evt:URL PageType="sdkcore-dummy-published-page-id">
      <evt:URLParam Name="target" Value="^TARGET:sys_target_name^"/>
      <evt:URLParam Name="type" Value="^TARGET:sys_target_type^"/>
      <evt:URLParam Name="metric" Value="^metric_name^"/>
      <evt:URLParam Name="metricColumn" Value="^metric_column^"/>
      <evt:URLParam Name="ctxType" Value="Hosts"/>
      </evt:URL>
    </evt:UIAttrib>
  </evt:UIAttributeList>
</evt:DetailUI>

Example 9-4 constructs a name-value pair under the Incident Details region. The name is the translated value of metric_name, which is an event class attribute. The value part is the value of metric_name, with a link to the METRIC_DETAILS page with specified URL parameters.

Note:

For the evt:URL tag, you must use an EDK published page id as the pageType. At design-time, you cannot validate the link navigation so if you are using this API, then you must verify that the link works correctly on the Incident Manager UI.

The URL parameters in the links can be:

Event attributes: Must be enclosed in carets (^). For example, ^metric_name^.

For information about event attributes, see Section 9.3.2, "About Events".
Target attributes: Must be prefixed with TARGET. For example, ^TARGET:sys_target_type^.

Possible target attributes:
- sys_target_name
- sys_target_type
- sys_target_owner
- sys_target_version
- sys_target_lifecycle_status
- sys_target_guid
  
  For more information about these attributes, see Table 9-2.
Event context attributes: Must be prefixed with EVENT. For example, ^EVENT:evt_context_attrib_name^.

Event context attributes enable the event publisher to provide additional event information to event attributes and are defined as name-value pairs.
Constants: Must be specified as literal strings. For example, byDay.

Note:

You can customize the Incident Details region to include class-specific attributes only.

9.5 Providing Content in the Guided Resolution Region

You can make the following customizations to the Guided Resolution region:

Customize Repair and Diagnostic links (these links can be added or removed)
Add recommendations to the Guided Resolution region
Specify a default search phrase for My Oracle Support Knowledge
Add areas with text to the Guided Resolution region

The Guided Resolution region provides links to relevant Enterprise Manager pages to help users debug and resolve issues. These context-sensitive links are grouped into multiple areas based on the nature of content in the destination page of the link. The following areas are displayed only if they have content.

Diagnose: This area contains links that can help users diagnose the issue. For example, for an event based on a target, the Diagnose area contains a link called View topology that drills down to the Topology Viewer. You can add or remove links in this area using the evt:DiagLinks tag (see Example 9-5).
Repair: This area contains links that can help users resolve the issue. For example, for metric alerts with thresholds, this area might contain a link to Edit Thresholds. You can add or remove links to and from this area using the evt:ActionLinks tag. This area displays for open events only.
Recommendation: This area contains text content drawn from the metric advisory, if available. You can customize the content of this area using the evt:Recommendation tag (see Example 9-6).
Any additional area: This area contains text content drawn from the metric advisory, if available. You can customize the content of this section using the evt:Sections tag (Example 9-8).

Example 9-5 provides an example of adding a link to the Diagnostics list in the Guided Resolution region using XML:

Example 9-5 Adding a Link to the Diagnostics Subsection

<evt:DiagLinks>
  <evt:Add>
    <evt:Link LinkID="diagLink1_example">
      <evt:Label>
      <evt:LocalizedLabel DefaultLabel="Edit Thresholds"
        NLSID="EDIT_METRIC_THRESHOLDS"
        ResourceBundle="oracle.sysman.resources.MntrResourceBundle"/>
      </evt:Label>
      <evt:URL PageType="sdkcore-published-page-id-for-edit-threshold">
      <evt:URLParam Name="target" Value="^TARGET:sys_target_name^"/>
      <evt:URLParam Name="type" Value="^TARGET:sys_target_type^"/>
      <evt:URLParam Name="event" Value="doEditTreshold"/>
      <evt:URLParam Name="metric" Value="^metric_name^"/>
      <evt:URLParam Name="collName" Value="^coll_name^"/>
      <evt:URLParam Name="keyValue" Value="^key_value^"/>
      <evt:URLParam Name="metricColumn" Value="^column^"/>
      </evt:URL>
    </evt:Link>
  </evt:Add>
</evt:DiagLinks>

In Example 9-5, the link text is derived from the evt:Label specification and the URL is derived from evt:URL.

The URL parameters in the links can be:

Event attributes: Must be enclosed in carets (^). For example, ^metric_name^.

For information about event attributes, see Section 9.3.2, "About Events".
Target attributes: Must be prefixed with TARGET. For example, ^TARGET:sys_target_type^.

Possible target attributes:
- sys_target_name
- sys_target_type
- sys_target_owner
- sys_target_version
- sys_target_lifecycle_status
- sys_target_guid
  
  For more information about these attributes, see Table 9-2.
Event context attributes: Must be prefixed with EVENT. For example, ^EVENT:evt_context_attrib_name^.

Event context attributes enable the event publisher to provide additional event information to event attributes and are defined as name-value pairs.
Constants: Must be specified as literal strings. For example, byDay.

9.5.1 Adding Recommendations using XML

The Actions list in the Guided Resolution region enables you to provide some text describing recommended steps that users can follow to diagnose or resolve the issue. Use any of the Label tags to specify the recommendations.

Example 9-6 Adding Recommendations

<evt:GuidedResolutionDetails>
  <evt:GuidedResolution>
    <evt:Recommendation ID="reco_foo">
      <evt:Label>
      <evt:LocalizedLabel
        DefaultLabel="Recommendation for my event class"
        NLSID="MY_EVENT_CLASS_NLSID"
        ResourceBundle="oracle.sysman.MyResourceBundle"/>
      </evt:Label>
    </evt:Recommendation>
  </evt:GuidedResolution>
</evt:GuidedResolutionDetails>

You can use other variants of the evt:Label tag to construct more complex Recommendations. For example, to substitute the value of an event attribute, such as alertAction as the recommendation, use Example 9-7:

Example 9-7 Adding a Complex Recommendation

<evt:GuidedResolutionDetails>
  <evt:GuidedResolution>

    <evt:Recommendation ID="reco_unique_id">
      <evt:Label>
        <evt:AttributeValue Name="alertAction" />
      </evt:Label>
    </evt:Recommendation>

  </evt:GuidedResolution>
</evt:GuidedResolutionDetails>

9.5.2 Customizing Sections

You can display textual information by adding sections to the Guided Resolution region. For example, while prioritizing an incident about an out-of-the-box Configuration Standard, it might be useful to see the rationale explaining why that Configuration Standard was added. Each added area has a header and some textual content.

To add sections to the Guided Resolution region, you can add specifications to the customization XML similar to Example 9-8:

Example 9-8 Adding Customized Areas

<evt:Sections>
  <evt:Add>
    <evt:Section ID = "section_eventclass_1">
    <evt:SectionHeader>
      <evt:Label>
        <evt:LocalizedLabel DefaultLabel="Section Hdr 1"
          NLSID="TRANSLATION_ID"ResourceBundle="oracle.sysman.MyResourceBundle"/>             
      </evt:Label>
    </evt:SectionHeader>
    <evt:SectionText>
      <evt:Label>
        <evt:LocalizedLabel DefaultLabel="Section for my event class"
          NLSID="MY_EVENT_CLASS_NLSID" ResourceBundle="oracle.sysman.MyResourceBundle"/>
      </evt:Label>
    </evt:SectionText>
    </evt:Section>
  </evt:Add>
</evt:Sections>

9.6 Defining a Search String for My Oracle Support Knowledge

The customization framework provides a default search phrase in the following order of preference:

Customized value from the plug-in developer
ORA error found in the Event Summary
Event Summary

The search string can be specified explicitly by using XML as shown in Example 9-9. This search string searches for a metric alert indicating high CPU usage for the plug-in component.

Example 9-9 Defining a Search String

<evt:GuidedResolutionDetails>
  <evt:GuidedResolution>
    <evt:SearchPhrase>High CPU Utilization </evt:SearchPhrase>
  </evt:GuidedResolution>
</evt:GuidedResolutionDetails>

9.7 Defining Conditions for Customization

To select the events for which customizations are to be applied, you can define conditions using the attributes of an event. To define conditions using attributes from the event payload (for example, system attributes such as target name, target type, or event-class specific attributes such as metric_name for metric alerts, or event-context attributes), use XML.

Conditions can be defined under the evt:ConditionDetails tag. You can specify various event attributes here and they are joined together implicitly using an AND condition.

Note:

You can define one condition only under the evt:ConditionDetails tag.

Example 9-10 Defining a Condition

<evt:CustomUI AppliesTo ="EVENT" EventClass ="metric_alert" TargetType =host">
  <evt:ConditionDetails>
    <evt:Condition>
      <evt:Attrib Name="metric_name" Value="Load"/>
      <evt:Attrib Name="metricColumn" Value="cpuUtil"/>

    </evt:Condition>
  </evt:ConditionDetails>
...
</evt:CustomUI>

The following operators are supported to define conditions:

EQ: Equals. This is the default operator
NE: Not equals
ISNULL: Is null
ISNOTNULL: Is not null
CONTAINS: Can be contained in the string (as a substring)
BEGINSWITH: Begins with (for example, the event name begins with Tablespace)
IN: In a predefined set of values (separated by pre-defined delimiter comma (,))
NOT_IN: Not in a predefined set of values. Use for exclusion

9.8 Registering Customizations

The event-specific customization XML files are located in the $PLUGIN_ORACLE_HOME/sysman/metadata/events/custmzn directory. In the shipped version of the product, these XMLs are registered as part of the plug-in installation.

If you are creating the XMLs for the first time in a view that is already set up or to test changes, use the Metadata Registration Service (MRS) to register XML for the event class. For more information about the MRS, see Section 13.7, "Updating Deployed Metadata Files Using the Metadata Registration Service (MRS)".

emctl register oms metadata -service eventSpecificCustmzn -file XML filename -pluginId plugin_name -sysman_pwd sysman -debug

For example:

emctl register oms metadata -service eventSpecificCustmzn -file metric_alert_host_load.xml -pluginId acme.demo.hostsample -sysman_pwd sysman -debug

You must restart the Oracle Management Service (OMS) after registering the event-specific customization XML, using the emctl command from the OMS home directory (OMS_HOME).

OMS_HOME>emctl stop oms
OMS_HOME>emctl start oms

You might encounter the following errors when you register your event-specific customization XML:

Syntax error in the XML

For information about the correct syntax and an example of the XML, see Section 9.3, "Creating Event-Specific Customization XML".
Incorrect values for attribute names

For information about attribute names, see Section 9.3.2, "About Events".
Incorrect credentials

Incorrect credentials will not allow you to connect to the Management Repository. Ensure that you are using authorized credentials.

9.9 Testing Incident Manager After Customization

Test the Incident Manager UI by publishing an event that matches the condition and then make sure that there is an incident created for it:

To access Incident Manager, from the Enterprise menu, select Monitoring, then select Incident Manager.

The Incident Manager: My open incidents and problems page appears.
From Views, select either of the following:
- All open incidents to find the incident
- Events without incidents if you did not create an incident