33 Initiating a SOA Composite from an Oracle ADF Web Application

This chapter describes what a user action or other activity in an Oracle ADF web application needs to do to invoke a SOA composite. The invocation is asynchronous and does not require a response. Inside the SOA composite, an Oracle Mediator component can provide routing and transformation, a BPEL component can provide business process orchestration, a human task service can provide workflows, and a decision service can provide complex business rules based decision making.

When to implement: A user action or other activity in an Oracle ADF web application needs to invoke a SOA composite. The invocation is asynchronous and does not require a response. Inside the SOA composite, an Oracle Mediator component can provide routing and transformation, a BPEL component can provide business process orchestration, a human task service can provide workflows, and a decision service can provide complex business rules based decision making.

Design Pattern Summary: A business component in the ADF Business Components Framework publishes a business event to execute a SOA composite application. The SOA composite application subscribes to the event using the Oracle Mediator component, and from there it can be routed to any other service component, such as BPEL.

Involved components:

Oracle ADF web application that includes ADF Business Components.

SOA composite application that includes an Oracle Mediator service component and an additional service component to which the event can be routed (such as a BPEL process service component).

33.1 Introduction to the Recommended Design Pattern

Oracle Fusion applications initiate business processes in response to user actions. Oracle ADF provides a change notification framework that is triggered at the end of a transaction involving ADF Business Components. This notification can be declaratively configured to raise business events that conform to an Event Description Language (EDL) definition. When an event is raised, it is published on the Event Delivery Network (EDN). For more information about the EDN, see the chapter "Using Business Events and the Event Delivery Network" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Process flows are implemented using a BPEL process service component as a bridge from EDN to the BPEL process. Because the events raised by the ADF Business Components are not a native BPEL construct, you use a mediator service component to subscribe to the event and to then invoke the BPEL process service component. The mediator service component acts as a binding between the EDN and the BPEL process service component. Whenever the event is raised by ADF Business Components (whether through a GUI action or programatically), the BPEL process service component is invoked. Figure 33-1 illustrates how these work together.

Figure 33-1 Mediator Service Component Subscribes to an Event and Invokes BPEL Service Component

This approach is recommended for the following reasons:

Validation logic can be consolidated in the entity object.

Multiple user interfaces can invoke the reusable entity object that produces the events.

Event subscription can be modeled on the mediator service component and not hard wired into the UI.

The producer of the event (in this case, ADF Business Components) does not need to know who the downstream consumers of the event are. If needed, the SOA back-end service can change, without needing to change anything in the Oracle ADF web application. Decoupling the Oracle ADF and SOA application lifecycles makes development more manageable.

Events raised by ADF Business Components are asynchronous with no return value. The event infrastructure leverages the WLS JMS provider, so any unconsumed events can be de-queued by the SOA platform at some later time if the platform isn't running, assuming the JMS implementation leverages Oracle Advanced Queuing. For information about integrating Oracle Advanced Queuing with Oracle BPEL Process Manager or Oracle Mediator, see the chapter "Oracle JCA Adapter for AQ" in the Oracle Fusion Middleware User's Guide for Technology Adapters.

33.2 Other Approaches

Instead of using ADF Business Components, and the change notification publisher in entity objects to invoke a BPEL service component, you could use one of the following approaches. These development approaches should be used only when the recommended approach cannot be implemented.

A web services data control created using a SOAP web service on the composite to create the view in the web application.

A custom Java class in the web application using SOAP.

A direct API call, or some other means to access the SOA composite.

33.3 Example

A web application built using ADF Business Components and Oracle ADF Faces allows users to register bugs found in software. An ADF Business Components entity object is used to create a bug, and contains an event whose payload is the attribute values for the created bug. The event is configured to be raised whenever the Create operation is called on the entity object.

A mediator service component subscribes to the event and accepts the event payload. A routing rule is configured for the mediator service component that routes the payload for the event to a BPEL process service component. This component then sends an email that contains the information from the payload to the bug's creator.

There are some cases in which one might need to propagate the end user ID of the event raiser across the invoked services for auditing purposes. It is recommended to propagate this information in the event payload. When raising events for CUD operations (create, update, delete), include the last_updated_by history column in the event definition. As this column exists in every Oracle Fusion Applications table, the user raising the event will always be propagated.

33.4 How to Initiate a BPEL Process Service Component from an Oracle ADF Web Application

To initiate a BPEL process service component from a web application, you first need to create the web application using ADF Business Components and Oracle ADF Faces. You then create a SOA composite application that contains a mediator service component to pass the event payload created by ADF Business Components, and execute a BPEL process service component.

To invoke a BPEL process service component from an Oracle ADF web application:

In the Oracle ADF web application, define an event on an entity object.

