42 Using Business Events and the Event Delivery Network

This chapter describes how to subscribe to or publish business events from Oracle Mediator or a BPEL process in a SOA composite application. Business events are published to the Event Delivery Network (EDN) and consist of message data sent as the result of an occurrence in a business environment. When a business event is published, other service components can subscribe to it.

This chapter includes the following sections:

For information about creating composite sensors on service components that subscribe to business events, see Defining Composite Sensors .

For information about troubleshooting business events, including specifying the number of threads, stopping event delivery, and specifying the maximum number of deliveries, see Appendix "Troubleshooting Oracle SOA Suite and Oracle BPM Suite" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

For information about managing business events from Oracle Enterprise Manager Fusion Middleware Control, see Chapter "Managing Business Events" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

For information about business event tuning, see Tuning Performance.

42.1 Introduction to Business Events

You can raise business events when a situation of interest occurs. For example, in a loan flow scenario, a BPEL process service component executing a loan process can raise a loan completed event at the completion of the process. Other systems within the infrastructure of this application can listen for these events and, upon receipt of one instance of an event:

Use the event context to derive business intelligence or dashboard data.
Signal to a mail department that a loan package must be sent to a customer.
Invoke another business process.
Send information to Oracle Business Activity Monitoring (BAM).

Business events are typically a one-way, fire-and-forget, asynchronous way to send a notification of a business occurrence. The business process does not:

Rely on any service component receiving the business event to complete.
Care if any other service components receive the business event.
Need to know where subscribers (if any) are and what they do with the data.

These are important distinctions between business events and direct service invocations that rely on the Web Services Description Language (WSDL) file contract (for example, a SOAP service client). If the author of the event depends on the receiver of the event, then messaging typically must be accomplished through service invocation rather than through a business event. Unlike direct service invocation, the business event separates the client from the server.

A business event is defined using the event definition language (EDL). The EDL is a schema used to build business event definitions. Applications work with instances of the business event definition.

The EDL consists of the following:

Defined events

One or more event definitions (event-definition element) with the same namespace (targetNamespace attribute of definitions root element), each having a local name (name attribute of the event-definition element). The namespace and local name constitute an event name (QName).
Payload definition

The most common use for a definition is an XML Schema (XSD). The payload of a business event is defined in an XSD that is imported (through the schema-import element) into the EDL. Each defined event (that is, event-definition element) can have a reference to an imported payload XSD element (the element attribute of the content element). The schema URI is contained in the root element of the payload.

The following example shows an EDL file with two business events in the BugReport event definition: bugUpdated and bugCreated. The namespace (/model/events/edl/BugReport) and associated schema file (BugReport.xsd) are referenced.

<?xml version = '1.0' encoding = 'UTF-8'?>
<definitions targetNamespace="/model/events/edl/BugReport"
 xmlns:ns0="/model/events/schema/BugReport"
 xmlns="http://schemas.oracle.com/events/edl">
   <schema-import namespace="/model/events/schema/BugReport"
 location="BugReport.xsd"/>

   <event-definition name="bugCreated">
      <content element="ns0:bugCreatedInfo"/>
   </event-definition>

   <event-definition name="bugUpdated">
      <content element="ns0:bugUpdatedInfo"/>
   </event-definition>
</definitions>

These two events are available for subscription in Oracle Mediator and a BPEL process.

Business events are deployed to the Oracle Metadata Services Repository (MDS Repository). Deploying a business event to the MDS Repository along with its artifacts (for example, the XSDs) is known as publishing the EDL (or event definition). This action transfers the EDL and its artifacts to a shared area in the MDS Repository. An object in an MDS Repository shared area is visible to all applications in the Resources window of Oracle JDeveloper. After an EDL is published, it can be subscribed to by SOA components such as Oracle Mediator or a BPEL process.

A subscription is for a specific qualified name (QName) (for example, x.y.z/newOrders). A QName is a tuple (URI, localName) that may be derived from a string prefix:localName with a namespace declaration such as xmlns:prefix=URI or a namespace context. In addition, subscriptions can be further narrowed down by using content-based filters.

Business events are published to the EDN. The EDN runs within every Oracle SOA Suite instance. Raised events are delivered by EDN to the subscribing service components. Oracle Mediator service components and BPEL process service components can subscribe to and publish events.

The EDN is based on a standard JMS messaging infrastructure that supports business event-based interactions among Oracle SOA Suite components and non-Oracle SOA Suite components. The EDN provides two JMS-based types:

