4 Installing Oracle BPEL Process Manager with the IBM WebSphere Application Server

4.3.1 Step 1: Install the Oracle Database

Follow these instructions to install 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, 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 again:

   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. Go to the following URL:

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

2. Go to the Oracle BPEL Process Manager 10.1.2.0.2 for WebSphere (v5.1.1.x) section.

   Oracle BPEL Process Manager for IBM WebSphere Application Server is available on the Windows and Linux operating systems.

3. Download the Oracle BPEL Process Manager for IBM WebSphere Application Server file.

4. Unzip the file on the host on which the database is installed.

5. Create the schema in either of two ways:

• Automatically Create the Schema

• Manually Create the Schema

4.3.3 Step 3: Install and Configure IBM WebSphere Application Server Version 5.1.1

1. Review the following prerequisites before installing the IBM WebSphere Application Server.

   • If installing on Linux, visit the following URL for instructions on creating groups and users prior to installing the IBM WebSphere Application Server.

     http://www-128.ibm.com/developerworks/linux/library/l-ss3pi-installwas5/
     
     

   • If installing on Windows, ensure that you have administrative privileges.

2. Install IBM WebSphere Application Server version 5.1.0.

3. Upgrade IBM WebSphere Application Server to version 5.1.1 by downloading and applying the following fix packs from IBM support:

   • Refer to the following URL for download and configuration instructions for fix APAR IC 45152 for IBM WebSphere Application Server MQ version 5.3

     http://www-1.ibm.com/support/docview.wss?rs=171&uid=swg24010287
     
     

   • Refer to the following URL for download and configuration instructions for fix APAR IY 59675 for IBM WebSphere Application Server version 5.1 with FixPack1

     http://www-1.ibm.com/support/docview.wss?uid=swg1IY59675
     
     

4. Install Oracle BPEL Process Manager for Developers version 10.1.2.0.2 into any directory on the same host on which the IBM WebSphere Application Server is installed.

   
   

   Note: Do not start Oracle BPEL Server from the Windows Start Menu or by running the SOA_Oracle_Home/integration/orabpel/bin/startorabpel script. These actions are not supported.

   
   

5. Modify the following mandatory installation properties in the Unzip_Location/cfg/constants.properties file.

   
   

   Note: Mandatory properties cannot be commented out or contain blank values. Failure to follow this requirement results in errors during installation.

   
   

   Property	Description
   WAS_HOME	The directory path in which IBM WebSphere Application Server is installed
   BPEL_HOME	The directory path in which Oracle BPEL Process Manager is installed
   BPEL_INSTALL_ROOT	The directory containing the JDK of Oracle BPEL Process Manager. For example, if the Oracle BPEL Process Manager home directory is C:/OraBPELPM_1/integration/orabpel, then BPEL_INSTALL_ROOT is typically C:/OraBPELPM_1.
   BS_PORT	The IBM WebSphere Application Server boot strap port
   SERVER_NAME	The name of the IBM WebSphere Application Server instance that runs Oracle BPEL Process Manager. The default value is oracleBPELServer, but this can be any valid name.
   ORACLE_JDBC_DRIVER_PATH	The JDBC driver path (odjbc14.jar)
   DRIVERTYPE	The JDBC driver type (thick or thin)
   HOSTNAME	The name or IP address of the host on which Oracle Database 10g is installed
   PORTNUMBER	The port number of the host on which Oracle Database 10g is installed
   SID	The service name of Oracle Database 10g
   JAASAUTHUSERID	The user name for accessing the Oracle BPEL Process Manager schema
   JASAUTHPASSWD	The password of the user name for accessing the Oracle BPEL Process Manager schema
   VHPORTS1	The virtual host or HTTP port number
   VHPORTS2	The virtual host or HTTP port number
   ISIMBEDDED	The Boolean value to specify for the messaging type

   
   

6. If you want to use the following optional properties, uncomment them and specify values.

   
   

   Note: Optional properties are commented by default. If you uncomment these properties, they cannot contain blank values. Change the default values for the four properties appropriately. Failure to follow this requirement results in errors during installation.

   
   

   Property	Description
   PROXYSET	Indicates if a proxy server is being used (true or false)
   PROXYHOST	The name or IP address of the host on which the proxy server is installed
   PROXYPORT	The port your host uses to access the proxy server
   NONPROXYHOSTS	The addresses for which the proxy server must be bypassed

   
   

