1. Monitoring Business Activity with Oracle BAM
  2. Using Oracle Business Activity Monitoring as an Administrator
  3. Creating Oracle BAM Enterprise Message Sources

15 Creating Oracle BAM Enterprise Message Sources

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:

15.1 Understanding Enterprise Message Sources

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

15.2 Creating Enterprise Message Sources

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.

This section includes the following topics:

15.2.1 Preparing to Create an Enterprise Message Source

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.

15.2.2 Creating an Enterprise Message Source: Steps

To create an EMS:

  1. Go to the Administrator page.
  2. Click Enterprise Message Sources, or right-click Enterprise Message Sources and select the Create menu item.

    The Enterprise Message Sources dialog appears.

  3. Type a Name and optionally edit the Display Name.

    The Name is case sensitive, must begin with a letter, and may consist only of letters, numbers, and the underscore character. It may have up to 128 characters. It cannot be changed after the EMS is created.

    The Display Name is case sensitive and may contain any characters except the forward slash (/), which indicates a folder path. It may have up to 128 characters. It can be changed at any time.

  4. Click Create.

    The EMS opens in a new tab.

  5. Specify the following Connection Information settings:

    • Outbound Connection JNDI — Type the JNDI name of a JMS connection factory created using the JMS Adapter. The default is eis/bam/wls/Queue.

      For a durable subscriber, the outbound connection JNDI should have a ClientID in FactoryProperties. You can use eis/bam/wls/DurableTopic or examine its properties.

      See Creating an Outbound Connection JNDI for information about how to create an outbound connection JNDI.

    • Topic/Queue Name — Type the JNDI name of a JMS topic or queue. The default is jms/demoQueue.

    • Durable Subscriber Name — Type the name of the subscriber, for example, BAMFilteredSubscription. The Durable Subscriber Name should match the event-publisher subscriber name property if it is provided.

      A durable subscription can preserve messages published on a topic while the subscriber is not active. It enables Oracle BAM to be disconnected from the JMS provider for periods of time, and then reconnect to the provider and process messages that were published during the disconnected period.

    • Auto-Start — Select Yes to specify that the EMS starts reading messages and sending them to the data object as soon as the Oracle BAM Server starts or restarts. The default value is No.

      Note:

      A system generated data object called EmsStatus that monitors the status of the EMS is automatically created when the server is started. Oracle strongly recommends that you refrain from deleting this data object.
  6. Specify the following Message Configuration settings:

    • Source Value Formatting: Use DateTime Specification — See Configuring a DateTime Specification.

    • Error Handling — See Configuring EMS Error Handling.

    • JMS Message Type — Select Text Message or Map Message.

      In a Text Message, payload contents are in XML format, and you must specify XML Message Formatting settings.

    • Message Selector — Type a single name-value pair to have the JMS provider select, or filter, messages on its behalf using application-specific criteria. When this parameter is set, the application-defined message property value must match the specified criteria for it to receive messages. To set message property values, use the stringProperty() method of the Message interface.

      The name value pair format should be name='value', for example, message='mymessage'. The equals sign (=) is the name-value pair separator. Currently only one name-value pair is supported.

    • Use Thread Pool for Parallel Message Processing — Check this box to improve performance by allowing multiple messages to be processed at once.

  7. If the JMS Message Type is Text Message, specify the following XML Message Formatting settings:

    • Message Element Name — Type the parent element that contains column values in either its sub-elements or attributes.

    • Message Element Namespace — To qualify messages, optionally type the namespace URI for the message element. Only message elements containing this namespace are persisted.

    • Batch Messages — Check this box to batch multiple messages in a single JMS message. Specify the wrapper element in Batch Element Name. To qualify batched messages, optionally specify the namespace URI in Batch Element Namespace.

    • XSL Formatting: Use Pre-Processing — Check this box to apply an XSL transformation to an incoming text message prior to message retrieval and column mapping. See Using Advanced XML Formatting.

    • XML Column Value — Select Element Tag or Attribute. Column values can be specified using either elements or attributes in an XML payload.

  8. Specify the following Source To Data-Object Field Mapping settings:

    • Use Self-Described Payload — Check this box if the EMS payload contains the data-object field mapping information.

      A self-described payload must specify dataObjectName, operationType, and keys as attributes of the root element. Keys are optional for insert operations. Specify multiple keys separated by commas. For example: 

      <msgRoot dataObjectName="DATADO" operationType="insert" keys="region">
  <region>N100</region>
  <state>DF</state>
  <sales>665</sales>