Set the event point to be the database operation (create, update, delete) that will raise the event. You can also create any conditions needed to determine when the event should be raised.

Note:

Event points can only be associated with Data Manipulation Language (DML) operations.

Personally identifiable information (PII) is any piece of information that can be used to uniquely identify a person. PII is sensitive and must be protected from potential misuse.

When data is included in events or a BPEL flow, it is potentially exposed. While the transport may be encrypted on the SOA side, the data is not. The data in events, payload and BPEL variables is not secured by the security restrictions for business objects. Consider what data is to be exposed in the payload so as to prevent unauthorized access.

Defining an event generates an Event Definition Language (.edl) file and XML schema definition (.xsd). The EDL file contains all event definitions for the entity and the XSD file defines the contents of an event's payload, in addition to other objects needed by the BPEL process service component. These files together define the contract between the Oracle ADF application and the SOA composite application, as for a particular event, they identify the elements the SOA composite expects. Both these files are placed in the events directory for the project, and can be found in the Application Navigator as children to the associated entity object.

In the example bug application, the BugReport entity object contains the BugCreated event. This event carries all the attributes on the entity object as its payload, and is published using the create operation as its event point.

Create the page in the view that will invoke the operation defined as the event point for the event (for example, through a command button bound to the commit operation or through the implicit call to the commit operation as a task flow return activity).

In the example bug application, this is a UI command component bound to the Commit operation on the BugReport entity object. Because this operation commits the data to the database, and the Commit operation's corresponding DML operation (create) is used to sync the ADF Business Components cache with the database, the ADF Business Components framework raises the event.

For verification purposes, you can either run the Oracle ADF web application from the Integrated Oracle WebLogic Server container included with Oracle JDeveloper, or you can deploy the Oracle ADF web application to a standalone container. This step includes procedures for running the Oracle ADF web application within the embedded container and the SOA composite on a standalone Oracle WebLogic Server container. See Step 4 for procedures on deploying to a standalone container.

Make sure that EDN data sources have been configured. Using Oracle WebLogic Server Administration Console, verify that EDNDataSource and EDNLocalTxDataSource have been configured.

Note:

Oracle ADF and SOA data sources for EDN must point to the same schema. The EDN schema cannot be shared by more than one SOA runtime environment (such as outside a cluster).

Create an XML file called weblogic.xml with the following contents, and save it in the WEB-INF directory. This maps the global JMS resources to local JNDI names. The names in this file are the defaults expected by the remote connection factory, so you do not need to specify them. An example is shown in Example 33-2.

Before configuring the mediator service component, manually copy the EDL and XSD files created in Step 1 to the SOA composite application project's source path.

Open the MPLAN file for the mediator service component and create a new subscription that points to the EDL file moved into the source path. This means the mediator service component will now be subscribed to that event.

In the following example application, a mediator service component named BugCreatedRouter is subscribed to the BugCreated event, as shown in Figure 33-2.

Use the Create BPEL Process dialog to configure the payload. Use the Input Element finder icon to select the payload from the schema created for the event.

In the example application, the input element would be the BugCreatedInfo payload under the BugReport.xsd node, as shown in Figure 33-3.

Figure 33-3 Determining the Input Element for the Payload

You create an activity that accepts the payload from the input element as its input parameters. In the sample application, an email activity is created that takes various input parameters from the payload as assigns them to the email's parameters.

In the mediator service component, add a routing rule and configure it so that it invokes the BPEL process service and contains a subscription to the ADF Business Components event. Ensure the following:

You select the initiate operation on the client of the BPEL process service component as the target service, as shown in Figure 33-4.

Figure 33-4 Target for a Routing Rule

Optionally, use the Transformation map to map the mediator service component's schema to the input schema of the BPEL process service component. However, this should not be necessary, as you should be using the same schema for both.

Deploy the SOA composite application to the SOA infrastructure. For details, see the chapter "Deploying SOA Composite Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

Use Oracle Enterprise Manager Fusion Middleware Control Console to view the SOA composite application to ensure it was properly deployed. For more information about using Oracle Enterprise Manager Fusion Middleware Control Console, see the chapter "Deploying SOA Composite Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

33.5.2 Using a JAX-WS Proxy to Invoke a Synchronous BPEL Process

Another way to invoke a SOA composite as a web service from an Oracle ADF web application is to use a JAX-WS proxy.

Use this pattern only for synchronously invoking BPEL processes where the calling application waits for a response. As such, any BPEL processes called using this pattern must be synchronous and brief so as to avoid any time out issues.

Caution:

Do not use this pattern for a long running or asynchronous BPEL process.