7. If you are using MQ as the messaging middleware, uncomment and specify values for the following properties.

   
   

   Note: MQ properties are commented by default. If you uncomment these properties, they cannot contain blank values. Failure to follow this requirement results in errors during installation.

   
   

   Property	Description
   QUEUEMANAGER	The name of the queue manager that provides access to the queues
   HOST	The name of the host on which the WebSphere MQ queue manager runs
   PORT	The TCP/IP port number used for connections to the WebSphere MQ queue manager
   CHANNEL	The name of the channel used for connections to the WebSphere MQ queue manager
   TRANSPORTTYPE	The communication channel to connect to the queue manager
   CCSID	The coded character set identifier for use with the WebSphere MQ queue manager
   INVOKERBASEQUEUENAME	The name of the invoker base queue to which messages are sent
   WORKERBASEQUEUENAME	The name of the worker base queue to which messages are sent
   ALIAS	The name for the component-managed authentication alias
   USERNAME	The user name for accessing the queue
   PASSWORD	The password for the user name

   
   

8. Start Server1 by following the startup instructions in the IBM WebSphere Application Server administration documentation.

   Server1 is the default IBM WebSphere Application Server instance that runs the WebSphere Administrative Console. This server has to be started before the user can access the WebSphere Administrative Console at the following URL:

   http://hostname:9090/admin
   
   

   Note that the instructions in this chapter assume the default name of Server1 is used for the instance name.

9. Edit the Unzip_Location/bin/wsadmin.properties file to set the com.ibm.ws.scripting.traceFile property and com.ibm.ws.scripting.validationOutput property to any preferred writable location with the full path and file name. The preferred file name for com.ibm.ws.scripting.traceFile is wstrace.trace. The preferred file name for com.ibm.ws.scripting.validationOutput is wstrace.out. When installation and configuration are complete, these files can be checked.

10. Remain in the Unzip_Location/bin directory.

11. Execute the following script at the operating system command prompt:

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

    
    

    This creates Oracle BPEL Server on the IBM WebSphere Application Server and configures the required applications, database connections, and adapters.

    Installation progress is logged to the Unzip_Location/bin/logs/output.log file.

12. If using Linux, enter the sudo password when prompted at the end of script execution. This is required for additional dependent files to be copied to the IBM WebSphere Application Server.

    Script execution completes.

13. Start Oracle BPEL Server (represented by the name oracleBPELServer) by following the startup instructions in the IBM WebSphere Application Server administration documentation.

    
    

    Note: Do not start Oracle BPEL Server from the Windows Start Menu or by running the SOA_Oracle_Home/integration/orabpel/bin/startorabpel script. These actions are not supported.

    
    

14. Restart Server1.

4.5.1 Verifying Installation from the WebSphere Console

1. Log in to the WebSphere Console and verify that oracleBPELServer is installed under Servers > Application Servers.

   
   Description of the illustration verif1.gif
   
   

2. Verify that the orabpel_sl shared library has been created under Environment > Shared Libraries.

   
   Description of the illustration verif2.gif
   
   

3. Verify that BPELDataSourceProvider and BPELXADataSourceProvider are created for oracleBPELServer under Resources > JDBC Providers.

   
   Description of the illustration verif3.gif
   
   

4. Test the database connectivity of the created data sources under Resources > JDBC Providers > BPELDataSourceProvider and Resources > JDBC Providers > BPELXADataSourceProvider.

   
   Description of the illustration verif4.gif
   
   

5. Verify that the orabpel and hw_services application enterprise archives (EARs) are installed under Applications > Enterprise Applications.

   
   Description of the illustration verif5.gif
   
   

4.5.2 Verifying the SelectAllByTitle Sample for the Database Adapter

1. Log into 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 the WebSphere Console under Resources > Resource Adapters > DB Adapter > J2C Connection Factories > BPEL Samples > Custom Properties > Connection String.

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

5. Change directories to the following:

   tutorials/122.DBAdapter/SelectAllByTitle
   
   

6. Run the following command:

   obant
   
   

   This compiles and deploys all projects dependent upon this tutorial. Projects are deployed into Oracle_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 as input on the Initiate page.

10. Click Post XML Message.

11. View the results and inspect the instance.

4.5.3 Verifying the OrderBooking Tutorial Sample

The Web application DTD link in the web.xml files included with Oracle BPEL Process Manager must be modified before deployment to the IBM WebSphere Application Server.

1. Search for the web.xml files in the Oracle_Home/bpel/samples directory.

2. Make the following change in each web.xml file related to the sample to run:

   Change:

   http://java.sun.com/j2ee/dtds/web-app_2_3.dtd
   
   

   To:

   http://java.sun.com/dtd/web-app_2_3.dtd
   
   

3. Select Start > All Programs > Oracle - Oracle_Home > Oracle BPEL Process Manager > Developer Prompt.

4. Change directories to the following:

   tutorials/127.OrderBookingTutorial
   
   