</msgRoot>

    • Use Persistence Payload — Check this box if the EMS payload does not contain the data-object field mapping information.

      A Persistence Payload adheres to the DataObjectOperations XSD, and EMS does not perform XML parsing on the payload. Each payload is passed directly to BAM Persistence for processing. This means that the payload allows any combination of operations — like insert, update, upsert, or delete — against any set of data objects. Thus, that set of multiple data objects is updated all at once.

      Note:

      The datetime specification and XML Message Formatting properties are not applicable when you use the Persistence Payload option.

    • Data Object Name — Type the name or click Browse to select a data object.

    • Operation — Select Insert, Upsert, Update, or Delete.

    • Key — Check this box if the field is a key.

    • Tag/Attr Name — Type the source tag or attribute name for the corresponding Data Object Field.

  9. Click Save.

    After you save the EMS, Edit, Start, Stop, Metrics, and Copy EMS buttons appear, and the EMS settings are no longer editable. See Using Enterprise Message Sources for more information.

15.2.3 Configuring a DateTime Specification

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:

  1. In an EMS that you are creating or editing, check Use DateTime Specification.

    A datetime format link that shows the default format, <MM/dd/yyyy HH:mm:ss.SSS>, appears.

  2. Click the datetime format link.

    The DateTime Specification dialog appears.

  3. Select a datetime pattern from the Pattern drop-down list or type a pattern.

    You must supply a valid date and time pattern that adheres to the Java SimpleDateFormat. Table 15-1 provides the syntax elements for SimpleDateFormat, and Table 15-2 provides some examples.

    When you explicitly select the HH:mm:ss datetime format, the default value 1/1/1970 is inserted for the date, and the EMS ignores the date value.

    When you explicitly select only the date (excluding the hour, minute, and second) as the datetime format, then the date is inserted with its hour, minute, and second set to 12:00:00 AM. The EMS ignores the time value.

  4. Optionally enter the locale information:

    • Language — This should be a lowercase two-letter ISO-639 code, for example, en, fr, de, it.

    • Country — This should be uppercase two-letter ISO-3166 code, for example, CN, TW, FR, DE.

    • Variant — This can be vendor or browser specific code. For example, use WIN for Windows or MAC for Macintosh. Where there are two variants, separate them with an underscore, and put the most important one first. For example, a Traditional Spanish collation might construct a locale with parameters for language, country, and variant as es, ES, Traditional_WIN.

  5. Click OK.

Table 15-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 15-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 15-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
15.2.3.1 Oracle AQ JMS DateTime Considerations

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.

15.2.4 Using Advanced XML Formatting

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:

  1. In an EMS that you are creating or editing, check XSL Formatting: Use Pre-Processing.
  2. Click Advanced Formatting Options.

    The XSL Transformation dialog opens.

  3. In the Enter XSL Transformation Code field, type or paste the XSL markup for the transformation. You can write the XSL markup in another editing tool and then copy and paste the code into this dialog.
  4. In the Sample XML to Transform field, type sample XML to test the transformation against. The sample XML is not saved in this dialog and is not displayed if you close and reopen this dialog.
  5. Click Verify XSL Syntax to validate the XSL syntax.
  6. Click Test transformation on sample XML to test your transformation.

    The results are displayed in the Results field, including any errors in the XSL syntax, the sample XML syntax, or the transformation.

  7. Click OK.

15.2.5 Configuring EMS Error Handling

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:

  1. In an EMS that you are creating or editing, check Log faulted messages to send error messages to the log, or check Write faulted messages to write error messages to an Oracle BAM data object or a JMS topic.

    You can select both options to log and write faulted messages.

  2. If you selected Log faulted messages, you can select Include payloads to include the payloads with the error messages in the log.
  3. If you selected Write faulted messages, select To Data Objects to insert the messages in a data object, or select To JMS Queue/Topic to write the messages to JMS. Then use Table 15-3 to provide additional information for the option you selected.

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

15.3 Using Enterprise Message Sources

You can modify EMS attributes to suit your organization’s needs.

This section includes the following topics:

15.3.1 Editing an Enterprise Message Source

To edit an EMS:

  1. Go to the Administrator page.
  2. 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.

  3. Click the EMS name, or right-click the EMS name and select the Edit menu item.

    The EMS opens in a new tab.

  4. If the EMS has been saved previously, click the Edit button to make the settings editable.
  5. Make any desired changes and click Save.
  6. Click the X on the EMS tab to close it.

