10 Upgrading Oracle BPEL Process Manager Applications

This chapter provides important supplementary information upgrading Oracle BPEL Process Manager applications to Oracle Fusion Middleware 11g.

Use Chapter 8, "Overview of Upgrading Oracle SOA Suite, WebCenter, and ADF Applications" for the tasks required to upgrade any Oracle SOA Suite, WebCenter, and ADF application.

Use the following sections to learn about the upgrade tasks you will likely need to perform to upgrade your Oracle BPEL Process Manager applications and projects to Oracle Fusion Middleware 11g:

Manual Upgrade Steps After Migrating Oracle BPEL Process Manager Applications
Additional Considerations for Oracle BPEL Process Manager Applications

10.1 Manual Upgrade Steps After Migrating Oracle BPEL Process Manager Applications

The following sections describe some of the common upgrade tasks you will have to perform after you open your Oracle Application Server 10g Oracle SOA Suite application in Oracle JDeveloper 11g.

These tasks represent items that are not upgraded automatically by the Oracle JDeveloper Migration Wizard:

Providing Missing Binding Information for External References
Correcting Problems With Oracle BPEL Process Manager Test Suites
Using Oracle BPEL Process Manager Deployment Plans After Upgrade
Upgrading Fault Policies in an Oracle BPEL Process Manager Project
Upgrading a 10g Project With No BPEL Folder

10.1.1 Providing Missing Binding Information for External References

This section describes how to fix compiler warning messages about missing bindings after you upgrade an Oracle BPEL Process Manager project in Oracle JDeveloper.

Why the Warning Messages Occur When a source project in your application depends on Oracle Application Server 10g Release 3 (10.1.3) Oracle BPEL Process Manager or Oracle Enterprise Service Bus (ESB) services, then as a pre-cursor to migration, the Oracle JDeveloper Migration Wizard creates local copies of their abstract WSDLs.

The abstract WSDLs, by definition, lack service and port endpoint information. During upgrade, when the Migration Wizard creates external composite references for the service dependencies, the references are created as abstract references with no binding information.

These abstract references are flagged with WARNING messages in the upgrade log. After upgrade, when you attempt to compile the projects, Oracle JDeveloper will generate compilation errors alerting you to the presence of abstract references in the composite.

Note that a similar message also appears when you are using Oracle SOA Suite 10g Web services that use HTTP bindings, which are not supported in Oracle SOA Suite 11g.

Using 10g Release 3 (10.1.3) or 11g Dependency Services Based on the upgrade and deployment schedules of all the services in the dependency tree, you can choose to continue to use 10g Release 3 (10.1.3) dependency services or proceed with the upgrade and redeployment of the dependency service.

In general, Oracle recommends that users study their source project and their dependencies before any upgrade work. This analysis will result in a smoother upgrade experience.

How to Correct Binding Errors Discovered During the Recompile To correct binding errors due to the abstract references, right-click on the reference node in the Oracle JDeveloper 11g composite editor and choose the correct concrete WSDL. If you want to continue using a 10g Release 3 (10.1.3) dependency service, you can do so. Some of the dependency service endpoint URLs that are captured in the upgrade log can be used for this step.

You can also redesign the dependency in Oracle JDeveloper 11g, using the WSIL Browser (Resource Palette), and discover the service from the UI in the composite modeler.

For more information, refer to the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.1.2 Correcting Problems With Oracle BPEL Process Manager Test Suites

During upgrade in Oracle JDeveloper, BPEL test suites are converted to composite test suites. However, only the "instance initiate" action is migrated. This results in a composite test which initiates only a test run. The rest of any BPEL-based test actions are not automatically migrated and must be manually set up after the upgrade.

To set up the tests in your 11g environment, refer to "Testing SOA Composite Applications" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.1.3 Using Oracle BPEL Process Manager Deployment Plans After Upgrade