5. Start SQL*Plus and execute the following script:

   SQL> @PracticeFiles/insertTable.sql;
   
   

   This creates the required sample tables in the database.

6. Run the following command:

   obant
   
   

   This compiles and deploys all projects dependent upon this tutorial. Projects are deployed into Oracle_Home/bpel/domains/domain_name/deploy. However, EAR files for CreateOrderBookingUI and SelectManufacturingUI must be manually deployed into the IBM WebSphere Application Server.

7. Change directories to PriceQuote/CreateOrderBookingUI.

8. Note the CreateOrderBookingUI.ear file that was created when you ran obant in Step 6.

9. Select Install Application in the WebSphere Administrative Console to deploy the CreateOrderBookingUI.ear file to the IBM WebSphere Application Server.

   Access the WebSphere Administrative Console at the following URL:

   http://hostname:9090/admin
   
   

10. Select oracleBPELServer as the deployment target.

11. Repeat Steps 8 through 10 for the PriceQuote/SelectManufacturingUI/SelectManufacturingUI.ear file.

12. Run the OrderBooking Tutorial by following steps e through h in 127.OrderBookingTutorial/Notes/Complete_RunSteps.pdf.

4.5.4 Running Adapter Samples

Ensure that the J2C connection factory properties shown in Table 4-2 are modified.

4.6.1 Workarounds

• Human workflow transaction rollback error

  The following exception may appear when accessing the Oracle BPEL Worklist Application. This exception can be ignored.

  [4/21/06 12:01:04:865 PDT] 369596c7 LocalTranCoor E WLTC0033E: Resource
  jdbc/BPELServerDataSourceWorkflow rolled back in cleanup of unresolved
  LocalTransactionContainment
  [4/21/06 12:01:04:896 PDT] 369596c7 LocalTranCoor E WLTC0032E: One or more
  resources rolled back. An unresolved LocalTransactionContainment had an
  unresolved action of rollback.
  [4/21/06 12:01:04:865 PDT] 369596c7 WebAppTransac E WTRN0043I: LocalTransaction
  rolled-back due to setRollbackOnly.
  [4/21/06 12:01:04:943 PDT] 369596c7 WebGroup E SRVE0026E: LocalTransaction
  rolled-back due to setRollbackOnly].
  com.ibm.ws.LocalTransaction.RolledbackException
  at com.ibm.ws.LocalTransaction.LocalTranCoordImpl.cleanup(LocalTranCoordImpl.java:
  1073)
  at com.ibm.ws.webcontainer.webapp.WebAppTransactionCollaborator.postInvoke
  (WebAppTransactionCollaborator.java:249)
  atcom.ibm.ws.webcontainer.webapp.WebAppRequestDispatcher.dispatch(WebAppRequest
  Dispatcher.java:708)
  atcom.ibm.ws.webcontainer.webapp.WebAppRequestDispatcher.forward(WebAppRequestD
  ispatcher.java:200)
  
  

• Remote method invocation (RMI) calls into Oracle BPEL Process Manager fail on the IBM WebSphere Application Server. The IIOP configuration and RMI invocation of processes are not currently working.

• When shutting down Oracle BPEL Server, IllegalAccessException errors display in the server logs. These errors can be ignored.

• Invoking any external Web service results in the following error:

  java.lang.ClassCastException:org.apache.axis.transport.http.HTTPSender
  
  

  Find the fix for this error at the following URL:

  http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg1PK19407
  
  

  1. Stop Server1 and Oracle BPEL Server.

  2. Go WebSphere_Home/lib/wsif.jar.

  3. Remove the client-config.wsdd file.

  4. Restart the servers.

  5. Run the tests.

• The while loop sample does not run.

  Find the fix for this error at the following URL:

  http://www-1.ibm.com/support/docview.wss?rs=180&uid=swg1PK19407
  
  

  1. Stop Server1 and Oracle BPEL Server.

  2. Go WebSphere_Home/lib/wsif.jar.

  3. Remove the client-config.wsdd file.

  4. Restart the servers.

  5. Run the tests.

4.6.2 Limitations

Note the following limitations:

• Oracle BPEL Process Manager 10.1.2.0.2 integration on IBM WebSphere Application Server version 5.1.1 has been tested on the following platforms:

  • Windows XP

  • Linux

• Oracle Database 10g version 10.1.0.5 has been tested as the dehydration store.

• Oracle Database Lite is not supported as the dehydration store.

• All samples except for the following have been tested:

  • Human workflow

  • SOAP attachment

4.6.3 Unsupported Features

The following Oracle BPEL Process Manager features are not supported:

• Sensors

• Oracle Application Server Integration B2B and Oracle Application Server Integration InterConnect interoperability

• Oracle BPEL Portlets