15.3.2 Starting and Stopping an Enterprise Message Source

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.

You can also start and stop an EMS using bamcommand like so:

bamcommand -cmd start -name <ems_name> -type ems

bamcommand -cmd stop -name <ems_name> -type ems

15.3.3 Monitoring Enterprise Message Source Metrics

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.

15.3.4 Copying an Enterprise Message Source

To copy an EMS:

  1. Go to the Administrator page.
  2. 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.

  3. Click the EMS name, or right-click the EMS name and select the Edit menu item.

    The EMS opens in a new tab.

  4. Click Copy EMS.

    The Copy EMS dialog appears.

  5. Type a Name and a Display Name.

    The Name is case sensitive, must begin with a letter, and may consist only of letters, numbers, and the underscore character. It may have up to 128 characters. It cannot be changed after the EMS is created.

    The Display Name is case sensitive and may contain any characters except the forward slash (/), which indicates a folder path. It may have up to 128 characters. It can be changed at any time.

  6. Click OK.

    The EMS copy opens in a new tab.

  7. Follow the steps in Creating an Enterprise Message Source: Steps beginning with step 5.

15.3.5 Securing an Enterprise Message Source

To change security settings for an EMS:

  1. Go to the Administrator page.

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

  3. Right-click the EMS and select Security from the pop-up menu.

    The security tab for the EMS opens.

  4. To add a role or group to whom you can explicitly grant or deny permissions, follow these steps:

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

    2. Type a Name for the role or group you are adding.

    3. Select from the drop-down List: Application Role or Group.

    4. Click Search to populate the Available Members list.

    5. To add a member to the Selected Members list, select the member and click the single right arrow.

    6. To add all members to the Selected Members list, select the member and click the double right arrow.

    7. To remove members from the Selected Members list, use the single and double left arrows.

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

  5. To remove a role or group, select the table row and click the Remove icon.

  6. To grant permissions, select Read, Write, Remove, or Security for the users, roles, and groups listed in the Grant Permissions table.

  7. To deny permissions, select Read, Write, Remove, or Security for the users, roles, and groups listed in the Deny Permissions table.

  8. Click Save.

15.3.6 Deleting an Enterprise Message Source

You must stop an EMS before you can delete it. See Starting and Stopping an Enterprise Message Source.

To delete an EMS:

  1. Go to the Administrator page.
  2. 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.

  3. Click the EMS icon and click the Delete icon, or right-click the EMS name and select the Delete menu item.

    A dialog asks you to confirm the EMS deletion.

  4. Click OK.

    The EMS disappears from the list.

15.4 Creating an Outbound Connection JNDI

You configure an outbound connection JNDI in the Oracle WebLogic Server Administration Console.

To create an outbound connection JNDI:

  1. Access the Oracle WebLogic Server console using a URL that includes the Oracle WebLogic Server hostname and the console port:
    http://wls-hostname:console-port/console

    For example:

    http://localhost:7011/console
  2. Log in using the Oracle WebLogic Server admin username and password.
  3. In the left pane of the Oracle WebLogic Server Administration Console, select Deployments.
  4. On the Summary of Deployments page, Control tab, expand the BamServer node.
  5. Click the BeamAdapter.rar link.
  6. On the Settings for BeamAdapter.rar page, click the Configuration tab and the Outbound Connection Pools subtab.
  7. Expand the oracle.tip.adapter.jms.IJmsConnectionFactory node.
  8. Click New.
  9. Select oracle.tip.adapter.jms.IJmsConnectionFactory and click Next.
  10. Type the JNDI Name and click Finish.

    The JNDI name for an EMS must begin with eis. An example JNDI name is eis/bam/wls/TestQueue.

  11. Click OK to save the outbound connection JNDI with a deployment plan.

    The default path is FMW_HOME/soa/bam/Plan.xml.

  12. When the Settings for BeamAdapter.rar page reappears, click the Configuration tab and the Outbound Connection Pools subtab again.
  13. Expand the oracle.tip.adapter.jms.IJmsConnectionFactory node again.
  14. Click the name of the outbound connection JNDI that you created.

    The Outbound Connection Properties page appears.

  15. Specify each of the following properties by clicking the Property Value table cell, typing the value, and pressing Enter.

    • ConnectionFactoryLocation — Type the value for your JMS provider. For Oracle WebLogic Server, enter weblogic.jms.ConnectionFactory, or your custom connection factory details.

    • FactoryProperties — Specify the following properties in the following format:

      InitialContextFactory=value;JNDIServiceProviderURL=value;