Oracle WebLogic Server JMS: By default, all business events use a single, default Oracle WebLogic Server JMS topic.
Oracle Advanced Queueing (AQ) JMS

You can create additional JMS topics (Oracle WebLogic Server JMS or AQ JMS) and map different event types to these additional JMS topics in Oracle Enterprise Manager Fusion Middleware Control.

Note:

The EDN does not support durable subscriptions (whether they are backed by native AQ or Oracle WebLogic Server JMS). The subscribing service component must be running to receive events.

42.1.1 EDN Integration with Oracle SOA Suite

Oracle SOA Suite EDN provides the following features:

A standard JMS-based messaging infrastructure that provides the following:
- A JMS-based event publish and subscribe architecture for Oracle SOA Suite and non-Oracle SOA Suite clients.
- Support for bidirectional interactions (can both publish to and subscribe from Oracle SOA Suite and non-Oracle SOA Suite clients).
- Support for both the Oracle AQ JMS and Oracle WebLogic Server JMS providers. An Oracle WebLogic Server JMS topic (default) and an AQ JMS topic are automatically configured for EDN use after installation. The default JMS type can be switched from Oracle WebLogic Server JMS (default) to AQ JMS in Oracle Enterprise Manager Fusion Middleware Control. For more information, see "Mapping Business Events to JMS Topic Destinations on the Business Events Page" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
- EDN support as a lightweight manager above both JMS providers.
- A plain JMS API and an Oracle SOA Suite, value-added EDN API for remote, non-Oracle SOA Suite clients to use for integrating with Oracle SOA Suite. For more information, see Java API Reference for Oracle SOA Suite Event Delivery Network.
- JMS transactions to guarantee EDN delivery (for both the one-and-only-one (OAOO) and guaranteed consistency methods).
- Durable and persistent publishing delivery options to prevent message loss. These default options are beneficial for interactions with remote, non-Oracle SOA Suite clients.
- A JMS adapter used internally for implementing many JMS features. For information about the JMS adapter, see the "Oracle JCA Adapter for JMS" chapter of Understanding Technology Adapters.
- No duplicate event processing in a multinode cluster.
Scalability at a fine-grained level. This enables different events to map to different JMS topic destinations, thereby eliminating the need for a single location to handle all events. This reduces potential bottlenecks. Mapping is performed by an administrator in Oracle Enterprise Manager Fusion Middleware Control. For more information, see the "Mapping Business Events to JMS Topic Destinations" section of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

Support for the following publish and subscribe scenarios:
- Publish and subscribe to events across the same composite or different composites.
  - Use the default EDN Oracle WebLogic Server JMS topic automatically provided.
  - Use the custom event-to-JMS-topic mapping provided in Oracle Enterprise Manager Fusion Middleware Control.
- Publish and subscribe to events with remote, non-Oracle SOA Suite participants through one of the following APIs:
  - Plain JMS API (for J2SE client environments)
  - EDI API EdnJmsConnection (for J2SE and J2EE client environments)
Instance tracking and fault recovery support in the Error Hospital. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite.
The storage of EDL files in the MDS Repository. This makes the files available for browsing in the Resources window in Oracle JDeveloper. For more information, see Managing Shared Data with the Design-Time .

Note:

For memory recommendations on sending large payloads in the event delivery network (EDN) with Oracle AQ JMS, see JVM Memory Sizing Recommendations for SOA Composite Applications.

42.1.2 Business Event API Support for Remote Clients

For remote clients to publish and subscribe to events in Oracle SOA Suite, there are several API options. Table 42-1 provides details.

Table 42-1 Remote API Options

Option Description Supported By Advantages/Disadvantages

Option	Description	Supported By	Advantages/Disadvantages
Plain JMS API	Use to directly interact with EDN JMS topics. This is typically a J2SE client with raw JMS access. The remote client must configure JNDI properties to point to the SOA server.	Oracle WebLogic Server JMS AQ JMS	The advantages are: Supports the standard JMS API, meaning you can use many JMS software tools. The disadvantages are: Service level degradation. Requires manual discovery of mapped JMS and configuration of JNDI. Requires extra coding, including handling of the internal EDN event structure, filter translation, subject propagation, transaction, error handling, and so on.
EDN API - `EdnJmsConnection`	For a J2SE client, such as Oracle Event Processing. This option provides all standard publish and subscribe options. The remote client must perform the following tasks: Configure JNDI properties to point to the SOA server. Invoke the EDN helper method `findRelevantBEConnFactory` to return an appropriate connection factory. This enables you to use a JMS connection for publishing and subscribing to events.	Oracle WebLogic Server JMS AQ JMS	The advantages are: No client JNDI configuration or JMS adapter deployment Handles JMS mapping, conversion, and translation. The disadvantages are: Based on the plain JMS connection factory and topic. For information about the JMS adapter, see the "Oracle JCA Adapter for JMS" chapter of Understanding Technology Adapters.