Deployment and configuration plans that you set up in Oracle Application Server 10g for your Oracle BPEL Process Manager user projects are not upgraded in Oracle JDeveloper 11g.

In Oracle Fusion Middleware11g, a composite can be accompanied by deployment and configuration plan during deployment. However, you must create the 11g deployment plan manually, after you have migrated the application in Oracle JDeveloper.

For more information about creating configuration plans in 11g, see "Moving SOA Composite Applications to and from Development, Test, and Production Environments" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.1.4 Upgrading Fault Policies in an Oracle BPEL Process Manager Project

When you open your 10g application in Oracle JDeveloper and use the Oracle JDeveloper Migration Wizard to upgrade the application, any fault policies and bindings that you set up in a user project are not automatically upgraded to 11g.

The reasons are as follows:

In Oracle BPEL Process Manager 10g, fault policies were stored with the server and bindings were either stored with the server or specified in bpel.xml. In Oracle BPEL Process Manager 11g, fault policies and fault bindings are stored in the Oracle JDeveloper 11g project.
In general, fault policies and bindings in Oracle BPEL Process Manager 11g are different than those in previous releases. For example, the file name and syntax is different, fault policies apply both to Oracle Mediator and Oracle BPEL Process Manager, and bindings are at a reference, component, and composite level in 11g.

For these reasons, you must manually recreate the fault policies and bindings in the Oracle JDeveloper 11g project after you upgrade your applications.

Similarly, when you upgrade an Oracle Enterprise Service Bus 10g Release 3 (10.1.3) project to 11g, you must add the retry parameters defined in esb_config.ini file to the 11g fault-policy.xml file.

For more information, see:

"Using Fault Handling in a BPEL Process" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite
"Using Mediator Error Handling" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.1.5 Upgrading a 10g Project With No BPEL Folder

If the 10g Release 3 (10.1.3) application you are upgrading includes a project where all the project artifacts are in one folder and the BPEL artifacts are not separated into their own folder in the project, then the Oracle JDeveloper Migration Wizard will not be able to upgrade those artifacts.

To avoid this problem, do one of the following:

Before upgrading the project, use Oracle JDeveloper 10g to create a BPEL folder and move all the artifacts (except the build.xml and build.properties files) into that folder. Then you can proceed with upgrading the project.
Use the Oracle SOA Suite command-line upgrade tool. The command-line tool will upgrade the artifacts even if a BPEL folder does not exist in the project. For more information, see Section 9.3.6, "Using the Oracle SOA Suite Command-Line Upgrade Tool".

10.2 Additional Considerations for Oracle BPEL Process Manager Applications

The following sections describe additional considerations you should review after upgrading Oracle BPEL Process Manager applications:

Verifying New and Deprecated Properties in the bpel.xml Deployment Descriptor
Upgrading User-Defined (Custom) XPath Functions in an Oracle BPEL Process Manager Project
Change in Support for Multiple BPEL Implementations
Verifying the Properties File Name When Upgrading Projects That Use Correlation Sets in an Asynchronous Service.
Upgrading Projects With the transaction=participate Property
Specifying Domain Descriptor Properties in Oracle BPEL Process Manager 11g
Upgrading Applications That Use Multiple Oracle BPEL Process Manager Domains

10.2.1 Verifying New and Deprecated Properties in the bpel.xml Deployment Descriptor

If any of your Oracle Application Server 10g Release 3 (10.1.3) applications reference any properties that were stored in the bpel.xml deployment descriptor, note that these properties are now set in the composite.xml deployment descriptor file.

For more information about the properties available in the composite.xml deployment descriptor, as well as important information about properties that are no longer supported in Oracle Fusion Middleware 11g, refer to "Deployment Descriptor Properties" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.2.2 Upgrading User-Defined (Custom) XPath Functions in an Oracle BPEL Process Manager Project

When you open and upgrade your applications in Oracle JDeveloper 11g, any custom XPath functions in the application projects are not upgraded automatically.

