Configuring and Customizing BEA WebLogic Process Integrator

 

This topic discusses post-installation configuration and customization options for WebLogic Process Integrator. It includes the following sections:

• Configuring WebLogic Process Integrator to Run in a Clustered Environment

• Configuring a Custom Java Message Service Queue

• Configuring Security Realms for WebLogic Process Integrator

• Customizing Database Settings

• Customizing Mail Session Settings

• Modifying Your Environment Settings

• Setting Up an Alternate Cloudscape Database

 

---

Configuring WebLogic Process Integrator to Run in a Clustered Environment

Configuring WebLogic Process Integrator to run in a cluster requires only that you properly distribute the application resources across all servers in the cluster. A WebLogic Process Integrator cluster configuration must use a master/slave architecture. All nonclusterable services are located on the master or primary server, while fully clusterable resources are located on the slave or secondary servers. The following is a list of clusterable and nonclusterable resources in WebLogic Process Integrator:

Clusterable services

• wlpi-ejb.jar—Contains all EJB definitions used by the WebLogic Process Integrator server

• repository-ejb.jar—Contains the ECI XML repository EJB definitions

• JMS Connection Factories—Can be deployed on all the servers to ensure that the JMS destinations can be located anywhere in the cluster

• MailSession—Required for sending e-mail from a workflow

• JDBC Connection Pool—Must exist on all servers for EJBs to work properly

• TxDataSource—Related to the JDBC Pool; required for proper EJB functioning

Nonclusterable services

• wlpi-mdb.jar—Contains Message Driven Bean (MDB) deployments

• wlpi-master-ejb.jar—Contains the Plug-in Manager Configuration EJB which is responsible for maintaining all plug-in configurations in the cluster

• Startup classes—Handle server initialization and timer services

• JMS Server—Defines all of the WebLogic Process Integrator JMS destinations; must be deployed on a single primary server

To take advantage of a cluster, multiple JMS servers with their own queues can be deployed on the secondary servers. You can create message-driven bean (MDB) deployments to listen to these queues so that the JMS workload can be spread out across the cluster. For more information, see Configuring a Custom Java Message Service Queue.

Configuring WebLogic Process Integrator for a clustered environment involves the following steps:

• Using the WebLogic Server Administration Console to create and configure new servers and a cluster

• Modifying the server startup scripts

• Starting the servers in the correct order

To create and configure a WebLogic Process Integrator cluster:

1. Start the WebLogic Process Integrator server in Mydomain, as described in Starting the WebLogic Process Integrator Server.

2. Start the WebLogic Server Administration Console.

3. In the navigation tree, go to Machines, and create new machines on which the managed servers will run in the cluster, using the machine names as the host names, for example, machine1.

4. In the navigation tree, choose Servers, and create new servers which will run as managed servers in the cluster, for example, wlpi_server1, which runs on machine1. For each managed server, specify the listener port number and IP address. The listener port numbers for all managed servers should be the same.

5. In the navigation tree, choose Cluster, and create a new cluster for the managed servers. Specify the cluster address as the IP addresses of the managed servers in the cluster, separated by commas.

6. In the right pane, select the Multicast tab, and assign a unique multicast IP address in the subnet to the cluster. This can be any IP address in which the first number is greater than or equal to 224. The multicast IP address should not be used by other applications in the subnet.

7. Add the managed servers to the cluster.

8. For the following items, select the Targets and Clusters tabs, and set the Target Clusters to the cluster you created in step 5:

   • Services—>TxDataSources—>TxDataSource

   • Services—>Mail—>wlpiMailSession

   • Services—>JMS—>JMS Connection Factories—>wlpiFactory

   • Services—>JMS—>JMS Connection Factories—>wlpiQueueFactory

   • Deployments—>EJBs—>pobean.jar

   • Deployments—>EJBs—>repository-ejb.jar

   • Deployments—>EJBs—>wlpi-ejb.jar