Plain JMS API

Use to directly interact with EDN JMS topics. This is typically a J2SE client with raw JMS access.

The remote client must configure JNDI properties to point to the SOA server.

Oracle WebLogic Server JMS
AQ JMS

The advantages are:

Supports the standard JMS API, meaning you can use many JMS software tools.

The disadvantages are:

Service level degradation.
Requires manual discovery of mapped JMS and configuration of JNDI.
Requires extra coding, including handling of the internal EDN event structure, filter translation, subject propagation, transaction, error handling, and so on.

EDN API - EdnJmsConnection

For a J2SE client, such as Oracle Event Processing. This option provides all standard publish and subscribe options.

The remote client must perform the following tasks:

Configure JNDI properties to point to the SOA server.
Invoke the EDN helper method findRelevantBEConnFactory to return an appropriate connection factory. This enables you to use a JMS connection for publishing and subscribing to events.

Oracle WebLogic Server JMS
AQ JMS

The advantages are:

No client JNDI configuration or JMS adapter deployment
Handles JMS mapping, conversion, and translation.

The disadvantages are:

Based on the plain JMS connection factory and topic.

For information about the JMS adapter, see the "Oracle JCA Adapter for JMS" chapter of Understanding Technology Adapters.

For more information about the EDN APIs, see Java API Reference for Oracle SOA Suite Event Delivery Network.

42.1.2.1 Guidelines for Manually Setting Event Delivery Network Properties When Invoking the BusinessEvent.setProperty API

When publishing an event delivery network (EDN) business event, most properties cannot be manually set by invoking the BusinessEvent.setProperty(String name, Object value) API.

42.1.2.1.1 Properties That Cannot Be Manually Set

Do not set the following EDN business event properties. The values for these properties are internally set and used by EDN.

General properties:
- BusinessEvent.EVENT_ID ("id")
- BusinessEvent.PARENT_ID ("parent-id")
- BusinessEvent.PUBLISHED_TIME ("published-time")
- BusinessEvent.OWNER ("owner")
- BusinessEvent.SOURCE ("source")
- BusinessEvent.MODE ("mode")

All tracking properties, for example:
- BusinessEvent.PROPERTY_ECID ("tracking.ecid")
- BusinessEvent.PROPERTY_COMPOSITE_INSTANCE_ID ("tracking.compositeInstanceId")
- BusinessEvent.PROPERTY_PARENT_COMPONENT_INSTANCE_ID ("tracking.parentComponentInstanceId")
- BusinessEvent.PROPERTY_CONVERSATION_ID ("tracking.conversationId")
- tracking.compositeInstanceCreatedTime"

42.1.2.1.2 Properties That Can Be Manually Set

You can set the following properties:

BusinessEvent.PRIORITY ("priority")
BusinessEvent.CONTEXT ("context")

42.1.3 Local and Remote Event Connections

A single SOA composite application instance can reside in a single container or can be clustered across multiple containers. Another application (for example, an Oracle Application Development Framework (ADF) Business Component application) can be configured to run in the same container as the SOA composite application instance or in a different container.

Raising an event from a Java EE application can be done through a local event connection or a remote event connection:

Local event connection

If the publisher resides on the same Oracle WebLogic Server as the application and the publisher uses a local business event connection factory, the event is raised through a local event connection.
Remote event connection

If the caller resides in a different container (different JVM) then the application, the event is raised through a remote event connection.

If another application (for example, an Oracle ADF Business Component application) is configured to run in the same container as the SOA composite application, it is optimized to use local event connections.

42.2 Creating Business Events in Oracle JDeveloper

This section provides a high-level overview of how to create and subscribe to a business event.

42.2.1 How to Create a Business Event

To create a business event:

Create a SOA project as an empty composite.
Launch the Create Event Definition wizard in either of the following ways:
1. From the File main menu, select New > Event Definition.
2. From the File main menu, select New > Application > SOA Tier > Service Components > Event Definition.
The Create Event Definition dialog appears.

Enter the details described in Table 42-2.

Table 42-2 Create Event Definition Dialog Fields and Values

Field Value

