Customizing WebLogic Integration

The following sections describe how to modify the default installation of WebLogic Integration:

• WebLogic Integration Commands and Supporting Files

• Specifying a New Database for a Domain

• Initializing the Database for a Domain

• Using the Database Wizard

• Updating the Database Configuration from the WebLogic Server Administration Console

• Creating and Customizing a New Domain

• Updating the WebLogic Integration Environment

• Configuring a Custom Java Message Service Queue

• Deploying EJBs and Java Classes for Business Operations

• Configuring BPM to Support Null Variables

• Understanding the BPM Security Model

• Updating Passwords

• Customizing Mail Session Properties

• Root Directory of a Domain

• Using an Alternate Character Set

• Changing WebLogic Integration Port Numbers

• Deploying B2B Without Persistence

For information about more advanced configuration options, such as clustering, see Deploying BEA WebLogic Integration Solutions.

 

---

WebLogic Integration Commands and Supporting Files

A number of commands and supporting files are provided with WebLogic Integration. Many of the commands are used by the Database Wizard and the RunSamples script described in Domain Configuration Requirements. Although such commands are not normally invoked in isolation, in some situations you may need to modify a command or troubleshoot the execution of a command. To help you familiarize yourself with the use of these commands, a command reference is provided in WebLogic Integration Commands.

In addition, examples of the files that control the configuration and startup of a typical WebLogic Integration domain are provided in WebLogic Integration Sample Configuration Files.

 

---

Specifying a New Database for a Domain

Which method you use to specify a new database for a domain depends on:

• Whether the database you are replacing is used for the samples domain or for a custom domain you created using the Configuration Wizard

  Note: For information about creating and customizing a WebLogic Integration domain, see Creating and Customizing a New Domain.

• Whether or not you need to preserve the WebLogic Integration repository data stored in the current database for the domain

The following table summarizes the methods used in each situation.

Table 3-1 Database Update Methods  

If you are updating the database for . . .	And you . . .	Then . . .
A custom domain	Do not want to preserve repository data in the existing database	1. Start the Database Wizard for the domain. 2. Select the Create Database option. This option prompts for the new database access information, and initializes the database.
	Want to preserve repository data in the existing database	1. Export the information required. 2. Start the Database Wizard for the domain. 3. Select the Create Database option. This option prompts for the new database access information, and initializes the database. 4. Import the information required. See Note
The samples domain	Do not want to preserve repository data in the existing database	1. Start the Database Wizard for the domain. 2. Select the Switch Database option to update the configuration. 3. Execute the RunSamples command to initialize the new samples database.
	Want to preserve repository data in the existing database	1. Export the information required. 2. Start the Database Wizard for the domain. 3. Select the Switch Database option to update the configuration. 4. Execute the RunSamples command to initialize the new samples database. 5. Import the information required.
Note You also have the option of preserving the existing domain. To do so, simply configure a new domain to use the new database, as described in Creating and Customizing a New Domain. You can then export workflow packages or B2B configuration elements, as required, for import to the new domain. When it is no longer needed, you can delete the obsolete domain.

 

The following table provides the location of the information required to perform the preceding tasks.

Table 3-2 Finding Instructions for Updating a Database

To learn how to perform this task . . .	Refer to . . .
Start the Database Wizard	Using the Database Wizard
Execute the RunSamples command	Configuring and Starting the Samples Domain
Export and import B2B configuration elements	Importing and Exporting B2B Integration Components in Administering B2B Integration
Export and import workflow packages	Importing and Exporting Workflow Packages in Using the WebLogic Integration Studio

 

 

---

Initializing the Database for a Domain

Which method you use to initialize the database for a domain depends on whether the database will be used for the samples domain or for a custom domain created with the Configuration Wizard:

• If you are initializing a database for the samples domain, use the RunSamples command to initialize the database, as described in Configuring and Starting the Samples Domain.

• If you are initializing a database for a domain created with the Configuration Wizard, use the Database Wizard. Select the Create Database option to create and initialize the database and then load the system data into the database. See the following section, Using the Database Wizard.

  Note: For information about creating and customizing a domain, see Creating and Customizing a New Domain.

For additional information about the tasks performed by the RunSamples command and the Database Wizard, see Domain Configuration Requirements.

 

---

Using the Database Wizard

As described in Configuring the Database for a Domain, the WebLogic Integration Database Wizard is provided to automate database configuration tasks. A domain-specific version of the command is installed in each WebLogic Integration domain.

The following sections provide the information you need to use the Database Wizard to initialize the database for a domain, specify a new database for a domain, or migrate a WebLogic Integration 2.1 database to WebLogic Integration 7.0:

• Database Connection Information

• Database Wizard Options

• How the Database Wizard Works

• Database Configuration Modes

• Using the Database Wizard in Graphical Mode

• Using the Database Wizard in Console Mode

Database Connection Information

The following table summarizes the information required to connect to each supported database type. The Database Wizard prompts you to provide the values required to connect to the database you are configuring.

Table 3-3 Database Access Information  

Database Type	Connection Parameters	Description
PointBase	None	A PointBase database is created for the domain in the DOMAIN_HOME\dbInfo\pointbase\db directory. Default access parameters are used.
Oracle	Server Hostname	Name of the system that hosts the Oracle Server
	Server Port Number	Oracle port number (the default is 1521)
	User	User ID (schema)
	Password	User password
	Oracle SID	Oracle system identifier
	Net Service Name	Name of the database as it appears in tnsnames.ora or in the Names server
Microsoft SQL Server	Hostname	Name of the system that hosts the Microsoft SQL Server
	Port	Microsoft port number (the default is 1433)
	User	Account login name
	Password	Account password
	Database Name	Name of the database defined on the Microsoft SQL Server
	Server Name	The server alias as it appears on the General tab in your Client Network Utility. If no alias is configured, the hostname is used.
Sybase	Hostname	Name of the system that hosts the Sybase server
	Port	Sybase port number (the default is 5000)
	User	Account login name
	Password	Account password
	Database Name	Name of the database defined on the Sybase server
	Server Name	The server name assigned in the Sybase client configuration. This name is set using the Directory Services Editor (DSEDIT1).

 

Database Wizard Options

The Database Wizard provides the following options:

• Switch Database
  Select this option to switch the database for the domain. The environment variables used by commands that are invoked to initialize the database (commands such as CreateDB and RunSamples) are updated, and the config.xml file is modified to reflect the new settings. This option does not initialize the database; it merely configures the environment in preparation for database initialization.

• Create Database
  Select this option to initialize the database currently specified, or to switch to a new database and initialize it.

  Note: Although this option is available for the samples domain, it does not complete all the tasks required to initialize the samples database. To initialize the database for the samples domain, you must execute the RunSamples command, as described in Configuring and Starting the Samples Domain.

How the Database Wizard Works

The WebLogic Integration Database Wizard updates the environment variables set by the setDBVars and setDBVarsExt commands for the domain, updates the config.xml file to reflect the database access information provided, and invokes the commands required to perform the selected tasks.

For detailed information about the environment variables and command files used, see the wliconfig command in WebLogic Integration Commands.

Database Configuration Modes

Like the WebLogic Integration installer, the WebLogic Integration Database Wizard supports the following modes:

• Graphical mode
  Both the Windows and UNIX versions of the wizard provide an interactive graphical mode. This mode requires a graphics (windowing) terminal or workstation.

• Console mode
  The UNIX version of the wizard provides an interactive, text-only method that can be used to configure the database for a domain on a system that does not include a graphics terminal or workstation.

Follow the procedure appropriate for your system, as described in the following sections:

• Using the Database Wizard in Graphical Mode

• Using the Database Wizard in Console Mode

Using the Database Wizard in Graphical Mode

The following procedure describes how to update your database configuration using the WebLogic Integration Database Wizard in graphical mode.

To configure the database for a domain:

1. If you are using a UNIX platform, go to step 2. If you are using a Windows platform, complete the appropriate step from the following table.

   To configure the database for . . .	Choose . . .
   The WebLogic Integration samples domain	Start—>Programs—>BEA WebLogic Platform 7.0—>WebLogic Integration 7.0—>Integration Examples—>Integration Database Wizard
   A domain created with the Configuration Wizard	Start—>Programs—>BEA WebLogic Platform 7.0—>User Projects—>domain—>Integration Database Wizard

   
    

   The Choose Configuration Option dialog box is displayed. Go to step 3.