9. For the following items, select the Targets and Servers tabs, and set the Target Servers to a managed server you designate as the primary server:

   • Deployments—>EJBs—>wlpi-mdb-ejb.jar

   • Deployments—>EJBs—>wlpi-master-ejb.jar

   • Deployments—>Startup and Shutdown—>TimeProcessor

   • Deployments—>Startup and Shutdown—>WLPIInit

To modify the server startup scripts:

1. For the administration server, from the config/mydomain directory of your WebLogic Process Integrator integration, open the server startup script file, startmydomain.cmd (in Windows) or startmydomain.sh (on UNIX), in a text editor.

2. Add the following option to the command line:

   -Dweblogic.management.discover=true

3. Create a managed server startup script in config/mydomain by copying the administration server startup script, and changing the name of the server to be started, as follows:

   -Dweblogic.Name=the managed server name

4. Add an option to the script for looking up the administration server, as follows:

   -Dweblogic.management.server=[t3://]hostname:port

To start the clustered servers:

1. Start the administration server.

2. Start the primary managed server.

3. Start the other managed servers.

 

---

Configuring a Custom Java Message Service Queue

You can create custom Java Message Service (JMS) queues and run the Message Driven Bean Generator utility (MDBGenerator.cmd on Windows and MDBGenerator.sh on UNIX) to generate a deployable.jar file that will listen on the custom queue. Configuring the custom queue involves the following steps:

• Using the WebLogic Server Administration Console to create the custom JMS queue

• Running the MDBGenerator utility to generate a message-driven bean (MDB) to listen on the queue

• Updating the WebLogic Process Integrator configuration to recognize the new MDB

For more information on creating JMS queues, see your WebLogic Server 6.0 documentation.

To create the custom JMS queue:

1. Start the WebLogic Process Integrator server in Mydomain as described in Starting the WebLogic Process Integrator Server.

2. Start the WebLogic Server Administration Console.

3. In the navigation tree, choose JMS—>Servers—>JMSServer-0—>Destinations, and create a new JMSQueue, specifying a name and JNDI name for the queue. Accept the default settings for the other fields, or see your WebLogic Server 6.0 documentation for other options.

   Note: Do not use any priority settings for ordered queues.

4. Shut down and restart the WebLogic Process Integrator server.

5. Once the server has restarted, verify that the queue has been created by restarting the WebLogic Server Administration Console and choosing JMS—>Servers—>JMSServer-0—>Destinations.

To run the MDBGenerator utility:

1. Open a command prompt, and go to the bin sub-directory of your WebLogic Process Integrator installation.

2. At the command prompt, do one of the following:

   • On a Windows system, enter the following:

     mdbg queue_name [-min number] [-max number] [-order number] [-transact] [-validate]

   • On a UNIX system, enter the following:

     sh mdbg.sh queue_name [-min number] [-max number] [-order number] [-transact] [-validate]

     The arguments for the mdgb command are listed in the following table.

     Table 4-1 MDBGenerator Command-Line Arguments

     Argument	Description
     queue_name	The name of the custom queue for which you want to generate the MDB.
     -min number	The minimum number of unordered listeners.
     -max number	The maximum number of unordered listeners.
     -order number	The number of orderered listeners. The number must be prime and below 31.
     -transact	Sets the transaction to required.
     -validate	Turns on XML validation.

     
      

     The queue_name-mdb-generator.jar file is created in the bin directory.

3. Move the generated file to the lib directory of your WebLogic Process Integrator installation.

4. From the config/mydomain directory of your WebLogic Process Integrator installation, open the config.xml file in a text editor. (A sample version of the file is provided in WebLogic Process Integrator Sample Configuration Files.)

5. Under the XML tag <Application Name="WLPI Application" Path="lib"> after all other <EJB Component> elements, add the following line:

   <EJBComponent Name="queue_name-mdb-generator.jar" Targets="myserver" URI="queue_name-mdb-generator.jar" DeploymentOrder="5"/>

   Note: The config.xml file is case-sensitive. Be sure to enter text using the proper case.

6. Save the file.

7. Shut down and restart the WebLogic Process Integrator server.

 

---

Configuring Security Realms for WebLogic Process Integrator

WebLogic Process Integrator 2.0 uses a new security model in which:

• WebLogic Process Integrator users and groups are maintained in a BEA WebLogic Server security realm

• WebLogic Process Integrator organizations are WebLogic Process Integrator-specific entities that exist outside the security realm

• WebLogic Process Integrator roles map to WebLogic Server groups

In addition to the default users (for a list of these users, and their passwords, see WebLogic Process Integrator Default Users and Passwords), WebLogic Process Integrator 2.0 uses three types of groups:

• Permission groups—These define the types of operations member users can perform. The permission groups and their default member users are shown in the following table.

  Table 4-2 Permission Groups and Members

  Permission Group	Members
  AdministerUser	admin, joe, mary, wlcsystem, wlpisystem
  ConfigureComponents	admin, joe, mary, wlcsystem, wlpisystem
  ConfigureSystem	admin, joe, mary, wlcsystem, wlpisystem
  CreateTemplate	admin, joe, mary, wlcsystem, wlpisystem
  DeleteTemplate	admin, joe, mary, wlcsystem, wlpisystem
  ExecuteTemplate	admin, joe, mary, wlcsystem, wlpisystem
  MonitorInstance	admin, joe, mary, wlcsystem, wlpisystem
  UpdateTemplate	admin, joe, mary, wlcsystem, wlpisystem

  
   

• System groups—These are required by the WebLogic Process Integrator system. They are wlpiUsers, wlpiAdministrators, and everyone. System groups and their member users are listed in the following table.

  Table 4-3 System Groups and Members

  System Group	Members
  everyone	admin, joe, system, mary, wlcsystem, wlpisystem
  wlpiAdministrators	admin, joe, system, mary, wlpisystem
  wlpiUsers	admin, joe, system, mary, wlcsystem, wlpisystem

  
   

• Role groups—These are mapped to WebLogic Process Integrator roles, and can be created automatically when you create a role in the WebLogic Process Integrator Studio. The default role groups and their member users are shown in the following table.

  Table 4-4 Role Groups and Members

  Role Group	Members
  AccountingCDE	admin, joe
  CustomerServiceCDE	admin
  Role1Org1	admin, joe, mary
  Role2Org1	admin, joe, mary
  ShippingCDE	admin, mary

  
   

When you install WebLogic Process Integrator 2.0, the software is configured, by default, to use a file security realm, where default users, groups, and access control lists are read from the fileRealm.properties file in your WebLogic Process Integrator domain directory.

You can also use an RDBMSRealm, or an alternate security realm. (For an overview of the available WebLogic Server security realm types, see "Security Fundamentals" at http://download.oracle.com/docs/cd/E13222_01/wls/docs60/security/concepts.html) By using any of these security realms, properly configured, you can create users, organizations, and roles through the BEA WebLogic Process Integrator Studio.

To set up the RDBMSRealm, follow the procedure given below. To customize the RDBMSRealm properties, see Customizing Database Settings. To create an alternate security realm, follow the procedure given in Configuring an Alternate Security Realm.

Configuring the RDBMS Security Realm

To change the security realm from fileRealm.properties to RDBMSRealm:

1. Start the WebLogic Process Integrator server in Mydomain as described in Starting the WebLogic Process Integrator Server.

2. Start the WebLogic Server Administration Console.

3. In the navigation tree, go to Security, and in the right pane, select the General tab.

4. From the Caching Realm drop-down list, select wlpiCachingRealm, and click Apply.

5. Shut down the WebLogic Process Integrator server.

6. Go to the config/mydomain directory of your WebLogic Process Integrator installation, and back up the file fileRealm.properties by copying and renaming it.

7. Open the original fileRealm.properties file in a text editor.

8. Delete all entries beginning with user and group, and save the file.

9. Restart the WebLogic Process Integrator server.

Configuring an Alternate Security Realm

If you want to create an alternate security realm, the realm must conform to certain guidelines, as follows:

• WebLogic Process Integrator users are WebLogic Server users.

• You must create the following users: system, admin, and wlpisystem.

• You must create the following WebLogic Server groups: all permission groups, as listed in Table 4-2, and the wlpiUsers group.

• The wlpisystem user must be a member of all the required groups.

• Any user who wants to use WebLogic Process Integrator must be a member of the wlpiUsers group.

Consult your WebLogic Server 6.0 documentation for procedures on creating an alternate security realm.

Once a manageable security realm is configured and populated in conformance with the preceding guidelines, you can create additional users, roles, and organizations, and assign permissions to users and roles, through the WebLogic Process Integrator Studio. For information and procedures, see Administering Data in Using the BEA WebLogic Process Integrator Studio.

 

---

Customizing Database Settings

Database JDBC Connection Pool and RDBMSRealm parameters are automatically provided at installation time when you configure your database, and are stored in an XML file for retrieval each time you start the WebLogic Process Integrator server. If you want to customize or update these parameters, you can do so in two ways:

• With the WebLogic Process Integrator server running in Mydomain, start the WebLogic Server Administration Console and choose Services—>JDBC—>Connection Pools—>wliPool, and edit properties listed on the General and Connections tabs. Next, choose Security—>Realms—>wlpiRDBMSRealm and edit properties listed on the Database tab. Typically edited parameters for both JDBC and RDBMSRealm are provided in Table 4-5 and Table 4-6, respectively.

• Edit the config.xml file found in the Mydomain directory. Procedures for doing so are given below, and a sample version of the file is provided in WebLogic Process Integrator Sample Configuration Files.

Note: The config.xml file contains settings for all supported databases, with unused databases commented out. If you edit the file through the WebLogic Server Administration Console, all unused database information is lost.

To customize JDBC Connection Pool settings:

1. If you are running the WebLogic Process Integrator server, shut it down.

2. From the config/mydomain directory of your WebLogic Process Integrator installation, open the config.xml file in a text editor.

   Note: The config.xml file is case-sensitive. Be sure to enter text using the proper case.

3. If you want to change database products, comment out the current database, and un-comment the database you want to use.

   Note: Commented text in XML is surrounded by angle brackets, exclamation marks, and dashes, such as the following: <!---this is commented text---!>

4. Provide values for JDBC Connection properties as described in the following table.

   Table 4-5 JDBC Connection Pool Properties

   Property	Description
   user	The account login name required for connecting to the database server.
   password	The password required for connecting to the database server.
   URL: hostname	The name of the server machine hosting the database.
   URL: portname	The port to be used to connect to the server. The default settings are: Oracle: 1521 Sybase: 5000 Microsoft SQL Server: 1433
   URL: dbname	The database or service name for the database that contains the WebLogic Process Integrator and repository tables.

   
    

5. Provide values for RDBMS Realm properties, as described in the following table.

   Table 4-6 RDBMS Realm Properties

   Property	Description
   DatabasePassword	The password required for connecting to the database server.
   DatabaseUserName	The account login name required for connecting to the database server.
   DatabaseURL: hostname	The name of the server machine hosting the database.
   DatabaseURL: portname	The port to be used to connect to the server. The default settings are: Oracle: 1521 Sybase: 5000 Microsoft SQL Server: 1433
   DatabaseURL: dbname	The database or service name for the database that contains the WebLogic Process Integrator and repository tables.

   
    

6. Save the file.

7. Restart the WebLogic Process Integrator server.

 

---

Customizing Mail Session Settings

If you specified mail session configuration information during the installation process, these parameters are stored in an XML file for retrieval each time you start the WebLogic Process Integrator server. You can also provide those settings after installation, customize or update these parameters, or, depending on your e-mail server, specify additional information in two ways:

• With the WebLogic Process Integrator server running in Mydomain, start the WebLogic Server Administration Console and choose Services—>Mail—>wlpiMailSession, and edit properties listed on the Configuration tab. Mail session properties are described in Table 4-7 and Table 4-8 below.

• Edit the config.xml file found in the Mydomain directory. Procedures for doing so are given below, and a sample version of the file is provided in WebLogic Process Integrator Sample Configuration Files.

Note: The config.xml file contains settings for all supported databases, with unused databases commented out. If you edit the file through the WebLogic Server Administration Console, all unused database information is lost.

To customize Mail Session settings:

1. If you are running the WebLogic Process Integrator server, shut it down.

2. From the config/mydomain directory of your WebLogic Process Integrator installation, open the config.xml file in a text editor.

   Note: The config.xml file is case-sensitive. Be sure to enter text using the proper case.

3. Edit properties described in the following table.

   Table 4-7 Mail Session Properties

   Property	Description
   mail.from	The e-mail address from which e-mail is sent from a WebLogic Process Integrator workflow.
   mail.host	The domain name of the mail or SMTP server.

   
    

4. Optionally, add properties described in the following table.

   Table 4-8 Additional Mail Session Properties

   Property	Description
   mail.sender	The name of the sender that appears in an e-mail when it is received. The default is WebLogic Process Integrator.
   mail.user	If required by the mail server, the user name used for logging on.
   mail.password	If required by the mail server, the password used for logon authentication.

   
    

5. Save the file.

6. Restart the WebLogic Process Integrator server.

 

---

Modifying Your Environment Settings

Environment settings are provided during the installation process and are stored in the following script files:

• setEnv.cmd/setEnv.sh—sets the environment variables for WebLogic Process Integrator server. It is described in more detail in Updating Server Settings, and a sample file is provided in WebLogic Process Integrator Sample Configuration Files.

• setwlpiclientenv.cmd/setwlpiclientenv.sh—sets the environment variables for both WebLogic Process Integrator client applications: Studio and Worklist. It is described in more detail in Updating Client Settings, and a sample file is provided in WebLogic Process Integrator Sample Configuration Files.

Updating Server Settings

To update server settings:

1. If you are running the WebLogic Process Integrator server, shut it down.

2. From the config/mydomain directory of your WebLogic Process Integrator installation, open the file setEnv.cmd (on Windows) or setEnv.sh (on UNIX) in a text editor, and edit the variables as described in the following table.

   Table 4-9 Server Environment Variables

   Variable	Description
   JAVA_HOME	The root directory of the Java run-time environment. WebLogic Process Integrator expects to find a Java archive file called rt.jar in the jre/lib subdirectory of this directory.
   WL_HOME	The root directory of the WebLogic Process Integrator installation. This directory is detected by the installation program.
   BEA_HOME	The BEA Home directory you specified during the Installation.
   WLINT_HOME	The root directory you specified during the installation of WebLogic Process Integrator or another WebLogic Integration product. The default path is bea\wlintegration2.0.
   WLPI_HOME	This directory is created, by default, under the BEA WebLogic Integration home directory during the installation. The default path is bea\wlintegration2.0\processintegrator.

   
    

3. Save the file.

4. Restart the WebLogic Process Integrator server.

Updating Client Settings

To update server settings:

1. If you are running WebLogic Process Integrator Studio or Worklist, exit the application.

2. From the bin sub-directory of your WebLogic Process Integrator installation, open the file setwlpiclientenv.cmd (on Windows) or setwlpiclientenv.sh (on UNIX) in a text editor, and edit the variables described in the following table.

   Table 4-10 Client Environment Variables

   Variable	Description
   JAVA_HOME	The root directory of the Java run-time environment. BEA WebLogic Process Integrator expects to find a Java archive file called rt.jar in the jre/lib sub-directory of this directory.
   WLPI_HOME	This directory is created, by default, under the BEA WebLogic Integration home directory during the installation. The default path is bea\wlintegration2.0\processintegrator.
   NETSCAPE_HOME (UNIX only)	The root directory for your Netscape installation. This is required for viewing the Studio online help.

   
    

3. Save the file.

4. Restart the WebLogic Process Integrator client application.

 

---

Setting Up an Alternate Cloudscape Database

If you want to set up an alternate Cloudscape database, other than the one that is installed by default in Mydomain, you need to do the following:

• Use Cloudview to create the WebLogic Process Integrator tables

• Use Cloudview to create the Repository tables (if you have not already done so for another WebLogic Integration installation)

• Update the WebLogic Process Integrator configuration to recognize the new database

Procedures for these steps are given below. Sample configuration files are also provided in WebLogic Process Integrator Sample Configuration Files.

To create an alternate WebLogic Process Integrator Cloudscape database for Mydomain:

1. If you are running the WebLogic Process Integrator server, shut it down.

2. Start the Cloudview administration tool by doing one of the following:

   • On a Windows system, go to the bin sub-directory of your WebLogic Process Integrator installation and run the startcloudview.cmd script.

   • On a UNIX system, go to the bin sub-directory of your WebLogic Process Integrator installation and enter the following:

     sh startcloudview.sh

3. Do one of the following:

   • If you have already created a Repository database, choose File—>Open, and navigate to the database. Go to step 7.

   • If you have not yet created a Repository database, choose File—>New—>Database. The New Database dialog box appears.

4. Click Directory to browse to the directory in which you would like to create the database, or enter a path in the Name field.

5. At the end of the path, add a name for the database, for example WLIDB.

6. Click OK.

7. In the right pane of the window, select the Database tab.

8. Click the Script button, and from the pop-up menu, select Open.

9. Navigate to the ddl subdirectory of your WebLogic Process Integrator installation, select the wlpi_cloudscape.ddl file, and click Open. The contents of the file appear in the SQL window.

10. Click the Execute button to execute the script. When the script has finished running, the WebLogic Process Integrator tables have been created.

To create the Repository tables for a new WebLogic Process Integrator Cloudscape database:

1. In Cloudview, choose File—>Open, and navigate to the database in which you have created the WebLogic Process Integrator tables.

2. In the right pane of the window, select the Database tab.

3. Click the Script button, and from the pop-up menu, select Open.

4. Navigate to the repository/cloudscape sub-directory of your WebLogic Integration installation, select the REPOSITORY_SCHEMA_BASE.sql file, and click Open. The contents of the file appear in the SQL window.

5. Click the Execute button to execute the script. When the script has finished running, the Repository tables have been created.

   Note: If you encounter an error stating that a table could not be found during the script execution, delete all drop table lines from the SQL window, and re-execute the script.

To update the WebLogic Process Integrator configuration:

1. From the config/mydomain sub-directory of your WebLogic Process Integrator installation, open the file config.xml in a text editor. (A sample version of this file is provided in WebLogic Process Integrator Sample Configuration Files.)

   Note: The config.xml file is case-sensitive. Be sure to enter text using the proper case.

2. In the <JDBCConnectionPool> tag, edit the following line to replace db with the new database name:

   URL="jdbc:cloudscape:db"

3. Save the file.

4. From the config/mydomain sub-directory of your WebLogic Process Integrator installation, open the server startup script file—startmydomain.cmd (on Windows) or startmydomain.sh (on UNIX)—in a text editor. (A sample version of this file is provided in WebLogic Process Integrator Sample Configuration Files.)

5. Edit the bold section of the following line to update the path for the directory in which the new database resides. (Do not include the name of the database in the path:)

   -Dcloudscape.system.home=%WLINT_HOME%\repository\cloudscape

6. If you are using a version of Cloudscape other than the one shipped with WebLogic Server 6.0, edit the bold section of the following classpath line to update the path for the cloudscape.jar file:

   %WL_HOME%\samples\eval\cloudscape\lib\cloudscape.jar

7. Save the file.

You are now ready to start WebLogic Process Integrator.