4 Installing Oracle BPEL Process Manager with JBoss Application Server

4.3.1 Step 1: Configure the Oracle Database

This section describes the steps to install and configure Oracle Database 10g:

1. Install Oracle Database 10g 10.1.0.2.

2. Open SQL*Plus and log in as a user with the SYSDBA privilege.

3. Shut down the database:

   SQL> SHUTDOWN IMMEDIATE
   

4. Install the Oracle Database 10g 10.1.0.5 patch in the same Oracle home in which you installed Oracle Database 10g.

5. If using Linux only, then log in as the root user and run the following command from the operating system command prompt:

   /etc/init.d/init.cssd stop
   

6. Start the database in upgrade mode in SQL*Plus:

   SQL> STARTUP UPGRADE
   

7. Run the following script:

   SQL> @ORACLE_HOME/rdbms/admin/catpatch.sql;
   

8. Shut down the database:

   SQL> SHUTDOWN IMMEDIATE
   

9. Restart the database:

   SQL> STARTUP
   

10. Run the following script:

    SQL> @ORACLE_HOME/rdbms/admin/utlrp.sql;
    

4.3.2 Step 2: Create the Oracle BPEL Process Manager Schema in the Oracle Database

1. Navigate to the install\soa_schemas\irca directory within the Oracle BPEL Process Manager 10.1.3.1 installables. The .bat.sh scripts to run IRCA are located in this directory.

   See Also:

   Step 3: Install Oracle BPEL Process Manager 10.1.3.1 for OC4J to download the Oracle BPEL Process Manager 10.1.3.1.

2. Set ORACLE_HOME to point to the Oracle Database installation location. For example,

   set ORACLE_HOME=c:\Oracle10g
   

3. Run the following irca script:

   For...	Run...
   Windows XP	irca.bat orabpel
   Linux	irca.sh orabpel

   
   

   This runs the irca script packaged with the Oracle BPEL Process Manager installation.

4. Enter sys as the user name and the sys password when prompted.

   The orabpel schema is loaded into the Oracle Database.

4.3.3 Step 3: Install Oracle BPEL Process Manager 10.1.3.1 for OC4J

This is the standalone version of BPEL. Note that the basic SOA Suite installation cannot be used for this setup. You can download this standalone version of Oracle BPEL Process Manager 10.1.3.1 from the Oracle BPEL Process Manager Downloads Web site at

http://www.oracle.com/technology/software/products/ias/bpel/index.html

Install Oracle BPEL Process Manager for Developers version 10.1.3.1 into any directory on the same host on which JBoss will be installed.

Oracle BPEL installation on JBoss requires to reference the binaries, property files, and path from the Oracle BPEL installation. This is an important prerequisite to the JBoss installation.

4.3.4 Step 4: Apply the SOA Suite Patchset 10.1.3.3 on BPEL PM Standalone 10.1.3.1

You need to download the SOA Suite patchset 10.1.3.3 from OracleMetaLink and then apply the patchset on BPEL PM standalone 10.1.3.1. Perform the following steps:

1. Log in to OracleMetaLink at http://metalink.oracle.com. The OracleMetaLink home page is displayed.

2. Click Patches & Updates. The Patches & Updates page is displayed.

3. Click Simple Search.

4. In the Search By field, enter 6148874. The details of the patchset 6148874 are displayed.

5. Follow the instructions in the patchset to install the patchset on the BPEL PM standalone 10.1.3.1.

   Note:

   The specific instruction in the 10.1.3.3 patchset installations which mentions that BPEL PM must be running can be ignored.

4.3.5 Step 5: Install JBoss Application Server and Configure BPEL PM Standalone for JBoss

1. Install JBoss Application Server.