As a result, after you upgrade your application, you must copy any XPath function classes into the server classpath and register the function in the server configuration file. This is a manual step because the Oracle JDeveloper Migration Wizard cannot assume the server information.

For more information, refer to "Creating User-Defined XPath Extension Functions" in the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.

10.2.3 Change in Support for Multiple BPEL Implementations

You cannot upgrade a single BPEL file with multiple implementations in Oracle BPEL Process Manager 11g.

To migrate and merge multiple 10g Release 3 (10.1.3) projects with a single BPEL implementation file, you must rename the BPEL file in each project. In the bpel.xml file in each project, the bpel filename and deployment ID name must be renamed the same name, as well.

Before you upgrade the application, review the bpel.xml file and *.bpel file. Make sure that the BPEL file name and the process name are the same; then review the bpel.xml file and verify that the BPEL file name is the same as the deployment ID name.

10.2.4 Verifying the Properties File Name When Upgrading Projects That Use Correlation Sets in an Asynchronous Service.

If you created an Oracle BPEL Process Manager 10g project that used correlation sets in an asynchronous service, as described in the Oracle BPEL Process Manager 10g Release 3 (10.1.3) Developer's Guide, make sure that the correlation set properties file uses the following proper naming convention:

BPEL_FILE_NAME_Properties.wsdl

If this file naming convention is not followed in the Oracle BPEL Process Manager 10g project, the properties will not be upgraded correctly. If you need to change the name to meet the file naming conventions, then also update the wsdl file that imports the property file name, accordingly.

10.2.5 Upgrading Projects With the transaction=participate Property

If you open and upgrade an Oracle BPEL Process Manager 10g project that has a configuration property, transaction=participate, then that property will not be migrated to 11g when you open the application in Oracle JDeveloper 11g. This configuration property is no longer supported in Oracle Fusion Middleware 11g.

If you open and upgrade an Oracle BPEL Process Manager 10g project has a partnerLink binding property, transaction=participate, then that property will be dropped on the caller side. The callee project instead should have the property setting bpel.config.transaction=required. This caller to callee setting propogation is not performed by upgrade and must be performed manually after you upgrade the application and before you attempt to deploy it on Oracle Fusion Middleware 11g.

10.2.6 Specifying Domain Descriptor Properties in Oracle BPEL Process Manager 11g

In Oracle BPEL Process Manager 10g, you specify domain properties in the domain.xml descriptor file.

In Oracle BPEL Process Manager 11g, you specify Oracle BPEL Process Manager engine properties in bpel-config.xml and soa-infra-config.xml (both are accessible as MBeans).

Table 10-1 compares the domain descriptor properties available in Oracle BPEL Process Manager 10g and Oracle BPEL Process Manager 10g.

There is only one domain in Oracle BPEL Process Manager 11g, which means that these properties will affect the entire server.

Table 10-1 Domain Descriptor Properties in Oracle BPEL Process Manager 10g and 11g

