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.

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.

     The Persistence payload can be in POJO (EJB,JMS), XML (EJB,JMS,HTTP/REST) or JSON (EJB,JMS,HTTP/REST) format. BAM Persistence processes the operations in this collection in the order they were added. You can send a JMS message to BAM Persistence containing any of the three formats as Object or Text messages.

     The following XSD shows the format of the XML schema.

     <?xml version="1.0" encoding="UTF-8"?>
     <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <xsd:complexType name="column" abstract="true">
           <xsd:sequence/>
           <xsd:attribute name="name" type="xsd:string"/>
           <xsd:attribute name="predicate" type="filterPredicate"/>
           <xsd:attribute name="action" type="updateAction"/>
        </xsd:complexType>
        <xsd:complexType name="DataObjectDeleteOperation">
           <xsd:complexContent>
              <xsd:extension base="dataObjectFilteredOperation">
                 <xsd:sequence/>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="dataObjectFilteredOperation" abstract="true">
           <xsd:complexContent>
              <xsd:extension base="dataObjectOperation">
                 <xsd:sequence>
                    <xsd:element name="filter-columns" minOccurs="0">
                       <xsd:complexType>
                          <xsd:sequence>
                             <xsd:choice maxOccurs="unbounded">
                                <xsd:element name="string" type="stringColumn" minOccurs="0"/>
                                <xsd:element name="integer" type="integerColumn" minOccurs="0"/>
                                <xsd:element name="float" type="floatColumn" minOccurs="0"/>
                                <xsd:element name="decimal" type="decimalColumn" minOccurs="0"/>
                                <xsd:element name="date" type="dateColumn" minOccurs="0"/>
                             </xsd:choice>
                          </xsd:sequence>
                       </xsd:complexType>
                    </xsd:element>
                 </xsd:sequence>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="DataObjectInsertOperation">
           <xsd:complexContent>
              <xsd:extension base="dataObjectOperation">
                 <xsd:sequence>
                    <xsd:element name="insert-columns" minOccurs="0">
                       <xsd:complexType>
                          <xsd:sequence>
                             <xsd:choice maxOccurs="unbounded">
                                <xsd:element name="string" type="stringColumn" minOccurs="0"/>
                                <xsd:element name="integer" type="integerColumn" minOccurs="0"/>
                                <xsd:element name="float" type="floatColumn" minOccurs="0"/>
                                <xsd:element name="decimal" type="decimalColumn" minOccurs="0"/>
                                <xsd:element name="date" type="dateColumn" minOccurs="0"/>
                             </xsd:choice>
                          </xsd:sequence>
                       </xsd:complexType>
                    </xsd:element>
                 </xsd:sequence>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="dataObjectOperation" abstract="true">
           <xsd:sequence/>
           <xsd:attribute name="dataobject" type="xsd:string"/>
           <xsd:attribute name="cdc" type="xsd:boolean" use="required"/>
        </xsd:complexType>
        <xsd:complexType name="DataObjectOperations">
           <xsd:sequence>
              <xsd:element name="operations" minOccurs="0">
                 <xsd:complexType>
                    <xsd:sequence>
                       <xsd:choice maxOccurs="unbounded">
                          <xsd:element name="insert" type="DataObjectInsertOperation" minOccurs="0"/>
                          <xsd:element name="update" type="DataObjectUpdateOperation" minOccurs="0"/>
                          <xsd:element name="upsert" type="DataObjectUpsertOperation" minOccurs="0"/>
                          <xsd:element name="delete" type="DataObjectDeleteOperation" minOccurs="0"/>
                       </xsd:choice>
                    </xsd:sequence>
                 </xsd:complexType>
              </xsd:element>
           </xsd:sequence>
        </xsd:complexType>
        <xsd:complexType name="DataObjectUpdateOperation">
           <xsd:complexContent>
              <xsd:extension base="dataObjectFilteredOperation">
                 <xsd:sequence>
                    <xsd:element name="update-columns" minOccurs="0">
                       <xsd:complexType>
                          <xsd:sequence>
                             <xsd:choice maxOccurs="unbounded">
                                <xsd:element name="string" type="stringColumn" minOccurs="0"/>
                                <xsd:element name="integer" type="integerColumn" minOccurs="0"/>
                                <xsd:element name="float" type="floatColumn" minOccurs="0"/>
                                <xsd:element name="decimal" type="decimalColumn" minOccurs="0"/>
                                <xsd:element name="date" type="dateColumn" minOccurs="0"/>
                             </xsd:choice>
                          </xsd:sequence>
                       </xsd:complexType>
                    </xsd:element>
                 </xsd:sequence>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="DataObjectUpsertOperation">
           <xsd:complexContent>
              <xsd:extension base="dataObjectFilteredOperation">
                 <xsd:sequence>
                    <xsd:element name="update-columns" minOccurs="0">
                       <xsd:complexType>
                          <xsd:sequence>
                             <xsd:choice maxOccurs="unbounded">
                                <xsd:element name="string" type="stringColumn" minOccurs="0"/>
                                <xsd:element name="integer" type="integerColumn" minOccurs="0"/>
                                <xsd:element name="float" type="floatColumn" minOccurs="0"/>
                                <xsd:element name="decimal" type="decimalColumn" minOccurs="0"/>
                                <xsd:element name="date" type="dateColumn" minOccurs="0"/>
                             </xsd:choice>
                          </xsd:sequence>
                       </xsd:complexType>
                    </xsd:element>
                    <xsd:element name="insert-columns" minOccurs="0">
                       <xsd:complexType>
                          <xsd:sequence>
                             <xsd:choice maxOccurs="unbounded">
                                <xsd:element name="string" type="stringColumn" minOccurs="0"/>
                                <xsd:element name="integer" type="integerColumn" minOccurs="0"/>
                                <xsd:element name="float" type="floatColumn" minOccurs="0"/>
                                <xsd:element name="decimal" type="decimalColumn" minOccurs="0"/>
                                <xsd:element name="date" type="dateColumn" minOccurs="0"/>
                             </xsd:choice>
                          </xsd:sequence>
                       </xsd:complexType>
                    </xsd:element>
                 </xsd:sequence>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="dateColumn">
           <xsd:complexContent>
              <xsd:extension base="column">
                 <xsd:sequence/>
                 <xsd:attribute name="value" type="xsd:string"/>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="decimalColumn">
           <xsd:complexContent>
              <xsd:extension base="column">
                 <xsd:sequence/>
                 <xsd:attribute name="value" type="xsd:decimal"/>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="floatColumn">
           <xsd:complexContent>
              <xsd:extension base="column">
                 <xsd:sequence/>
                 <xsd:attribute name="value" type="xsd:double"/>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="integerColumn">
           <xsd:complexContent>
              <xsd:extension base="column">
                 <xsd:sequence/>
                 <xsd:attribute name="value" type="xsd:long"/>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:complexType name="stringColumn">
           <xsd:complexContent>
              <xsd:extension base="column">
                 <xsd:sequence/>
                 <xsd:attribute name="value" type="xsd:string"/>
              </xsd:extension>
           </xsd:complexContent>
        </xsd:complexType>
        <xsd:element name="dataObjectOperations" type="DataObjectOperations"/>
        <xsd:simpleType name="filterPredicate">
           <xsd:restriction base="xsd:string">
              <xsd:enumeration value="NULL"/>
              <xsd:enumeration value="NOTNULL"/>
              <xsd:enumeration value="LIKE"/>
              <xsd:enumeration value="NOTLIKE"/>
              <xsd:enumeration value="EQ"/>
              <xsd:enumeration value="NE"/>
              <xsd:enumeration value="GT"/>
              <xsd:enumeration value="GTE"/>
              <xsd:enumeration value="LT"/>
              <xsd:enumeration value="LTE"/>
           </xsd:restriction>
        </xsd:simpleType>
        <xsd:simpleType name="updateAction">
           <xsd:restriction base="xsd:string">
              <xsd:enumeration value="REPLACE"/>
              <xsd:enumeration value="INCREMENT"/>
              <xsd:enumeration value="DECREMENT"/>
           </xsd:restriction>
        </xsd:simpleType>
     </xsd:schema>

     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.

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.

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.

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.

EMS <<EMS Name>> failed to process the payload: <<payload>> with the following exception:
<<Exception details>>.

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.

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.

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.

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

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.

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.

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.