JNDIUserName=value;JNDIPassword=value

      For example:

      java.naming.factory.initial=weblogic.jndi.WLInitialContextFactory;
java.naming.provider.url=t3://www.example.com:7001;
java.naming.security.principal=weblogic;
java.naming.security.credentials=weblogic1

      Property descriptions are as follows:

      • InitialContextFactory — The initial context factory to be used for looking up specified JMS connection factory or destination.

      • JNDIServiceProviderURL — The configuration information for the service provider. Used to set the javax.naming.Context.PROVIDER_URL property and passed as an argument to initialContext().

      • JNDIUserName — The identity of the principal for authenticating the JNDI service caller. This user must have RMI login permissions. Used to set javax.naming.Context.SECURITY_PRINCIPAL and passed to initialContext().

      • JNDIPassword — The identity of the principal for authenticating the JNDI service caller. Used to set javax.naming.Context.SECURITY_CREDENTIALS and passed to initialContext().

    • IsTopic — Type true for a Topic or false for a Queue.

    • Password and Username — Type the credentials used to authenticate a connection to a JMS provider for either application-managed or container-managed authentication.

  16. Click Save.
  17. Re-start WLS and BAM servers.

    Note:

    You must update the adapter deployment if you change Oracle BAM adapter properties. For more information, see Updating the Oracle BAM Adapter Deployment.

15.5 Updating the Oracle BAM Adapter Deployment

When you deploy a SOA composite using a new JNDI, its name must be specified in the JCA file and be referable on the weblogic server (WLS) before you deploy the composite so BAM Adapter properties are updated.

To update Oracle BAM Adapter deployments:
  1. Log in to the administration console.
  2. Click the Lock and Edit button.
  3. In Deployments, check the box next to bamjcaadapter.
  4. Click Update, then check the Redeploy this application using the following deployment files: button that appears in the next screen.
  5. Click Finish.

15.6 Using Foreign JMS Providers

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

  1. Make the JMS and JNDI client library of the foreign provider available to applications deployed on Oracle WebLogic Server.

    Identify the JMS and JNDI client Java Archive (JAR) files of the foreign provider and place them in the WLS_HOME/lib directory.

  2. Create a foreign server using Oracle WebLogic Server Administration Console.

    Go to JMS Modules in Oracle WebLogic Server Administration Console, and create a new module.

    Inside this module, click New, select Foreign Server, and create a new foreign server by navigating through all the pages.

    Provide appropriate JNDI properties for the remote provider for the foreign server definition.

  3. Create JMS resources (that is, connection factories and destinations) for the foreign JMS server.

    Inside the Foreign Server link, select the Destination tab and create links for

    • Remote ConnectionFactory

    • Remote Destination (Queue/Topic)

    Local JNDI names configured for these destinations must be used while configuring EMS to consume messages from these destinations.

  4. Configure an EMS definition on the Administrator page of BAM Composer to consume messages from foreign destinations.

    The whole process of accessing JMS resources hosted on foreign providers is transparent to Oracle BAM Server. After the previous steps have been followed correctly, remote destinations from foreign JMS providers are published on the local WL server JNDI tree, so that applications deployed on the server (like Oracle BAM EMS) can look them up, just like any other collocated Oracle WebLogic Server JMS resource. Oracle WebLogic Server takes care of communicating with the appropriate foreign JMS provider at runtime.

15.7 Configuring the JCA Alerts Mechanism in EMS

An Oracle BAM EMS instance starts the JCA Service in a background thread. If JCA encounters any exception such as a Remote Queue failure, the JCA Service sends an alert exception to BAM EMS.

Oracle BAM now provides for an alert mechanism that can notify you about these JCA exceptions.

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.

To configure a JCA alert mechanism:
  1. In Oracle BAM Composer, create a new project or select an existing project. For more information on creating a project, see Creating a Project.
  2. Add the EmsHistory data object to the project.
  3. Create an alert. See Creating an Alert for more information.
  4. Select the When a data field in a data object meets specified conditions Event Trigger.
  5. Click the <this data field has a condition of x> condition and select the EmsHistory data object.
  6. Add a row filter with the conditions EMS NAME and is not null and click OK.
  7. Click <select user> and assign an appropriate user role.
  8. Click the <add action> link, select Send a message via email, then complete all required fields in the Message Editor.
  9. Click OK.