Field	Value
Name	Enter a name or accept the default name of `EventDefinitionnumber`. The name you enter here becomes the EDL file name in the Applications window. Note: Do not enter a forward slash (`/`) as the event name. This creates an event definition file consisting of only an extension for a name (`.edn`).
Directory	Displays the directory path in which to create the event definition file.
Namespace	Accept the default namespace or enter a value for the namespace in which to place the event. This enables the subscriber to receives events of the indicated namespace.

Name

Enter a name or accept the default name of EventDefinitionnumber. The name you enter here becomes the EDL file name in the Applications window.

Note: Do not enter a forward slash (/) as the event name. This creates an event definition file consisting of only an extension for a name (.edn).

42.3 Subscribing to or Publishing a Business Event from an Oracle Mediator Service Component

This section describes how to subscribe to a business event or publish a business event from an Oracle Mediator service component.

42.3.1 How to Subscribe to a Business Event

To subscribe to a business event:

From the Components window, drag a Mediator service component into the . This service component enables you to subscribe to the business event.
In the Name field, enter a name.
From the Template list, select Subscribe to Events.

The dialog is refreshed to display an events table.
Click the Add icon to select an event.

The Event Chooser dialog appears.
Select an existing event or click the Add icon to create a new event, and click OK.

You are returned to the Create Mediator dialog.

Complete the remaining fields of the dialog. Table 42-3 provides details.

Table 42-3 Events Table of Create Mediator Dialog

