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

The following JMS servers are certified and supported:

• 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:

1. In the Data Exchange: Data Exchange Hub page click Create. The Create Data Exchange Hub page appears.

   1. Specify a unique name for the Data Exchange hub.

   2. Provide the JNDI Service Provider URL for the Data Exchange hub.

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

   4. Provide the user credentials to access this hub.

2. Configure the JMS server with the required JMS topic names and/or queue names.

   Note:

   Inbound JMS Destinations

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

Although such usage is uncertified and unsupported, it is possible to use third-party JMS servers as a Data Exchange hub in a development or test scenario by performing the following procedure.

1. Copy your JMS server's JMS client libraries to the following location:

   $ORACLE_HOME/middleware/oms/sysman/archives/emgc/deployments/EMGC_DOMAIN/emgc.ear/APP-INF/lib
   

2. Restart Cloud Control after copying the .jar file(s).

3. Create the JMS destinations according to the procedures specified for your JMS server. Refer to the list of Topics and Queues.

1. From the Data Exchange page, click the Outbound Data Exchange Session link.
2. Click Create. The Session Setup step of the wizard appears.
   1. 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.
   2. Specify a unique name for this outbound data exchange session in the Name field.
   3. 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.
   4. In the Users field, enter the name of an Oracle BAM user or a comma-separated list of Oracle 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.
   5. For the Destination Type drop-down, select one of the messaging models to send or receive messages from Cloud 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.

   6. Select either a Normalized or Denormalized message format. For more information on these formats, see Outbound Data Exchange Session.
   7. In the Metrics Granularity drop-down, select whether you want to send raw metrics data through an outbound session, or whether you want to send average data for 24 hours, 7 days, or 31 days.
   8. Click Next. The Select Targets and Metrics/Alerts/Availability step of the wizard appears.
3. Click Add. The Add Target page of this wizard step appears.
4. 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.
5. 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.

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

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

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

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

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:

1. Use the pre-packaged WLST python scripts available in the $ORACLE_HOME/sysman/bam directory.

2. 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).

3. Use configEMSYSJMSSystemResource.py found in the directory in step 1 to create the required JMS topics and queues:

   java weblogic.WLST comfigEMSYSJMSSystemResource.py <jndi provider URL> <username> <password> <WLS server name>
   

   Example:

   java weblogic.WLST configEMSYSJMSSystemResource.py "t3://localhost:7001" weblogic <password> 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

     • jms/EMSYSMetricsDataLast24HoursTopic

     • jms/EMSYSMetricsDataLast7DaysTopic

     • jms/EMSYSMetricsDataLast31DaysTopic

     • jms/EMSYSTargetStatusLast24HoursTopic

     • jms/EMSYSTargetStatusLast7DaysTopic

     • jms/EMSYSTargetStatusLast31DaysTopic

     • jms/EMSYSTargetSLALast24HoursTopic

     • jms/EMSYSTargetSLALast7DaysTopic

     • jms/EMSYSTargetSLALast31DaysTopic

   • Queues:

     • jms/EMSYSTargetsQueue

     • jms/EMSYSMetricsQueue

     • jms/EMSYSAlertsDataQueue

     • jms/EMSYSMetricsDataQueue

     • jms/EMSYSSecurityFilterQueue

     • jms/EMSYSTargetStatusQueue

     • jms/EMSYSTargetSLAQueue

     • jms/EMSYSMetricsDataLast24HoursQueue

     • jms/EMSYSMetricsDataLast7DaysQueue

     • jms/EMSYSMetricsDataLast31DaysQueue

     • jms/EMSYSTargetStatusLast24HoursQueue

     • jms/EMSYSTargetStatusLast7DaysQueue

     • jms/EMSYSTargetStatusLast31DaysQueue

     • jms/EMSYSTargetSLALast24HoursQueue

     • jms/EMSYSTargetSLALast7DaysQueue

     • jms/EMSYSTargetSLALast31DaysQueue

4. Use EMSYSJMSSystemResource.py to remove and clean up the JMS destinations the script configEMSYSJMSSystemResource.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 <password>
   

The JMS destinations shown in Table 3-3 are used for an outbound Data Exchange session.

The following sections explain the outbound message schema. The schema varies depending on whether the message format is normalized or denormalized.

To avoid regressions and conflicts between different type of metric data, the XML element and target names differ for raw versus historical data. Table 3-10 shows the differences for these based on the type of granularity generated.

You can tune outbound session message parameters using the emctl command, as shown in Table 3-22.

emctl {set property|get property}
 {oracle.sysman.core.dataExchange.MaxDataPointsPerMessage | 
  oracle.sysman.core.dataExchange.IntervalBetweenMessage | 
  oracle.sysman.core.dataExchange.FirstDatasetWindow}

1. From the Data Exchange page, click the Inbound Data Exchange Session link.
2. Click Create.

   The Session Setup step of the wizard appears.

   1. 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.
   2. Specify a unique name for this inbound data exchange session in the Name field.
   3. 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 Cloud Control. If not, the event is associated with the special built-in metric, named ExternalAlertMetric.

   4. Click Next.
      The Select Business Events/Indicators step of the wizard appears.
3. If you need to send business events to Cloud Control, click Add Business Events. Otherwise, skip to step 4. The Select Business Events/Indicators: Add Business Events page appears.
   1. 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.
   2. 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-2. 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 Cloud Control end rather than changing the message format itself.

      Figure 3-2 XSLT Conversion of XML Source Document

      
      

      

      
      
   3. 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 Cloud 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.

   4. Associate the business events with a target that Cloud 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.

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

4. If you need to send business indicators to Cloud Control, click Add Business Indicators. Otherwise, skip to step 5. The Select Business Events/Indicators: Add Business Indicators page appears.
   1. 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.
   2. Optionally check Apply XSL Transformation for incoming messages to apply an XSL style sheet to the incoming message. 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.
   3. Specify the business indicators that need to be sent to Cloud 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.
   4. 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 Cloud 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.

   5. Associate the business indicators with a target that Cloud 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.

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

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

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

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

The following sections are described:

• Notification Method

• Notification Rules

1. From Enterprise Manager Cloud Control, click the Jobs tab.
2. Click Advanced Search.
3. In Target Type, select Targetless from the drop-down list.
4. In Status, select All from the drop-down list.
5. Click Go.
6. 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.

7. Click the Status value link; for instance, Succeeded or Failed.
8. Click Step.

   • For inbound sessions, the step name is receiveMetricDataViaJms.

   • For outbound sessions, the step name is sendMetricDataViaJms.

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

10. Check for the following:

    • Exceptions or errors

    • emoms.log (in the same directory) for any other exception for the same timestamp

11. Change the log level in emomslogging.properties to DEBUG and restart Enterprise Manager for more detailed debugging information.