2. On a UNIX platform, do the following:

   1. Go to the DOMAIN_HOME directory.

      For example, if you created mydomain in the /home/bea/user_projects directory, enter the following:

      cd /home/bea/user_projects/mydomain

   2. Execute the following command:

      wliconfig

   The Choose Configuration Option dialog box is displayed, as shown in the following figure.

   Figure 3-1 Choose Configuration Option Dialog Box

   
    

   Note: If you are on a UNIX system, and are connecting to a Microft SQL Server database, you will be unable use the wizard to initialize the database because there is no Microsoft SQL client for UNIX. Instead, you will need to initialize the database from a Windows system.

3. Select the appropriate option. See Database Wizard Options.

4. Click Next.

   The Database Selection dialog box is displayed. This dialog box reflects the database that is currently configured for the domain. For example, if you specified the connection parameters for a Pointbase database when you created the domain, Pointbase is selected, as shown in the following figure.

   Figure 3-2 Database Selection Dialog Box

   
    

5. Do one of the following:

   • To accept the current setting, click Next.

   • To change to a new database, select the desired database, and then click Next.

   • The Database Configuration dialog box is displayed, as shown in the following figure. This dialog box reflects information that was provided when you created the domain, or when you last used the wizard to specify a new database.

     Figure 3-3 Database Configuration Dialog Box

     
      

6. Do one of the following:

   • To accept the current values, click Next.

   • To change to a new database, provide the information required to connect to the database, and then click Next. For a summary of the information required for each database type, see Database Connection Information.

   The results are as follows

   • If you selected Switch Database, the selected action proceeds. When the changes are complete, the Changes Successful dialog box is displayed, as shown in Figure  3-7. Go to step 12.

   • If you selected Create Database, you are prompted to locate the client installation directory for the database, as shown in the following figure.

     Figure 3-4 Locate Database Client Dialog Box

     
      

7. Click Browse to display the Open dialog box.

8. Navigate to your database client installation directory. For example, if you are using a Microsoft SQL Server 7.0 client, navigate to the MSQL7 directory, as shown in the following figure. (In this example, the database client installation directory is c:\Program Files\MSSQL7.)

   Figure 3-5 Open Dialog Box

   
    

9. Click Open.

   A message confirming that the appropriate client application was found is displayed, as shown in the following figure.

   Figure 3-6 Confirmation Message

   
    

   Note: If an error message is displayed indicating that the client application was not found, click OK to dismiss the message, and then Click Browse to locate the correct directory.

10. Click OK to dismiss the message and return to the Locate Database Client dialog box.

11. Click Next to continue.

    When the changes are complete, the Changes Successful dialog box is displayed, as shown in the following figure.

    Figure 3-7 Changes Successful Dialog Box

    
     

    Note: If there is an error in the execution of the selected action, an Error dialog box is displayed. This dialog box indicates the location of a log file. View the log file to determine how to address the problem.

12. Click Finish to exit the installer.

Using the Database Wizard in Console Mode

This section summarizes the console-mode database configuration procedure, a set of steps that emulates the graphical installation procedure.

To start the Database Wizard in console mode, enter the following commands at the prompt:

cd DOMAIN_HOME
wliconfig console

The following listing shows the console-mode prompts and responses for the Create Database option described in Database Wizard Options. (Responses are indicated in bold.)

The prompts that are presented will vary from those shown, depending on your responses to the Please Select Configuration Option: and Please specify the database type to configure: prompts.

Listing 3-1 Database Wizard Procedure in Console Mode

===============================================================================
BEA WebLogic Integration Database Wizard 7.0
-------------------------------------------------------------------------------

===============================================================================
Configuration Selection
--------------------------------------------------

          1- Switch Database
          2- Create Database

Please Select Configuration Option: 2


===============================================================================
Database Selection
--------------------------------------------------


Please specify the database type to configure.

          1- Oracle
        ->2- Microsoft SQL Server
          3- Sybase
          
Select a number or <Enter> for default(2): 1
Oracle Server Hostname: oraclehost
Oracle Server Port Number: 1521
Oracle User: myuser
Oracle Password: mypassword
Oracle SID: nj908
Oracle Net Service Name: oraclehost.world

Please enter the location of your Oracle client installation: c:\oracle
Searching for Oracle client(Sqlplus.exe)...

Found client Sqlplus.exe at c:\oracle\sqlplus.exe

        ->1- Use Located Client
          2- Choose new Location

Please choose a number(1): 1

===============================================================================
Switching Database please wait...
--------------------------------------------------


===============================================================================
Creating Database please wait...
--------------------------------------------------


===============================================================================
Finalizing changes, please wait...
--------------------------------------------------


Your configuration changes were successful. Press Enter to exit the Configuration Utility.

 

---

Updating the Database Configuration from the WebLogic Server Administration Console

Although the Database Wizard should be used to update the database configuration for any WebLogic Integration domain, there may be circumstances under which it is necessary to update the configuration from the WebLogic Server Administration Console. This section describes the procedure for doing so.

You should be aware that if you use this method to change to a new database, you will be unable to use the wizard, the createDB command, or the RunSamples command to create the tables in, or to populate, the database. These commands rely on settings for certain environment variables and the database access information stored in the DOMAIN_HOME/dbInfo directory. Unless you update this information manually, the wizard, the createDB command, and the RunSamples command will not work on the new database.

If you use the WebLogic Server Administration Console to update the database configuration, you can create the tables by executing the database-specific SQL scripts that are located in the WLI_HOME/dbscripts directory. Once you have created the tables, you can use the Bulk Loader or the B2B Console to import system data from the WLI_HOME/dbscripts/SystemRepData.xml file.

Updating the JDBC Connection Pool

To update the WebLogic Integration JDBC connection pool:

1. Start the WebLogic Server Administration Console, as described in Starting the WebLogic Server Administration Console.

2. In the navigation tree, choose Services—>JDBC—>Connection Pools—>wlipool.

3. Select the high-level Configuration tab.

4. If it is not already displayed, select the nested General tab.

5. Edit the URL, Driver Classname, and Properties, as required, to customize the settings for your JDBC connection pool. For additional information, see Database Access Parameters.

6. Click Apply to save your changes.

7. Close the WebLogic Server Administration Console.

8. Shut down and restart WebLogic Integration to initiate the new settings.

Updating the RDBMS Realm Properties

By default, the RDBMS realm is not configured for the samples domain or a custom domain created with the Configuration Wizard. To configure an RDBMS realm for a domain, you must manually add elements to the config.xml file. This procedure is described in "Migrating from the RDBMS Realm" in Migrating WebLogic Integration 2.1 to WebLogic Integration 7.0 in BEA WebLogic Integration Migration Guide. An RDBMS realm must be configured before the RDBMS realm properties can be updated.

To update the RDBMS realm properties:

1. Start the WebLogic Server Administration Console, as described in Starting the WebLogic Server Administration Console.

2. In the navigation tree, choose Security—>Realms—>wlpiRDBMSRealm.

3. Select the high-level Configuration tab.

4. Select the nested Database tab.

5. Edit the Driver, URL, Username, and Password, as required, to customize the settings for your database. For additional information, see Database Access Parameters in the following section.

6. Click Apply to save your changes.

7. Close the WebLogic Server Administration Console.

8. Shut down and restart WebLogic Integration to initiate the new settings.

Database Access Parameters

The following table summarizes the database access parameter information required to configure the JDBC connection pool from the WebLogic Server Administration Console.

Table 3-4 JDBC Connection Pool Parameters  

Parameter	Description
JDBC Driver	JDBC driver to be used to connect to the database: If you are using the Oracle thin driver, enter: oracle.jdbc.driver.OracleDriver If you are using the Sybase jConnect driver, enter: com.sybase.jdbc.SybDriver If you are using the PointBase driver, enter: com.pointbase.jdbc.jdbcUniversalDriver If you are using the WebLogic jDriver for SQL Server, enter: weblogic.jdbc.mssqlserver4.Driver
Database User	Account login name required for connecting to the database server.
Database Password	Password required for connecting to the database server.
URL	URL for the database, as specified in the JDBC driver documentation. The format for the JDBC connection pool URL is discussed in the following section.

 

