Oracle® Enterprise Manager Connectors Integration Guide 11g Release 1 (11.1.0.0) E17065-02 |
|
![]() Previous |
![]() Next |
A Data Exchange Connector is a JMS server-based integration vehicle that helps you to build a bi-directional data exchange setup between Enterprise Manager and other management systems. The Data Exchange Connector architecture is based on open standards such as Java Message Service (JMS) and XML. This helps in facilitating easy extensibility and interoperability.
The data exchange environment necessitates creation of a data exchange hub and data exchange sessions. This chapter explains the key concepts, components, and features involved in the data exchange process.
Also provided are specific steps to integrate Enterprise Manager with Oracle Business Activity Monitoring Server (OBAM).
This chapter discusses these topics:
Typically, an enterprise may have Enterprise Manager monitoring most of the systems and services within it. However, other monitoring systems or external management systems such as the OBAM server might also exist within the business environment of the enterprise. These management systems and Enterprise Manager might be collecting monitoring information that is different, yet related to the same business application. It is imperative for the business that Enterprise Manager and these external management systems co-exist and interact seamlessly.
A Data Exchange Connector effectively addresses this communication requirement by transferring data in XML format using JMS Topic or Queue messages. This is made possible by creating a data exchange hub and a data exchange session.
Figure 3–1 provides an architectural overview of the Data Exchange Connector.
Table 3-1 explains the data requirements and purpose of data exchange between Enterprise Manager and an external management system.
Table 3-1 Data Exchange between Enterprise Manager and External Management System
Data Exchange | Requirement | Purpose |
---|---|---|
From Enterprise Manager to external management system |
|
|
From external management system to Enterprise Manager |
|
|
Integrating the two systems using Data Exchange Connector helps the systems to complement each other and serve business requirements effectively and economically.
The following list explains the normal process followed when sending data from Enterprise Manager to external management systems.
Only real-time metric and availability values are forwarded. Historical data is not forwarded.
Metric data is forwarded in batches at scheduled intervals. In each batch, a maximum of 100 data points can be sent. An interval of two seconds is maintained between subsequent forwarding to reduce the JMS server load.
For a given metric, all new data points in the interval are sent to the external system. If there are no new values, no data is sent. For the initial forwarding, data points since the previous one hour are considered.
For example, if an outbound session is scheduled from 9:00 a.m. to 9:00 p.m. with an interval frequency of 30 minutes, initially (at 9:00 a.m.) metric values collected between 8:00 a.m. and 9:00 a.m. are forwarded. Subsequently, the metric values received in that interval are sent. So at 9:30 a.m., metric values received between 9:00 a.m. and 9:30 a.m., and at 10:00 a.m. metric values received between 9:30 a.m. and 10:00 a.m., are forwarded.
Alerts are sent without latency. Each outbound message only has one alert embedded in it.
Service-level Agreement (SLA) data sent out is the SLA value for the past 24 hours. If an outbound session with an SLA metric is scheduled at January 15th at 4:00 p.m., the value sent out is the SLA value from January 14th at 4:01 pm to January 15th at 4:00 p.m.
The following sections explain the major concepts that you must understand to successfully set up a data exchange environment between Enterprise Manager and an external management system.
A data exchange hub is a JMS-compliant server that acts as the conduit between Enterprise Manager and an external management system. Data is sent and received between external systems and Grid Control through such a hub. The hub should be configured with known JMS destination information (Outbound JMS Destinations) so that the messages can be sent and retrieved seamlessly. The Data Exchange Hub page shows a list of existing Data Exchange hubs and their related JNDI Service Provider URLs, provided that at least one hub has already been created. Examples of a hub are WebLogic Server (WLS), Oracle Containers for JEE (OC4J), and so forth.
See Also: "Creating a Data Exchange Hub" on page 3-5 |
An inbound data exchange session is created to receive business indicators, events, or both from the data source of an external system to Enterprise Manager.
An outbound data exchange session is created to send metric values, alerts, target availability, or a combination of them from Enterprise Manager to an external system.
The data can be sent in either of the following formats:
Normalized message format
Denormalized message format
In this format, data is sent in two phases.
Session Setup Phase — Meta information for targets and metrics such as target name, target type, metric name, and metric column are sent along with their GUIDs when the session is created in Enterprise Manager Grid Control.
Session Execution Phase — Actual metrics are sent when the session is executed. They are tagged with the GUIDs to avoid sending redundant meta information for every message, thereby keeping the wire footprint low.
This message format is effective if the external system is backed by a persistence store, such as a database, so that it can retrieve the metadata by joining the tables when rendering the charts or reports based on GUIDs.
In this format, target and metric meta information is sent along with every message in the session execution phase. No messages are sent during the session setup phase. This message format is effective if the external system is not backed by a persistence store. Though each message repeats the meta information, digesting the data for charting and reporting is easier.
To correctly parse and interpret the contents, it is imperative for the external system to understand the syntax and semantics of the XML messages embedded in the JMS destinations. The schema of the message varies depending on the message format (normalized or denormalized).
The same JMS destinations are used for both formats; therefore, sessions with different message formats should not run concurrently because it confuses the consumer of these messages. Oracle recommends that the sessions with different formats be run exclusively.
Data source is a logical representation of an external system source from which business indicators or events are retrieved. A data source definition represents the following:
The structure and schema of the business content (business indicators) received from the external system.
The transport (JMS destinations) information by way of which the external data (business events and indicators) is received.
Associated target in Enterprise Manager to which the external data (business events and indicators) is associated.
From Enterprise Manager Grid Control, click Setup.
The setup links appear in the left margin.
Click Data Exchange.
The Data Exchange page appears as shown in Figure 3–2.
Set up the Data Exchange Connector.
The following sections provide information required to set up a Data Exchange Connector:
Any certified JMS-compliant server can act as a hub. The following are tested and certified:
WebLogic Server 8.1 series and above
OC4J 10.1.3.1 series
Oracle Enterprise Service Bus (OESB) 10.1.3.1 series
OC4J 10.1.2.0 series
Do the following to create a data exchange hub:
In the Data Exchange: Data Exchange Hub page (Figure 3–2), click Create. The Create Data Exchange Hub page appears, as shown in Figure 3–3.
Specify a unique name for the Data Exchange hub.
Provide the JNDI Service Provider URL for the Data Exchange hub.
Select a context factory name from the list according to the matrix in Table 3–2.
Table 3-2 Context Factory Name
Hub Corresponds to ... | Context Factory |
---|---|
WebLogic Server |
weblogic.jndi.WLInitialContextFactory |
10.1.2.X OC4J |
com.evermind.server.rmi.RMIInitialContextFactory |
10.1.3.X OC4J |
oracle.j2ee.rmi.RMIInitialContextFactory |
Non-WebLogic Server and non-OC4j JMS Server |
For third-party servers, select Other and provide a factory name in the Enter JNDI Initial Context Factory Name field. |
Provide the user credentials to access this hub.
Configure the JMS server with the required JMS topic names and/or queue names.
See Also: "Inbound JMS Destinations" on page 27 |
Click OK to save the configuration and return to the Data Exchange: Data Exchange Hub page.
After you create a hub for data exchange, you can set up an outbound or inbound data exchange session.
To create an outbound data exchange session, specify the input provided in the following procedure for the respective pages of the setup wizard.
From the Data Exchange page, click the Outbound Data Exchange Session link.
Click Create. The Session Setup step of the wizard appears.
Ensure that you have access to at least one Data Exchange hub that is configured with the topics to receive data from Enterprise Manager. To set up a Data Exchange hub, see "Creating a Data Exchange Hub" on page 3-5.
Specify a unique name for this outbound data exchange session in the Name field.
Select a Data Exchange hub from the list of hubs already created and listed alphabetically. By default, the first hub in the list is selected.
In the Users field, enter the name of a BAM user or a comma-separated list of BAM users (for example: user1, user2) on the external system who can access the data being sent. The name or name of these users for this session will be associated with the Oracle BAM server. The receiving system must interpret and enforce security. If you leave this field blank, no user information is sent.
For the Destination Type drop-down, select one of the messaging models to send or receive messages from Grid Control. Queues provide point-to-point messaging interaction based on Queue logic. Topics provide broadcast model-based subscription methodology.
If the session uses Topic as the Destination Type, all messages for this session are sent on the corresponding pre-defined topics. For Queues, all messages are sent on the pre-defined Queues. Mix-and-match of destination types for a particular session is not supported.
Select either a Normalized or Denormalized message format. For more information on these formats, see "Outbound Data Exchange Session" on page 3-3.
Click Next. The Select Targets and Metrics/Alerts/Availability step of the wizard appears.
Click the search icon to invoke the Search and Select Targets pop-up, choose a target that is to be part of the Data Exchange transactions being set up, then click Select. A list of all metrics and objects for the target now appear on the Add Target page.
Specify which metrics and alerts you want to send during the outbound session for the target. Specify which metrics and alerts you want to send during the outbound session for the target. You can use the batch selection buttons if you want to select or deselect all targets and all alerts.
You need to select Send Metric Values for the Availability metric for target availability information.
You cannot select the Send Alerts for the Service-Level Agreement (SLA) metric. This metric is only applicable and available for service targets. For example, host targets do not have this metric.
Some metrics may require you to specify an object. For example, you can qualify the Filesystem Space Available (%) metric by the name of a particular mount point.
Click OK to save your selections and return to the Select Targets and Metrics/Alerts/Availability step.
You can now view or edit your selections. You can also use your selections as a template for another target by clicking the Add-like icon.
Click Next if you are satisfied with your metric values and alerts selections. The Schedule step of the wizard appears. Select one of the following scheduling choices:
Schedule Later — You can defer scheduling and subsequently schedule the session from the Outbound Data Exchange Session sub-page after you click Finish in the Review step of the wizard.
Schedule Now — Choose one of the following sub-types:
One Time (Immediately): If you select this option, the session runs once just when you finish creating it.
One Time (Later): If you select this option, you need to specify a time zone and a start date and time for the session.
Repeating: For this default option, you need to specify the time zone and the start time. Additionally, you can specify the frequency type and interval at which you want the session to run, and whether it should be repeated indefinitely or until a specified time and date.
Click Next or Review to go to the Review step of the wizard.
If you need to make changes, click Back until you reach the step you need to change. Otherwise, go to the next step.
Click Finish. The Outbound Data Exchange Session sub-page reappears and shows your newly created session and its status in the table.
Before the job finishes executing, you can either view the schedule by clicking the View Schedule link in the Actions column and then stop the execution if desired, or you can stop the execution immediately by clicking Stop.
Predefined topic and queue names are used to send data from Enterprise Manager to external systems through the hub. You should configure the data exchange hub with the JMS destination information specified in Table 3–3 through Table 3–9. It is not mandatory to define both topics and queues. If you always want to use the topics, for example, you can remove the queue definitions or not initially create them, and vice versa.
Example - Configuring JMS Destinations for WebLogic Server
You can use any JMS-compliant server with the Data Exchange Connector as described in this example.
To configure the JMS destinations for WebLogic Server, do the following:
Use the pre-packaged WLST python scripts available in the $ORACLE_HOME/sysman/bam directory.
Set the proper CLASSPATH before going to the next step. You can set the CLASSPATH by running setWLSEnv.sh found under ORACLE_HOME (typically in the middleware/wlserver_10.3/server/bin directory).
Use configEMSYSJMSSystemResource.py found in the directory in step 1 to create the required JMS topics and queues:
java weblogic.WLST createEMSYSJMSSystemResource.py <jndi provider URL> <username> <password> <WLS server name>
Example:
java weblogic.WLST createEMSYSJMSSystemResource.py "t3://localhost:7001" weblogic welcome1 AdminServer
A successful run of the script produces the following components:
Resources and Destinations:
EMSYSJMSServer for JMS Server
EMSYSJMSSystemResource for JMS System Resource
EMSYSJMSServerDeployment for sub-deployment
Connection Factories:
jms/EMSYSTopicConnectionFactory
jms/EMSYSQueueConnectionFactory
Topics:
jms/EMSYSTargetsTopic
jms/EMSYSMetricsTopic
jms/EMSYSAlertsDataTopic
jms/EMSYSMetricsDataTopic
jms/EMSYSSecurityFilterTopic
jms/EMSYSTargetStatusTopic
jms/EMSYSTargetSLATopic
Queues:
jms/EMSYSTargetsQueue
jms/EMSYSMetricsQueue
jms/EMSYSAlertsDataQueue
jms/EMSYSMetricsDataQueue
jms/EMSYSSecurityFilterQueue
jms/EMSYSTargetStatusQueue
jms/EMSYSTargetSLAQueue
Use EMSYSJMSSystemResource.py to remove and clean up the JMS destinations the script createEMSYSJMSSystemResource.py created. CLASSPATH should also be set as defined in Step 2 for the following command:
java weblogic.WLST deleteEMSYSJMSSystemResource.py <jndi provider URL> <username> <password>
Example:
java weblogic.WLST deleteEMSYSJMSSystemResource.py "t3://localhost:7001" weblogic welcome1
The JMS destinations shown in Table 3–3 are used for an outbound Data Exchange session.
Table 3-3 JMS Destination for Targets
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSTargetsTopic or jms/EMSYSTargetsQueue |
JMS Message Type |
Text message |
Description |
Target metadata information, such as target name and type are sent on this destination. |
Note:
|
Table 3-4 JMS Destination for Metrics
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSMetricsTopic or jms/EMSYSMetricsQueue |
JMS Message Type |
Text message |
Description |
Metric metadata information, such as metric name, column, and target type are sent on this destination. |
Table 3-5 JMS Destination for Metric Data
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSMetricsDataTopic or jms/EMSYSMetricsDataQueue |
JMS Message Type |
Text message |
Description |
This destination is used to send the actual metric values. |
Table 3-6 JMS Destination for Target Status
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSTargetStatusTopic or ms/EMSYSTargetStatusQueue |
JMS Message Type |
Text message |
Description |
Target status information is sent on this destination. |
Table 3-7 JMS Destination for Security Filter
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSSecurityFilterTopic |
JMS Message Type |
Text message |
Description |
Security filter information is sent on this destination. |
Table 3-8 JMS Destination for Alert Data
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSAlertsDataTopic |
JMS Message Type |
Text message |
Description |
Alerts are sent on this destination. |
Table 3-9 JMS Destination for SLA Data
Details | Description |
---|---|
ConnectionFactory Name |
jms/EMSYSTopicConnectionFactory or jms/EMSYSQueueConnectionFactory |
Destination Name |
jms/EMSYSATargetSLATopic or jms/EMSYSATargetSLAQueue |
JMS Message Type |
Text message |
Description |
The target SLA is sent on this destination. SLA metrics are only shown for Service targets. |
The following sections explain the outbound message schema. The schema varies depending on whether the message format is normalized or denormalized.
The schema for outgoing messages for a normalized format is as follows:
For each selected target, corresponding target metadata information is sent to the external system during the session setup phase. The schema of these messages is as follows:
Table 3-10 Normalized Target Message
Title | Description |
---|---|
Path Expression |
EMSYSData/Target |
Schema File Location |
$ORACLE_HOME/sysman/bam/OutboundTarget.xsd |
Destination |
jms/EMSYSTargetsTopic or jms/EMSYSTargetsQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="Target" type="de:TargetType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Target Type --> <xs:complexType name="TargetType"> <xs:all> <xs:element name="TargetName" type="xs:string"/> <xs:element name="TargetType" type="xs:string"/> <xs:element name="TargetGUID" type="xs:string"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <Target> <TargetName>/ade/foo_core9/oracle.stacd16.us.oracle.com_home</TargetName> <TargetType>oc4j</TargetType> <TargetGUID>852464ac3e4176460458297faaffe926</TargetGUID> </Target> <Target> <TargetName>stacd16.us.oracle.com</TargetName> <TargetType>host</TargetType> <TargetGUID>00645a665bfd9b72b2a6bb6ef49606b0</TargetGUID> </Target> </de:EMSYSData> |
For each selected metric, corresponding metric metadata information is sent to the external system during the session setup. The schema of these messages is as follows:
Table 3-11 Normalized Metric Message
Title | Description |
---|---|
Path Expression |
EMSYSData/Metric |
Schema File Location |
$ORACLE_HOME/sysman/bam/OutboundSecurityFilter.xsd |
Destination |
jms/EMSYSMetricsTopic or jms/EMSYSMetricsQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="Metric" type="de:MetricType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Metric Type --> <xs:complexType name="MetricType"> <xs:all> <xs:element name="MetricName" type="xs:string"/> <xs:element name="MetricType" type="xs:string"/> <xs:element name="MetricGUID" type="xs:string"/> <xs:element name="MetricColumn" type="xs:string" minOccurs="0"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <Metric> <MetricColumn>DiskActivityavserv</MetricColumn> <MetricGUID>6ca028d5078fe542b2ee0c1b013727d7</MetricGUID> <TargetType>host</TargetType> <MetricName>DiskActivity</MetricName> </Metric> <Metric> <MetricColumn>cpuUtil</MetricColumn> <MetricGUID>0c71a1afac2d7199013837da35522c08</MetricGUID> <TargetType>host</TargetType> <MetricName>Load</MetricName> </Metric> </de:EMSYSData> |
Normalized Security Filter Message
External systems that consume data from Enterprise Manager can enforce access control based on the session name. This can be achieved by capturing the security filter. The schema of these security filter messages is as follows:
Table 3-12 Normalized Security Filter Message
Title | Description |
---|---|
Path Expression |
EMSYSData/SecurityFilter |
Schema File Location |
$ORACLE_HOME/sysman/bam/OutboundMetric.xsd |
Destination |
jms/EMSYSSecurityFilterTopic or jms/EMSYSSecurityFilterQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="SecurityFilter" type="de:SecurityFilterType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Security Filter Type --> <xs:complexType name="SecurityFilterType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="UserName" type="xs:string"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <SecurityFilter> <SessionName>LoanSession</SessionName> <UserName>LoanAdminUser</UserName> </SecurityFilter> </de:EMSYSData> |
Normalized Metric Data Message
In the normalized message format, the metrics are sent along with the GUIDs to avoid sending meta information for every message. The schema of this metric message is as follows:
Table 3-13 Normalized Metric Data Message
Title | Description |
---|---|
Path Expression |
EMSYSData/MetricData |
Schema File Location |
$ORACLE_HOME/sysman/bam/ OutboundNormalizedMetricsData.xsd |
Destination |
jms/EMSYSMetricsDataTopic or jms/EMSYSMetricsDataQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="MetricData" type="de:MetricDataType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Metric Data Type --> <xs:complexType name="MetricDataType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetGUID" type="xs:string"/> <xs:element name="MetricGUID" type="xs:string"/> <xs:element name="Timestamp" type="xs:dateTime"/> <xs:element name="Value" type="xs:float" minOccurs="0"/> <xs:element name="StringValue" type="xs:string" minOccurs="0"/> <xs:element name="KeyValue" type="xs:string" minOccurs="0"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <MetricData> <SessionName>Session1</SessionName> <TargetGUID>00645a665bfd9b72b2a6bb6ef49606b0</TargetGUID> <MetricGUID>df8067b7d515747434b58d69230b8451</MetricGUID> <Timestamp>2001-12-17T09:30:47-05:00</Timestamp> <Value>3.14159</Value> </MetricData></EMSYSData> |
In the normalized message format, the alerts are sent along with the GUIDs to avoid sending meta information for every message. The schema of this alert message is as follows:
Table 3-14 Normalized Alert Message
Title | Description |
---|---|
Path Expression |
EMSYSData/Alert |
Schema File Location |
$ORACLE_HOME/sysman/bam/ OutboundNormalizedAlertsData.xsd |
Destination |
jms/EMSYSAlertsDataTopic or jms/EMSYSAlertsDataQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="Alert" type="de:AlertType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Alert Type --> <xs:complexType name="AlertType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetGUID" type="xs:string"/> <xs:element name="MetricGUID" type="xs:string"/> <xs:element name="Timestamp" type="xs:dateTime"/> <xs:element name="Severity" type="xs:string"/> <xs:element name="Value" type="xs:float" minOccurs="0"/> <xs:element name="Message" type="xs:string" minOccurs="0"/> <xs:element name="KeyValue" type="xs:string" minOccurs="0"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <Alert> <MetricGUID>0c71a1afac2d7199013837da35522c08</MetricGUID> <Value>25.35</Value> <Message>CPU Utilization is 25.35%, crossed warning (15) or critical (95) threshold.</Message> <Severity>Warning</Severity> <Timestamp>07/13/2006 14:59:42</Timestamp> <SessionName>Session9</SessionName> <TargetGUID>00645a665bfd9b72b2a6bb6ef49606b0</TargetGUID> </Alert> </de:EMSYSData |
List of Severities
CLEAR
INFO
WARNING
CRITICAL
AGENT UNREACHABLE CLEAR
AGENT UNREACHABLE START
BLACKOUT END
BLACKOUT START
METRIC ERROR END
METRIC ERROR START
Normalized Target Availability Message
The schema of a normalized target availability information message is as follows:
Table 3-15 Normalized Target Availability Message
Title | Description |
---|---|
Path Expression |
EMSYSData/TargetStatus |
Schema File Location |
$ORACLE_HOME/sysman/bam/OutboundNormalizedTargetStatus.xsd |
Destination |
jms/EMSYSTargetStatusTopic or jms/EMSYSTargetStatusQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="TargetStatus" type="de:TargetsStatusType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Target Status Type --> <xs:complexType name="TargetStatusType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetGUID" type="xs:string"/> <xs:element name="Status" type="xs:integer"/> <xs:element name="Timestamp" type="xs:dateTime"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <TargetStatus> <Status>1</Status> <Timestamp>07/11/2006 16:21:53</Timestamp> <SessionName>Session1</SessionName> <TargetGUID>00645a665bfd9b72b2a6bb6ef49606b0</TargetGUID> </TargetStatus> </de:EMSYSData> |
Possible status values are provided in the following table:
Value | Status |
---|---|
1 | Target is up and reachable |
-1 |
|
0 |
|
Normalized Target SLA Message
The schema of a normalized target SLA information message is as follows:
Table 3-16 Normalized Target SLA Message
Title | Description |
---|---|
Path Expression |
EMSYSData/TargetSLA |
Schema File Location |
$ORACLE_HOME/sysman/bam/OutboundNormalizedTargetSLA.xsd |
Destination |
jms/EMSYSTargetSLATopic or jms/EMSYSTargetSLAQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <!-- Schema for Normalized Outbound Target Status message --> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/ DataExchange/10203/OutboundData/"xmlns:de="http://xmlns.oracle.com/ EnterpriseManager/DataExchange/10203/OutboundData/ " xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <!-- Define the root element --> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root type --> <xs:complexType name="EMSYSDataType"> <!-- Zero or more TargetSLA elements --> <xs:sequence> <xs:element name="TargetSLA" type="de:TargetSLAType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the TargetSLA Type --> <xs:complexType name="MetricDataType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetGUID" type="xs:string"/> <xs:element name="SLA" type="xs:integer"/> <xs:element name="Timestamp" type="xs:dateTime"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/ 10203/OutboundData/"> <TargetSLA> <SLA>100</SLA> <Timestamp>07/11/2008 16:21:53</Timestamp> <SessionName>Session1</SessionName> <TargetGUID>00645a665bfd9b72b2a6bb6ef49606b0</TargetGUID> </TargetSLA> </de:EMSYSData> |
Following sections describe the schema for the outgoing messages for denormalized format.
Denormalized Metric Data Message
Schema of a denormalized metric data message is as follows:
Table 3-17 Denormalized Metric Data Message
Title | Description |
---|---|
Path Expression |
EMSYSData/MetricData |
Schema File Location |
$ORACLE_HOME/sysman/bam/ OutboundDenormalizedMetricsData.xsd |
Destination |
jms/EMSYSMetricsDataTopic or jms/EMSYSMetricsDataQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="MetricData" type="de:MetricDataType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Metric Data Type --> <xs:complexType name="MetricDataType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetName" type="xs:string"/> <xs:element name="TargetType" type="xs:string"/> <xs:element name="MetricName" type="xs:string"/> <xs:element name="MetricColumn" type="xs:string" minOccurs="0"/> <xs:element name="Timestamp" type="xs:dateTime"/> <xs:element name="Value" type="xs:float" minOccurs="0"/> <xs:element name="StringValue" type="xs:string" minOccurs="0"/> <xs:element name="KeyValue" type="xs:string" minOccurs="0"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <MetricData> <SessionName>Session1</SessionName> <TargeName>OC4J 10.1.3</TargetName> <TargetType>generic_service</TargetType> <MetricName>Usage Value</MetricName> <Timestamp>2001-12-17T09:30:47-05:00</Timestamp> <Value>3.14159</Value> </MetricData> </EMSYSData> |
Denormalized Alert Message
Schema of a denormalized alert message is as follows:
Table 3-18 Denormalized Alert Message
Title | Description |
---|---|
Path Expression |
EMSYSData/Alert |
Schema File Location |
$ORACLE_HOME/sysman/bam/ OutboundDenormalizedAlertsData.xsd |
Destination |
jms/EMSYSAlertsDataTopic or jms/EMSYSAlertsDataQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="Alert" type="de:AlertType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Alert Type --> <xs:complexType name="AlertType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetName" type="xs:string"/> <xs:element name="TargetType" type="xs:string"/> <xs:element name="MetricName" type="xs:string"/> <xs:element name="MetricColumn" type="xs:string" minOccurs="0"/> <xs:element name="Timestamp" type="xs:dateTime"/> <xs:element name="Severity" type="xs:string"/> <xs:element name="Value" type="xs:float" minOccurs="0"/> <xs:element name="Message" type="xs:string" minOccurs="0"/> <xs:element name="KeyValue" type="xs:string" minOccurs="0"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <Alert> <SessionName>Session9</SessionName> <TargeName>OC4J 10.1.3</TargetName> <TargetType>generic_service</TargetType> <MetricName>Usage Value</MetricName> <Value>25.35</Value> <Message>CPU Utilization is 25.35%, crossed warning (15) or critical (95) threshold.</Message> <Severity>Warning</Severity> <Timestamp>07/13/2006 14:59:42</Timestamp> </Alert> </de:EMSYSData> |
Denormalized Target Availability Message
Schema of a denormalized target availability message is as follows:
Table 3-19 Denormalized Target Availability Message
Title | Description |
---|---|
Path Expression |
EMSYSData/TargetStatus |
Schema File Location |
$ORACLE_HOME/sysman/bam/ OutboundDenormalizedTargetStatus.xsd |
Destination |
jms/EMSYSTargetStatusTopic or jms/EMSYSTargetStatusQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root element --> <xs:complexType name="EMSYSDataType"> <xs:sequence> <xs:element name="TargetStatus" type="de:TargetStatusType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Target Status Type --> <xs:complexType name="TargetStatusType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetName" type="xs:string"/> <xs:element name="TargetType" type="xs:string"/> <xs:element name="Status" type="xs:integer"/> <xs:element name="Timestamp" type="xs:dateTime"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <TargetStatus> <Status>1</Status> <Timestamp>07/11/2006 16:21:53</Timestamp> <SessionName>Session1</SessionName> <TargeName>OC4J 10.1.3</TargetName> <TargetType>generic_service</TargetType> </TargetStatus> </de:EMSYSData> |
Denormalized Target SLA Message
The schema of a denormalized target SLA information message is as follows:
Table 3-20 Denormalized Target SLA Message
Title | Description |
---|---|
Path Expression |
EMSYSData/TargetSLA |
Schema File Location |
$ORACLE_HOME/sysman/bam/OutboundDenormalizedTargetSLA.xsd |
Destination |
jms/EMSYSTargetSLATopic or jms/EMSYSTargetSLAQueue |
Schema |
<?xml version="1.0" encoding="UTF-8"?> <!-- Schema for Denormalized Outbound Target Status message --> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/ DataExchange/10203/OutboundData/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/ 10203/OutboundData/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <!-- Define the root element --> <xs:element name="EMSYSData" type="de:EMSYSDataType"/> <!-- Define the root type --> <xs:complexType name="EMSYSDataType"> <!-- zero or more target status elements --> <xs:sequence> <xs:element name="TargetSLA" type="de:MetricDataType" minOccurs="0" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> <!-- Define the Target Status Type --> <xs:complexType name="TargetSLAType"> <xs:all> <xs:element name="SessionName" type="xs:string"/> <xs:element name="TargetName" type="xs:string"/> <xs:element name="TargetType" type="xs:string"/> <xs:element name="SLA" type="xs:integer"/> <xs:element name="Timestamp" type="xs:dateTime"/> </xs:all> </xs:complexType> </xs:schema> |
Sample |
<de:EMSYSData xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/OutboundData/"> <TargetSLA> <SLA>100</SLA> <Timestamp>07/11/2006 16:21:53</Timestamp> <SessionName>Session1</SessionName> <TargeName>OC4J 10.1.3</TargetName> <TargetType>generic_service</TargetType> </TargetSLA> </de:EMSYSData> |
To create an inbound data exchange session, specify the input provided in the following procedure for the respective pages of the setup wizard.
From the Data Exchange page, click the Inbound Data Exchange Session link.
Click Create. The Session Setup step of the wizard appears.
Ensure that you have access to at least one Data Exchange hub that is configured with the topics to receive data from Enterprise Manager. To set up a Data Exchange hub, see "Creating a Data Exchange Hub" on page 3-5.
Specify a unique name for this inbound data exchange session in the Name field.
Select a Data Exchange hub from the list of hubs already created and listed alphabetically. By default, the first hub in the list is selected.
Incoming business events are associated with a corresponding business KPI if you import the KPI to Grid Control. If not, the event is associated with the special built-in metric, named ExternalAlertMetric.
Click Next. The Select Business Events/Indicators step of the wizard appears.
If you need to send business events to Grid Control, click Add Business Events. Otherwise, skip to step 4. The Select Business Events/Indicators: Add Business Events page appears.
Specify the name of an existing data source from which the event will be retrieved. The data source names within a session should be unique.
Optionally check Apply XSL Transformation for incoming messages to apply an XSL style sheet to the incoming message, the conversion of which is shown in Figure 3–4. A multi-line text box appears when you click Show, where you can insert an XSL document. If you choose this option, click Check Syntax to check the accuracy of your entry before proceeding.
The most common usage for XSLT conversion involves incoming messages transporting business KPIs or events. When the KPIs or events do not produce the expected message (schema), you can apply the XSL at the Grid Control end rather than changing the message format itself.
Specify JMS destination details for incoming events. You need to specify the ConnectionFactory, the destination from which data is retrieved, and an optional Durable Subscriber Name (only needed for topics, not for queues) so that all messages pertaining to the topic go to the specified subscriber. Specifying a Durable Subscriber for topics prevents you from losing any incoming events.
To ensure that an authenticated connection will be created between Grid Control and the Data Exchange hub, you can specify a user name and password so that the connection can be established with these credentials. Click Test Connection to verify that your input is valid.
Associate the business events with a target that Grid Control is monitoring. You can associate business events with any Enterprise Manager monitored target.
The target drop-down lists all the available target types, with the Generic Service target type being the default. If you want to choose the business event associated with a specific target that is not available in the list, add the target from the Targets page and then restart the procedure of creating an inbound session.
Click OK to save your configuration, then view your input in a tabular format and edit your selections if necessary.
You can also use your selections as a template for another target by clicking Add-like.
If you need to send business indicators to Grid Control, click Add Business Indicators. Otherwise, skip to step 5. The Select Business Events/Indicators: Add Business Indicators page appears.
Specify the name of an existing external data source from which the indicators will be retrieved. The data source names within a session should be unique. If the XML message sent from the data source is namespace-enabled, select the check-box indicating this, and also specify the fully-qualified namespace.
Optionally check Apply XSL Transformation for incoming messages to apply an XSL style sheet to the incoming message, shown in Figure 3–4. A multi-line text box appears after you click Show, where you can insert an XSL document. If you choose this option, click Check Syntax to check the accuracy of your entry before proceeding.
Specify the business indicators that need to be sent to Grid Control by clicking Add Indicator. The corresponding metric name for the business indicator is <Source Name>_<Indicator Name>. All indicators can only have numeric values.
Specify JMS destination details for incoming indicators. You need to specify the ConnectionFactory, the destination from which data is retrieved, and an optional Durable Subscriber Name (only needed for topics, not for queues) so that all messages pertaining to the topic go to the specified subscriber. Specifying a Durable Subscriber topic prevents you from losing any incoming indicators.
To ensure that an authenticated connection will be created between Grid Control and the Data Exchange hub, you can specify a user name and password so that the connection can be established with these credentials. Click Test Connection to verify that your input is valid.
Associate the business indicators with a target that Grid Control is monitoring. Unlike business events, which can be associated with any target type instance, business indicators can be associated only with instances that are of the Service target type.
The target drop-downs list all the available target types, with the Generic Service target type being the default. If you want to choose the business event associated with a specific target that is not available in the list, add the target from the Targets page and then restart the procedure of creating an inbound session.
Click OK to save your input, then view your input in a tabular format and edit your selections if necessary.
You can also use your selections as a template for another target by clicking Add-like.
Click Next if you are satisfied with the configuration. The Schedule step of the wizard appears. Select one of the following scheduling choices:
Schedule Later — You can defer scheduling and subsequently schedule the session from the Outbound Data Exchange Session sub-page after you click Finish in the Review step of the wizard.
Schedule Now — Choose one of the following sub-types:
One Time (Immediately): If you select this option, the session runs once just when you finish creating it.
One Time (Later): If you select this option, you need to specify a time zone and a start date and time for the session.
Repeating: For this default option, you need to specify the time zone and the start time. Additionally, you can specify the frequency type and interval at which you want the session to run, and whether it should be repeated indefinitely or until a specified time and date.
Click Next or Review to go to the Review step of the wizard.
If you need to make changes, click Back until you reach the step you need to change. Otherwise, go to the next step.
Click Finish. The Inbound Data Exchange Session sub-page reappears and shows your newly created session and its status in the table.
Before the job finishes executing, you can either view the schedule by clicking the View Schedule link in the Actions column and then stop the execution if desired, or you can stop the execution immediately by clicking Stop.
Unlike the outbound data exchange setup wherein pre-defined topics and queues are used to send Enterprise Manager data, no pre-defined topics or queues are used to receive business performance indicators and events.
However, you should configure the JMS topics or queues used for the data sources in the JMS server used for inbound data exchange session.
The following sections define the inbound message schemas. Samples messages are provided along with each schema.
After creating the session, the sender can forward the data in XML format using the data exchange hub through the JMS destinations defined in the inbound data exchange session.
Messages can be either namespace qualified or unqualified. If the messages are namespace qualified, the namespace should be entered during the data source setup time.
<po:PurchaseOrder xmlns:po:"http://acme.com/Orders"> <OrderAmount>5000</OrderAmount> <NoOfItems> 15 </NoOfItems> </po:PurchaseOrder>
Unqualified XML Message Sample
<PurchaseOrder> <OrderAmount>5000</OrderAmount> <NoOfItems> 15 </NoOfItems> </PurchaseOrder>
The incoming messages should follow the semantics provided below:
The local name of the top-level element should be same as the data source name as in Example 3–1.
If the message is qualified, the namespace should be defined during the data source setup time.
One or more indicators can be sent as child elements within this element as in Example 3–1.
A sub-element with the Timestamp as the name has special semantics. If a sub-element with the Timestamp name exists, the indicators are inserted with this Timestamp value. If no Timestamp element exists, the current time is used when inserting the indicator into the repository.
For example, if the request is received as follows with the Timestamp sub-element, the indicators are inserted with this timestamp (2006-10-30 17:43:19.474):
<po: PurchaseOrder xmlns:po:"http://acme.com/Orders"> <OrderAmount>5000</OrderAmount> <NoOfItems> 15 </NoOfItems> <Timestamp>2006-10-30 17:43:19.474</Timestamp> </po: PurchaseOrder>
If no Timestamp sub-element is present, the indicators are inserted to the repository with the current timestamp at which they are received.
Example 3-1 Data Source Scenario
You create a Data Source for the incoming business indicators with the Data Source name Order
. You add the following three KPIs:
OrderAmount
NoOfItems
Credit
In this case, the incoming XML message should be in the following format:
<Order> <OrderAmount>35</OrderAmount> <NoOfItems>102</NoOfItems> <Credit>72</Credit> <Timestamp>2007-01-16 16:29:00.978</Timestamp> </Order>
Note: In the example, the local name of the top-level element should be same as the Data source name<Order> .
Also, the indicators such as |
If TargetName
and TargetType
are part of the message, they should match the target name and type for the associated target (for that datasource).
If TargetName
is not part of the message, it defaults to the target to which the datasource was associated.
If TargetType
is not part of the message, it defaults to the target type of the target.
If Timestamp
is not included in the message, it defaults to the current timestamp.
If Category
is not included in the message, it defaults to the category GenericExternalAlertMetric
.
If MetricName
is not included in the message, it defaults to the Alert metric.
ProducerID
is optional for the categories GenericExternalAlertMetric
and Metric
.
However, producer ID is needed for user-defined metrics. In this case, ProducerID
should be same as the metric author.
External systems can send their own alerts/events to Enterprise Manager for display in the Enterprise Manager pages and be computed as part of SLA.
This schema is available in the following location:
$ORACLE_HOME/sysman/bam/InboundEvents.xsd
The schema of the incoming Alert message is as follows:
<?xml version="1.0" encoding="UTF-8"?> <xs:schema targetNamespace="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/InboundEvents/" xmlns:de="http://xmlns.oracle.com/EnterpriseManager/DataExchange/10203/InboundEvents/" xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified"> <!-- Define the Alert element --> <xs:element name="Alert" type="de:AlertType"/> <!-- Define the Alert Type --> <xs:complexType name="AlertType"> <xs:all> <xs:element name="TargetType" type="xs:string" minOccurs="0"/> <xs:element name="TargetName" type="xs:string" minOccurs="0"/> <xs:element name="Category" type="xs:string" minOccurs="0"/> <xs:element name="MetricName" type="xs:string" minOccurs="0"/> <xs:element name="ProducerID" type="xs:string" minOccurs="0"/> <xs:element name="Severity" type="xs:string"/> <xs:element name="Message" type="xs:string" minOccurs="0"/> <xs:element name="Key1" type="xs:string" minOccurs="0"/> <xs:element name="Key2" type="xs:string" minOccurs="0"/> <xs:element name="Key3" type="xs:string" minOccurs="0"/> <xs:element name="Key4" type="xs:string" minOccurs="0"/> <xs:element name="Value" type="xs:string" minOccurs="0"/> <xs:element name="TimeStamp" type="xs:dateTime" minOccurs="0"/> </xs:all> </xs:complexType> </xs:schema>
The following sections explain how to use the Data Exchange Connector to integrate OBAM with Enterprise Manager.
The tested and certified versions of OBAM server are:
Oracle BAM server 10gR2 (10.1.2.0.0) and 10gR2 patch sets
Oracle BAM server 10gR3 (10.1.3.1.0) and 10gR3 patch sets
Oracle BAM server 11gR1 (11.1.1.1.0) and 11gR1 patch sets
Note: Oracle BAM Server 10gR2 and 10gR3 are OC4J-based. Oracle BAM Server 11gR1+ is WebLogic Web Server-based. Consequently, the setup steps differ considerably.The following sections provide basic steps and guidelines. Refer to the Oracle BAM Server documentation for specific information and details. |
For successful data flow from Enterprise Manager to OBAM, do the following:
Import required artifacts, explained in Importing OBAM Artifacts for an Outbound Session.
Update JNDI details, explained in Updating JNDI.
Run the link plans shown in Table 3–23. (This is only needed for OBAM 10g R3 and previous versions.)
OBAM server is not packaged or installed as part of Enterprise Manager. It is assumed that an OBAM instance exists and is up and running. To read and persist the data from Enterprise Manager, certain artifacts should be existing and running. Import the artifacts from the pre-packaged scripts.
To import OBAM artifacts needed for the integration with OBAM server, as super user, run the following script:
For Oracle BAM 11gR1 (11.1.1.1.0) or later versions:
ICommand cmd=import file=emsys_all_11.xml
For Oracle BAM 10gR3 or older versions:
ICommand cmd=import file=emsys_all_10.xml
Both of these files are available at the following location:
$ORACLE_HOME/sysman/bam directory
The export script above creates the following OBAM artifacts:
EM-BAM Enterprise Link Plans (only when emsys_all_10.xml is used). See Table 3–23.
Table 3-21 lists the data objects the Import command creates.
Table 3-21 EM-BAM Data Objects
Data Object | Description |
---|---|
/SYSMAN/EMSYSTargets |
Contains target metadata information, such as target name and target type. |
/SYSMAN/EMSYSMetrics |
Contains metric metadata, such as metric name, metric column, and target type. |
/SYSMAN/EMSYSAlertsData |
Holds the incoming system alerts received from Enterprise Manager. It contains information that includes alert message, alert severity, alert timestamp, and target information on which this alert has occurred. |
/SYSMAN/EMSYSTargetSLAData |
Holds the target SLA information received from Enterprise Manager. |
/SYSMAN/EMSYSTargets |
Contains target metadata information, such as target name and target type. |
/SYSMAN/EMSYSMetricsData |
Holds the metrics information received from Enterprise Manager. It has information about the target and metric for which metrics are received along with metric value and timestamp. |
/SYSMAN/EMSYSSecurityFilter |
Acts as the security filter for all other data objects. It contains the session name and users who can access the corresponding session data. |
Table 3-22 lists the enterprise message sources the Import command creates.
Table 3-22 EM-BAM EMS Definitions
Data Definition | Description |
---|---|
EMSYSMetricsEMS |
Contains the EMS definition for incoming metric metadata listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSMetricsTopic. |
EMSYSTargetsEMS |
Contains the EMS definition for incoming target metadata listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSTargetsTopic. |
EMSYSSecurityFilterEMS |
Contains the EMS definition for security filter data listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSSecurityFilterTopic. |
EMSYSAlertsDataEMS |
Contains the EMS definition for incoming alerts listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSAlertsDataTopic. |
EMSYSMetricsDataEMS |
Contains the EMS definition for incoming metrics listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSMetricsDataTopic. |
EMSYSTargetStatusDataEMS |
Contains the EMS definition for incoming target status messages metrics listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSTargetStatusTopic. |
EMSYSTargetSLAEMS |
Contains the EMS definition for incoming target SLA messages listening on jms/EMSYSTopicConnectionFactory and jms/EMSYSTargetSLATopic. |
EMSYSMetricsEMS-Queue |
Contains the EMS definition for incoming metric metadata listening on jms/EMSYSQueueConnectionFactory and jms/EMSYSMetricsQueue. |
EMSYSTargetsEMS-Queue |
Contains the EMS definition for incoming target metadata listening on jms/EMSYSQueueConnectionFactory and jms/EMSYSTargetsQueue. |
EMSYSSecurityFilterEMS-Queue |
Contains the EMS definition for security filter data listening on jms/EMSYSQueueConnectionFactory and jms/EMSYSSecurityFilterQueue. |
EMSYSAlertsDataEMS-Queue |
Contains the EMS definition for incoming alerts listening on jms/EMSYSQueueConnectionFactory and jms/EMSYSAlertsDataQueue. |
EMSYSMetricsDataEMS-Queue |
Contains the EMS definition for incoming metrics listening on jms/EMSYSQueueConnectionFactory and jms/EMSYSMetricsDataQueue. |
EMSYSTargetStatusDataEMS- Queue |
Contains the EMS definition for incoming target SLA messages listening on jms/EMSYSQueueConnectionFactory and jms/EMSYSTargetSLAQueue. |
You should update all EMSs described in Table 3–22 to reflect the correct JNDI initial context factory and provider URLs of your JMS servers. To do this:
In the OBAM Console, click Architect.
The BAM Architect screen appears (Figure 3–5).
Select Enterprise Message Sources in the top left drop-down list.
The left pane displays the six Enterprise Message Sources.
Click the Message Source links and do the following:
In the right pane, click Edit and modify the JNDI Service Provider URL details from t3://localhost to the JNDI Service Provider URL of your Data Hub.
Click Save.
Repeat this for all Message Source objects.
For 11gR1 or new versions of OBAM:
Enable Global trust or Cross domain trust between the Data hub WebLogic server and the OBAM WebLogic server. Refer to WebLogic documentation for details.
For 10gR3 or older versions of OBAM:
Update java.naming.security.principal
to the JMS server password in jndi.properties
in the BAM_HOME
\BAM\j2re1.4.1_01\lib
directory.
Restart all OBAM services.
Besides the BAM data objects (Table 3–21) and EMS definitions (Table 3–22), the link plans shown in Table 3–23 are also created when you use emsys_all_10.xml to create the artifacts. These are only needed for Oracle BAM Server 10gR3 or older versions. The plans shown in Table 3–23 are created based on the Import command.
Plan | Description |
---|---|
EMSYSMetricsPlan |
Contains the definition to receive, transform, and persist incoming metric metadata messages. This should be running before creating and setting up an outbound session in Enterprise Manager. |
EMSYSTargetsPlan |
Contains the definition to receive, transform, and persist incoming target metadata messages. This should be running before creating and setting up an outbound session in Enterprise Manager. |
EMSYSSecurityFilterPlan |
Contains the definition to receive, transform, and persist incoming security filter messages. This should be running before creating and setting up an outbound session in Enterprise Manager. |
EMSYSAlertsDataPlan |
Contains the definition to receive, transform, and persist incoming alert messages. This should be running when the outbound session with at least one selected alert is running in Enterprise Manager. |
EMSYSMetricsDataPlan |
Contains definition to receive, transform, and persist incoming metric messages. This should be running when the outbound session with at least one selected metric is running in Enterprise Manager. |
EMSYSTargetStatusDataPlan |
Contains definition to receive, transform, and persist incoming target status messages. This should be running when the outbound session with at least one availability selected metric is running in Enterprise Manager. |
EMSYSTargetSLADataPlan |
Contains definition to receive, transform, and persist incoming target SLA messages. This should be running when the outbound session with at least one SLA selected metric is running in Enterprise Manager. |
EMSYSAlertsDataRollup |
Contains the definition to move the data in EMSYSAlertsData that is more than 24 hours old to You can run this based on demand. |
EMSYSMetricsDataRollup |
Contains the definition to move the data in EMSYSMetricsData that is more than 24 hours old to EMSYSMetricsData.Archive. You can run this based on demand. |
EMSYSTargetStatusDataRollup |
Contains the definition to move the data in EMSYSTargetStatusData that is more than 24 hours old to EMSYSTargetStatusData.Archive. You can run this based on demand. |
Additional EM-BAM Supplemental Data Objects
Table 3–24 lists the supplemental data objects related to repositories for archived data.
Table 3-24 EM-BAM Supplemental Data Objects
Plan | Description |
---|---|
/SYSMAN/EMSYSAlertsData.Archive |
Holds the archived data for /SYSMAN/EMSYSAlertsData. |
/SYSMAN/EMSYSMetricsData.Archive |
Holds the archived data for /SYSMAN/EMSYSMetricsData. |
/SYSMAN/EMSYSTargetStatusData. Archive |
Holds the archived data for /SYSMAN/EMSYSTargetStatusData. |
Unlike the Enterprise Manager to OBAM server data transfer, where pre-defined OBAM artifacts, such as Data Objects, EMS, and Plans (when needed) are defined and shipped along with Enterprise Manager, no such artifacts are defined or shipped for the data transfer from OBAM to Enterprise Manager. This is because the Data Object or EMS are unknown.
Consequently, for inbound data transfer from OBAM 11g or later versions, the integrator needs to use Oracle Data Integrator to read the data from the data object and put it on an outbound JMS topic or queue. For OBAM 10g or previous versions, the integrator can use outbound Plans to read data from data objects and put it on an outbound JMS topic or queue. Refer to ODI and OBAM documentation for specific information.
After you configure the OBAM server with necessary artifacts and the JMS server with JMS topic or queue names, ensure the following for successful data flow from Enterprise Manager to OBAM:
OBAM server and Enterprise Manager are up and running.
JMS server, configured with required JMS topics or queues, is up and running.
All enterprise plans (only for OBAM 10g or older versions) described in Table 3–23 are running.
You can start plans manually or schedule them from Design Studio or through an alert.
After ensuring the specifications, proceed with the following:
Create a data exchange hub and outbound data exchange session instances in Enterprise Manager.
Always use a normalized message format for sessions that are for the consumption of the OBAM server. OBAM server plans are catered to understand only normalized messages.
Schedule the outbound data exchange.
Enterprise Manager sends data as scheduled in the outbound Data Exchange session.
To use an OC4J as a data exchange hub instead of WebLogic Server, perform the following steps:
Copy the client libraries and restart Grid Control:
For a 10.1.3.x OC4J, copy the 10.1.3.x oc4jclient.jar file to:
$ORACLE_HOME/middleware/oms/sysman/archives/emgc/deployments/EMGC_DOMAIN/ emgc.ear/APP-INF/lib
For a 10.1.2.x OC4J, copy the 10.1.2.x oc4j.jar file to:
$ORACLE_HOME//middleware/oms/sysman/archives/emgc/deployments/EMGC_DOMAIN/ emgc.ear/APP-INF/lib
Restart Grid Control after copying the.jar file.
Configure the OC4J with the JMS destinations. You can do this with Application Server Control or by manually updating the jms.xml file as follows:
The following example shows a jms.xml section for an OC4J:
<topic-connection-factory/> location="jms/EMSYSTopicConnectionFactory" <topic> name="EMSYSAlertsDataTopic" location="jms/EMSYSAlertsDataTopic" <description>Topic for alerts data</description> </topic> <topic> name="EMSYSMetricsDataTopic" location="jms/EMSYSMetricsDataTopic" <description>Topic for metrics data</description> </topic> <topic> name="EMSYSMetricsTopic" location="jms/EMSYSMetricsTopic" <description>Topic for metrics metadata</description> </topic> <topic> name="EMSYSSecurityFilterTopic" location="jms/EMSYSSecurityFilterTopic" <description>Topic for security filter</description> </topic> <topic> name="EMSYSTargetStatusTopic" location="jms/EMSYSTargetStatusTopic" <description>Topic for target status</description> </topic> <topic> name="EMSYSTargetSLATopic" location="jms/EMSYSTargetSLATopic" <description>Topic for target SLA</description> </topic> <topic> name="EMSYSTargetsTopic" location="jms/EMSYSTargetsTopic" <description>Topic for targets metadata</description> </topic> <queue-connection-factory/> location="jms/EMSYSQueueConnectionFactory" <queue> name="EMSYSAlertsDataQueue" location="jms/EMSYSAlertsDataQueue" <description>Queue for alerts data</description> </queue> <queue> name="EMSYSMetricsDataQueue" location="jms/EMSYSMetricsDataQueue" <description>Queue for metrics data</description> </queue> <queue> name="EMSYSMetricsQueue" location="jms/EMSYSMetricsQueue" <description>Queue for metrics metadata</description> </queue> <queue> name="EMSYSSecurityFilterQueue" location="jms/EMSYSSecurityFilterQueue" <description>Queue for security filter</description> </queue> <queue> name="EMSYSTargetStatusQueue" location="jms/EMSYSTargetStatusQueue" <description>Queue for target status</description> </queue> <queue> name="EMSYSTargetSLAQueue" location="jms/EMSYSTargetSLAQueue" <description>Queue for target SLA</description> </queue> <queue> name="EMSYSTargetsQueue" location="jms/EMSYSTargetsQueue" <description>Queue for targets metadata</description> </queue>
The following sections provide various tips and troubleshooting information that might help in resolving various issues you encounter during the data exchange process.
A data exchange hub connection created in Grid Control can error out due to authentication issues. These errors can appear in the following places:
Grid Control log files
Grid Control data exchange pages. For example:
An error occurred while verifying the Data Exchange hub <hub_name>:
You are not authorized to access the Data Exchange hub. The <session_name> session was not created successfully.
Data exchange hub logs, such as an OC4J container error from OC4J logs. For example:
2008-01-29 17:37:28.259 NOTIFICATION J2EE RMI-00004 Invalid username or password for default (oc4jadmin). Authentication failed.
08/02/28 17:37:28 INFO: RMIProto .readConnectionHeader Local ORMI version = 1. 3 different from remote version 1.1 will use 1.1
2008-01-29 17:37:28.290 ERROR [RealmLoginModule] authentication failed
Follow these steps to resolve the connection problem:
Make sure the username/password combination is correct for the data exchange hub. You can check this with client programs, such as JDeveloper or a JMS client.
Recreate the Data Exchange hub connection entry in Grid Control as follows:
Log in to Grid Control as a super user/administrator.
From Enterprise Manager Grid Control, click Setup.
The setup links appear in the left margin.
Click Data Exchange.
The Data Exchange page appears (Figure 3–2).
In the Data Exchange Hub tab, select the hub connection and click Delete.
Create a new Data Exchange hub. See Creating a Data Exchange Hub.
Important: The verifications suggested in this section are meant for troubleshooting purposes and not for modification. Updating notification methods or rules can result in undesirable consequences. |
For each data hub used for an outbound session, a new notification method is created. The name of the method is hub_name
NotifDevice
, where hub_name
is the name of the data hub for which the method is created.
For each outbound session (with Alerts selected), a notification rule is created.
The name of the rule is session_name
NotifRule
, where session_name
is the name of the outbound session for which the rule is created.
To verify that the rule is successfully created:
From Enterprise Manager Grid Control, click the Preferences link.
In the left pane under Notification, click Rules.
The Notification Rules page appears.
Click on the corresponding Rule and make sure the selected targets and metrics are correct.
Ensure that the following JNDI details are correctly entered for the Data Hub you use:
JNDI URL
Username
Password
For an inbound session setup, do not provide JNDI credentials for JMS in the data source definitions.
If the JMS topic or queue is secured by providing authentication details, provide the username and password. If not, leave the fields blank.
Ensure that the JMS server is up and running and configured with the required JMS topic and queue names.
Ensure that either an inbound or outbound session is scheduled and is running.
For an inbound session data source, to ensure that the topic details are correctly entered, click Test Connection.
Using the same topic or queue name for two active inbound sessions could result in corrupted data.
Frequency for an inbound session should either be synchronized with or relative to the frequency at which the external system sends data.
For example, setting the inbound session frequency to 2 minutes is ineffective if the external system sends data only once in 10 minutes.
For an outbound session, ensure that Receiver or EL Plans (in the case of OBAM) are running.
To improve efficiency, outbound session schedule frequency should be relative or synchronized with the frequencies at which Enterprise Manager collects the metrics defined in the session.
For example, in Enterprise Manager, if the collection frequency for metrics defined in the outbound session is 5 minutes, setting a lesser outbound frequency (one minute, for instance) is ineffective, as the possibility of new data is remote. In such cases, setting the outbound frequency to 5 or 10 minutes would be effective.
Note that only new metric values (if any) are forwarded.
Do not schedule two or more outbound sessions with different message formats at the same time.
Unless a lower frequency level is absolutely required, always set higher frequency intervals. This helps to reduce the Enterprise Manager/JMS server load.
Always check the log if data could not be received or if the status is Failure
. To check logs:
From Enterprise Manager Grid Control, click the Jobs tab.
Click Advanced Search.
In Target Type, select Targetless from the drop-down list.
In Status, select All from the drop-down list.
Click Go.
Click the Job you want to verify.
For an inbound session, the name of the job is <Session Name>ISJOB
.
For an outbound session, the name of the job is <Session Name>OSJOB
.
Click the Status value link; for instance, Succeeded
or Failed
.
Click Step.
For inbound sessions, the step name is receiveMetricDataViaJms
.
For outbound sessions, the step name is sendMetricDataViaJms
.
Note the Step ID Value and search logs (typically located in the directory $ORACLE_HOME/sysman/log
) based on the ID in the log directory using the following command:
"grep –i "JobWorker
stepID"
*.trc
Note: The default system log directory is$ORACLE_HOME/sysman/log |
Check for the following:
Exceptions or errors
emoms.log
(in the same directory) for any other exception for the same timestamp
Change the log level in emomslogging.properties
to DEBUG
and restart Enterprise Manager for more detailed debugging information.
For the convenience of integrators, Oracle provides sample demonstrations detailing the end-to-end data flow. To access the demonstrations, go to the following directory:
$ORACLE_HOME/sysman/bam
Instructions for an outbound session sample are provided in the file outboundsession_sample_readme.txt
. You can create the report required for the demonstration by importing the file outboundsession_report.xml
as detailed in the readme file.
Instructions for an inbound session sample are provided in the file inboundsession_sample_readme.txt
. You can create the artifacts required for the demonstration by importing the file inboundsession.xml
as detailed in the readme file.
The following list provides online resources that can help you effectively use all associated technologies involved in the data exchange process.
Oracle Business Activity Monitoring: http://www.oracle.com/technology/products/integration/bam/index.html
Oracle Data Integrator:
http://www.oracle.com/technology/products/oracle-data-integrator/index.html
Java Message Service:
Oracle Containers for J2EE (OC4J):
Oracle Enterprise Service Bus (ESB):
http://www.oracle.com/technology/products/integration/esb/index.html
Enterprise Manager Metrics:
Oracle Enterprise Manager Framework, Host, and Third-Party Metric Reference Manual available at the following URL: