Creating and Managing a BPEL Domain

This technical note introduces the concept of BPEL domains with the Oracle BPEL Process Manager. A BPEL domain allows a developer or administrator to partition a single instance of the Oracle BPEL Process Manager into multiple virtual BPEL sand boxes. A BPEL domain is identified by an ID and protected by a password. When the Oracle BPEL Process Manager is installed, an initial domain named "default" is created. The initial password of the "default" domain is set to bpel.

Here are some examples of how customers are using BPEL domains:

1. Partition a single Oracle BPEL Process Mananger instance into a multi-developer environment. In this case the domain ID usually identifies the developer owning that domain.
2. Partition a single Oracle BPEL Process Mananger instance into both a development and QA environment. In that case the domain IDs might be "test" and "QA"
3. Partition a single Oracle BPEL Process Mananger instance into an environment that can be used by multiple departments or partners. In these cases, the domain ids are the names of the departments or partners.

In the rest of this document, we address some of the key questions associated with the use of BPEL domains.

How do I create a BPEL domain?

In version 2.0 RC4 and later, the BPEL console includes a user interface ([1] http://localhost:9700/BPELConsole/createDomainForm.jsp) for allowing developers and administrators to create a new BPEL domain. To create a new domain, you need to know the admin password of the server. The initial admin password is set to "bpel" at install time.

If you take a look at the following JSP ([2] http://localhost:9700/BPELConsole/createDomain.jsp) you will notice that the Oracle BPEL Process Manager also exposes a set of API for programmatically creating an new BPEL domain. Please refer to the Java Doc of the Oracle BPEL Process Manager for more information on how to use that API.

How do I deploy a BPEL suitcase to a specific domain?

Note that a BPEL suitcase is the jar that is created when you compile a BPEL process. It includes the .bpel implementation of the process, its WSDL file, deployment descriptor and any other local resources that are required, such as XML Schemas, Java classes or libraries, etc.

You have 3 options to deploy a BPEL suitcase into a domain:

1. If the domain is local, then you can simply configure the deploy option of the bpelc ant task to perform local deployment to a specific domain. Here is an example of an ant build script which deploys the BPEL suitcase to the "qa" domain:

<?xml version="1.0"?>
<project name="LoanFlow" default="main" basedir=".">
<property name="deploy" value="qa"/>
<property name="rev" value="1.0"/>
<target name="main">
<bpelc orabpelhome="${orabpelHome}" rev="${rev}" deploy="${deploy}"/>
</target>
</project>

2. If the domain is not local to the environment where the BPEL suitcase is being compiled then you can use the "Deploy New Process" task in the BPEL Console Dashboard, to remotely upload and deploy a BPEL jar. Links for this task are located in the bottom-left portion of the Dashboard tab and bottom-right portion of the BPEL Processes tab. You can simply run the bpelc task without the deploy option to create the BPEL suitcase jar in the current directory. If you have already deployed the BPEL Suitcase locally, then you can upload it from your local deployment directory. See the next section for more information on where deployed BPEL suitcases can be found.

3. Finally, to the Oracle BPEL Process Manager, deploying a BPEL process is equivalent to a simple copy of the BPEL suitcase jar into the deploy directory of the appropriate BPEL domain. So, even if you are accessing the domain remotely, all you need is disk sharing, ftp, scp, or other access to the server that is hosting the domain. You can even add this to your Ant build.xml script to remove the deploy option as described above and then add your own task to perform the remote copy of the generated jar into the appropriate location.

Where does the BPEL jar for a specific domain go?

For a domain named "qa", and a default Oracle BPEL Process Manager installation into the C:\ directory on Windows, BPEL jar files for the qa domain will reside in: C:\orabpel\domains\qa\deploy. If you use the bpelc task with a deploy property value of "qa", the BPEL jar will automatically be copied to this directory. If you want to manually or remotely deploy a BPEL jar to a BPEL domain, simply copy it into that directory and it will be automatically detected and loaded into that domain by the Oracle BPEL Process Manager.

How do I undeploy a BPEL process from a specific domain?

In version 2.0 RC4 and later, the BPEL console includes a user interface for managing the lifecycle and state of a deployed BPEL process. This user interface can be found by selecting the name of the BPEL process on the Dashboard tab and then selecting the Manage tab on the left. On this page you can first retire and then undeploy the selected BPEL process. Retiring a process prevents any new instances of that process from being created. If a specific version of a BPEL process is undeployed before all pending in-flight instances are completed, those instances will be marked as stale and their execution will be cancelled. Note that every task that can be performed in the BPEL Console user interface can also be performed programmatically - please refer to the Java Doc of the Oracle BPEL Process Manager for more information.