Database Access URL Format

Each JDBC connection pool URL includes the following:

• host specifies the name of the database server host.

• port specifies the port to be used to connect to the database server.

• database specifies the database containing the repository tables on the database server.

The following table provides a sample URL for each supported database.

For the following driver . . .	The URL is . . .
Oracle thin driver	jdbc:oracle:thin:@host:port:database For example: jdbc:oracle:thin:@rdbmshost:1521:wlidb
WebLogic jDriver for Microft SQL Server	jdbc:weblogic:mssqlserver4:database@host:port?sql7=true For example: jdbc:weblogic:mssqlserver4:wlidb@rdbmshost:1433?sql7=true
Sybase jConnect driver	jdbc:sybase:Tds:host:5000/database For example: jdbc:sybase:Tds:rdbmshost:5000/wlidb
PointBase driver	jdbc:pointbase://host:port/database For example: jdbc:pointbase://localhost:9092/WLIDB

 

 

---

Creating and Customizing a New Domain

This section outlines the basic procedure for creating and customizing a WebLogic Integration domain. Detailed information is found in the following documents:

• Deploying BEA WebLogic Integration Solutions

• Using the Configuration Wizard

• Configuration Wizard Template Reference

Preparing to Create a Domain

Before you create a new domain, you should, at a minimum, complete the following tasks:

• Identify the configuration template that most accurately meets your application requirements.

  A set of domain configuration templates is included in your WebLogic Platform installation. These templates are used by the Configuration Wizard to create new WebLogic Server domains. To help you determine which configuration template most accurately meets your application requirements, review WebLogic Integration Configuration Templates and Configuration Wizard Template Reference.

  Note: Make sure you select a template that supports WebLogic Integration functionality. By using this type of template, you can ensure that the domain created is based on the WebLogic Server 6.x file-based realm in compatibility mode (FileRealm). The new WebLogic Server 7.0 LDAP-based realm is not supported with WebLogic Integration. If you create a new domain by selecting a WebLogic Server or WebLogic Portal template, the WebLogic Server 7.0 LDAP-based realm will be used in the new domain. For directions on configuring an RDBMS realm for WebLogic Integration, see "Migrating from the RDBMS Realm" in Migrating WebLogic Integration 2.1 to WebLogic Integration 7.0 in BEA WebLogic Integration Migration Guide.

• Review Using the Configuration Wizard to find out what kind of information you will need to provide.

• Determine whether this domain is intended for a single-server (standalone) or a multiple-server configuration. The following procedure allows you to create a new domain for a single-server (standalone) configuration. For directions on creating a multiple-server configuration, see "Step 2. Create a WebLogic Integration Domain" in Configuring a Clustered Deployment in Deploying BEA WebLogic Integration Solutions.

Procedure for Creating and Customizing a Domain for a Single Server

To create and customize a WebLogic Integration domain for a single server:

1. Run the Configuration Wizard by completing the procedure appropriate for your platform:

• On a Windows system you have a choice of three methods:

  • To start the Configuration Wizard from a menu:

    Choose Start—>Programs—>BEA WebLogic Platform 7.0—>Domain Configuration Wizard.

  • To start the Configuration Wizard in graphical mode from the command line:

    cd c:\bea\weblogic700\integration
    setenv.cmd
    cd c:\bea\weblogic700\common\bin
    dmwiz

  • To start the Configuration Wizard in console or text based mode:

    cd c:\bea\weblogic700\integration
    setenv.cmd
    cd c:\bea\weblogic700\common\bin
    dmwiz console

• On a UNIX system you have a choice of two methods:

  • To start the Configuration Wizard in graphical mode:

    cd /home/joe/bea/weblogic700/integration
    . setenv.sh
    cd /home/joe/bea/weblogic700/common/bin
    dmwiz.sh

  • To start the Configuration Wizard in console or text based mode:

    cd /home/joe/bea/weblogic700/integration
    . setenv.sh
    cd /home/joe/bea/weblogic700/common/bin
    dmwiz.sh console

  The Choose Domain Type and Name window is displayed.

  For more information, see Using the Configuration Wizard in the BEA WebLogic Platform document set, available at the following URL:

  http://download.oracle.com/docs/cd/E13196_01/platform/docs70/confgwiz/index.html

2. In the Choose Domain Type and Name dialog box, select a domain template that contains the components of WebLogic Integration required for your application.

3. In the Choose Server Type dialog box, select Single Server (Standalone Server).

4. When prompted, continue to provide the information required to create the new domain. When the process is complete, select End Configuration Wizard in the Configuration Wizard Complete dialog box, and then click the Done button to dismiss the Configuration Wizard.

5. (Optional) Save a copy of the generated config.xml file. The generated config.xml file contains configuration information in the comments. This information is deleted when the instance of WebLogic Server is started. To make a copy of the config.xml file, enter the command appropriate for your operating system:

   • On a Windows system:

     copy config.xml config.xml.backup

   • On a UNIX system:

     cp config.xml config.xml.backup

6. Configure the database connection information for the new domain. Start the WebLogic Integration Database Wizard (wliconfig) in the new domain created in steps 1 to 4.

   For example, if you created a domain named mydomain in the default location, enter the commands appropriate for your operating system:

   • On a Windows system:

     cd %BEA_HOME%\user_projects\mydomain
     wliconfig

   • On a UNIX system:

     cd $BEA_HOME/user_projects/mydomain
     wliconfig

   The Choose Configuration Option window is displayed.

7. Continue to provide the information required to configure the database. For detailed directions, see Using the Database Wizard in Graphical Mode.

The following section provides additional information about the directories and files installed when you create a WebLogic Integration domain.

Supporting Directories and Files

The following table lists the directories and files that are included in a domain that supports WebLogic Integration. All the scripts and directories listed in Table  3-5 are located in the domain directory. For example, if you created domain using the Configuration Wizard in the c:\bea\user_projects\mydomain directory, the applications directory path would be c:\bea\user_projects\mydomain\applications.

Note: Each item is included in all domains that support WebLogic Integration, unless otherwise specified.

Table 3-5 Contents of Domain Directory  