2. Download the orabpel_10133_Jboss.zip file, which enables you to configure Oracle BPEL Process Manager on JBoss at http://www.oracle.com/technology/software/products/ias/bpel/index.html. Create the orabpel_10133_Jboss folder and unzip orabpel_10133_Jboss.zip to this folder.

   Note:

   • The directory to which you download the Oracle BPEL Process Manager should be the same host on which JBoss is installed.

   • Unzip the orabpel_10133_Jboss.zip file as a non-root user (same user as was used to install Oracle BPEL Process Manager 10.1.3.1 for OC4J). For example, Oracle.

   • It is advisable not to delete the orabpel_10133_Jboss folder, as the contents of this folder are used for configuring BPEL PM to work on JBoss. However, after the configuration, this folder will no longer be used, but in case of a reinstallation, you will need to download, unzip the folder, and perform all the steps again.

3. Modify the following mandatory installation properties in the orabpel_10133_Jboss\Installables_V5\cfg\constants.properties file:

   Note:

   Mandatory properties cannot have a comment tag or contain blank values. Failure to follow this requirement results in errors during installation. Also, ensure that you enter the appropriate information for each of the fields. Any typo will cause errors during installation.

   Property	Description
   JBOSS_HOME	The directory path in which JBoss Application Server is installed. For example, JBOSS_HOME=C:\jboss-4.0.5.GA.
   BPEL_HOME	The directory path in which Oracle BPEL Process Manager is installed. For example, BPEL_HOME=C:\product\10.1.3.1\OraBPEL_1\bpel
   BPEL_INSTALL_PATH	The directory containing the JDK of Oracle BPEL Process Manager. For example, if the Oracle BPEL Process Manager home directory is C:\product\10.1.3.1\OraBPEL_1\bpel, then BPEL_INSTALL_PATH is typically C:\product\10.1.3.1\OraBPEL_1.
   DRIVERTYPE	The JDBC driver type (thick or thin). For example, DRIVERTYPE=jdbc:oracle:thin.
   HOSTNAME	The name or IP address of the host on which the Oracle Database 10g is installed. For example, HOSTNAME=stda.us.oracle.com.
   PORTNUMBER	The port number of the host on which the Oracle Database 10g is installed. For example, PORTNUMBER=1087.
   SID	The name that identifies a specific instance of running the Oracle Database10g. For example, SID=ORCL.
   JAASAUTHUSERID	The user name for accessing the Oracle BPEL Process Manager schema. For example, JAASAUTHUSERID=oracle
   JASAUTHPASSWD	The password for accessing the Oracle BPEL Process Manager schema. For example, JASAUTHPASSWD=welcome1
   PROXYSET	Indicates if a proxy server is being used (true or false). For example, PROXYSET=true.
   PROXYHOST	The name or IP address of the host on which the proxy server is installed. For example, PROXYHOST=www-proxy.us.oracle.com.
   PROXYPORT	The port where the proxy server is running. For example, PROXYPORT=80
   NONPROXYHOST	The addresses for which the proxy server must be bypassed that are divided by the vertical bar (|). For example, NONPROXYHOST=*.oracle.com|*.oraclecorp.com|localhost|127.0.0.1|10.177.251.61|rajeshc-pc|rajeshc-pc.idc.oracle.com

   
   

4. Run the following script from the orabpel_10133_Jboss\Installables_V5\bin folder at the operating system command prompt:

   For...	Run...
   Windows XP	setup.bat
   Linux	setup.sh

   
   

   Note:

   The setup.sh script would not have execute privileges. So, run chmod +x setup.sh.

   This script creates two servers, Oracle BPEL Server (oracleBPELServer) and Decision Server (decisionServer). The script also configures the required applications, queues, database connections, adapters, and JCAs.

   Installation progress is logged to the orabpel_10133_jboss\Installables_V5\bin\logs\output.log file.

5. Apply the jbossws-1.2.1 patch.

   By default, Jboss4.0.5 comes with the Web service deployer 1.0.4(jbossws-1.0.4). There are issues while running Web services using this deployer, so you need to upgrade to jbossws1.2.1.

   You can download jbossws-1.2.1.GA.zip from the JBoss Web Services Downloads Web site at

   http://labs.jboss.com/jbossws/downloads

   After the download, follow the instructions given in Install.txt file, and apply the patch to the already configured oracleBPELServer.

   This patch would require you to run the ant command, which is available at ORACLE_HOME\bpel\system\appserver\oc4j\ant\bin\ant.

6. Before starting oracleBPELServer, update the following values in the BPEL_HOME/domains/default/config/domain.xml file:

   Property	Change From	Change To
   <property id="datasourceJndi">	<value>jdbc/BPELServerDataSourceWorkflow</value>	<value>java:jdbc/BPELServerDataSourceWorkflow</value>
   property id="txDatasourceJndi">	<value>jdbc/BPELServerDataSource</value>	<value>java:jdbc/BPELServerDataSource</value>

   
   

   Note:

   This step needs to be run only when oracleBPELServer is started for the first time.

7. Start oracleBPELServer as follows:

   For...	Run...
   Windows XP	JBOSS_HOME\bin\startServer.bat -c oracleBPELServer
   Linux	JBOSS_HOME/bin/startServer.sh -c oracleBPELServer

   
   

8. (Optional). Start decisionServer as follows:

   For...	Run...
   Windows XP	JBOSS_HOME\bin\startServer.bat -c decisionServer
   Linux	JBOSS_HOME/bin/startServer.sh -c decisionServer

   
   

   Note:

   Starting decisionServer is not mandatory. Decision Service applications need to be deployed only into the decisionServer server. Start this server only if decision service applications are available.

9. Log in to the Oracle BPEL console at the following URL, using admin as the username and password:

   http://localhost:9700/BPELConsole

10. (Optional). Commands to stop the oracleBPELServer or decisionServer:

    Note:

    Use these commands to stop OracleBPELServer or decisionServer.

    Stop oracleBPELServer as follows:

    For...	Run...
    Windows XP	stopServer.bat -s jnp://localhost:9099
    Linux	stopServer.sh -s jnp://localhost:9099

    
    

    Stop decisionServer as follows:

    For...	Run...
    Windows XP	stopServer.bat -s jnp://localhost:9599
    Linux	stopServer.sh -s jnp://localhost:9599

    
    

4.4.1 From the BPEL PM Developer Prompt Using Ant

You can use ant in the BPEL PM developer prompt to deploy BPEL Processes. This section contains the following topics:

• Prerequisite Checks

• Steps to Deploy Using the BPEL PM Prompt

4.4.2 From JDeveloper

You can also deploy J2EE applications from JDeveloper. This section contains the following topics:

• Prerequisite Checks

• Steps to Deploy Using JDeveloper

4.5.1 Using LDAP

This section describes the following steps to configure LDAP in JBoss and to enable LDAP authentication for oracleBPELServer:

1. Navigate to login-config.xml under JBOSS_HOME\server\oracleBPELServer\conf.

2. Precede the "UsersRolesLoginModule" text with a comment character for application-policy BPELAuthentication.

3. Remove the comment character for the "LdapLoginModule" text (By default, the "LdapLoginModule" is commented.)

4. Save the changes.

5. Restart oracleBPELServer.

The above step disbales the default file-based authentication and enables external LDAP authentication.

4.5.2 Using High Availability Setup

This section describes High Availability (HA) support available for BPEL PM 10.1.3.3 on JBoss. This section contains the following topics:

• Prerequisite Checks

• Steps to Configure HA for BPEL PM

4.6.1 Verifying the Oracle BPEL Process Manager Console

Perform the following steps to check if the Oracle BPEL Process Manager Console has started:

1. Navigate to http://localhost:9700/BPELConsole or to the location where the software is installed, for example, http://<machine-name>:9700/BPELConsole/. The Oracle BPEL Process Manager Console is displayed.

   
   Description of the illustration console.gif
   
   