Oracle BPEL Process Manager 10g in domain.xml file	Oracle BPEL Process Manager 11g MBean Property	Description
auditDetailThreshold	auditDetailThreshold	The maximum size (in bytes) of an audit trail details string before it is stored separately from the audit trail. If a details string is larger than this threshold, then it will not be immediately loaded when the audit trail is initially retrieved; a link will be displayed with the size of the details string. Typically, the details string will contain the contents of a BPEL variable. In cases where the variable is very large, performance may be severely impacted by logging it to the audit trail. The 10g default value is 50 kilobytes.
auditLevel	auditLevel	Controls the amount of audit events logged by a process. The supported logging levels are: off - absolutely no logging performed whatsoever; may result in a slight performance boost for processing instances. minimal - all events are logged; however, no audit details are logged. production - all events are logged. The audit details for assign activities are not logged; the details for all other nodes are logged. development - all events are logged; all audit details for all additives are logged. The 10g default value is "development".
bpelcClasspath	bpelcClasspath	Server-side BPEL process compiler classpath. Any user-specific classes or libraries used by a BPEL java exec node (that have not been packaged in the BPEL archive) need to be specified here so that the server-side BPEL process compiler can successfully compile the BPEL process.
datasourceJndi	datasourceJndi (Moved to soa-infra-config.xml)	The JNDI name for the domain data source. This data source may refer to any data source (JTA not required).
deliveryPersistPolicy	deliveryPersistPolicy	Changes whether the delivery messages are persisted. Delivery messages include invoke message, callback message and subscription message. on - delivery messages are persisted off - delivery messages are kept only in memory. off.immediate - applicable for asynchronous processes only; messages are delivered synchronously regardless of the interface. The 10g default value is "on".
dspEngineThreads	dspEngineThreads	The total number of threads that will be allocated to process engine dispatcher messages. Engine dispatch messages are generated whenever an activity must be processed asynchronously by the BPEL engine. If the majority of processed deployed on the BPEL server are durable with a large number of dehydration points (mid-process receive, onMessage, onAlarm, wait), greater performance may be achieved by increasing the number of engine threads. Note that higher threads counts may cause greater CPU utilization due to higher context switching costs. The 10g default value is 30 threads. Any value less than 1 thread will be changed to the default.
dspInvokeAllocFactor	N/A	The percentage of active threads that should be tasked to process incoming invocation messages. After a thread has finished processing a message it may be retasked to process an engine or invocation message, depending upon the current thread allocation situation. This property was replaced by `dspInvokeThreads` in 10g Release 3 (10.1.3.4). The 10.1.3.1.0 default value is 0.4 (40 percent).
dspInvokeThreads	dspInvokeThreads	The total number of threads that will be allocated to process engine dispatcher messages. Engine dispatch messages are generated whenever an activity must be processed asynchronously by the BPEL engine. If the majority of processed deployed on the BPEL server are durable with a large number of dehydration points (mid-process receive, onMessage, onAlarm, wait), greater performance may be achieved by increasing the number of engine threads. Note that higher threads counts may cause greater cpu utilization due to higher context switching costs. The 10g default value is 30 threads. Any value less than 1 thread will be changed to the default.
dspMaxThreads	N/A	The maximum number of active threads that will be processing messages during peak load times. This is the simplest way to throttle the performance of the domain. The maximum value is dependent upon the application server or OS configuration. This property was replaced by dsp(Engine\|Invoke\|System)Threads in 10.1.3.4.0. The 10.1.3.1.0 default value is 100 threads.
dspMinThreads	N/A	The minimum number of active threads that will be processing messages during peak load times. If the current number of active threads is under this number the load factor is not taken into consideration when determining if a new thread should be allocated or not. This property was replaced by `dsp(Engine\|Invoke\|System)Threads` in 10.1.3.4.0. The 10.1.3.1.0 default value is 5 threads.
dspSystemThreads	dspSystemThreads	The total number of threads that will be allocated to process system dispatcher messages. System dispatch messages are general housecleaning tasks that are typically processed quickly by the server (for example, releasing stateful message beans back to the pool). Typically, only a small number of threads are required to handle the number of system dispatch messages generated during runtime. The 10g default value is 2 threads. Any value less than 1 thread will be changed to the default.
expirationMaxRetry	expirationMaxRetry	The maximum number of times a failed expiration call (wait/onAlarm) will be retried before failing. If the activity or instance the expiration call is targeting cannot be found, the call will be rescheduled again. The 10g default is 5.
expirationRetryDelay	expirationRetryDelay	The amount of time in seconds to wait before rescheduling a failed expiration call. The 10g default value is 120 seconds.
instanceKeyBlockSize	instanceKeyBlockSize	The size of the block of instance ids to allocate from the dehydration store during each fetch. Instance ids for instantiated instances are pre-allocated from the dehydration store and kept in-memory. Once all of the in-memory instance ids have been exhausted, the next request will retrieve the next block from the dehydration store. Generally, the higher the block size, the less impact fetching instance ids will have on the overall performance of the engine (as the cost of allocating the block is amortized over a larger number of instances). The only downside to a large block size is the gap between instances in a clustered installation (as each node will have its own in-memory block of instance ids) and wasting instance ids if the engine is shutdown and the block is not utilized fully. The 10g default value is 10000.
largeDocumentThreshold	largeDocumentThreshold	The maximum size (in bytes) a BPEL variable can be before it is stored in a separate location from the rest of the instance scope data. Large XML documents will severely impact the performance of the entire BPEL server if they are constantly read-in and written-out whenever processing on an instance must be performed. By writing the variable to separate storage the performance impact is limited to times when the variable is explicitly used in a BPEL activity. The 10g default value is 50 kilobytes.
minBPELWait	minBPELWait	The minimum amount of time allowed for a BPEL wait duration. Wait times shorter than this duration will not be respected and will essentially be "skipped" altogether. The 10g default value is 2 seconds.
processCheckSecs	N/A	The number of seconds to wait since the last time the process container checked the bpel archive before checking it again. By "checking" we mean checking the last modified time stamp on the bpel archive for a particular process; if the specified number of seconds has passed and the bpel archive file has been modified since the last time we checked, the process will be refreshed from the new archive. If not enough time has passed since the last time the stale check was performed, the currently loaded process classes will be used. To disable process checking use a value of -1; in this case once a process has been loaded the container will never check if a newer version of the same process has been deployed. The 10g default value is 1 second. This property is not relevant in 11g anymore as the SOA infrastructure now handles deployment via HTTP only.
statsLastN	statsLastN	The size of the "most recently processed" request list. After each request is finished, statistics for the request are kept in a list. A value less than or equal to 0 will disable statistics gathering. NOTE: engine throughput may be affected slightly if this option is enabled. Please choose a reasonable value for n (1000 is the recommended value).
syncMaxWaitTime	syncMaxWaitTime	The maximum time the process result receiver will wait for a result before returning. Results from asynchronous BPEL processes are retrieved synchronously via a receiver that will wait for a result from the container. The 10g default value is 45 seconds.
txDatasourceJndi	txDatasourceJndi (moved to soa-infra-config.xml)	The JNDI name for the domain transactional data source. This data source must be configured for JTA support.
uddiLocation	oracle.soa.uddi.registry.inquiryUrl (moved to soa-infra-config.xml)	The inquiry URL of the Uddi v3 compliant registry
uddiPassword	oracle.soa.uddi.registry.password (moved to soa-infra-config.xml)	Set if UDDI is secured, password
uddiUsername	oracle.soa.uddi.registry.username (moved to soa-infra-config.xml)	Set if UDDI is secured, username
validateXML	validateXML	If set to "true" the engine will apply schema validation for incoming and outgoing XML documents. The 10g default value "false".

10.2.7 Upgrading Applications That Use Multiple Oracle BPEL Process Manager Domains

If you have developed and deployed your Oracle Application Server 10g BPEL projects using multiple Oracle BPEL Process Manager domains, then you should be aware that Oracle Fusion Middleware 11g does not support multiple BPEL domains.

If you are using multiple domains in Oracle Application Server 10g, then you have two options when you upgrade to Oracle Fusion Middleware 11g:

You can install and configure multiple Oracle SOA Suite Oracle WebLogic Server domains. You can then map each of your Oracle BPEL Process Manager 10g domains to a separate Oracle WebLogic Server domain.
You can deploy all your Oracle BPEL Process Manager projects to a single Oracle SOA Suite Oracle WebLogic Server domain.

For more information, refer to the Oracle Fusion Middleware Installation Guide for Oracle SOA Suite.