Directory/File	Content Description
applications directory	Application-specific information: the content of this directory depends on your application requirements. For more information about setting up the applications directory, see "Directory Structure" in "Web Applications Basics" in Assembling and Configuring Web Applications in the BEA WebLogic Server documentation at the following URL: http://download.oracle.com/docs/cd/E13222_01/wls/docs70/webapp/basics.html
dbInfo directory	Database-specific information used when creating and initializing the database. Note: If you need to update the configuration information in the database variable files in each subdirectory, use the Database Wizard to do so. For more information, see Using the Database Wizard. This directory contains the following subdirectories (corresponding to any databases that are supported): oracle: Oracle database pointbase: PointBase database mssql: Microsoft SQL database sybase: Sybase database Within each database directory, the following files are defined: setDBVars command: basic database variables for the domain setDBVarsExt command: extended database variables for the domain For more information about the setDBVars and setDBVarsExt commands, see setDBVars setDBVarsExt.
scripts directory	Script used to change the current database setting and to process domain-specific files. It contains a single ant call that references the top-level script, WLI_HOME/lib/scripts/SwitchDB.xml. This script is called when the Database Wizard executes the switchdb command to update the database configured for the domain. For more information about the switchdb command, see switchdb.
config.xml file	Configuration information that describes the WebLogic Server domain and controls the deployed resources. For more information about the contents of the config.xml file, see config.xml.
fileRealm.properties file	Default security realm in which the User, Group, and ACL objects that are created when WebLogic Server is started are stored. For more information about the contents of this file, see fileRealm.properties. For more information about the BPM security model, see Understanding the BPM Security Model.
SerializedSystemIni.dat file	Data file used to hash system passwords. This file is associated with the corresponding fileRealm.properties file. For more information about this file, see "Protecting User Accounts" in "Configuring WebLogic Security" which, in turn, is available in the Managing WebLogic Security. The guide is available from the BEA WebLogic Server documentation set at the following URL: http://download.oracle.com/docs/cd/E13222_01/wls/docs70/secmanage/security7.html
Start script For example: startWeblogic.cmd (Windows) or startWeblogic.exe (UNIX)	Script used to start the instance of WebLogic Server in the current domain. Although you can modify the functionality as desired, this script typically performs the following tasks: Sets up the environment by calling the setenv command Sets the current domain by calling the appropriate command Loads the database-specific variables into the current process using the setdbdata command Removes old log files Executes the Java command that starts WebLogic Server in the domain and deploys WebLogic Integration applications and resources as specified in the config.xml file (described previously in this table) Note: For more information about the start script and the commands that might be defined in the script, see startWeblogic. Note: You may want to update or add other command-line options, as required by your application. For more information about WebLogic Server command-line options, see "Starting the WebLogic Administration Server from the Command Line" in "Starting the WebLogic Administration Server" which, in turn, is available in "Starting and Stopping WebLogic Servers" in the WebLogic Server Administration Guide. The guide is provided, with the BEA WebLogic Server documentation set, at the following URL: http://download.oracle.com/docs/cd/E13222_01/wls/docs70/adminguide/startstop.html
Stop script For example: stopWeblogic.cmd (Windows) or stopWeblogic.exe (UNIX)	Script used for graceful shutdown of the instance of WebLogic Server for the current domain. Although you can modify the functionality as desired, this script typically performs the following tasks: Sets up the environment by calling the setenv command Issues a shutdown request to the instance of WebLogic Server running in the domain For more information about the stop script and commands that might be defined in it, see stopWeblogic. You may want to or add or update command-line options, as required by your application. For more information about WebLogic Server command-line options, see "Starting the WebLogic Administration Server from the Command Line" in "Starting the WebLogic Administration Server," which, in turn, is available in the "Starting and Stopping WebLogic Servers" section of the WebLogic Server Administration Guide. The guide is provided in the BEA WebLogic Server documentation set at the following URL: http://download.oracle.com/docs/cd/E13222_01/wls/docs70/adminguide/startstop.html
Customized versions of other WebLogic Integration commands	WebLogic Integration commands that may be customized within your application environment. For example, depending on the template used to create the domain, customized versions of the following WebLogic Integration commands may be included in the domain: checkdomain: Customized version reflects the current domain in the call to setdomain (within the echo line). This command is called by the setdbdata command. setdbdata: Customized version calls the customized version of the checkdomain command. This command is called by the setDomainTypeData command. setDomainTypeData: Customized version sets environment variables specific to the domain, and calls the customized version of the setdbdata command. Use of this file is recommended as a way of setting application integration-specific variables. This command is called by the corresponding start script, described previously in this table. For more information, see WebLogic Integration Commands.

 

 

---

Updating the WebLogic Integration Environment

The environment variables used by WebLogic Integration are set by the setEnv.cmd (Windows) or setenv.sh (UNIX) file. This file is located in the WebLogic Integration installation directory (WLI_HOME). An example of this file is provided in WebLogic Integration Sample Configuration Files.

The variables in the setEnv file are set when you install WebLogic Integration and normally do not need to be updated. If you must update the environment, however, you can do so by completing the following procedure.

To update the WebLogic Integration environment:

1. Do one of the following:

   • On Windows:

     Navigate to the WebLogic Integration installation directory, right-click setEnv.cmd, and then select Edit from the shortcut menu to open the file in Notepad.

   • On UNIX:

     Go to the appropriate domain directory and open setenv.sh in your preferred text editor.

2. Set the following variables to values appropriate for your environment:

   • JAVA_HOME
     Location of your JDK 1.3.1 installation. For example: C:\bea\jdk131_03.

   • BEA_HOME
     Location of your BEA Home directory. For example: C:\bea.

   • WL_HOME
     Location of your WebLogic Platform installation. For example: C:\bea\weblogic700\server.

   • WLI_HOME
     Location of your WebLogic Integration installation. For example: C:\bea\weblogic700\integration.

   • SAMPLES_HOME
     Location of your WebLogic Integration samples. For example: C:\bea\weblogic700\samples. For additional information, see WebLogic Integration Sample Configuration Files.

3. Save your changes and close the file.

When you execute the startWeblogic command (as described in Starting WebLogic Integration) the setEnv command is invoked and the environment variables become effective.

 

---

Configuring a Custom Java Message Service Queue

You can create custom Java Message Service (JMS) queues and run the message-driven bean generator utility to generate a deployable Java Archive (JAR) file that listens on the custom queue. Configuring a custom queue involves the following steps:

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

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

• Updating the WebLogic Integration configuration to recognize the new MDB

For more information about creating JMS queues, see your WebLogic Server 7.0 documentation.

To create the custom JMS queue:

1. Start WebLogic Integration, as described in Starting WebLogic Integration.

2. Start the WebLogic Server Administration Console, as described in Starting the WebLogic Server Administration Console.

3. In the navigation tree, choose JMS—>Servers—>WLIJMSServer—>Destinations. To create a new JMSQueue, right-click Destinations and select Configure a new JMSQueue. Specify a name and JNDI name for the queue. Accept the default settings for the other fields, or see your WebLogic Server 7.0 documentation for other options.

   Note: Do not use priority settings for ordered queues.

4. Shut down WebLogic Integration, as described in Stopping WebLogic Integration.

5. Restart WebLogic Integration, as described in Starting WebLogic Integration.

6. When the server is running again, verify that the queue has been created by restarting the WebLogic Server Administration Console and choosing JMS—>Servers—>WLIJMSServer—>Destinations.

To run the mdbgenerator utility:

1. Open a command window, and go to the bin subdirectory of the WebLogic Integration installation directory.

2. At the command prompt, enter the following:

   mdbgenerator -queue queue_name [-min number] [-max number]
   [-order number] [-transact] [-validate] [-timeout seconds] [-help]

   The options for the mdbgenerator command are listed in the following table.

   Table 3-6 mdbgenerator Command-Line Options

   Option	Description
   -queue queue_name	Name of the custom queue for which you want to generate the MDB. This option is required.
   -min number	Minimum number of unordered listeners.
   -max number	Maximum number of unordered listeners.
   -order number	Number of ordered listeners. The number must be prime and less than or equal to 31.
   -transact	Sets the transaction to required.
   -validate	Turns on XML validation.
   -timeout seconds	Sets the transaction timeout in seconds. This option defaults to 30 seconds. This value is used only if the transact flag is not set. If the transact flag is set, the utility uses the WebLogic Server transaction timeout value, which can be set using the Administration Console and defaults to 30.
   -help	Displays command usage syntax.

   
    

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

3. Move the generated file to the lib subdirectory of your WebLogic Integration installation directory.

4. If it is running in the domain, shut down WebLogic Integration, as described in Stopping WebLogic Integration.

5. Open the config.xml file for the domain.

6. Locate the following XML Tag:

   <Application Name="WebLogic Integration" Path="c:/bea/weblogic700/integration/lib>

   After all other <EJB Component> elements, add the following line:

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

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

7. Update the application.xml file, located in the path/META-INF directory, where path represents the location specified by the path attribute of the application element as shown (highlighted in bold) in step 6. For example, in step 6 the application.xml file is located in the following directory:

   c:\bea\weblogic700\integration\lib\META-INF

   The order in which the J2EE components are deployed is determined by the order of the components in the application.xml file.

   Warning: Do not remove or change the order of any WebLogic Integration components listed in the application.xml file.

   Add <module> and <ejb> elements for the JAR file, right before the bpm-init-ejb.jar module element near the end of the application element in the application.xml file. For an example, see the code lines highlighted in bold in Listing  3-4.

Listing 3-2 Sample Domain application.xml File

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.2//EN' 'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>
<application>
	<display-name>WebLogic Integration</display-name>
	.
	.
	.
	<module>
		<ejb>queue_name-mdb-generator.jar</ejb>
	</module>

	<!--BPM Initialization Bean must be deployed after BPM plug-ins-->
	<module>
		<ejb>bpm-init-ejb.jar</ejb>
	</module>
</application>

8. Save the file.

9. Restart WebLogic Integration, as described in Starting WebLogic Integration.

 

---

Deploying EJBs and Java Classes for Business Operations

To deploy EJBs and make the associated business operations available for use in WebLogic Integration, you must perform the following steps:

1. Copy or move the EJB JAR file to the WLI_HOME/lib directory.