Element	Description
Consistency	Click inside the Consistency column to select a level of delivery consistency for the event. one and only one Events are delivered to the subscriber in its own global (that is, JTA) transaction. Any changes made by the subscriber within that transaction are committed after the event processing is complete. If the subscriber fails, the transaction is rolled back. Failed events with retriable exceptions are automatically retried a configured number of times before they are moved to the Error Hospital for recovery (that is, subject to manual retries). Failed events with nonretriable exceptions are moved to the Error Hospital without automatic retries, and are not recoverable. guaranteed Events are delivered to the subscriber in a local JMS transaction. The subscriber can choose to create its own local transaction for processing, but it is committed independently of the rest of event processing. The guaranteed consistency level is a lower quality of service option than one and only one, because a local transaction is used instead of a global transaction. Failed events with retriable exceptions are automatically retried a configured number of times before they are moved to the Error Hospital where they are recoverable, (that is, subject to manual retries. Failed events with nonretriable exceptions are moved to the Error Hospital without automatic retries, and are not recoverable. For information about the Error Hospital, see Section "Recovering From Faults in the Error Hospital" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
Durable	Durable subscriptions prevent against message loss caused by different life cycles of publishers, subscribers, and the framework. Select an option: yes: Events are retained if the subscriber is not running. This is the default selection. no: Events are dropped if the subscriber is not running.
Run as Publisher	Select a security publishing option: yes: The subscriber has the event publisher's security identity. This is the default selection. no: The subscriber does not have the event publisher's security identity.
Filter	If you want to filter the event, double-click the Filter column of the selected event or select the event and click the filter icon (first icon) above the table. This displays the Expression Builder dialog. This dialog enables you to specify an XPath filter expression. A filter expression specifies that the contents (payload or headers) of a message be analyzed before any service is invoked. For example, you can apply a filter expression that specifies that a service be invoked only if the message includes a customer ID. When the expression logic is satisfied, the event is accepted for delivery. For more information about filters, see How to Specify an Expression for Filtering Messages.

Figure 42-3 shows the Create Mediator dialog.

Figure 42-3 Create Mediator Dialog

Description of "Figure 42-3 Create Mediator Dialog"

Click OK.

Figure 42-4 shows an icon on the left side that indicates that Oracle Mediator is configured for an event subscription.

Figure 42-4 Configuration for Event Subscription

Description of "Figure 42-4 Configuration for Event Subscription"

42.3.2 How to Publish a Business Event

You can create a second Oracle Mediator to publish the event that you subscribed to in How to Subscribe to a Business Event. While not shown here, you can also create a BPEL component to publish the event.

To publish a business event:

Create a second Oracle Mediator service component that publishes the event to which the first Oracle Mediator subscribes.
Return to the first Oracle Mediator service component.
In the Routing Rules section, click the Add icon.
Click Service when prompted by the Target Type window.
Select the second Oracle Mediator service component.
From the File main menu, select Save All.

42.3.3 What Happens When You Create and Subscribe to a Business Event

The source code in the following example provides details about the subscribed event of the Oracle Mediator service component.

<component name="OrderPendingEvent">
    <implementation.mediator src="OrderPendingEvent.mplan"/>
    <business-events>
      <subscribe
         xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
         name="sub1:NewOrderSubmitted" consistency="oneAndOnlyOne"
         durable="true" runAsRoles="$publisher"/>
</business-events>
</component>

While not explicitly demonstrated in this example, you can define XPath filters on events. In the following example, the event is accepted for delivery only if the initial deposit is greater than 50000:

    <business-events>
        . . .
        . . .
        <filter>
            <xpath xmlns:be="http://oracle.com/fabric/businessEvent"
                 xmlns:ns1="http://xmlns.oracle.com/singleString"
                   <xpath expression= "/be:business-event/be:content/
                   sub1:AccountInfo/Details[@initialDeposit > 50000]" />
        </filter>
      . . .
      . . .
    </business-events>

42.3.4 What Happens When You Publish a Business Event

Two Oracle Mediator service components appear in the following example. One service component (OrderPendingEvent) subscribes to the event and the other service component (PublishOrderPendingEvent) publishes the event.

<component name="PublishOrderPendingEvent">
    <implementation.mediator src="PublishOrderPendingEvent.mplan"/>
    <business-events>
      <publishes xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
 name="pub1:NewOrderSubmitted" persistent="true" priority="7"
 timeToLive="36000000"/> 
    </business-events>
  </component>

<component name="OrderPendingEvent">
    <implementation.mediator src="OrderPendingEvent.mplan"/>
    <business-events>
      <subscribe
         xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
         name="sub1:NewOrderSubmitted" consistency="oneAndOnlyOne"
          durable="true" runAsRoles="$publisher"/>
</business-events>
</component>

42.3.5 What You May Need to Know About Subscribing to a Business Event

Only subscribers in default revisions of the SOA composite applications can receive business events. For example, note the following behavior.

To subscribe to a business event:

Create a composite application with an initial Oracle Mediator service component named M1 that publishes an event and a second Oracle Mediator service component named M2 that subscribes to the event. The output is written to a directory.
Deploy the composite application as revision 1.
Modify the composite application by adding a third Oracle Mediator service component named M3 that subscribes to the same event and writes the output to a different directory.
Deploy the composite application as revision 2 (the default).
Invoke revision 2 of the composite application.

Oracle Mediator M2 writes the output to one file in the directory. As expected, Oracle Mediator M3 picks up the event and writes the output successfully to another directory. However, Oracle Mediator M2 (from revision 1) is not picking up the published event from revision 2 of the composite application.

42.3.6 What You May Need to Know About Publishing Events Across Domains Using SAF

When publishing events across domains using Store-and-Forward (SAF), local subscribers cannot subscribe to the event. For example, assume you have the following subscribers:

Local subscriber (deployed on the same domain as the event publisher)
Remote subscriber (deployed on a domain external to the event publisher)

Both subscribe to the same event (for this example, named E), which has been configured to listen to the SAF topic. In this environment, only the remote subscriber can subscribe to the event. The local subscriber cannot subscribe to the event.

The JMS topic for EDN must be provisioned as a physical JMS topic instead of as an imported SAF topic. This is because an imported SAF topic has its own rules of context lookup and security checking that EDN does not natively support.

42.3.6.1 Workaround for Local Subscribers

As a workaround, you must perform the following procedures:

Create a local JMS topic that the publisher can locate. For example, in local domain A, which the event publisher can locate, you provision a regular Oracle WebLogic Server JMS topic (for example, named Ta) to which to publish events, and a subscriber (local in domain A) to listen for this topic.
In remote domain B, which a remote subscriber can locate, you create an imported SAF topic (for example, named safTb) that maps to topic Ta from domain A, and have the remote subscriber listen to safTb.

As an alternative to Step 2, you can provision another JMS topic (for example, named Tb) in domain B to which a remote subscriber listens, and create a JMS bridge that bridges source topic Ta to destination topic Tb.

42.3.7 How to Configure a Foreign JNDI Provider to Enable Administration Server Applications to Publish Events to the SOA Server

This section describes how to configure a foreign JNDI provider when the publishing application (for example, an ADF EAR file) is deployed on the administration server instead of the SOA server.

To configure a foreign JNDI provider to enable administration server applications to publish events to the SOA Server:

Log in to the Oracle WebLogic Server Administration Console.
```
http://host:port/console
```
In the Domain Structure section, expand Services > Foreign JNDI Providers.
Click Lock & Edit.
Click New.
In the Name field, enter a name (for example, SOA_JNDI), and click Next.
Select the AdminServer check box, and click Finish.
In the Name column, click the provider name you entered in Step 5.

Enter the details shown in Table 42-4, and click Save.

Table 42-4 Configuration Details

Field	Description
Initial Context Factory	Enter `weblogic.jndi.WLInitialContextFactory`.
Provider URL	Enter `t3://hostname`:`soa_server_port`.
User	Enter the Oracle WebLogic Server user name.
Password and Confirm Password	Enter the password for the Oracle WebLogic Server user name.

Click Links > New.
Enter the details shown in Table 42-5, and click OK.

Table 42-5 Configuration Details

Field Description

Name

Enter SOA_EDNDataSource.

Local Name

Enter jdbc/EDNDataSource.

Remote Name

Enter jdbc/EDNDataSource.
Click New.
Enter the details shown in Table 42-6, and click OK.

Table 42-6 Configuration Details

Field Description

Name

Enter SOA_EDNLocalTxDataSource.

Local Name

Enter jdbc/EDNLocalTxDataSource.

Remote Name

Enter jdbc/EDNLocalTxDataSource.
Click OK.
Click Activate Changes.
Modify the FMW_Home/user_projects/domains/domain_name/bin/setDomainEnv.sh file for Linux (or setDomainEnv.bat file for Windows) as follows:
```
WLS_JDBC_REMOTE_ENABLED="-Dweblogic.jdbc.remoteEnabled=true"
```
Restart the server.

Field	Description
Name	Enter `SOA_EDNDataSource`.
Local Name	Enter `jdbc/EDNDataSource`.
Remote Name	Enter `jdbc/EDNDataSource`.

Field	Description
Name	Enter `SOA_EDNLocalTxDataSource`.
Local Name	Enter `jdbc/EDNLocalTxDataSource`.
Remote Name	Enter `jdbc/EDNLocalTxDataSource`.

42.3.8 How to Configure the Connection Factory When the Oracle WebLogic Server JMS Runs in the Same Local JVM as the JMS Adapter

If Oracle WebLogic Server JMS is running in the local JVM (the same JVM as the JMS adapter), you must correctly configure the isTransacted connector factory property. For your servlet client, which is locally colocated with the Oracle WebLogic Server JMS server to work, perform the following steps:

Log in to Oracle WebLogic Server Administration Console, and select Deployments > JmsAdapter > Configuration -> Outbound Connection Pools.
Expand groups and instances, and select both eis/wls/EDNLocalTxDurableTopic and eis/wls/EDNLocalTxTopic.
Set isTransacted to false.
Save and restart the SOA server.

For more information, see Section "Synchronous/Asynchronous Request Reply Interaction Pattern" of Understanding Technology Adapters.

42.4 Subscribing to or Publishing a Business Event from a BPEL Process Service Component

This section describes how to subscribe to a business event or publish a business event from a BPEL process service component.

42.4.1 How to Subscribe to a Business Event

To subscribe to a business event:

From the Components window, drag a BPEL Process service component into the .
In the Name field, enter a name. Do not change any other default option and click OK.

The BPEL process service component is created.
Double-click the BPEL process service component. Oracle BPEL Designer is opened. Alternatively, you can also right-click the BPEL process service component and click Edit.
Drag a Receive activity from the Components window into the SOA Composite Editor, below the receiveInput activity.

Note:

The onMessage branch of a pick activity can also be set up to receive events from the EDN. For more information about the onMessage branch, see Selecting Between Continuing or Waiting on a Process with a Pick Activity.
Double-click the Receive activity. The Receive dialog opens. Alternatively, you can also right-click the Receive activity and click Edit.
In the Name field, enter a name.
From the Interaction Type list, select Event. The layout of the Receive dialog changes.
Click the Browse Events icon to the right of the Event field. The Subscribed Events dialog appears, as shown in Figure 42-5.

Figure 42-5 Subscribed Events Dialog

Description of "Figure 42-5 Subscribed Events Dialog"
Click the Add icon to select an event.

The Event Chooser dialog appears, as shown in Figure 42-6.

Figure 42-6 Event Chooser Dialog

Description of "Figure 42-6 Event Chooser Dialog"
Select the event you created and click OK.

You are returned to the Subscribed Events dialog.

Select a level of delivery consistency for the event. Table 42-7 provides details.

Table 42-7 Events Table of Subscribed Events Dialog

Element	Description
Consistency	Click inside the Consistency column to select a level of delivery consistency for the event. one and only one Events are delivered to the subscriber in its own global (that is, JTA) transaction. Any changes made by the subscriber within that transaction are committed after the event processing is complete. If the subscriber fails, the transaction is rolled back. Failed events with retriable exceptions are automatically retried a configured number of times before they are moved to the Error Hospital for recovery (that is, subject to manual retries). Failed events with nonretriable exceptions are moved to the Error Hospital without automatic retries, and are not recoverable. guaranteed Events are delivered to the subscriber in a local JMS transaction. The subscriber can choose to create its own local transaction for processing, but it is committed independently of the rest of event processing. The guaranteed consistency level is a lower quality of service option than one and only one, because a local transaction is used instead of a global transaction. Failed events with retriable exceptions are automatically retried a configured number of times before they are moved to the Error Hospital where they are recoverable, (that is, subject to manual retries. Failed events with nonretriable exceptions are moved to the Error Hospital without automatic retries, and are not recoverable. For information about the Error Hospital, see Section "Recovering From Faults in the Error Hospital" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
Durable	Durable subscriptions prevent against message loss caused by different life cycles of publishers, subscribers, and the framework. Select an option: yes: Events are retained if the subscriber is not running. This is the default selection. no: Events are dropped if the subscriber is not running.
Run as Publisher	Select a security publishing option: yes: The subscriber has the event publisher's security identity. This is the default selection. no: The subscriber does not have the event publisher's security identity.
Filter	If you want to filter the event, double-click the Filter column of the selected event or select the event and click the filter icon (first icon) above the table. This displays the Expression Builder dialog. This dialog enables you to specify an XPath filter expression. A filter expression specifies that the contents (payload or headers) of a message be analyzed before any service is invoked. For example, you can apply a filter expression that specifies that a service be invoked only if the message includes a customer ID. When the expression logic is satisfied, the event is accepted for delivery. For more information about filters, see How to Specify an Expression for Filtering Messages.

Click OK to close the Subscribed Events dialog.

You are returned to the Receive dialog.

Note:

Optionally, you can select the Create Instance check box, if this receive activity is the initiating receive activity that starts the BPEL process service component instance. This action enables creation of a new BPEL process service component instance for every invocation.

If this receive activity is a midprocess receive activity in which the BPEL instance is already started, then this receive activity waits for another event to continue the execution of this BPEL instance.
Click OK.

Figure 42-7 shows a BPEL process service component that is configured for event subscription.

Figure 42-7 BPEL Process Service Component Configuration for Event Subscription

Description of "Figure 42-7 BPEL Process Service Component Configuration for Event Subscription"

42.4.2 How to Publish a Business Event

To publish a business event:

Drag an Invoke activity from the Components window into the SOA Composite Editor, below the Receive activity created in How to Subscribe to a Business Event.
Double-click the Invoke activity. The Invoke dialog opens. Alternatively, you can also right-click the Invoke activity and click Edit.
In the Name field, enter a name.
From Interaction Type list, select Event. The layout of the Invoke dialog changes.
To the right of the Event field, click the Browse Events icon. The Event Chooser dialog appears.
Select the event you created and click OK.

You are returned to the Invoke dialog.
Click OK.

Figure 42-8 shows a BPEL process service component that is configured for an event subscription and publication. The blue lightning bolt in the circle on the left side indicates event subscription. The yellow lightning bolt in the circle on the right side indicates event publication. Clicking the blue arrow inside the title changes it to display the title of the published event.

Figure 42-8 BPEL Process Service Component Configuration for Event Subscription and Publishing

Description of "Figure 42-8 BPEL Process Service Component Configuration for Event Subscription and Publishing"

42.4.3 What Happens When You Subscribe to and Publish a Business Event

The source code in the following example shows how the composite.xml source changes for the subscribed and published events of a BPEL process service component.

<component name="EventBPELProcess">
   <implementation.bpel src="EventBPELProcess.bpel"/>
   <property name="configuration.monitorLocation" type="xs:string"
             many="false">EventBPELProcess.monitor</property>
   <business-events>
     <subscribe xmlns:sub1="http://mycompany.com/events/orders"
                name="sub1:OrderReceivedEvent" consistency="oneAndOnlyOne"
                durable="true" runAsRoles="$publisher"/>
     <publishes xmlns:pub1="http://mycompany.com/events/orders"
                name="pub1:ProductSoldAlert" persistent="true" priority="7"
                timeToLive="36000000"/>/>
   </business-events>
</component>

    <business-events>
      <publishes xmlns:sub1="/oracle/fodemo/storefront/entities/events/edl/OrderEO"
 name="pub1:NewOrderSubmitted" persistent="true" priority="7"
 timeToLive="36000000"/> 
    </business-events>
  </component>

While not explicitly demonstrated in this example, you can define XPath filters on events. A filter is typically present in event subscriptions. The subscribe element limits the type of event to which this service component is subscribed, and the filter section further limits the event to specific content in which the component is interested. In the following example, the event is accepted for delivery only if the initial deposit is greater than 50000.

    <business-events>
        . . .
        . . .
        <filter>
            <xpath xmlns:be="http://oracle.com/fabric/businessEvent"
                 xmlns:ns1="http://xmlns.oracle.com/singleString"
                   <xpath expression= "/be:business-event/be:content/
                   sub1:AccountInfo/Details[@initialDeposit > 50000]" />
        </filter>
      . . .
      . . .
    </business-events>

The standard BPEL activities such as receive, invoke, onMessage, and onEvent (in BPEL 2.0) are extended with an extra attribute bpelx:eventName, so that the BPEL process service component can receive events from the EDN event bus. The schema for the eventName attribute is shown in the following example:

<xs:attribute name="eventName" type="xs:QName">
        <xs:annotation>
            <xs:appinfo>
                <tns:parent>
                    <bpel11:onMessage/>
                    <bpel11:receive/>
                    <bpel11:invoke/>
                </tns:parent>
            </xs:appinfo>
        </xs:annotation>
    </xs:attribute>

The following example shows how the eventName attribute is used in the BPEL source file:

<receive name="OrderPendingEvent" createInstance="yes"
         bpelx:eventName="ns1:OrderReceivedEvent"/>
<invoke name="Invoke_1" bpelx:eventName="ns1:ProductSoldAlert"/>

If the bpelx:eventName attribute is used in a receive, invoke, onMessage, or onEvent (in BPEL 2.0) activity, then the standard attributes such as partnerLink, operation, or portType are not present. This is because the existence of the bpelx:eventName attribute shows that the activity is only interested in receiving events from the EDN event bus or publishing events to the EDN event bus.

The XSD file for the BPEL process service component is slightly modified, so that the partnerLink, operation, and portType attributes are no longer mandatory. The Oracle JDeveloper validation logic enforces the presence of either the bpelx:eventName attribute or the partnerLink, operation, and portType attributes, but not both. The following example shows the modified schema definition of a BPEL receive activity:

<complexType name="tReceive">
        <complexContent>
           <extension base="bpws:tExtensibleElements">
                <sequence>
                    <element name="correlations" type="bpws:tCorrelations" minOccurs="0"/>
                    <group ref="bpws:activity"/>
                </sequence>
                <!- BPEL mandatory attributes relaxed to optional for supporting BPEL-EDN ->
                <attribute name="partnerLink" type="NCName" use="optional"/>
                <attribute name="portType" type="QName" use="optional"/>
                <attribute name="operation" type="NCName" use="optional"/>
                <attribute name="variable" type="NCName" use="optional"/>
            </extension>
        </complexContent>
    </complexType>

The schema definition for the invoke and onMessage activities are modified similarly.

42.5 How to Integrate Oracle ADF Business Component Business Events with Oracle Mediator

This section provides a high-level overview of how to integrate Oracle ADF Business Component event conditions with SOA components. The SOA components include Oracle Mediator service components and BPEL process service components.

To integrate Oracle ADF Business Component business events with SOA components:

Create a business component project.
Add a business event definition to the project. This action generates an EDL file and an XSD file. The XSD file contains the definition of the payload. Ensure also that you specify that the event be raised by the Oracle ADF Business Component upon creation.

For more information about creating and publishing Oracle ADF Business Component business events, see Developing Fusion Web Applications with Oracle Application Development Framework.
Create a SOA composite application and manually copy the EDL and XSD schema files to the root directory of the SOA project. For example:
```
JDeveloper/mywork/SOA_application_name/SOA_project_name
```
Place schema files at the proper relative location from the EDL file based on the import.
Create an Oracle Mediator service component as described in How to Subscribe to a Business Event.
In the Event Chooser window, select the EDL file of the event, as described in How to Subscribe to a Business Event.
Create a BPEL process service component in the same SOA composite application for Oracle Mediator to invoke. Ensure that you select the payload of the Business Component business event XSD created in Step 2.
Double-click the BPEL process service component.
Drag an Email activity into the BPEL process service component.
Use the payload of the business event XSD to complete the Subject and Body fields.
Return to the Oracle Mediator service component in the .
Design a second service component to publish the event, such as a BPEL process service component or a second Oracle Mediator service component.

SOA composite application design is now complete.