This chapter provides information that you need to build an event connector and integrate it with Enterprise Manager.
This chapter has the following sections:
Enterprise Manager 11g provides a Management Connector Framework (referred to as Connector Framework) that enables developers to build event connectors based on metadata (XMLs and XSLs). The event connector allows Enterprise Manager to retrieve external events using a poll-based approach. You can also send events to external systems.
The following categories of metadata files are required to build an event connector:
Connector deployment descriptor
If IsNewTargetType is set to true, target type (targetType.xml) and default target (defaultTargetInstance.xml) definition files are also required.
Request transformation XSLs
Response transformation XSLs
Request XMLs
Before building the connector framework, ensure that you meet the following event system prerequisites:
The external event system exposes the following Web services:
getNewAlerts
getUpdatedAlerts
acknowledgAlerts (optional)
getResponse (optional)
updateAlert (optional)
uninitialize (optional)
initialize (optional)
setup (optional)
createEvent (optional)
updateEvent (optional)
cleanup (optional)
Note:
The custom Web service endpoint names can differ from those listed, and they are mapped by the connector framework.The Web service is of Document Literal style
Web services support SOAP header-based authentication.
The following sections provide details of various XML and XSL files that you must define for building an event connector.
Oracle recommends that you refer to the metadata files at the following location:
$OMS_HOME/sysman/connector/Microsoft_Operations_Manager_Connector
Define a connector descriptor XML file to describe the connector metadata and the configuration properties of the connector, such as Web service end points and authentication schema. This file should adhere to the schema connectorType.xsd.
A sample connector descriptor XML file is provided below. You need to define various elements. To do this, replace the highlighted text with the corresponding elements.
Example 2-1 Sample Connector Descriptor XML File
<?xml version='1.0' encoding='UTF-8'?>
<ManagementConnector xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/sysman/connector">
<Name>specify the connector name</Name>
<Version>specify the 5-digit version, e.g., 1.0.0.0.0</Version>
<Description>specify a short description</Description>
<Category>EventConnector</Category>
<!-- Category is fixed to EventConnector. -->
<EventConnector>
<!-- If IsNewTargetType is set to true, it means the developers want to define a new target type to hold external alerts. In that case, targetType.xml and defaultTargetType.xml need to be shipped in the connector jar. -->
<IsNewTargetType>true</IsNewTargetType>
<EventService>
<Method>getNewAlerts</Method>
<WebServiceEndpoint>
<![CDATA[specify URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>getUpdatedAlerts</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>acknowledgeAlerts</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>setup</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>destroy</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<!-- BaseURL element is for the default UI for event connectors, the following value should not be changed. -->
<BaseURL>/em/console/connector/event/configuration</BaseURL>
</EventConnector>
</ManagementConnector>
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/sysman/connector"
targetNamespace="http://xmlns.oracle.com/sysman/connector"
elementFormDefault="qualified" >
<xsd:element name="ManagementConnector">
<xsd:annotation>
<xsd:documentation>Deployment Descriptor for Management Connectors</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="Name" type="xsd:string"/>
<xsd:element name="Version" type="xsd:string"/>
<xsd:element name="Description" type="xsd:string"/>
<xsd:element name="Category">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="EventConnector"/>
<xsd:enumeration value="TicketingConnector"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:choice>
<xsd:element name="EventConnector" type="EventConnector"/>
<xsd:element name="TicketingConnector" type="TicketingConnector"/>
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:complexType name="EventConnector">
<xsd:sequence>
<xsd:element name="IsNewTargetType" type="xsd:boolean"/>
<xsd:element name="Authentication" type="Authentication" minOccurs="0"/>
<xsd:element name="HTTPAuthentication" type="Authentication" minOccurs="0"/>
<xsd:element name="ConfigData" type="ConfigData" minOccurs="0"/>
<xsd:element name="EventService" type="EventService" minOccurs="1" maxOccurs="unbounded"/>
<xsd:element name="TargetResponse" type="Response" minOccurs="0"/>
<xsd:element name="BaseURL" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="TicketingConnector">
<xsd:sequence>
<xsd:element name="Authentication" type="Authentication" minOccurs="0"/>
<xsd:element name="HTTPAuthentication" type="Authentication" minOccurs="0"/>
<xsd:element name="TicketingService" type="TicketingService" minOccurs="1" maxOccurs="unbounded"/>
<xsd:element name="BaseURL" type="xsd:string"/>
<xsd:element name="ExternalURL" type="ExternalURL"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="EventService">
<xsd:sequence>
<xsd:element name="Method" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="getNewAlerts"/>
<xsd:enumeration value="getUpdatedAlerts"/>
<xsd:enumeration value="acknowledgeAlerts"/>
<xsd:enumeration value="setup"/>
<xsd:enumeration value="initialize"/>
<xsd:enumeration value="uninitialize"/>
<xsd:enumeration value="cleanup"/>
<xsd:enumeration value="updateAlerts"/>
<xsd:enumeration value="createEvent"/>
<xsd:enumeration value="updateEvent"/>
<xsd:enumeration value="getResponse"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="WebServiceEndpoint" type="xsd:string"/>
<xsd:element name="SOAPAction" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="TicketingService">
<xsd:sequence>
<xsd:element name="Method" maxOccurs="1">
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="createTicket"/>
<xsd:enumeration value="updateTicket"/>
<xsd:enumeration value="getTicket"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="WebServiceEndpoint" type="xsd:string"/>
<xsd:element name="SOAPAction" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Authentication">
<xsd:sequence>
<xsd:element name="Username" type="Username"/>
<xsd:element name="Password" type="Password"/>
<xsd:element name="Attribute" type="Attribute" maxOccurs="unbounded" minOccurs="0"/>
<xsd:element name="Data" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ConfigData">
<xsd:sequence>
<xsd:element name="ConfigProperty" type="ConfigProperty" maxOccurs="unbounded" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Username">
<xsd:sequence>
<xsd:element name="AttributeName" type="xsd:string"/>
<xsd:element name="DisplayName" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Password">
<xsd:sequence>
<xsd:element name="AttributeName" type="xsd:string"/>
<xsd:element name="DisplayName" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Attribute">
<xsd:sequence>
<xsd:element name="AttributeName" type="xsd:string"/>
<xsd:element name="DisplayName" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ConfigProperty">
<xsd:sequence>
<xsd:element name="PropertyName" type="xsd:string"/>
<xsd:element name="DisplayValue" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Response">
<xsd:sequence>
<xsd:element name="ScriptName" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="ExternalURL">
<xsd:sequence>
<xsd:element name="Pattern" type="xsd:string"/>
<xsd:element name="UserVariable" type="xsd:string" maxOccurs="unbounded" minOccurs="0"/>
<xsd:element name="SubstitutionVariable" type="xsd:string" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
The target type definition XML file defines the target type where the retrieved external events are stored; for example, mom_managed_host for alerts from MOM. The file must be named targetType.xml.
<?xml version="1.0" encoding="UTF-8" ?>
<TargetMetadata xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
TYPE="hp_managed_host" TYPEDISPLAYNAME="OVO Managed Host" >
<Metrics>
<Metric>
<MetricName>
Response
</MetricName>
<Display>Response</Display>
<Category>Status</Category>
<ProducerId>xyz</ProducerId>
<MetricColumns>
<Column>Status</Column>
</MetricColumns>
<!-- No other Metric Columns should be defined for response Metric -->
</Metric>
<Metric>
<MetricName>Generic_Alert</MetricName>
<Display>Generic_Alert</Display>
<Category>Generic_Alert</Category>
<ProducerId>xyz</ProducerId>
<MetricColumns>
<Column1>AlertId</Column1>
<Column2>ComputerName</Column2>
<Column3>DomainName</Column3>
<Column4>Source</Column4>
<Column5>Rule</Column5>
</MetricColumns>
</Metric>
</Metrics>
<InstanceProperties>
<InstanceProperty NAME="HOSTNAME" CREDENTIAL="FALSE" OPTIONAL="FALSE">
<Display>
<Label>HOSTNAME_DISPLAY</Label>
<ShortName>HOSTNAME</ShortName>
</Display>
</InstanceProperty>
</InstanceProperties>
</TargetMetadata>
The target type definition is loaded during the deployment of the connector.
The targetType.xml file defines instance properties, and you can add multiple instance properties as in the following example:
<InstanceProperty NAME="HOSTNAME" CREDENTIAL="FALSE" OPTIONAL="FALSE"> <Display> <Label>HOSTNAME</Label> <ShortName>HOSTNAME</ShortName> </Display> </InstanceProperty>
The instance properties should be the identifying attributes for the targets. For example, if hostname is sufficient to uniquely identify the target, there should be only one instance property, hostname.
This section explains how you define and manage metrics in Enterprise Manager.
In the targetType.xml file, define at least two metrics for a new target type. The two mandatory metrics are:
Response
Generic_Alert
<Metrics> <Metric> <MetricName>Response</MetricName> <Display>Response</Display> <Category>Status</Category> <ProducerId>MySystem</ProducerId> <MetricColumns> <Column>Status</Column> </MetricColumns> <!-- No other Metric Columns should be defined for response Metric --> </Metric> <Metric> <MetricName>Generic_Alert</MetricName> <Display>Generic_Alert</Display> <Category>Generic_Alert</Category> <ProducerId>MySystem</ProducerId> <MetricColumns> <Column1>AlertId</Column1> </MetricColumns> </Metric></Metrics>
When external alerts are retrieved, they are mapped to a metric (<MetricName/> element in the response XSLT). If the metric is already defined, the alerts are associated with them. If not, a new metric is instantly created using Generic_Alert as a template, which is structurally the same as Generic_Alert but with a different name.
A maximum of 100 metrics are instantly created. Beyond that, alerts (that cannot be associated with existing metrics) are associated with Generic_Alert.
You can have up to five key fields as described in the sample below. One key field (equivalent of Alert ID) is mandatory. Column 1 identifies the uniqueness of the alert. Other columns are optional.
<Column1>AlertId</Column1>
<Column2>sth</Column2> <Column3>customfield1</Column3> <Column4>ruleid</Column4> <Column5>description</Column5>
Ensure that the key fields you define in getNewAlerts_response.xsl and getUpdatedAlerts_response.xsl are populated with appropriate values.
For example:
<key1> <xsl:value-of select="a:AlertId"/> </key1>
<key2>
<xsl:value-of select="a:sth"/>
</key1>
<key3>
<xsl:value-of select="a:customfield1"/>
</key3>
<key4> <xsl:value-of select="a:ruleId"/> </key4>
<key5> <xsl:value-of select="a:description"/> </key5>
Define only the key fields you defined for the Generic_Alert metric. For example, if you define only one key field for Generic_Alert, you need only transform the <key1/> element. If any extra values are added in the XSLT, they are removed during the alert processing.
If the key/field is declared and no value is assigned, a space (" ") is automatically added to the key/field so that the alert can be inserted into Enterprise Manager.
Provide a default target instance definition based on the target type you define. Name the file as defaultTargetInstance.xml. The file is read at the time you deploy the connector and a default target instance is created.
Name the default target instance as follows:
generic_<target_type_name>
For example, the target type defined for MOM Connector is mom_managed_host and the default target instance is generic_mom_managed_host.
By default, the default target instance holds all incoming alerts if no other specific target instance is created.
If the target type already exists in Enterprise Manager and you try to recreate it, the connector is not re-registered. Therefore, the configuration changes that you expect will not occur.
The Request XML and XSL files are required for a successful Web service operation. For example, the Microsoft Operations Manager (MOM) Connector needs the setup name and resolution state to be part of the setup Web service call to MOM. The request file, setup_request.xml is used for this.
Table 2-1 lists the Request XML files that you need to create. Ensure that the file names you provide exactly match those provided in the table.
Table 2-1 Default Request XML Files
| Template | Description |
|---|---|
|
getNewAlerts_request.xml (optional *) |
Generates the initial request XML file for new alerts. |
|
updateAlerts_request.xml |
Generates the initial request XML file for update alerts. |
|
setup_request.xml |
Registers the connector with the external eventing system. |
|
initialize_request.xml |
Initializes the connector with the external eventing system after setup. |
|
uninitialize_request.xml |
Un-initializes the connector with the external eventing system. |
|
cleanup_request.xml |
De-registers the connector with the external eventing system. |
|
acknowledgeAlerts_request.xml |
Defines the acknowledgement request and sends it to the external eventing system. |
*Either getNewAlerts_request.xml or getNewAlerts_request.xsl should be registered for getNewAlerts. Either getUpdatedAlerts_request.xml or getUpdatedAlerts_request.xsl should be registered for getUpdatedAlerts.
** CreateEvent and updateEvent are optional. But they are required if user wants to forward alert from EM to external system.
The following details apply to all methods in Table 2-2:
Setup and initialize are called in the order when the connector is configured if they're defined.
Uninitialize and cleanup are opposite actions to initialize and setup. uninitialize can be defined if initialize is defined. cleanup can be defined if setup is defined. They're called in the order of uninitialize and cleanup when the connector is deleted if they're defined.
GetNewAlerts and getUpdatedAlerts are called in the order when the EventCollection job is run every polling interval. For each new/updated alert, after it's been inserted/updated in Enterprise Manager, acknowledgeAlert and updateAlert will be called if they are defined.
CreateEvent and updateEvent are called to forward alert from EM to external system through notification. They're optional but need to be defined if you want this functionality.
GetResponse is called after getNewAlerts and getUpdatedAlerts when the EventCollection job is run every polling interval. It's used to update the status of proxy target added for the connector. This method is optional.
The following details apply to all templates in Table 2-2:
From version 10.2.0.5, the templates will be registered and saved in the repository. When registering the template, the internal name (-iname) should be the same as the method name (case sensitive), the template type (-ttype) shoud be: 1 for response xsl, 2 for request xsl, and 3 for request xml. For example, getNewAlerts_response.xsl should be registered with the internal name getNewAlerts and template type 1.
The template filename is no longer important, but we recommend using <methodName>_request.xml, <methodName>_request.xsl, and <methodName>_response.xsl.
The following examples show the code for these files.
<?xml version="1.0" encoding="utf-8" ?><getAlerts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/sysman/connector GenericGetAlertRequest.xsd" xmlns="http://xmlns.oracle.com/sysman/connector"> <registrationId>$REGISTRATION_ID$</registrationId> <maxCount>100</maxCount> <typeOfAlerts> NewAlerts</typeOfAlerts> <getAlertsData> <ConfigParam> <Name></Name> <Value></Value> </ConfigParam> </getAlertsData></getAlerts
generic_request_updatedalerts.xml
<?xml version="1.0" encoding="utf-8" ?>
<getAlerts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.oracle.com/sysman/connector GenericGetUpdateRequest.xsd"
xmlns="http://xmlns.oracle.com/sysman/connector">
<registrationId>$REGISTRATION_ID$</registrationId>
<maxCount>100</maxCount>
<typeOfAlerts> UpdatedAlerts</typeOfAlerts>
<getAlertsData>
<ConfigParam>
<Name></Name>
<Value></Value>
</ConfigParam>
</getAlertsData>
</getAlerts
<?xml version="1.0" encoding="UTF-8" ?>
<setup xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.oracle.com/sysman/connector GenericSetupRequest.xsd"
xmlns="http://xmlns.oracle.com/sysman/connector">
<setupname>$SETUP_NAME$</setupname>
<setupData>
<ConfigParam>
<Name></Name>
<Value></Value>
</ConfigParam>
</setupData>
</setup
initialize_request.xml (optional)
<?xml version="1.0" encoding="UTF-8" ?>
<initialize xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/sysman/connector">
<registrationId>$REGISTRATION_ID$</registrationId>
<typeofAlerts>NewAlerts UpdatedAlerts</typeofAlerts>
</initialize>
uninitialize_request.xml (optional)
<?xml version="1.0" encoding="UTF-8" ?>
<uninitialize xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/sysman/connector">
<registrationId>$REGISTRATION_ID$</registrationId>
<typeofAlerts>NewAlerts UpdatedAlerts</typeofAlerts>
</uninitialize>
cleanup_request.xml (optional)
<?xml version="1.0" encoding="UTF-8" ?>
<cleanup xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://xmlns.oracle.com/sysman/connector">
<registrationId>$REGISTRATION_ID$</registrationId>
<cleanupData>
<ConfigParam>
<Name></Name>
<Value></Value>
</ConfigParam>
</cleanupData>
</cleanup>
acknowledge_request.xml (optional)
<?xml version="1.0" encoding="utf-8" ?><getAlerts xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.oracle.com/sysman/connector GenericGetAlertRequest.xsd" xmlns="http://xmlns.oracle.com/sysman/connector"> <registrationId>$REGISTRATION_ID$</registrationId> <maxCount>100</maxCount> <typeOfAlerts> NewAlerts</typeOfAlerts> <getAlertsData> <ConfigParam> <Name></Name> <Value></Value> </ConfigParam> </getAlertsData></getAlerts>
Table 2-2 provides the list of request XSL files that you must define for building an event connector. If no transformation is required, you can define the following XSL files to allow the contents to pass through without any modification.
Table 2-2 Default Request XSL Files
| File Name | Description |
|---|---|
|
setup_request.xsl |
Transforms |
|
initialize_request.xsl |
Transforms |
|
getNewAlert_request.xsl |
Transforms |
|
getUpdatedAlert_request.xsl |
Transforms |
|
acknowledge_request.xsl |
Transforms |
|
uninitialize_request.xsl |
Transforms |
|
cleanup_request.xsl |
Transforms |
Response XSL files transform response received from the external event system. The response can be setup response, initialize response, and so on. They may not be related to alerts from external systems.
Table 2–3 lists the Response XSL files you need to create. Ensure that the file names you provide exactly match those provided in the table.
| File Name | Description |
|---|---|
|
Converts the incoming response from the external eventing system for Enterprise Manager to understand the registration ID. Subsequently, the external system uses this ID to identify the event connector. The response from the external system should be converted to the following format so that Enterprise Manager can understand and add the response to its repository:
|
|
|
Transforms the new incoming alerts to the base Enterprise Manager alert schema. |
|
|
Transforms the incoming updated alerts to the base Enterprise Manager alert schema. |
The following examples show the code for these files.
<?xml version='1.0' ?>
<xsl:stylesheet version="1.0"
xmlns:ns0="http://www.microsoft.com/EnterpriseManagement/Mom/Connector/V2"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:a="http://xmlns.oracle.com/sysman/connector">
<xsl:template match="/">
<ns0:registrationId>
<xsl:value-of select="ns0:SetupWithResolutionStateResponse/ns0:SetupWithResolutionStateResult"/>
</ns0:registrationId>
</xsl:template>
</xsl:stylesheet>
<?xml version='1.0' ?>
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
<EMAlerts>
<xsl:for-each select="getNewAlertsReturn/item">
<Alert>
<key1>
<xsl:value-of select="id"/>
</key1>
<key2>
<xsl:value-of select="application"/>
</key2>
<key3>
<xsl:value-of select="messageGroup"/>
</key3>
<key4>
<xsl:value-of select="node"/>
</key4>
<key5>
<xsl:value-of select="serviceName"/>
</key5>
<message>
<xsl:value-of select="messageText"/>
</message>
<producerID>xyz</producerID>
<targetName>
<xsl:value-of select="node"/>
</targetName>
<targetType>hp_managed_host</targetType>
<timeStamp>2006-10-09T09:23:32.6430000-07:00</timeStamp>
<metricName>
<xsl:value-of select="source"/>
</metricName>
<category>
<xsl:value-of select="messageGroup"/>
</category>
<severity>
<xsl:variable name="ovoseverity"><xsl:value-of select="severity"/></xsl:variable>
<xsl:variable name="critical">32</xsl:variable>
<xsl:variable name="major">128</xsl:variable>
<xsl:variable name="warning">16</xsl:variable>
<xsl:variable name="minor">64</xsl:variable>
<xsl:variable name="normal">8</xsl:variable>
<xsl:variable name="unknown">4</xsl:variable>
<xsl:variable name="none">0</xsl:variable>
<xsl:variable name="emclear">Clear</xsl:variable>
<xsl:variable name="emcritical">Critical</xsl:variable>
<xsl:variable name="emwarning">Warning</xsl:variable>
<xsl:variable name="eminformational">Informational</xsl:variable>
<xsl:choose>
<xsl:when test="$ovoseverity = $critical">
<xsl:value-of select="$emcritical"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$ovoseverity = $unknown">
<xsl:value-of select="$eminformational"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$ovoseverity = $none">
<xsl:value-of select="$eminformational"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$ovoseverity = $warning">
<xsl:value-of select="$emwarning"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$ovoseverity = $major">
<xsl:value-of select="$emcritical"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$ovoseverity = $minor">
<xsl:value-of select="$eminformational"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$ovoseverity = $normal">
<xsl:value-of select="$emclear"/>
</xsl:when>
</xsl:choose>
</severity>
</Alert>
</xsl:for-each>
</EMAlerts>
</xsl:template>
</xsl:stylesheet>
<?xml version='1.0' ?>
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:a="http://www.microsoft.com/EnterpriseManagement/Mom/Connector/V2">
<xsl:template match="/">
<EMAlerts>
<xsl:for-each select="a:GetDataResponse/a:GetDataResult/a:UpdatedAlerts/a:Alert">
<Alert>
<key1>
<xsl:value-of select="a:AlertId"/>
</key1>
<key2>
<xsl:value-of select="a:ComputerName"/>
</key2>
<key3>
<xsl:value-of select="a:ComputerDomain"/>
</key3>
<key4>
<xsl:value-of select="a:Name"/>
</key4>
<key5>
<xsl:value-of select="a:RuleId"/>
</key5>
<message>
<xsl:value-of select="a:Description"/>
</message>
<producerID>xyz</producerID>
<targetName>
<xsl:value-of select="a:ComputerName"/>
</targetName>
<targetType>hp_managed_host</targetType>
<timeStamp>
<xsl:value-of select="a:TimeLastModified"/>
</timeStamp>
<username></username>
<password></password>
<metricName>
<xsl:value-of select="a:Source"/>
</metricName>
<category>
<xsl:value-of select="a:Source"/>
</category>
<value>
<xsl:value-of select="a:sth"/>
</value>
<severity>
<xsl:variable name="momseverity" select="a:Severity"/>
<xsl:variable name="criticalerror">CriticalError</xsl:variable>
<xsl:variable name="error">Error</xsl:variable>
<xsl:variable name="warning">Warning</xsl:variable>
<xsl:variable name="information">Information</xsl:variable>
<xsl:variable name="securityissue">SecurityIssue</xsl:variable>
<xsl:variable name="unknown">Unknown</xsl:variable>
<xsl:variable name="serviceunavailable">ServiceUnavailable</xsl:variable>
<xsl:variable name="success">Success</xsl:variable>
<xsl:variable name="emclear">Clear</xsl:variable>
<xsl:variable name="emcritical">Critical</xsl:variable>
<xsl:variable name="emwarning">Warning</xsl:variable>
<xsl:variable name="eminformational">Informational</xsl:variable>
<xsl:choose>
<xsl:when test="$momseverity = $criticalerror">
<xsl:value-of select="$emcritical"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $unknown">
<xsl:value-of select="$eminformational"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $error">
<xsl:value-of select="$emcritical"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $securityissue">
<xsl:value-of select="$emcritical"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $warning">
<xsl:value-of select="$emwarning"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $serviceunavailable">
<xsl:value-of select="$eminformational"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $information">
<xsl:value-of select="$eminformational"/>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="$momseverity = $success">
<xsl:value-of select="$emclear"/>
</xsl:when>
</xsl:choose>
</severity>
</Alert>
</xsl:for-each>
</EMAlerts>
</xsl:template>
</xsl:stylesheet>
The getResponse operation is mapped to a Web service. The connector framework uses it to determine the response of the existing target in Enterprise Manager for the defined target type.
Table 2-4 provides the metadata details. The required meta files are similar to any other methods described in "Default Request XML Files".
Note:
The Response Metric Collection script does not apply for building the MOM Connector.Table 2-4 Metadata for getResponse Operation
| Value | Description |
|---|---|
|
getResponse_request.xml |
Template to generate the |
|
getResponse_request.xsl |
Transforms |
T he status returned should be transformed into the following status codes:
0 — Target down 1 — Target up
If neither value applies, the target status displays as Pending.
To determine the response status, Enterprise Manager connector sends getResponse_request.xml in the following format:
<?xml version="1.0" encoding="utf-8" ?> <GetResponseRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Target> <Name>SMP-MPI2</Name> <InstanceProperty> <Name>host name</Name> <Value>smp-mpi2.us.oracle.com</Value> </InstanceProperty> <!-- InstanceProperty can repeat multiple times. InstanceProperty are the properties that can identify the managed entity in the external system. --> </Target> <!-- Target element can repeat. --> <Attribute> <Name>RegistrationId</Name> <Value>$REGISTRATION_ID$</Value> <!-- one example is RESITRATION_ID, <Name>registrationId</Name><Value>$REGISTRATION_ID$</Value> --> </Attribute> </GetResponseRequest>
In this case, you have to define an XSL file named getResponse_request.xsl to compute and return a response to Enterprise Manager in the following XML format that Enterprise Manager can understand:
<?xml version="1.0" encoding="utf-8" ?> <GetResponseReponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Target> <Name>SMP-MPI2</Name> <Type>hp_managed_node</Type> <Status>0<Status> </Target> </GetResponseResponse>
Based on the response above, the status of the target is updated in Enterprise Manager.
To complete the integration of the connector, package all XML and XSL files (defined in the section "Defining XML and XSL Files") as a .jar file and then deploy, register, and configure the connector. To do this:
Copy the .jar file to the Oracle Management Service (OMS). For multiple OMSs, copy the .jar file for all OMSs.
Run the following command on all OMS's:
emctl extract_jar connector [-jar <jarfile>] [-cname <connectorName>]
Where -jar is the Connector Jar File(full path) and -cname is the Connector Name
Files are extracted from the .jar file to the following directory:
$ORACLE_HOME/sysman/connector/connector name_wo_space
The command replaces the spaces in the connector_name with an underscore ("_") in connector_name_wo_space.
Deploy the connector by running the following command:
emctl register_connector connector [-dd <connectorType.xml>] [-repos_pwd <repos password>]
Where -dd is the Connector Deployment Descriptor File (full path) and -repos_pwd is the Enterprise Manager Root (SYSMAN) Password.
Table 2-5 lists the emctl parameters and provides a description for each.
| Parameter | Description |
|---|---|
|
|
The connector deployment descriptor. |
|
|
Fully qualified name of the ticket template file. The file resides in the Connector home directory:
Oracle recommends that you use intuitive names since there might be notification methods created with the same names, and you have to choose one of them when you use the Auto Ticketing feature. Use If the file is in a different directory, provide the complete path for the file. |
|
|
Host name of the Enterprise Manager repository. |
|
|
Listener port of the repository. |
|
|
Repository database instance ID or service name if you are using a RAC database as the repository. |
|
|
Specify |
|
|
Password for |
|
|
Connector type name you define in |
|
|
Connector name. This should be the same as the connector type name. For example, |
|
|
An intuitive name for the ticket template that will be displayed in Enterprise Manager. |
|
|
A short description for the ticket template. This description is also displayed in Enterprise Manager. |
|
|
Jar file, full jar file path |
|
|
Connector name |
|
|
Connector type name |
|
|
Connector descriptor file, full path |
|
|
Enterprise Manager root (SYSMAN) password |
|
|
Template file, full path |
|
|
Internal name (For details about this parameter, you can refer to the existing Connector documentation.) |
|
|
Template name |
|
|
Template type |
|
|
Template description |
Log into the Enterprise Manager console and configure the event connector as described in the next section.
To register a template, run the following command:
emctl register_template connector [-t <template.xsl>] [-repos_pwd <repos password>] [-ctname <connectorTypeName>] [-cname <connectorName>] [-iname <internalName>] [-tname <templateName>] [-ttype <templateType>] [-d <description>]
Where the following parameters apply:
-t Template(full path)
-repos_pwd Enterprise Manager Root (SYSMAN) Password
-ctname Connector Type Name
-cname Connector Name
-iname Template Internal Name
-tname Template Name Displayed
-ttype Template Type
<templateType> 1 - inbound transformation
<templateType> 2 - outbound transformation
<templateType> 3 - XML outbound transformation
-d Description
To configure the event connector:
As Super Administrator from the Enterprise Manager Grid Control console, click Setup.
The Overview of Setup page appears.
Click Management Connectors.
The Management Connectors Setup page appears. A row with the connector name you defined should appear in this page.
Click the Configure icon of the connector that you registered.
The connector configuration page and the General tab of the Configure Management Connector page appear.
Configure all mandatory fields indicated with an asterisk ( * ).
Click OK.
The Management Connector Setup page reappears. The row for the connector you defined should have a check mark in the Configured column.
When you deploy or install an event connector, the default target instance is created when the connector is configured instead of registered. The default target instance holds all the external events retrieved by this event connector if no other targets are created. You can optionally create specific targets to hold external events.
Do the following to create additional target instances:
From the Enterprise Manager console, click Setup.
The setup links appear in the left margin.
Click Management Connectors.
The Management Connectors home page appears. A row with the connector name you defined should appear in this page.
Click Configure icon for the Event Connector, then click the Targets tab.
The Targets page appears.
In the Targets page, you can do the following:
To add a target, specify the Target Name and other required properties, then click OK.
To remove any added target, select the target, click Remove, then click OK.
To enable a generic target (not available or deleted), click Enable.
After the transformation, if the incoming alert has a target name that matches the target name defined in Enterprise Manager, the alert is associated with that target. Otherwise, the alerts are redirected to the default target instance, generic_target_type. For example, if the connector contains a target type called my_managed_device, the default target instance will be generic_my_managed_device.
Beginning with Enterprise Manager 10g Release 4, you can send alerts to external systems in real time through Web services. You can choose which type of alerts to send, such as critical alerts on a production database. Enterprise Manager 10g Release 4 supports metric alerts. You can also enforce the registration for external systems to retrieve real-time information.
To send alerts, your external system needs to support the following:
"create event" and "update event" literal-document style Web services, as described in the following section.
IP-based or SOAP header-based authentication.
You also need to change the connector built for alert exchange as described in the following sections.
The following mappings are required:
createEvent
updateEvent
Deployment Descriptor File Example
The code in bold shows the additions for createEvent and updateEvent.
<ManagementConnector xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/sysman/connector">
<Name>specify the connector name</Name>
<Version>specify the 5-digit version, e.g., 1.0.0.0.0</Version>
<Description>specify a short description</Description>
<Category>EventConnector</Category>
<!-- Category is fixed to EventConnector. -->
<EventConnector>
<!-- If IsNewTargetType is set to true, it means the developers want to define a new target type to hold external alerts. In that case, targetType.xml and defaultTargetType.xml need to be shipped in the connector jar. -->
<IsNewTargetType>true</IsNewTargetType>
<EventService>
<Method>getNewAlerts</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>getUpdatedAlerts</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>acknowledgeAlerts</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>setup</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>destroy</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>createEvent</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<EventService>
<Method>updateEvent</Method>
<WebServiceEndpoint>
<![CDATA[specify the URL]]>
</WebServiceEndpoint>
<SOAPAction>specify the SOAP action</SOAPAction>
<Namespace>specify the namespace</Namespace>
<NamespacePrefix>specify the namespace prefix</NamespacePrefix>
</EventService>
<!-- BaseURL element is for the default UI for event connectors, the following value should not be changed. -->
<BaseURL>/em/console/connector/event/configuration</BaseURL>
</EventConnector>
</ManagementConnector>
The following request transformation files are required:
createEvent_request.xsl
updateEvent_request.xsl
You can use the EMEvent.xsd schema to decide which Enterprise Manager fields you want to make available for mapping when sending alerts to external systems. The schema is available in the following path:
$ORACLE_HOME/sysman/connector/common/schema/EMEvent.xsd
Example files and the schema are shown below.
createEvent_request.xsl Transformation File Example
<?xml version='1.0' ?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:ns0="..."
xmlns:a="http://xmlns.oracle.com/sysman/connector">
<xsl:template match="a:EMEvent">
<ns0:InsertAlerts>
<ns0:registrationId>
<xsl:for-each select="a:Property">
<xsl:if test="a:Name = 'REGISTRATION_ID'">
<xsl:value-of select="a:Value"/>
</xsl:if>
</xsl:for-each>
</ns0:registrationId>
<ns0:alerts>
<ns0:AlertInsert>
<ns0:Name>
<xsl:value-of select="a:MetricColumn"/>
</ns0:Name>
<ns0:ComputerName>
<xsl:value-of select="a:TargetHost"/>
</ns0:ComputerName>
<ns0:ComputerDomain></ns0:ComputerDomain>
<ns0:Description>
<xsl:value-of select="a:CollectionTime"/>
Received alert reported by Oracle Enterprise Manager:
Target Type: <xsl:value-of select="a:TargetType"/>
Target Name: <xsl:value-of select="a:TargetName"/>
Metric Name: <xsl:value-of select="a:MetricName"/>
Metric Column: <xsl:value-of select="a:MetricColumn"/>
<xsl:choose>
<xsl:when test="a:KeyValues">
Key Values: <xsl:for-each select="a:KeyValues">
<xsl:value-of select="."/>;
</xsl:for-each>
</xsl:when>
</xsl:choose>
Severity: <xsl:value-of select="a:Severity"/>
<xsl:choose>
<xsl:when test="normalize-space(a:NotificationRuleName) != ''">
Notification Rule: <xsl:value-of select="a:NotificationRuleName"/>
</xsl:when>
</xsl:choose>
Message: <xsl:value-of select="a:Message"/>
</ns0:Description>
<ns0:Severity>
<xsl:choose>
<xsl:when test="a:SeverityCode = '15'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '18'">Information</xsl:when>
<xsl:when test="a:SeverityCode = '20'">Warning</xsl:when>
<xsl:when test="a:SeverityCode = '25'">CriticalError</xsl:when>
<xsl:when test="a:SeverityCode = '115'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '125'">Warning</xsl:when>
<xsl:when test="a:SeverityCode = '215'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '225'">Warning</xsl:when>
<xsl:when test="a:SeverityCode = '315'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '325'">Error</xsl:when>
<xsl:otherwise>Error</xsl:otherwise>
</xsl:choose>
</ns0:Severity>
<ns0:Source>
<xsl:value-of select="a:TargetType"/>: <xsl:value-of select="a:TargetName"/>
</ns0:Source>
<ns0:TimeRaised>
<xsl:value-of select="a:CollectionTime"/>
</ns0:TimeRaised>
</ns0:AlertInsert>
</ns0:alerts>
</ns0:InsertAlerts>
</xsl:template>
</xsl:stylesheet>
updateEvent_request.xsl Transformation File Example
<?xml version='1.0' ?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:ns0="..."
xmlns:a="http://xmlns.oracle.com/sysman/connector">
<xsl:template match="a:EMEvent">
<ns0:UpdateAlerts>
<ns0:registrationId>
<xsl:for-each select="a:Property">
<xsl:if test="a:Name = 'REGISTRATION_ID'">
<xsl:value-of select="a:Value"/>
</xsl:if>
</xsl:for-each>
</ns0:registrationId>
<ns0:updatedAlerts>
<ns0:AlertUpdate>
<ns0:AlertId>
<xsl:value-of select="a:ExternalEventId"/>
</ns0:AlertId>
<ns0:OwnerNameUseExisting>true</ns0:OwnerNameUseExisting>
<ns0:SeverityUseExisting>false</ns0:SeverityUseExisting>
<xsl:variable name="Severity">
<xsl:choose>
<xsl:when test="a:SeverityCode = '15'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '18'">Information</xsl:when>
<xsl:when test="a:SeverityCode = '20'">Warning</xsl:when>
<xsl:when test="a:SeverityCode = '25'">CriticalError</xsl:when>
<xsl:when test="a:SeverityCode = '115'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '125'">Warning</xsl:when>
<xsl:when test="a:SeverityCode = '215'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '225'">Warning</xsl:when>
<xsl:when test="a:SeverityCode = '315'">Success</xsl:when>
<xsl:when test="a:SeverityCode = '325'">Error</xsl:when>
<xsl:otherwise>Error</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<ns0:Severity>
<xsl:value-of select="$Severity"/>
</ns0:Severity>
<xsl:choose>
<xsl:when test="a:SeverityCode = '15'">
<ns0:ResolutionStateUseExisting>false</ns0:ResolutionStateUseExisting>
<ns0:ResolutionState>255</ns0:ResolutionState>
</xsl:when>
<xsl:otherwise>
<ns0:ResolutionStateUseExisting>true</ns0:ResolutionStateUseExisting>
<ns0:ResolutionState>0</ns0:ResolutionState>
</xsl:otherwise>
</xsl:choose>
<ns0:LastModifiedByUseExisting>true</ns0:LastModifiedByUseExisting>
</ns0:AlertUpdate>
</ns0:updatedAlerts>
</ns0:UpdateAlerts>
</xsl:template>
</xsl:stylesheet>
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/sysman/connector"
targetNamespace="http://xmlns.oracle.com/sysman/connector"
elementFormDefault="qualified">
<xsd:include schemaLocation="EMEventType.xsd"/>
<xsd:element name= "EMEvent" type="EMEventType"/>
</xsd:schema>
<?xml version="1.0" encoding="US-ASCII" ?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified">
<xsd:complexType name="EMEventType">
<xsd:sequence>
<xsd:element name="TicketId" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="ConnectorId" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="EventId" type="EventIdType" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="EventGuid" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="ExternalEventId" type="xsd:string"
minOccurs="0" maxOccurs="1"/>
<xsd:element name="ViolationId" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="EventType" type="EventTypeType" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="TargetType" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="TargetName" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="TargetProperties" type="TargetPropertiesType"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="MetricColumn" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="MetricName" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="KeyColumn" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="KeyValues" type="xsd:string" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="Message" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="Severity" type="SeverityType" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="SeverityCode" type="SeverityCodeType"
minOccurs="0" maxOccurs="1"/>
<xsd:element name="JobID" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="JobName" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="JobType" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="JobOwner" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="JobStatus" type="JobStatusType" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="JobStatusCode" type="JobStatusCodeType" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="JobTarget" type="JobTargetType" minOccurs="0"
maxOccurs="unbounded"/>
<xsd:element name="StepOutput" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="CollectionTime" type="xsd:dateTime"
minOccurs="1" maxOccurs="1"/>
<xsd:element name="EventPageURL" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="EMUser" type="xsd:string" minOccurs="1"
maxOccurs="1"/>
<xsd:element name="HDUser" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="NotificationRuleName" type="xsd:string"
minOccurs="0" maxOccurs="1"/>
<xsd:element name="TargetHost" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="GracePeriodCheckMade" type="xsd:string"
minOccurs="0" maxOccurs="1"/>
<xsd:element name="TargetTimezone" type="xsd:string"
minOccurs="1" maxOccurs="1"/>
<xsd:element name="Property" type="PropertyType" minOccurs="0"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="TargetPropertiesType">
<xsd:sequence>
<xsd:element name="name" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
<xsd:element name="value" type="xsd:string"
minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="EventIdType">
<xsd:sequence>
<xsd:element name="TargetId" type="xsd:string" minOccurs="1"
maxOccurs="1"/>
<xsd:element name="MetricId" type="xsd:string" minOccurs="1"
maxOccurs="1"/>
<xsd:element name="KeyId" type="xsd:string" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="SeverityType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Clear"/>
<xsd:enumeration value="Info"/>
<xsd:enumeration value="Warning"/>
<xsd:enumeration value="Critical"/>
<xsd:enumeration value="Unreachable Clear"/>
<xsd:enumeration value="Unreachable Start"/>
<xsd:enumeration value="Blackout End"/>
<xsd:enumeration value="Blackout Start"/>
<xsd:enumeration value="Metric Error End"/>
<xsd:enumeration value="Metric Error Start"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="SeverityCodeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="15"/>
<xsd:enumeration value="18"/>
<xsd:enumeration value="20"/>
<xsd:enumeration value="25"/>
<xsd:enumeration value="115"/>
<xsd:enumeration value="125"/>
<xsd:enumeration value="215"/>
<xsd:enumeration value="225"/>
<xsd:enumeration value="315"/>
<xsd:enumeration value="325"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="PropertyType">
<xsd:sequence>
<xsd:element name="Name" type="xsd:string"/>
<xsd:element name="Value" type="xsd:string" nillable="true"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="EventTypeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Alert"/>
<xsd:enumeration value="JobStatus"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:complexType name="JobTargetType">
<xsd:sequence>
<xsd:element name="TargetName" type="xsd:string"/>
<xsd:element name="TargetType" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="JobStatusType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="Scheduled"/>
<xsd:enumeration value="Running"/>
<xsd:enumeration value="Error"/>
<xsd:enumeration value="Failed"/>
<xsd:enumeration value="Succeeded"/>
<xsd:enumeration value="Suspended by User"/>
<xsd:enumeration value="Suspended on Agent Unreachable"/>
<xsd:enumeration value="Stopped"/>
<xsd:enumeration value="Suspended on Lock"/>
<xsd:enumeration value="Suspended on Event"/>
<xsd:enumeration value="Suspended on Blackout"/>
<xsd:enumeration value="Stop Pending"/>
<xsd:enumeration value="Suspend Pending"/>
<xsd:enumeration value="Inactive"/>
<xsd:enumeration value="Queued"/>
<xsd:enumeration value="Failed and Retried"/>
<xsd:enumeration value="Waiting"/>
<xsd:enumeration value="Skipped"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="JobStatusCodeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="1"/>
<xsd:enumeration value="2"/>
<xsd:enumeration value="3"/>
<xsd:enumeration value="4"/>
<xsd:enumeration value="5"/>
<xsd:enumeration value="6"/>
<xsd:enumeration value="7"/>
<xsd:enumeration value="8"/>
<xsd:enumeration value="9"/>
<xsd:enumeration value="10"/>
<xsd:enumeration value="11"/>
<xsd:enumeration value="12"/>
<xsd:enumeration value="13"/>
<xsd:enumeration value="14"/>
<xsd:enumeration value="15"/>
<xsd:enumeration value="16"/>
<xsd:enumeration value="17"/>
<xsd:enumeration value="18"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:schema>
The following response transformation files are required:
createEvent_response.xsl
updateEvent_response.xsl
You can use the EMEventResponse.xsd schema to decide how to transform the response from external systems to the expected response from Enterprise Manager. The schema is available in the following path:
$ORACLE_HOME/sysman/connector/common/schema/EMEventResponse.xsd
After the transformation, Enterprise Manager expects a <SuccessFlag> and one of the following elements depending on the value:
true — Enterprise Manager expects an <externalEventID>, which is the ID of the alert in the external system. This is used to update the alert in the future.
false — Enterprise Manager expects an <ErrorMessage>. Enterprise Manager annotates the alert with the externalEventID or ErrorMessage.
Example files and the schema are shown below.
createEvent_response.xsl Response Transformation File Example
<?xml version='1.0' ?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:ns0="..."
xmlns:a="http://xmlns.oracle.com/sysman/connector">
<xsl:template match="ns0:InsertAlertsResult">
<a:EMEventResponse>
<xsl:choose>
<xsl:when test="ns0:InsertedAlerts/ns0:SuccessfulAlertInsert/ns0:NewAlertId">
<a:SuccessFlag>true</a:SuccessFlag>
<a:ExternalEventId>
<xsl:value-of select="ns0:InsertedAlerts/ns0:SuccessfulAlertInsert/ns0:NewAlertId"/>
</a:ExternalEventId>
</xsl:when>
<xsl:otherwise>
<a:SuccessFlag>false</a:SuccessFlag>
<a:ErrorMessage>
<xsl:value-of select="ns0:FailedAlerts/ns0:FailedAlertInsert/ns0:Error"/>
</a:ErrorMessage>
</xsl:otherwise>
</xsl:choose>
</a:EMEventResponse>
</xsl:template>
</xsl:stylesheet>
updateEvent_response.xsl Response Transformation File Example
<?xml version='1.0' ?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:ns0="..."
xmlns:a="http://xmlns.oracle.com/sysman/connector">
<xsl:template match="ns0:UpdateAlertsResult">
<a:EMEventResponse>
<xsl:choose>
<xsl:when test="ns0:UpdatedAlerts/ns0:guid">
<a:SuccessFlag>true</a:SuccessFlag>
<a:ExternalEventId>
<xsl:value-of select="ns0:UpdatedAlerts/ns0:guid"/>
</a:ExternalEventId>
</xsl:when>
<xsl:otherwise>
<a:SuccessFlag>false</a:SuccessFlag>
<a:ErrorMessage>
<xsl:value-of select="ns0:FailedUpdatedAlerts/ns0:FailedAlertUpdate/ns0:Error"/>
</a:ErrorMessage>
</xsl:otherwise>
</xsl:choose>
</a:EMEventResponse>
</xsl:template>
</xsl:stylesheet>
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="http://xmlns.oracle.com/sysman/connector"
targetNamespace="http://xmlns.oracle.com/sysman/connector"
elementFormDefault="qualified">
<xsd:element name="EMEventResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="SuccessFlag" type="xsd:boolean"
minOccurs="1" maxOccurs="1"/>
<xsd:choice>
<xsd:element name="ExternalEventId" type="xsd:string"
minOccurs="1" maxOccurs="1"/>
<xsd:element name="ErrorMessage" type="xsd:string"
minOccurs="1" maxOccurs="1"/>
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Follow the steps provided in this section if you choose HTTPS as the protocol to establish a connection between the external eventing system and Enterprise Manager.
Generate a certificate request file for the external eventing system and send it to the Certificate authority, such as VeriSign.
Note:
The certificate request file is dependent on the Web server the external eventing system uses.After you get the certificate, import it to the Web server the external eventing system uses. The import mechanism varies depending on the Web server the external eventing system uses.
Note:
Oracle Wallet Manager is available at$ORACLE_HOME/bin on OMS. See the Oracle Application Server Administrator's Guide for details.Get the port number from user_projects/domains/EMGC_DOMAIN/config/config.xml:
<server> <name>EMGC_ADMINSERVER</name> <ssl> <name>EMGC_ADMINSERVER</name> <enabled>true</enabled> <hostname-verification-ignored>true</hostname-verification-ignored> <listen-port>7022</listen-port> </ssl> <listen-port-enabled>false</listen-port-enabled> <listen-address>server_name</listen-address> </server>
Connect to the WebLogic Admin Console:
Connect to https://server_name:7022/console/, login: [username]/[password]
Navigate to Environment->Servers->EMGC_DOMAIN->Keystore tab
If two-way SSL is required for external web service, go to SSL->Advanced->Use Server Certs and be sure it is checked
Make sure that CA signed the external system server's certificate is added to trustStore specified in the Keystore tab, for example, WebLogic's DemoTrust, or java standard cacerts
See Also:
For information on creating an Oracle Wallet, see "Creating and Viewing Oracle Wallets with orapki" in the Oracle Database Advanced Security Administrator's Guide, 10g Release 2 (10.2).