2. Add a deployment descriptor for the EJB to the WebLogic Integration application element.

   For more information about the EJB deployment descriptor files, see "Deploying EJBs to WebLogic Server" in Programming WebLogic Enterprise Java Beans in the BEA WebLogic Server documentation set at the following URL:

   http://download.oracle.com/docs/cd/E13222_01/wls/docs70/ejb/deploy.html

3. Add the EJB to the WebLogic Integration application element by manually updating the configuration file, config.xml. This file is located in the directory indicated by DOMAIN_HOME, where DOMAIN_HOME is the full pathname for the root of the domain (for example, c:\bea\user_projects\domain).

   This step is described in Adding an EJB to the WebLogic Integration Application Element. The initial configuration of the WebLogic Integration application element is shown in Figure  A-3. (See WebLogic Integration Sample Configuration Files.)

To deploy custom Java classes and make them available in your WebLogic Integration applications, you must add the Java Archive (JAR) file containing the custom Java classes to your CLASSPATH. This procedure is described in Adding Java Classes to the CLASSPATH.

Note: The term WebLogic Integration application refers to an application that is developed by customers using WebLogic Integration. Do not confuse this term with the WebLogic Integration or WLI application elements in the config.xml file. The WebLogic Integration application element contains the collection of J2EE components that make up WebLogic Integration. In the WebLogic Integration sample config.xml file, WLI is the name of the application element that contains the collection of J2EE components that make up WebLogic Integration. In config.xml files generated by the Configuration Wizard, WebLogic Integration is the name of the application element that contains the collection of J2EE components that make up WebLogic Integration.

Adding an EJB to the WebLogic Integration Application Element

To add an EJB to the WebLogic Integration application element, complete the following steps:

1. Update config.xml (the configuration file, located in the DOMAIN_HOME directory) to specify the deployment descriptor files associated with the WebLogic Integration application element.

   To specify the EJB descriptor files, use the <EJBComponent> element.

   The following code listing is excerpted from the config.xml file for the samples domain. It shows the information required to deploy an EJB called MyEJB.jar. This file is located in the SAMPLES_HOME/integration/config/samples directory, where SAMPLES_HOME represents the WebLogic Platform samples directory. Notable lines of code are shown in bold.

Listing 3-3 Adding an EJB to the WebLogic Integration Application Element

<Application Name="WebLogic Integration"
  Path="c:/bea/weblogic700/integration/lib" TwoPhase="true">

	<!--Repository-->
	<EJBComponent Name="repository-ejb.jar" Targets="myserver"
	   URI="repository-ejb.jar" />

	<!--B2B-->
	<EJBComponent Name="WLI-B2B Startup" Targets="myserver" 
	   URI="b2b-startup.jar" />
	<WebAppComponent Name="TransportServlet" Targets="myserver"
	   URI="b2b.war" />
	<EJBComponent Name="WLI-B2B RN MDB" Targets="myserver"
	   URI="b2b-rosettanet.jar" />
	<WebAppComponent Name="b2bconsole" ServletReloadCheckSecs="1"
	   Targets="myserver" URI="b2bconsole.war"/>

	<!--AI-->
	<EJBComponent Name="WLI-AI Server" Targets="myserver"
	   URI="wlai-server-ejb.jar"/>
	<WebAppComponent Name="wlai" URI="wlai.war" Targets="myserver"/>
	<EJBComponent Name="WLI-AI Async Processor" Targets="myserver"
	   URI="wlai-asyncprocessor-ejb.jar"/>
	<EJBComponent Name="WLI-AI Event Processor" Targets="myserver"
	   URI="wlai-eventprocessor-ejb.jar"/>
	
	<!--BPM-->
	<EJBComponent Name="wlpi-ejb.jar" Targets="myserver" URI="wlpi-ejb.jar" />
	<EJBComponent Name="wlpi-master-ejb.jar" Targets="myserver"
	   URI="wlpi-master-ejb.jar" />
	<EJBComponent Name="wlpi-mdb-ejb.jar" Targets="myserver"
	   URI="wlpi-mdb-ejb.jar" />

	<!--XT-->
	<EJBComponent Name="wlxtpi.jar" Targets="myserver" URI="wlxtpi.jar"/>

	<!--Plugins-->
	<EJBComponent Name="WLI-B2B RN Plugin for BPM" Targets="myserver"
	   URI="wlc-wlpi-plugin.jar" />
	<EJBComponent Name="WLI-B2B EBXML Plugin for BPM" Targets="myserver"
	   URI="ebxml-bpm-plugin.jar"/>
	<EJBComponent Name="WLI-AI Plug-In for BPM" Targets="myserver"
	   URI="wlai-plugin-ejb.jar"/>
	<WebAppComponent Name="WLAIPlugin" URI="wlai-plugin.war" Targets="myserver"/>
	<WebAppComponent Name="XTPlugin" Targets="myserver" URI="wlxtpi.war"/>

	<!--Samples-->
	<WebAppComponent Name="com.bea.wlpi.SamplePlugin" Targets=""
	   URI="sampleplugin.war"/>
	<EJBComponent Name="sampleplugin-ejb.jar" Targets=""
	   URI="sampleplugin-ejb.jar"/>
	<EJBComponent Name="wlxtejb.jar" Targets="" URI="WLXTEJB.jar"/>
	<EJBComponent Name="pobean.jar" Targets="myserver" URI="pobean.jar"/>

	<!--BPM Initialization-->
	<EJBComponent Name="WLI-BPM Initialization" Targets="myserver"
	   URI="bpm-init-ejb.jar"/>
	<EJBComponent Name="WLI Error Listener" Targets="myserver"
	   URI="wli-errorlistener-mdb.jar"/>
</Application>

Note: Add your EJBs to the end of the WebLogic Integration or WLI application element list (before the </Application> tag).

Warning: In the sample config.xml file, WLI is the name of the application element that contains the collection of J2EE components that make up WebLogic Integration. In config.xml files generated by the Configuration Wizard, WebLogic Integration is the name of the application element that contains the collection of J2EE components that make up WebLogic Integration.

For more information about updating the config.xml file, see BEA WebLogic Server Configuration Reference in the BEA WebLogic Server documentation set at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/config_xml/index.html

2. Update the application.xml file. This file is located in the path/META-INF directory, where path represents the location specified by the path attribute of the application element, as shown (highlighted in bold) in Listing  3-3. In the example shown in Listing  3-3, the application.xml file is located in the following directory:

   c:\bea\weblogic700\integration\lib\META-INF

   The following code listing is excerpted from the application.xml file for the samples domain. It shows the information required to deploy an EJB called MyEJB.jar.

   The order in which the EJB JAR files are deployed is determined by the order in which the EJB JAR files are listed in the application.xml file. If you are adding more than one EJB JAR file, keep in mind the following rule of thumb: in general, if EJB A is dependent on EJB B, then EJB B must be deployed first.

   Warning: Do not remove or change the order of any of the WebLogic Integration EJB JAR or WAR files listed in the application.xml file.

   To specify EJB JAR files, add a <module> element and an <ejb> element for every EJB JAR file, right before thebpm-init-ejb.jar module element near the end of the application element in the application.xml file. For an example, see the code lines highlighted in bold in Listing  3-4.

Listing 3-4 Sample Domain application.xml File

<!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application
  1.2//EN' 'http://java.sun.com/j2ee/dtds/application_1_2.dtd'>
<application>
	<display-name>WebLogic Integration</display-name>
	.
	.
	.
	<module>
		<ejb>MyEJB.jar</ejb>
	</module>

	<!--BPM Initialization Bean must be deployed after BPM plug-ins-->
	<module>
		<ejb>bpm-init-ejb.jar</ejb>
	</module>
</application>

3. Restart the server, as described in Getting Started.

Adding Java Classes to the CLASSPATH

You can add the JAR file for your custom Java classes to the server CLASSPATH in one of the following ways:

• Add the JAR file to the setenv command file.
  If you add the JAR file to the WLISERVERCP environment variable in the setEnv command file, it will be available to any WebLogic Integration domain installed on the machine; each time startWeblogic is executed, it invokes the setEnv command before issuing the Java command that starts the server.

• Add the JAR file to the startWeblogic command file.
  If you add the JAR file to the CLASSPATH specified in the startWeblogic command file, the Java classes will be available only on the server started by that command file.

