35 Managing Business Events

This chapter describes how to manage business events and the Event Delivery Network (EDN), including subscribing to business events, managing subscribers, and recovering from business event faults. Business events consist of message data sent as the result of an occurrence in a business environment. When a business event is published, other service components or database agents can subscribe to it.

This chapter includes the following sections:

For information about troubleshooting business event issues, see Section B.6, "EDN Troubleshooting."

For more information about business events, see Chapter "Using Business Events and the Event Delivery Network" of Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

35.1 Introduction to the Event Delivery Network

The subsystem of Oracle SOA Suite that accepts published business events and delivers them to the subscribers is called the EDN. EDN has two different implementations:

  • EDN-DB

    EDN-DB uses an Oracle database as a back-end store and depends on Oracle-specific features.

  • EDN-JMS

    EDN-JMS uses a JMS queue as a back-end store.

The correct implementation is configured during installation by Oracle Universal Installer. You can also make postinstallation changes. From an application development point of view, the two implementations are identical and the behavior is the same.

35.2 Subscribing to Business Events

You can subscribe to business events in Oracle Enterprise Manager Fusion Middleware Control. Business events consist of message data sent as the result of an occurrence in a business environment. You create business events in Oracle JDeveloper and include them in SOA composite applications that you deploy to Oracle Enterprise Manager Fusion Middleware Control. Service components and database agents can subscribe to business events. Only database agents can be subscribed to from Oracle Enterprise Manager Fusion Middleware Control. Service components are only subscribed to from Oracle JDeveloper. When a business event is published, the entity subscribed to that event receives it.

To subscribe to business events:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...

    Select Business Events.

    Right-click soa-infra and select Business Events.


    The Events page displays the following details:

    • A utility for searching for a specific business event by specifying a full or partial name and clicking the Search icon. Click the Help icon for details.

    • Business events, including the namespace used, event name, number of subscriptions to each event, and number of failed event deliveries. Business events are contained within their namespace.

    Description of busevent_events1.gif follows
    Description of the illustration busevent_events1.gif

  2. Select a specific event in the Namespaces and Events section.

  3. Click Show Event Definition.

    The event definition language (EDL) file for the selected event appears. The business event is defined using EDL. EDL is a schema used to build business event definitions.

    In this example, business events named OrderUpdateEvent, OrderInformationCheckEvent, ContinueOrderProcessingEvent, and StopOrderProcessingEvent appear in the event definition.

    Description of busevent_def.gif follows
    Description of the illustration busevent_def.gif

  4. Click OK to close the dialog.

  5. Click Subscribe to subscribe a database agent to the event selected in the Namespaces and Events table.

    Note:

    The Events page for EDN-JMS implementations does not display the Subscribe button for subscribing a database agent to the selected event.

    The Create Database Subscription dialog appears. You create an agent to listen for and subscribe to appropriate events when they are published.

    Description of busevent_events2.gif follows
    Description of the illustration busevent_events2.gif

  6. Enter the following values. An asterisk indicates a required field.

    Field Description

    Event Namespace

    Displays the event namespace.

    Event Name

    Displays the event name.

    Database Agent

    Specify a database agent name or click Create Agent to create an agent. The agent listens for and subscribes to appropriate events when they are published.

    Consistency Level

    Select one of the following options:

    • Guaranteed: Delivers events to the subscriber asynchronously without a global transaction. The subscriber can choose to create its own local transaction for processing, but it is committed independently of the rest of the event processing. By default, guaranteed delivery attempts to deliver the event three times to the subscriber. If it cannot deliver the event in these three attempts, then the delivery fails. Also, there is a possibility that a system failure can cause an event to be delivered multiple times because there is no global transaction. If the subscriber throws an exception (or fails in any way), the exception is logged, but the event is not resent.

    • Immediate: Delivers events to the subscriber in the same transaction and same thread as the publisher. The publish call does not return until all immediate subscribers have completed processing. If any subscribers throw an exception, no additional subscribers are invoked and an exception is thrown to the publisher.

    XPath Filter

    If you want to filter the event, specify an XPath expression. When the subscription is delivered and the expression logic is satisfied, the event is accepted for delivery. If the logic is not satisfied, the event is not delivered.


  7. Click Subscribe.

  8. Click Test to test a selected event. This action enables you to publish a test event that subscribers can act upon.

    The Test Event dialog appears.

  9. Specify the XML payload to use in the test.

  10. Click Publish.