In this pattern, SOA composite services are exposed as web services. You generate a JAX-WS proxy client to invoke the SOA composite exposed as a web service from your ADF Business Components application module.

You use the web services wizard to generate a web service proxy, and then call the web service using method calls.

An indirection for the web service proxy node enables retrieving the location of the web service WSDL, username and password from connections.xml. To use the indirection, access the proxy via oracle.adf.model.connections.webservice.WebServiceConnection.

33.6 Securing the Design Pattern

33.6.1 Running the Mediator as an Event Publisher

To make the mediator run as an event publisher:

Open the composite.xml file for the SOA composite application and manually add the runAsRoles="$publisher"' attribute to the composite subscriptions. Example 33-7 shows the composite subscription for the sample application.

33.6.2 Securing Event-Driven Applications

Events enable event-driven applications and are not related to OWSM. Therefore, OWSM policies do not apply to events.

Events raised by Oracle ADF web applications automatically propagate the event's publisher ID in the event header. No action is required to perform identity propagation. The publisher's ID corresponds to the end-user authenticated in the application.

33.7 Verifying the Deployment

You can verify the deployment by testing the Oracle ADF web application. Alternatively, you can send EDN events at the command line to verify event-raising functionality.

33.7.1 How to Verify the Deployment

To properly verify this design pattern, you should test the Oracle ADF web application and enable logging, use Oracle Enterprise Manager Fusion Middleware Control Console to verify the process instance creation, and check the SOA logs.

To verify this design pattern:

Test your Oracle ADF web application using various testing and debugging methods described in the chapter "Testing and Debugging ADF Components" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition). Be sure to enable ADF Business Components runtime logging by setting the Java VM parameter in the run/debug profile to jbo.debugoutput=console. Doing so logs the event and its payload in the JDeveloper log console.

Run the Oracle ADF web application and invoke the method that raises the event.

View the ADF Business Components runtime log in the JDeveloper log console to view the event and payload.

Use Fusion Middleware Control Console for tracking composite instances and for a variety of debugging, monitoring and testing functions.

Launch Fusion Middleware Control Console using the following URL:

http://<hostname>:<port number>/em

Open Fusion Middleware Control Console to verify the process instance has been created. Use the Audit tab to verify that the payload is correct.

33.7.2 How to Test EDN Functionality from the Command Line

You can test EDN functionality using SendEvent and edn.debug.event-connection at the command line.

33.7.2.1 SendEvent

SendEvent is a command line utility for sending an event to a database-based Oracle Event Delivery Network instance. SendEvent can send an empty event (of a given queue name) or an entire event from a file. Running the command displays a list of command line options.

33.7.2.2 BusinessEventConnectionFactorySupport

You can use BusinessEventConnectionFactorySupport in your Oracle ADF web application to test your event publishing code. Rather than sending an event to a queue, you can configure your Oracle ADF web application to print the event information to the log using BusinessEventConnectionFactorySupport.

To do so, set the system property edn.debug.event-connection to true when running your application. When the application sends an event, the information for that event is logged, including the event body in its entirety. This enables you to see the events that will be sent to EDN when the application runs on a SOA server.

The log name is oracle.integration.platform.blocks.event.debug, but in most configurations the information prints to stdout by default.

To set the system property:

When Oracle WebLogic Server starts up, add the system property shown in Example 33-11 to the JAVA_OPTIONS environment variable.

Example 33-11 Setting the EDN Debug System Property

-Dedn.debug.event-connection=true

To access the EDN database log:

You can use the EDN database log shown in Example 33-12 for diagnostic purposes.

Example 33-12 EDN Database Log

http://HOSTNAME:7001/soa-infra/events/edn-db-log

33.8 Troubleshooting the Use Case

Following are tips that may help resolve common issues that arise when developing or running this use case.

33.8.1 Deployment

If deployment of the SOA composite application fails, then verify the following:

The location element in the EDL file located in the directory is relative to the directory that contains the EDL file.

If you get an invalid XPath expression exception, use a static value instead of a value from the payload.

33.8.2 Runtime Errors

If your Oracle ADF web application encounters a runtime class load error for EventConnectionFactory, you need to add a library reference to oracle.soa.workflow.wc.

33.9 What You May Need to Know About Initiating a SOA Composite from an Oracle ADF Web Application

Before you implement these design patterns, you should be aware of the following:

If you change the event name or event payload, the mediator will not respond to the raising of the event. If you need to make changes, you should create a new event. During development, you need to change the mediator (if the name of the event changes) and/or the BPEL process being invoked (if the payload changes).

33.10 Known Issues and Workarounds

Following are known issues:

You must add a library reference to oracle.soa.workflow.wc in order to raise events successfully.

You can only specify $publisher as the runAsRole for an event subscription.