Adding the JAR File to the setEnv Command File

To add the JAR file to the setEnv command file:

1. Open WLI_HOME/setEnv.cmd (Windows) or WLI_HOME/setenv.sh (UNIX) in your preferred text editor.

2. Locate the following line:

   set WLISERVERCP=%WLISERVERCP%;%JAVA_HOME%\lib\tools.jar

3. Add the complete pathname to the end of this statement, using a semi-colon to separate the new entry from the existing entries.

4. Save and close the file.

To make a Java class available to client applications, you can also add a Java class to the WLICP variable that is used to set the CLASSPATH for WebLogic Integration clients.

Note: You may notice that the WLISERVERCP environment variable does not appear in the startWeblogic command file. For each domain, a setDomainTypeData file is invoked after the setEnv command file. The value of the WLISERVERCP environment variable is transferred to the SVRCP environment variable in this command file.

Adding the JAR File to the startWebLogic Command File

To add the JAR file to the startWeblogic command file:

1. Open the startWeblogic.cmd (Windows) or startWeblogic (UNIX) command file in your preferred text editor.

2. Locate the Java command that starts the server:

   REM Start weblogic
   %JAVA_HOME%\bin\java %DB_JVMARGS% -Xmx256m -classpath %SVRCP%...

3. Add the following command just above the start server command:

   set SVRCP=%SVRCP%;MyJAR

   Here, MyJAR is the complete pathname for the JAR file that contains the Java classes.

4. Save and close the file.

 

---

Configuring BPM to Support Null Variables

Support for null variables can be enabled at server startup by modifying the Java command in the startWeblogic command to include the following:

-Dwli.bpm.server.evaluator.supportsNull=true 

When added to the Java command that starts the server, this option turns on null variable support for BPM. If this option is set to false, or if it is omitted from the command, then support for null variables is disabled.

After the server has started in a domain, the first time an expression is evaluated, a message indicating the status of null variable support is displayed:

• If null support is enabled, the message WebLogic Integration BPM server supports NULL is displayed.

• If null support is disabled, the message WebLogic Integration BPM server does not support NULL is displayed.

The server displays this message only once, the first time an expression is evaluated.

The following sections summarize how variable initial values and expression evaluation work when null support is enabled, and when it is disabled.

wli.bpm.server.evaluator.supportsNull=true

When wli.bpm.server.evaluator.supportsNull=true, the following rules apply:

• The value NULL (case-insensitive) is a valid constant in an expression that yields null. For example, set workflow variable $a expression NULL.

• The operators = and <> can be used to compare null values. All other comparison operations (>=, < ... ) on any null value yield false.

  For example, if the workflow variables $a and $c have a null value, and $b has a non-null value, then:

  $a=NULL      true
  $a=$c        true
  $a<>NULL     false
  $b<>NULL     true
  $b>$a        false

• Null values cannot be used in arithmetic expressions. For example, $a * NULL causes an exception.

• Null values cannot be used in logical expressions. For example,
  $a XOR NULL causes an exception.

• Null values can be used in string concatenation (StrCat). For example: "wli "+ NULL yields "wli null".

• With regard to variable initial values: NO variable is assigned an initial value; all variables have null as the initial value. This differs from the functionality that applies when null support is disabled.

• Any type of variable can be assigned a NULL value.

• Null variable values can be monitored and updated in the Studio. When you are monitoring a workflow instance, a null variable value is displayed as null. You can set a variable value to null in the Update Variable dialog box.

The following section describes the usage rules that apply when wli.bpm.server.evaluator.supportsNull=false. It is important that you understand the differences before you set this option to true.

If you have workflows that were defined in a previous version, or with null support disabled, these workflows will not work as they did earlier if they rely, in any way, on functionality that is affected. You must reexamine any legacy workflows and initialize appropriate workflow variable values. If you do not do so, the workflow may not run when you enable null variable support.

wli.bpm.server.evaluator.supportsNull=false

When wli.bpm.server.evaluator.supportsNull=false, the WebLogic Integration process engine operates exactly as it has operated in previous releases. The following rules apply:

• The value NULL (case-insensitive) is not valid in any expression. For example, $a * NULL is invalid.

• All comparison operations (=, <>, >=, < ... ) on any null value yield false.

  For example, if the workflow variables $a and $c have a null value, and $b has a non-null value, then:

  $a=$c      false
  $a<>$c     false
  $b<>$c     false
  $b>$a      false

• Null values cannot be used in arithmetic expressions. For example, $b * NULL causes an exception.

• Null values cannot be used in logical expressions. For example, $a XOR NULL causes an exception.

• Null values can be used in string concatenation (StrCat). For example: "wli "+ EventAttribute("not-existing-attribute") yields "wli null".

• Variables are set to the following initial values:

  String       ""
  Boolean      false
  Integer      0
  Double       0.0
  Date         Current date
  Entity       null
  Session      null
  Object       null
  XML          null

• Only string variables can be assigned a null value. Assigning a null value to any other variable type causes an exception.

• You cannot monitor or update null variable values.

 

---

Understanding the BPM Security Model

The security model provided by WebLogic Integration for business process management (BPM) functions is distinguished by the following characteristics:

• Users and groups are maintained in a BEA WebLogic Server security realm.

• Organizations are BPM-specific entities that exist outside the security realm.

• Roles map to WebLogic Server groups.

Note: For important background information about the WebLogic Server Security Service, see the following documents:

• Introducing WebLogic Platform 7.0 Security—This document provides important information if you are planning to use BPM with other BEA WebLogic Platform components.

• Using WebLogic Integration Security (in Deploying WebLogic Integration Solutions)—This topic provides an overview of WebLogic Integration security and gives practical advice about configuring the security for your WebLogic Integration domain.

When you use the Configuration Wizard to create a domain that supports BPM functionality, the domain is configured to use a FileRealm security realm. In this type of realm, default users, groups, and access control lists (ACLs) are maintained in the fileRealm.properties file, which is located in the domain directory.

A default RDBMSRealm can also be configured. To configure an RDBMS realm for a domain, you need to do the following:

• Manually add elements to the config.xml file. This procedure is described in "Migrating from the RDBMS Realm" in Migrating WebLogic Integration 2.1 to WebLogic Integration 7.0 in BEA WebLogic Integration Migration Guide.

• Add the path for the rdbmsrealm.jar file to your classpath. By default, this JAR file is located in the WLI_HOME\lib directory.

If you configure this realm, then users and groups are maintained in the database configured for the WebLogic Integration repository.

The BPM-defined ACL objects are managed differently from users and groups. Even if you enable the RDBMSRealm, ACL objects are stored in the FileRealm (the fileRealm.properties file) and must be managed through the WebLogic Server Administration Console.

You can use the existing FileRealm, enable the RDBMSRealm, or configure an alternate security realm. For an overview of the supported WebLogic Server security realm types, see "Security Fundamentals" at the following URL:

http://download.oracle.com/docs/cd/E13222_01/wls/docs70/security/concepts.html

No matter what type of security realm you configure, you can continue to create users, organizations, and roles through the WebLogic Integration Studio, as long as the security realm you configure conforms with the guidelines described in Security Realm Guidelines.

Note: WebLogic Integration and WebLogic Server user names and passwords (users created using the WebLogic Integration Studio) can contain any character from the JDK-supported character sets, including international characters.

The procedure for enabling the RDBMSRealm is provided in Enabling the RDBMS Security Realm.

The procedure for creating a custom security realm is provided in Configuring a Custom Security Realm. If you are creating another type of security realm (for example, NT or UNIX), see the WebLogic Server documentation for instructions.

BPM User Groups and Permissions

To support BPM functionality, default users (described in WebLogic Integration Users and Passwords) are organized into three types of user groups:

• Permission groups—Members are defined by the types of operations they can perform.

• System groups—These are required by the process engine.

• Role groups—Members are defined by their BPM-defined roles. When you create a role in the Studio, a corresponding role-specific group is created in the security realm.

The following tables list the default groups and the members assigned to them.

Table 3-7 Permission Groups and Members  