2. Log in using admin/admin or the username/password that you configured as per the application authentication policy.

   
   Description of the illustration index.gif
   
   

4.6.2 Verifying the SelectAllByTitle Sample for the Database Adapter

1. Log in to the database and start SQL*Plus.

2. Run the setup.sql script:

   SQL> @Oracle_Home\samples\tutorials\122.DBAdapter\sql\setup.sql;
   

   This script creates and populates the movies table in the database.

3. Point the database adapter to your database in JBoss console under Deployments, DB Adapter, Configuration, Outbound Connection Pools, eis/DB/BPELSamples, Properties.

   Note:

   Refer to Section 4.6.3, "Running Adapter Samples" for more information.

4. Select Start, All Programs, Oracle - Oracle_Home, Oracle BPEL Process Manager, Developer Prompt.

5. Change to the following directory:

   tutorials\122.DBAdapter\SelectAllByTitle
   

6. Run the following command:

   ant
   

   This compiles and deploys all projects dependent on this tutorial. Projects are deployed into BPEL_HOME\bpel\domains\domain_name\deploy.

7. Select Start, All Programs, Oracle - Oracle_Home, Oracle BPEL Process Manager, BPEL Console.

8. Click SelectAllByTitle in the Deployed BPEL Processes list.

9. Enter the movie title on the Initiate page.

10. Click Post XML Message.

11. View the results and inspect the instance.

4.6.3 Running Adapter Samples

This section contains the following topics:

4.6.4 Deploying Samples Using Ant

Ensure that admin.user and admin.password in BPEL_HOME\bpel\utilities\ant-orabpel.properties are updated with the credentials of a valid user from the authentication store setup for authentication.Samples can be deployed from the developer prompt using the ant script following the above step.The samples containing only BPEL processes can be fully deployed using the ant script.Samples containing additional components such as Decision Service applications, workflow forms, and UI applications need to be deployed in the following manner.

1. Use the ant script to deploy the BPEL process of the sample.

2. For each Decision Service application, manually edit the jsps and the decisionservice.xml file to replace the variables for domain, host the port as required. Generate the war or ear file, and deploy into DecisionServer. Start the application.

3. For each workflow form application, generate the war or ear file, and deploy into oracleBPELServer. Start the application.

4. For each UI Application, manually edit the doApply.jsp file to replace the variables for domain, host the port as required. Generate the war or ear file, and deploy into oracleBPELServer. Start the application.

4.7.1 Limitations

Note the following limitations:

• JBoss and Oracle BPEL Process Manager 10.1.3.1 should be installed as the same user on Linux, and the user should not be a root user.

  Note:

  If you install JBoss and BPEL PM 10.1.3.1 as different users, then the file permissions and ownership for files under the following directories should be verified and changed to BPEL PM install user:

  • BPEL_HOME\lib

  • BPEL_HOME\lib\rules

  • BPEL_HOME\system\appserver\oc4j\webservices\lib

  • BPEL_HOME\system\services\lib

  • BPEL_HOME\system\config

  • BPEL_HOME\utilities\

4.7.2 Known Issues

Note the following known issues:

JMS Adapter

• JMS Adapter throws the following NullPointerException during initialization on non-Oracle platforms:

  JmsConnectionFactory: Unable to set connectionparameters for OracleConnectionManager
  java.lang.NullPointerException
  at
  oracle.tip.adapter.jms.JmsConnectionFactory.<init>(JmsConnectionFactory.java:91)
  at oracle.tip.adapter.jms.JmsManagedConnectionFactory.createConnectionFactory
  (JmsManagedConnectionFactory.java:80)
  

  This is a benign error and does not stop the JMS connection factory from initializing.

Decision Services

• Data type binding warnings and errors are displayed during deployment and start of Decision Service (Business Rules) applications. These errors and warnings can be ignored.