Note:

Enforcement of policies for event subscriptions is not supported in this release. You can attach or detach a policy to or from a service component that subscribes to a business event (such as Oracle Mediator) without being warned. This action does not result in any errors; policy enforcement simply does not occur.

For more information, see the following documentation:

35.3 Managing Business Event Subscribers

You can also create, edit, and delete existing database subscriptions. When a business event is published, service components and database agents can subscribe to it. Use this page to view all subscriptions to business events. This page also enables you to manage event subscriptions by database agents. Service component subscriptions are created in Oracle JDeveloper during design time and cannot be modified in Oracle Enterprise Manager Fusion Middleware Control.

Notes:

  • If your SOA composite application includes a business event subscription, and you deploy different revisions of the composite, all event subscriptions from all revisions of the composite are active and receive messages. To receive the event with the latest revision of the composite only, it is recommended that you retire all previous revisions of the composite.

  • A BPEL component in a retired SOA composite application cannot receive a business event, even if the event is associated with a noninitiating receive activity of the BPEL process.

To manage business event subscribers:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...
    1. Select Business Events.

    1. Right-click soa-infra.

    2. Select Business Events.


  2. Click Subscriptions.

    The Subscriptions page displays the following details:

    • A utility for searching for a specific subscription by specifying criteria and clicking Search. Click the Help icon for details.

    • The database subscriptions, including the event name, namespace used, subscription agent name, optionally defined XPath filters, consistency level, and number of failed deliveries. You create database subscriptions to business events on this page during runtime.

    • The component subscriptions, including the event name, namespace used, the service component subscribing to the event, the SOA composite application, any optionally defined XPath filters, and the consistency level.

    Description of busevent_subscribers.gif follows
    Description of the illustration busevent_subscribers.gif

    Note:

    For business events implementing EDN - JMS, the Create Database Agent icon, Edit Database Agent icon, Delete Database Agent icon, and Manage Database Agents button are not displayed.

  3. Click the appropriate icon below the Database Subscriptions title to create, edit, or delete a database subscription.

    Description of busevent_events3.gif follows
    Description of the illustration busevent_events3.gif

  4. Click Manage Database Agents to edit the PL/SQL procedure or delete agents not currently subscribing to events.

  5. In the Subscription Component column, click a service component to access its home page.

  6. In the Composite column, click a SOA composite application to access its home page.

For more information about business events, see Chapter "Using Business Events and the Event Delivery Network" of Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

35.4 Recovering from Business Event Faults

You can recover from business event faults that are identified as recoverable.

To recover from business event faults:

  1. Access this page through one of the following options:

    From the SOA Infrastructure Menu... From the SOA Folder in the Navigator...
    1. Select Business Events.

    1. Right-click soa-infra.

    2. Select Business Events.


  2. Click Faults.

    The Faults page displays the following details:

    • A utility for searching for a specific business event fault by specifying criteria and clicking Search.

    • Faults occurring in a business event, including the error message, whether you can recover from the fault, the time at which the fault occurred, the event namespace, event name, the subscriber, and the subscription type (database or component). The Recoverable? column identifies faults for which recovery actions can be performed.

    Description of busevent_faults.gif follows
    Description of the illustration busevent_faults.gif

  3. From the View list, select Columns > Fault ID to display the fault IDs for each error message.

  4. Click a specific fault that has been identified as recoverable and select one of the following options:

    Action Description

    Retry

    Retries the instance in which the fault occurred.

    Note: When a business event fault is awaiting recovery, the overall SOA composite application instance is displayed as completed with faults.

    Abort

    Terminates the entire instance in which the fault occurred.


  5. In the Logs column, click a specific log to access the Log Messages page with filtered messages specific to that instance.

For more information about business events, see Chapter "Using Business Events and the Event Delivery Network" of Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.