Permission Group	Members
AdministerUser	admin, joe, mary, guest, wlisystem
ConfigureComponents	admin, joe, mary, guest, wlisystem
ConfigureSystem	admin, joe, mary, guest, wlisystem
CreateTemplate	admin, joe, mary, guest, wlisystem
DeleteTemplate	admin, joe, mary, guest, wlisystem
ExecuteTemplate	admin, joe, mary, guest, wlisystem
MonitorInstance	admin, joe, mary, guest, wlisystem
UpdateTemplate	admin, joe, mary, guest, wlisystem

 

Table 3-8 System Groups and Members  

System Group	Members
everyone	admin, joe, system, mary, guest, wlisystem
wlpiAdministrators	admin, joe, system, mary, guest, wlisystem
wlpiUsers	admin, joe, system, mary, guest, wlisystem

 

Table 3-9 Role Groups and Members  

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

 

Security Realm Guidelines

You can create an alternate security realm as long as it conforms to the following guidelines:

• BPM users must be WebLogic Server users.

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

• You must create the following WebLogic Server groups:

  • All permission groups, as listed in Table  3-7

  • wlpiUsers group

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

• Any user who requires access to the WebLogic Integration process engine or the XML repository must be a member of the wlpiUsers group.

For procedures for creating an alternate security realm, see your WebLogic Server 7.0 documentation.

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

Enabling the RDBMS Security Realm

To change the security realm from the default FileRealm to the RDBMSRealm:

1. Make sure that the database used for the RDBMS realm is also populated with the WebLogic Integration repository. (You can populate the database with the repository by using the Integration Database Wizard, which you can start by choosing Start—>Programs—>BEA WebLogic Platform 7.0—>WebLogic Integration 7.0—>Integration Examples—>Integration Database Wizard.)

2. Configure the RDBMSRealm by manually adding elements to the config.xml file. This procedure is described in "Migrating from the RDBMS Realm" in Migrating WebLogic Integration 2.1 to WebLogic Integration 7.0 in BEA WebLogic Integration Migration Guide.

3. Start WebLogic Integration, as described in Starting WebLogic Integration.

4. Start the WebLogic Server Administration Console, as described in Starting the WebLogic Server Administration Console.

5. In the navigation tree, select Compatibility Security.

6. Select the Filerealm tab.

   Note: If the following message is displayed, click Cancel to dismiss.

   Figure 3-8 Leaving the Page? Confirmation

   
    

7. From the Caching Realm drop-down list, select wlpiCachingRealm.

8. Click Apply.

9. Shut down WebLogic Integration, as described in Stopping WebLogic Integration.

10. Go to the DOMAIN_HOME directory for the domain you are updating.

11. Back up the file fileRealm.properties by copying and renaming it.

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

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

    Note: Do not delete any entries that begin with acl. ACL objects are always maintained in the fileRealm.properties file, whether or not the RDBMSRealm is enabled.

14. Restart WebLogic Integration, as described in Starting WebLogic Integration.

Configuring a Custom Security Realm

Configuring a custom security realm involves the following tasks:

1. Creating the custom realm.

2. Configuring the caching realm (wlpiCachingRealm).

3. Enabling the caching realm.

4. Removing the RDBMSRealm (optional).

The following sections provide a procedure for each of these tasks.

Creating the Custom Realm

To create a custom security realm:

1. Start WebLogic Integration, as described in Starting WebLogic Integration.

2. Start the WebLogic Server Administration Console, as described in Starting the WebLogic Server Administration Console.

3. In the navigation tree, choose Compatibility Security—>Realms and click Realms.

4. In the right pane, select Configure a new Custom Realm link.

   The Configuration tab for the new realm is displayed.

5. Enter a name for the custom realm. For example, CUSTOMRealmForNetscapeDirSvr.

   Note: You can ignore the other tabs and attributes; the settings are not used.

6. Create the custom realm, as described in "Installing a Custom Security Realm" in Compatibility Security in the WebLogic Server Administration Console Online Help.

7. Click Create.

Configuring the Caching Realm

To configure the caching realm:

1. In the navigation tree, choose Compatibility Security—>Caching Realms—>wlpiCachingRealm.

2. Select the realm you created from the Basic Realm drop-down list.

3. In the right pane, select Configure a New Caching Realm.

4. Deselect the Case Sensitive Cache option.

5. Click Apply.

Enabling the WLPI Caching Realm

To enable the WLPI caching realm:

1. In the navigation tree, select Security.

2. Select the Filerealm tab.

   Note: If the following message is displayed, click Cancel to dismiss.

   Figure 3-9 Leaving the Page? Confirmation

   
    

3. Select wlpiCachingRealm from the Caching Realm drop-down list.

4. Click Apply.

Removing the RDBMS Realm

Note: This step is optional.

To remove the RDMBS realm:

1. In the navigation tree, choose Security—>Realms.

2. Click the garbage can icon to the right of wlpiRDBMSRealm.

Note: If you remove a RDBMS realm that is referenced by a Caching Realm, you might need to edit the config.xml file and modify the value of the CachingRealm's BasicRealm attribute to point to your new custom realm.

 

---

Updating Passwords

To ensure system security, update the default passwords listed in WebLogic Integration Users and Passwords, as described in the following procedures.

Warning: The wlisystem user name and password are stored in the WebLogic Integration repository and used in the WebLogic Integration run-time environment. This type of password must be updated using the B2B Console; do not use the WebLogic Server Administration Console for this purpose. If you modify the wlisystem password through the B2B Console, the password is updated in both the WebLogic Integration repository and the security realm.

Note: WebLogic Integration and WebLogic Server user names and passwords (users created using the WebLogic Integration Studio) can contain any character from the JDK-supported character sets, including international characters.

Updating the system Password

The password for the system login for the active domain can be changed through the WebLogic Server Administration Console, as described in the following procedure.

To change the password, complete the following procedure:

1. Start the WebLogic Server Administration Console, as described in Starting the WebLogic Server Administration Console.

2. Select Users from the navigation tree to open the Users page.

3. In the Change a User's Password section, enter, in the name field, the name of the user who owns the password you want to change.

   For example, to change the system password, enter system.

4. Enter the existing password in the Old Password field.

5. Enter the new password in the New Password field.

6. Retype the new password in the Confirm Password field.

7. Click Change to update the password.

8. Modify the password specified in the startWebLogic.cmd (Windows) or startWebLogic (UNIX) for the domain.

Warning: The startWeblogic.cmd (Windows) or startWeblogic (UNIX) command is configured for automatic login. If you change the password for system, you must modify the password specified in this file. See the sample startWebLogic file in WebLogic Integration Sample Configuration Files.

Updating the BPM Passwords

You can update the passwords for the BPM users admin, joe, mary, and any new users you create in the Studio application, through the WebLogic Server Administration Console, as described in the previous section.

Updating the wlisystem Password

The password for the wlisystem user can be changed only through the B2B Console, as described in the following procedure. Do not update this password from the WebLogic Server Administration Console.

To update the password for the wlisystem user:

1. Start the B2B Console, as described in Starting the B2B Console.

2. Select B2B from the navigation tree.

3. If it is not already selected, select the high-level Configuration tab, and then select the nested Security tab.

   The Security tab is displayed, as shown in the following figure. The content of the System Password field is the password for the wlisystem user.

   Figure 3-10 B2B Configuration Security Tab

   
    

4. To update the wlisystem password, highlight the current content of the System Password field, and then carefully type the new password over it.

5. Click Apply to update the wlisystem password.

   This procedure updates the wlisystem password in both the WebLogic Integration repository and the security realm.

 

---

Customizing Mail Session Properties

The mail session properties you specify when you use the Configuration Wizard to create a domain are used to set up a basic mail session configuration for the domain. You can modify the mail session configuration by updating existing settings, or by adding properties. The following procedure describes how to update the mail session properties for any domain.

To update the mail session properties for any domain, complete the following procedure:

1. Start the WebLogic Server Administration Console for the domain, as described in Starting WebLogic Integration.

2. Choose Services—>Mail—>wlpiMailSession. The wlpiMailSession Configuration tab is displayed, as shown in the following figure.

   Figure 3-11 wlpiMailSession Configuration Tab

   
    

3. Edit the contents of the Properties field as required.

   The following table provides descriptions of the properties that can be set.

   Table 3-10 Mail Session Properties  

   Property	Description
   mail.from	E-mail address from which e-mail is sent by a workflow.
   mail.host	Domain name of the mail or SMTP server.
   mail.sender	Name of the sender that appears in an e-mail when it is received. The default is WebLogic Integration.
   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.

   
    

