This chapter describes how to create and use Enterprise Message Sources (EMS) in Oracle Business Activity Monitoring (Oracle BAM). It explains how to use XML formatting configuration parameters, specify date and time patterns and locale information, handle errors in EMS payloads, and use Java Message Service (JMS) resources hosted on remote providers.
This chapter includes the following sections:
An Enterprise Message Source (EMS) provides direct Java Message Service (JMS) connectivity to the Oracle BAM Server. JMS is the standard messaging API for passing data between application components and allowing business integration in heterogeneous and legacy environments.
The EMS does not configure Extract Transform and Load (ETL) scenarios, but rather maps from a message directly to a data object on the Oracle BAM Server. However, you can still use XML Stylesheet Language (XSL) to perform a transformation in between. Each EMS connects to a specific JMS topic or queue, and the information is delivered into a data object in Oracle BAM. Use the Oracle BAM Composer Administrator page to configure EMS definitions.
The default JMS provider is Messaging for Oracle WebLogic Server. Oracle Advanced Queuing (AQ) JMS is supported. Tibco JMS, a non-Oracle provider, is also supported.
See Using Foreign JMS Providers for more information.
The following message types are supported:
Map message
Text message with XML payload
The following XML formatting options are supported for Text message transformation:
Pre-processing
Message specification
Column value (Column values can be provided either as elements or attributes in the XML payload.)
This section includes the following topics:
Before defining an EMS, consider these points:
If you are using a third-party JMS application, you must configure the JMS Adapter to specify the message source connection details. Oracle BAM uses the JMS Adapter to connect. See Using Foreign JMS Providers for more information.
If a non-Oracle WebLogic Server JMS server is used (such as Tibco) then the durable subscription name should not be repeated in any of the Enterprise Message Sources created. Some JMS servers do not allow the clients to have more than one ConnectionFactory for a single topic destination, and Oracle BAM does not support reuse of the same ConnectionFactory for the same topic.
The JMS server (where you host queues and topics) can be configured on a different system than that which hosts the Oracle BAM Server. (For Oracle Advanced Queuing, or AQ, it is acceptable to host on the same server as Oracle BAM because the database hosts the JMS server, but for other cases it is recommended to host the JMS server on another system).
Do not configure two Enterprise Message Sources on the same topic or queue. If you require two Enterprise Message Sources on the same Queue, each EMS must have different Message Selector value specified; otherwise, the messages are duplicated on both of the Enterprise Message Sources.
Oracle recommends that you update no more than one Data Object with one EMS any time. This maintains the sequence of events as well as removes any collisions as a result of multiple avenues writing to the same Data Object.
Even if the source events are published from multiple sources, they can all be written to the same JMS topic or queue with the same message selector (if needed) for the Data Object.
When you define an EMS, you specify all of the fields in the messages to be received. Some messaging systems have a variable number of user-defined fields, while other systems have a fixed number of fields.
For any string type field, you can apply formatting to that field to break apart the contents of the field into separate, individual fields. This is useful for messaging systems where you cannot create user-defined fields and the entire message body is received as one large field. The formatting specifications allow you to specify the path to a location in the XML tree, and then extract the attributes or tags as fields.
For large XML documents, normal XSLT processing implications on performance apply. It is therefore recommended that, where possible, data transformation be done at the source, before the JMS queue bound for consumption in BAM is populated.
To have a distributed JMS queue for an EMS write to a data object as a single transaction, the connection factory value for the outbound connection JNDI pertaining to the queue must be XA enabled (weblogic.jms.XAConnectionFactory
). This helps the JMS sessions to be automatically enlisted in the JTA transaction. Because BAM already uses the XA data source, the JMS and Persistence APIs seamlessly participate in the XA transaction.
JMS messages are dequeued after delivery. If a transaction commits, database changes are committed and the JMS message is removed from the queue. If a rollback occurs, the message is returned to the queue for retry.
You can enter a date and time pattern and provide locale information.
When including a timestamp field in an EMS payload, consider the following:
Inserting null in a timestamp field might not be in the control of a client such as EMS.
When no value is given for a timestamp field (as in Oracle BAM), EMS assigns the current date and time.
When the incoming timestamp value does not adhere to the xsd:dateTime
or the datetime format specified in the EMS, the current datetime is inserted.
Note that when Use DateTime Specification is disabled (not checked), the incoming value must be in xsd:dateFormat
. That is, xsd:dateFormat
([-]CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm]) is the default format when DateTime Specification is not configured.
Valid value patterns for xsd:dateTime
include:
2001-10-26T21:32:52
2001-10-26T21:32:52+02:00
2001-10-26T19:32:52Z
2001-10-26T19:32:52+00:00
-2001-10-26T21:32:52
2001-10-26T21:32:52.12679
To configure a DateTime Specification:
Table 14-1 Syntax Elements for SimpleDateFormat
Symbol | Meaning | Presentation | Example |
---|---|---|---|
G |
Era |
Text |
AD |
y |
Year |
Number |
2003 |
M |
Month |
Text or Number |
July; Jul; 07 |
w |
Week in year (1-53) |
Number |
27 |
W |
Week in month (1-5) |
Number |
2 |
D |
Day in year (1-365 or 1-364) |
Number |
189 |
d |
Day in a month |
Number |
10 |
F |
Day of week in month (1-5) |
Number |
2 |
E |
Day in week |
Text |
Tuesday; Tue |
a |
AM/PM marker |
Text |
AM |
H |
Hour (0-23) |
Number |
0 |
k |
Hour (1-24) |
Number |
24 |
K |
Hour (0-11 AM/PM) |
Number |
0 |
h |
Hour (1-12 AM/PM) |
Number |
12 |
m |
Minute in an hour |
Number |
30 |
s |
Second in a minute |
Number |
55 |
S |
Millisecond (0-999) |
Number |
978 |
z |
Time zone |
General time zone |
Pacific Standard Time; PST; GMT-08:00 |
Z |
Time zone |
RFC 822 time zone |
-0800 |
' |
Escape for text |
Delimiter |
MMM ''01 -> Jul '01 |
The examples in Table 14-2 show how date and time patterns are interpreted in the United States locale. The date and time used in all of the examples are 2001-07-04 12:08:56
local time in the U.S. Pacific Time time zone.
Table 14-2 Date and Time Pattern Examples
Date and Time Pattern | Result |
---|---|
"yyyy.MM.dd G 'at' HH:mm:ss z" |
2001.07.04 AD at 12:08:56 PDT |
"EEE, MMM d, '' yy" |
Wed, Jul 4, '01 |
"h:mm a" |
12:08 PM |
"hh 'o''clock' a, zzzz" |
12 o'clock PM, Pacific Daylight Time |
"K:mm a, z" |
0:08 PM, PDT |
"yyyyy.MMMMM.dd GGG hh:mm aaa" |
02001.July.04 AD 12:08 PM |
"EEE, d MMM yyyy HH:mm:ss Z" |
Wed, 4 Jul 2001 12:08:56 -0700 |
"yyMMddHHmmssZ" |
010704120856-0700 |
"yyyy-MM-dd'T'HH:mm:ss.SSSZ" |
2001-07-04T12:08:56.235-0700 |
If you are sending datetime data to an Oracle BAM EMS through Oracle AQ JMS, the following must be considered while configuring a DateTime Specification.
The default datetime formats in Oracle database are specified either explicitly, with the NLS session parameters NLS_DATE_FORMAT
, NLS_TIMESTAMP_FORMAT
, and NLS_TIMESTAMP_TZ_FORMAT
, or implicitly, with the NLS session parameter NLS_TERRITORY
.
If trigger processing code (PL/SQL) does not override the date format with explicit formatting, the dates are formatted according to the format specified by NLS parameters for the database session, and sent accordingly to EMS. This situation means that the EMS DateTime Specification must have the equivalent format of NLS parameters to parse and interpret the incoming data.
However, problems arise on the EMS side if a database administrator changes the NLS parameters. It is always safe to use explicit formatting using the to_char()
function, rather than rely on the default NLS parameters specified format.
A line such as this example in Trigger processing code
'<HIREDATE>' || :new.HIREDATE || '</HIREDATE>' ||
should be changed to something similar to
'<HIREDATE>' || to_char(:new.HIREDATE, 'MM/dd/yy HH24:MI:SS') || '</HIREDATE>' ||
The corresponding format selected from EMS DateTime Specification drop-down list is MM/dd/yy H:mm:ss
.
Similarly, for timestamp data, if the format selected on the database side with the to_char()
function is MM/dd/yy HH24:MI:SS.FF
, the corresponding EMS DateTime Specification format is MM/dd/yy H:mm:ss:SSS
.
The Advanced formatting options allow an EMS to contain a user-supplied XSL Transformation (XSLT) for each formatted field in the message.
Uses for XSLT include:
Handling of hierarchical data. The Data Flow does not handle hierarchical data. The XSLT can flatten the received XML into a single record with repeating fields.
Handling of message queues that contain messages of multiple types in a single queue. The Data Flow requires that all records from the Message Receiver be of the same schema. The EMS output can be defined as a combined superset of the message schemas that are received, and the XSL transformation can identify each message type and map it to the superset schema as appropriate.
Handling of XML that, while not expressing hierarchical data, does contain needed data at multiple levels in the XML. EMS formatting can only read from one level with the XML. The XSL transformation can identify the data needed at various levels in the input XML and output it all in new XML that contains all of the data combined at one level.
To specify an XSL transformation:
Configure the Error Handling settings to specify how you want EMS payload errors to be handled. You can configure how to handle errors in EMS payloads in these ways: write the error message to a log file, insert the error message into a data object, or publish the error message to a JMS topic or queue.
Error handling occurs after rollback has occurred and after all JMS message retries have failed.
To configure fault handling:
Table 14-3 Parameters for Write Faulted Messages Options
Option | Parameter | Description |
---|---|---|
To Data Object |
Error Data Object |
The data object name to which to write the error message. |
To Data Object |
Data Object Field |
The field in the data object to which to write the error message. Be sure to select a string field that is long enough to accommodate the longest error payload. |
To JMS Queue/Topic |
Initial Context Factory |
The initial context factory to be used for looking up specified JMS connection factory or destination. For example: weblogic.jndi.WLInitialContextFactory |
To JMS Queue/Topic |
JNDI Service Provider URL |
Configuration information for the service provider to use. Used to set javax.naming.Context.PROVIDER_URL property and passed as an argument to initialContext(). An incorrect provider URL is the most common cause of errors. For example: t3://localhost:7001 |
To JMS Queue/Topic |
Topic/Queue Connection Factory |
The name used in a JNDI lookup of a previously created JMS connection factory. For example: jms/QueueConnectionFactory |
To JMS Queue/Topic |
Topic/Queue Name |
The Topic/Queue used to post the error message. For example: jms/demoQueue jms/demoTopic |
To JMS Queue/Topic |
JNDI Username |
The identity of the principal for authenticating the JNDI service caller. This user must have RMI login permissions. |
To JMS Queue/Topic |
JNDI Password |
The identity of the principal for authenticating the JNDI service caller. |
To JMS Queue/Topic |
JMS Username (Optional) JMS Password (Optional) |
You can optionally provide this information when a new JMS connection is created by a connection factory. Used to authenticate a connection to a JMS provider for either application-managed or container-managed authentication. |
The following example is the format of a published message:
EMS <<EMS Name>> failed to process the payload: <<payload>> with the following exception: <<Exception details>>.
For example:
EMS MyInsertEMS, failed to process the payload: <testems><test>abcd</test1> with the following exception: The end-tag for element type "test" must end with a '>' delimiter.
Use caution while designing the fault handling when the error message is pushed to a JMS topic or queue. If this topic or queue is in turn configured for another (or the same) EMS, then that EMS pulls the same message again, which fails recursively. Although Oracle BAM has taken care of the message by encoding that message with a CDATA, there might be other issues such as SQL exceptions that might fail recursively.
This section includes the following topics:
To open the EMS, see Editing an Enterprise Message Source.
Use the Start and Stop buttons on an EMS definition tab to start and stop the EMS. In the Stopped status, the consumer is inactive.
Starting an EMS subscribes it and stopping an EMS unsubscribes it.
By default, the EMS starts when the Oracle BAM Server is started.
Click Edit to change the Auto-Start setting.
Note:
The default value for EMS Auto-Start is No.To open the EMS, see Editing an Enterprise Message Source.
Use the Metrics button on an EMS definition tab to monitor selected EMS statistics. The Metrics dialog displays the Server Name, Messages Sent, Messages Persisted, and Messages Lost counters. These values are accumulated since last start or reset.
Server Name indicates the name of the server on which EMS is currently running. This facilitates the identification of the node at which EMS is running in cluster environments.
Messages Lost is calculated by subtracting Messages Persisted from Messages Sent.
Click Refresh to see these latest counter values.
Click Reset to set counter values to zero.
Note:
If you want better throughput and do not need Metrics data, you can set the JVM argument to-Dems.metrics.required=false
at server start. After specifying the flag, you will not see the message count in Metrics and because the state is not maintained, you can expect a better performance.To change security settings for an EMS:
Go to the Administrator page.
In the left navigation pane, click the arrow to the left of Enterprise Message Sources.
All EMS objects in the current project are displayed in a list.
Right-click the EMS and select Security from the pop-up menu.
The security tab for the EMS opens.
To add a role or group to whom you can explicitly grant or deny permissions, follow these steps:
Click the Add icon in the Grant Permissions or Deny Permissions table.
The Add Application Roles, Groups, and Users dialog opens.
See Managing Oracle BAM Users for information about how to add users to roles and groups.
Type a Name for the role or group you are adding.
Select from the drop-down List: Application Role or Group.
Click Search to populate the Available Members list.
To add a member to the Selected Members list, select the member and click the single right arrow.
To add all members to the Selected Members list, select the member and click the double right arrow.
To remove members from the Selected Members list, use the single and double left arrows.
When the Selected Members list is final, click OK.
The Add Application Roles, Groups, and Users dialog closes, and the Name you specified appears in the table.
To remove a role or group, select the table row and click the Remove icon.
To grant permissions, select Read, Write, Remove, or Security for the users, roles, and groups listed in the Grant Permissions table.
To deny permissions, select Read, Write, Remove, or Security for the users, roles, and groups listed in the Deny Permissions table.
Click Save.
You must stop an EMS before you can delete it. See Starting and Stopping an Enterprise Message Source.
To delete an EMS:
You configure an outbound connection JNDI in the Oracle WebLogic Server Administration Console.
To create an outbound connection JNDI:
Oracle WebLogic Server can integrate non-Oracle WebLogic Server (foreign) JMS providers with applications deployed in it. One such application is Oracle BAM.
Foreign JMS providers have their own JMS client and Java Naming and Directory Interface (JNDI) Client APIs. Some configuration must be done to identify these depedencies and make these APIs available on Oracle WebLogic Server so that JMS resources hosted on a remote provider can be looked up by applications deployed in Oracle WebLogic Server.
See "Oracle JCA Adapter for JMS" in Understanding Technology Adapters and "Configuring Foreign Server Resources to Access Third-Party JMS Providers" in Administering JMS Resources for Oracle WebLogic Server for more information.
The high level configuration steps are:
To address this, Oracle BAM ships with an EMSHistory data object. It is automatically created when you start the server. JCA service exceptions are captured by this data object, which keeps the EMS instance running. If you would like to make the EMS instance stop, you can configure it accordingly.