1. Modeling OSM Processes
  2. Working with Tasks
  3. Task Editor
  4. Task Editor Automation Tab
  5. Properties View External Event Receiver Tab

Properties View External Event Receiver Tab

Use the Properties view External Event Receiver tab to define how OSM retrieves and processes messages placed on the queue by external systems.

The Properties view External Event Receiver tab appears only for Automator and Sender plug-in types defined as external event receivers. External event receivers listen to external system queues or topics for JMS messages. To define a plug-in as an external event receiver, select the External Event Receiver option on the Add Automation dialog box when creating a new automation entry.

Field Use

JNDI Name

Enter the name of the external system from which the plug-in receives messages. JNDI Name is mandatory and contains a system-supplied default value which you must change to reflect your own system topology. The JNDI Name must be unique in the workspace.

The default value with which Design Studio initially populates this field depends on where the automation is defined:

  • If automation is defined for a task (automated task, task state-based event notification, task jeopardy notification), the JNDI name defaults to TaskName.AutomationName.jndiName, where TaskName is the name you provided when defining the task, and AutomationName is the name you provided when defining the automation.

  • If automation is defined for an order (order milestone-based event notification, order data changed event notification, order jeopardy notification), the JNDI name defaults to OrderName.AutomationName.jndiName, where OrderName is the name you provided when defining the order, and AutomationName.jndiName is the name you provided when defining the automation.

  • If automation is defined for a process (task state-based event notification, task status-based event notification), the JNDI name defaults to ProcessName.AutomationName.jndiName, where ProcessName is the name you provided when defining the task, and AutomationName is the name you provided when defining the automation.

Destination Type

Select the type of the response destination. A JMS destination is either a javax.jms.Queue or a javax.jms.Topic. Topics are generally used when messages are published for general availability to multiple external systems. Queues are generally used if the sender wants only a single external system to consume the message.

URL, Initial Context Factory, Connection Factory

(Optional) Enter this information to connect to an external application server. Specify the URL and the InitialContextFactory class for the JNDI provider, and specify the ConnectionFactory class for the JMS server.

Message Property Selector

Enter a selector based on the message properties applied to the external queue. Using an XPath expression or query statement in this field enables you to filter incoming messages to only those messages with specific properties defined at the header level. Using a message property enables you to interrogate the message on the external queue and determine which plug-in should perform the processing of this task instance.

When you have multiple plug-ins with identical event receiver types defined for a task, the OSM server will select the first plug-in whose message property selector evaluates to true. A message on an external JMS queue can be consumed only once. Consequently, it is critical to ensure that your plug-ins consume the appropriate messages. Useful properties for selection include source, type, process, process status, or priority.

For example, for a single task, you might create multiple external event receiver Automator plug-ins, each defined with a mutually exclusive message property to distinguish between task priority levels, where one plug-in processes tasks defined as high priority, and a different plug-in processes tasks defined as low priority.

Note: See the JMS specification for the syntax of this selector expression on the Oracle Technology Network website at:

http://www.oracle.com/technetwork/java/jms/index.html

Note: When you define only one automation plug-in external event receiver for each automated task, and you use the Optimized build-and-deploy mode to build and deploy automation plug-ins, you are not required to enter a selector in the Message Property Selector field. (For OSM 7.3 servers and later, Optimized is the only build-and-deploy mode available.) In this case, automated tasks can share the same JMS queue without a message property selector being set. You must set a message property selector when you do either of the following:

  • Define multiple automation plug-in external event receivers for the same automated task.

  • Use the Legacy build-and-deploy mode to build and deploy cartridges with automation plug-ins.

  • Use the Both (Allow server preference to decide) build-and-deploy mode to build and deploy cartridges with automation plug-ins and configure the OSM server dispatch mode for the Internal mode.

    For information on build-and-deploy modes, see "Defining Build-and-Deploy Modes for Automation Plug-ins."

Note: XPath and XQuery fields are limited to 4000 characters.

XML Message Body Selector

In the Select field, enter an XPath expression to select an element from the XML body content. In the Compare field, enter the string value of the element to determine the match. Using an XPath expression in this field enables you to filter incoming messages to only those messages defined with specific properties in the body of incoming messages.

The XML Message Body Selector function is deprecated, but it is supported for backward compatibility. Oracle recommends that you use an alternate way of filtering messages such as message property selector.

For example, the following sample response from the external system includes a <typeOrder> element that defines the order type:

<orderResponse xmlns="http://xmlns.oracle.com/communications/sce/dictionary/OsmCentralOMExample/interactionResponse" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <numSalesOrder>1</numSalesOrder>
    <numOrder>3</numOrder>
    <typeOrder>NEW</typeOrder>
    <errorCode>0</errorCode>
    <message>OK</message>
    <status>A</status>
</orderResponse>

For this example response, to consume only the NEW type of order, you can use either of the following in the Select field:

  • For a non-namespace-aware query:

    /*[local-name() ='orderResponse']/*[local-name()='typeOrder']/text()

  • For a namespace-aware query:

    /*[local-name() ='orderResponse' and namespace-uri()=' ://xmlns.oracle.com/communications/sce/dictionary/OsmCentralOMExample/interactionResponse']/*[local-name()='typeOrder' and namespace-uri()='://xmlns.oracle.com/communications/sce/dictionary/OsmCentralOMExample/interactionResponse']/text()

In both cases, you would set the Compare field to NEW. All selected messages that contain a typeOrder parameter value of NEW (for example, as opposed to Revision, or Follow-On) would be directed to the automation plug-in.

Note: You can use the XML Message Body Selector with response messages of type XMLMessage. OSM ignores the selector for other message types, such as TextMessage. If you need to use the message body selector ensure that messages are of type XMLMessage message. For non-XMLMessage messages you are restricted to the Message Property Selector.

Note: XPath and XQuery fields are limited to 4000 characters.

Related Topics

Example: Modeling a Basic Automator Plug-In

Configuring Automation Plug-In Properties

Working with Automated Tasks