4. Click Apply when your changes are complete.

 

---

Root Directory of a Domain

Some components of WebLogic Integration need access to particular files, such as the XML DTD, in the root directory. By default, the startWeblogic script for WebLogic Integration uses the home directory of the domain (DOMAIN_HOME) as the domain's root directory.

For example, suppose that, using the Configuration Wizard, you create a domain in c:/bea/user_projects/mydomain. That directory is now known as DOMAIN_HOME. The startWeblogic.cmd script, located in the DOMAIN_HOME directory, sets the root directory (also known as the run-time directory) to the same directory (c:/bea/user_projects/mydomain) using the weblogic.RootDirectory property.

 

---

Using an Alternate Character Set

If you are running WebLogic Integration in another locale, no special configuration is required, as long as your database, your operating system, WebLogic Integration, and the WebLogic Integration client applications (the Studio, Worklist, and Format Builder), are all running in the same locale.

The only change required after installation is to your B2B preferences. To enable the B2B Console to allow input from an alternate character set, you must verify that language and character set preferences are properly defined. For details about setting the language and the default character set for the language, see "Setting Preferences" in Configuring B2B Integration in the Online Help for the WebLogic Integration B2B Console.

 

---

Changing WebLogic Integration Port Numbers

Two WebLogic Integration instances running on a single machine cannot share the default port number (7001). If you are running two instances on one machine, you must change the port number used by one of them.

Warning: You may need to change parameters other than the WebLogic Server listen port number. For more information, see Table  3-11.

The following steps contain instructions for changing the WebLogic Integration port numbers in your application:

• Step 1. Change the WebLogic Server Listen Port Number

• Step 2. Changing Other WebLogic Integration Port Numbers

Step 1. Change the WebLogic Server Listen Port Number

The WebLogic Server listen port number specifies the dedicated TCP/IP port at which the server listens for connections. To change the listen port configured for a server, follow the steps in Changing the Listen Port from the WebLogic Server Administration Console or Changing the Listen Port by Editing the Configuration File.

Changing the Listen Port from the WebLogic Server Administration Console

To change the listen port from the WebLogic Server Administration Console:

1. Start the WebLogic Server Administration Console as described in Starting the WebLogic Server Administration Console.

2. In the navigation tree (in the left pane) of the WebLogic Server Administration Console, choose Servers—>myserver, where myserver is the name of the WebLogic Server with the listen port you want to change, as shown in the following figure.

   Figure 3-12 Choosing a Server

   
    

   The Configuration page for WebLogic Server is displayed, as shown in the following figure.

   Figure 3-13 WebLogic Server Administration Console Configuration Page

   
    

3. Enter the new port number in the Listen Port field, and then click Apply.

4. Restart the server to activate the new setting.

Warning: You must change the listen port using the WebLogic Server Administration Console. Do not change the port number using the B2B Console.

Changing the Listen Port by Editing the Configuration File

Note: Do not edit the config.xml file while the server is running. If the server is running, update the listen port as described in the preceding procedure.

To change the listen port by editing the config.xml file:

1. Open the administration server DOMAIN_HOME/config.xml file in your preferred text editor.

   Here DOMAIN_HOME is the complete path to the root of the domain (for example, the c:\bea\user_projects\domain directory).

2. In the config.xml file, locate the ListenPort setting for the server targeted for the listen port number change (shown in bold in Listing  3-5).

3. Set the ListenPort to a unique number that is not used by other WebLogic Server instances running on the same machine.

Listing 3-5 Changing the ListenPort Element in the config.xml File

<Server
 ListenPort="7001"
 Name="myserver"
  TransactionLogFilePrefix="c:\bea\weblogic700\samples/integration/config/samples/logs/"
 StdoutDebugEnabled="true"
 StdoutEnabled="true" 
 StdoutSeverityLevel="64" NativeIOEnabled="true">

Step 2. Changing Other WebLogic Integration Port Numbers

Which steps you must complete to update the remainder of the WebLogic Integration port numbers is determined by which features of WebLogic Integration are used in the application. To find out which steps are required to change the port number for your application, refer to the following table.

Table 3-11 Changing WebLogic Integration Port Numbers

If your application implements this WebLogic Integration functionality . . .	Complete the procedure in the following section . . .
B2B security	"Configuring the SSL Protocol and Mutual Authentication" in "Configuring Security" in Implementing Security with B2B Integration
Application integration	Changing the Application View Console Port Number
B2B engine	Changing B2B URI Endpoints
B2B Administration Console	Changing the B2B Console Port Number
Application intergration, B2B, or BPM	Changing the WebLogic Integration Shutdown Scripts

 

Warning: The samples contain many files in which the port number is set. To avoid introducing errors, we recommend that you do not change the default port number in the samples.

Changing B2B URI Endpoints

A WebLogic Integration URI endpoint specifies the location at which a trading partner listens for a B2B message. If you have already changed the listen port for your WebLogic Server, as described in Step 1. Change the WebLogic Server Listen Port Number, and you are using WebLogic Integration B2B functionality, you must change the URI Endpoints for your B2B trading partners.

To change the port number in the URI Endpoint:

1. Start the B2B Console, as described in Starting the B2B Console.

2. In the navigation tree (in the left pane) of the B2B Console, choose B2B—>Trading Partners.

3. From the list shown in the right pane, select a trading partner that is involved in your WebLogic Integration application.

4. In the right pane, click the URI, update the port number, and then click Add/Apply. Repeat this step for all URIs in the chain.

5. Repeat steps 2-4 for all trading partners that are configured.

Warning: URI endpoints are also specified in the Bulk Loader repository data file. If you change the port number in the URI endpoint in the repository and you want your Bulk Loader repository to reflect that change, make sure you export the current repository information using the B2B Console or the command-line Bulk Loader. For more information, see "Importing and Exporting B2B Integration Components" in Administering B2B Integration.

Changing the Application View Console Port Number

If you have changed the listen port for your WebLogic Server, as described in Changing B2B URI Endpoints, and you are using the WebLogic Integration Application View Console, you must update the port number specified in the startAIconsole command.

To update the port number specified in the startAIconsole command:

1. In your preferred text editor, open the appropriate command file: WLI_HOME/bin/startAiconsole.cmd (Windows) or WLI_HOME/bin/startAIconsole.sh (UNIX).

2. Set the port number to the value you assigned when updating the listen port for the server.

3. Save the file.

Changing the B2B Console Port Number

If you have changed the listen port for WebLogic Server, as described in Changing B2B URI Endpoints, and you are using the WebLogic Integration B2B Console, you must update the port number specified in the startB2Bconsole command.

To update the port number specified in the startB2Bconsole command:

1. In your preferred text editor, open the appropriate command file: WLI_HOME/startB2bconsole.cmd (Windows) or WLI_HOME/startB2bconsole.sh (UNIX.

2. Set the port number to the value you assigned when updating the listen port for the server.

3. Save the file.

Changing the WebLogic Integration Shutdown Scripts

If you have changed the listen port for WebLogic Server, as described in Changing B2B URI Endpoints, you must change the port number in the shutdown script for the server.

To change the port number in a shutdown script:

1. In your preferred text editor, open the file for the appropriate server shutdown command: DOMAIN_HOME\stopWeblogic.cmd (Windows) or DOMAIN_HOME/stopWeblogic.cmd (UNIX).

   For example, if you are defining a server port number for a domain called mydomain in the c:\bea\user_projects directory, open the c:\bea\user_projects\mydomain\stopWebLogic.cmd file.

2. Set the port number to the value you set when updating the listen port for the server.

3. Save the file.

 

---

Deploying B2B Without Persistence

By default, WebLogic Integration is deployed in persistence mode, which means that WebLogic Integration can recover in the event of hardware or network failures. For more information about the benefits of deploying WebLogic Integration in persistence mode, see "What to Expect from WebLogic Integration Recovery" in Understanding WebLogic Integration High Availability in Deploying BEA WebLogic Integration Solutions.

The ability to turn off persistence is supported only for the B2B functionality provided by WebLogic Integration. Persistence is turned off using the WebLogic Server Administration console. For more information, see Configuring Persistence and Recovery in Administering B2B Integration.