Creating New Server Environments

 

A server environment is a set of configuration parameters and files that can be used to run a WebLogic Server instance. A BEA WebLogic Application Integration (hereafter referred to as Application Integration) server environment is a specific type of server environment that allows you to run an Application Integration server. When you have completed the initial installation of BEA WebLogic Application Integration, you can tailor a server environment to the needs of your existing or future integration solutions, or to a group of users that will be using the server, or both.

For example, after getting familiar with Application Integration by using the demonstration environment setup for you during installation, you may wish to create an environment for the development of your own integration solutions or adapters. You may also want to use a database other than the demonstration Cloudscape database (For example, MS SQL Server or Oracle).

You might also wish to configure the plug-in to run in a selected domain, designate or create a new domain in which Application Integration can run, or deploy the sample adapters to a specific domain. You can create such an environment, or any other environment you choose, by running the setup utility provided in <WLI_HOME>/applinteg/engine/config.

This section provides information on the following subjects:

• Preparing to Customize Your Server Environment

• Accessing the Setup Utility

• Creating a New Domain

• Changing Database Information

  • Step 1: Create Tables for the Database

  • Step 2: Run the Setup Utility to Change Database Information

• Rerunning the Setup Utility to Deploy Adapters

• Configuring the Plug-In to Run in a Selected Domain

  • Running the Setup Utility to Configure the Plug-In in a New Domain

  • Starting WebLogic Process Integrator with the Application Integration Plug-in

  • Verifying the Deployment of BEA WebLogic Application Integration and the Plug-In

 

---

Preparing to Customize Your Server Environment

Before you create a new server environment, you should decide what your requirements are for the environment. For example, what type of database will you use for the Application Integration repository? What adapters do you wish to use in this environment? The worksheet in Table 3-1 is provided for you to record your choices for some of the parameters that will be required when creating a new environment.

Table 3-1 System Environment Setup Worksheet

Parameter Name	Instructions for Changing this Parameter	Your Parameter
Domain	This should be the name of a WebLogic Server domain configuration directory (usually under the WebLogic Server home directory, or the Application Integration home directory). This domain may already exist, or be a non-existent domain. If no domain of the given name exists, the setup utility will create a new domain with the given name using an existing template. You will be asked to choose an existing domain to act as this template. Write down the domain name, and template domain (if any) in the `Your Parameter' column. Refer to Creating a New Domain.
Database Type	The type of database to use for the Application Integration repository. You must have installed a JDBC driver for the chosen database type. Make sure you know the JDBC driver's class name, and how to format a JDBC URL for this driver. Write down the database type and JDBC driver's class name in the `Your Parameter' column. See WebLogic JDBC documents or the documents from your database vendor for more information. Refer to Changing Database Information.
Database Instance	Pick a database instance to use for the repository and DBMS adapter. Make sure you know how to format a JDBC URL that refers to this database instance. Write down the JDBC URL for your database in the `Your Parameter' column. See WebLogic JDBC documents or the documents from your database vendor for more information. Refer to Changing Database Information.
Database User Name and Password	Pick a valid user for the designated database instance. This user should have permission to select, insert, update, and delete against tables making up the WebLogic Integration repository. If you will be using the DBMS adapter, it is recommended that this user also have "create" privileges in the designated database instance. Enter the user name and password for the user in the "Your Parameter" column.
Database Connection Properties	Enter the JDBC connection properties needed to make JDBC connections to the database instance you designated above. In most cases, these include the user name and password you entered above. However, connection properties are specific to the JDBC driver you use, so consult your database documentation for more information.
Adapters to be Deployed	Application Integration comes with DBMS, E-mail, and Sample adapters. The DBMS and E-mail adapters may be installed automatically by the setup utility. You should decide which (if any) of these adapters you wish to have deployed in the new environment. Refer to Rerunning the Setup Utility to Deploy Adapters.

 

---

Accessing the Setup Utility

The setup utility is a command-line interactive utility for configuring a new BEA WebLogic Application Integration server environment or reconfiguring an existing Application Integration server environment. You can run the setup utility repeatedly against the same server environment to make incremental changes to the environment's configuration.

Each time you run the setup utility, your responses are saved for future use. When you run the setup utility, it will check to see if a set of saved responses already exists. If so, it will allow you to reuse your previous responses as the default responses for the current session. This way, you can repeatedly run the setup utility, changing only those responses necessary to achieve incremental configuration changes desired.

Note: Often, you will see the term "server environment" referred to simply as "domain" because the domain directory generally contains all the configuration information for the server environment.

To run the setup utility

1. Open a command prompt window and `cd' to the directory into which Application Integration was installed (e.g. d:/bea/wlintegration2.0). This directory is hereafter referred to as <WLI_HOME>.

2. Change to the config directory by entering cd/applinteg/engine/config.

3. Copy the setupEnv.example.cmd for Windows or setupEnv.example.sh for UNIX and rename it to setupEnv.cmd for Windows and setupEnv.sh for UNIX.

4. Open this script in a text editor such as Notepad (for Windows).

5. Make sure the variables in setupEnv are set correctly.

   Note: For a complete step-by-step description of the setup utility, see The Setup Utility.

   BEA_HOME=@BEA_HOME

   WL_HOME=@WL_HOME

   WLAI_HOME=@WLAI_HOME

6. Save the script and exit back to the command prompt or shell.

 

---

Creating a New Domain

You may wish to create a new domain for a special project such as developing an adapter or testing a certain integration solution. The setup utility simplifies the process of creating a new domain. The setup utility supports the following scenarios for creating a new domain:

• Creating a domain that is an exact replica of an existing domain.

• Creating a domain that is an extension/modification of an existing domain.

To create a new domain that is an exact replica of an existing domain (that uses the same database instance for the repository) complete the following steps:

1. Run the setup utility as described in Accessing the Setup Utility. When "Use previous responses" displays, enter "Y".

2. When prompted for domain name, enter a new domain name. You will be prompted to give the name of an existing domain to "clone". Enter the name of the domain that will act as the source for cloning. This step will copy the entire domain directory, and rename it to the new name.

3. Accept the database type default value.

4. If the database type is Cloudscape, enter "N" when asked if you want to reinitialize the database. This will preserve the existing repository contents.

5. Accept all defaults after this point. These defaults will be the responses you gave in the previous run of the setup utility.

To create a new domain that is an extension/modification of an existing domain, complete the following steps:

1. Run the setup utility as described in Accessing the Setup Utility. When "Use previous responses" displays, enter "N".

2. When prompted for domain name, enter a new domain name. You will be prompted to enter the name of an existing domain to "clone". Enter the name of the domain that will act as the source for cloning. This step will copy the entire domain directory, and rename it to the new name.

3. From this point on, you may override any default values. Change the responses that affect the configuration you want to change in the new domain. Accept the default responses that affect the configuration you want to keep from the old domain.

4. For more information on changing specific types of setup information, see Accessing the Setup Utility.

 

---

Changing Database Information

If you selected either Oracle or MS SQL Server for your custom domain during the installation process (see, Step 5: Selecting the Database for the Custom Domain), you must create the tables required by Application Integration on the database server before starting Application Integration from that domain. Scripts have been provided which automate the table creation process. After you have run the correct database scripts, you must rerun the The setup utility to change database information in an existing domain.

To change database information:

• Step 1: Create Tables for the Database

• Step 2: Run the Setup Utility to Change Database Information

Step 1: Create Tables for the Database

Table 3-2 summarizes the location of the scripts used to create the tables required by Application Integration. Each directory in Table 3-2 contains the following SQL script. The scripts are specific to database type.

For Windows, run createDB.cmd

For UNIX, run createDB.sh

This script is used to create the common tables used by all WebLogic Integration components. Because all WebLogic Integration components are configured to use the same database, this script is run only for the first WebLogic Integration component installed. If this script has already been run for another component, there is no need to run it again for Application Integration.

Note: If you selected Cloudscape for the custom domain, the tables required have already been created. The scripts used and the procedure required to manually create the tables in Cloudscape have been documented in Table 3-2 for informational purposes only.

Table 3-2 Table Creation Scripts

To create tables for this database...	Use the files in this directory...
Oracle 8.1.6	<WLI_HOME>/applinteg/repository/oracle
Microsoft SQL Server 7.0	<WLI_HOME>/applinteg/repository/mssql
Cloudscape 3.5.x	<WLI_HOME>/applinteg/repository/cloudscape

Step 2: Run the Setup Utility to Change Database Information

This section describes how to change database information in an existing domain. Database information includes, database type, JDBC driver class name, JDBC URL for designating the database instance, and JDBC DataSource name for managing connections to the database instance.

Note: This section assumes that you are configuring an environment that uses only BEA WebLogic Application Integration. If you are using other BEA WebLogic Integration components, such as BEA WebLogic Process Integrator to run the plug-in, see Running the Setup Utility to Configure the Plug-In in a New Domain.

The database may be used for any purpose within your Application Integration server environment. The main purposes for the database are the BEA WebLogic Integration repository and the DBMS sample adapter. For detailed steps for running the setup utility, see The Setup Utility.

To change just the database information for a domain:

1. Run the setup utility as described in Accessing the Setup Utility.

2. When "Use previous responses" displays, enter yes or no.

3. Accept all defaults except where noted.

4. At the "Database Name" prompt, enter the name of the database to use. This is the database instance that contains (or will contain) the WebLogic Integration repository tables. If you are using MS SQL Server, enter the name of the MS SQL Server database. For Oracle, enter the network alias for the Oracle server. For Cloudscape, enter the Cloudscape database name listed under the Cloudscape system home data directory.

   Note: Before the Application Integration server can be started, the database designated at this prompt must exist and the repository tables must be installed. If you choose Cloudscape as the database type, the setup utility can create the database and install the repository tables for you. For all other database types, you must create the database and install the repository tables using the SQL DDL scripts that are provided in <WLI_HOME>/applinteg/repository/<db type> directory. For an example of the scripts that are provided, see Table 3-2.

5. Choose whether or not to use Cloudscape as your database type. If you wish to use Cloudscape for the database, enter yes. Otherwise, enter no.

6. If you picked Cloudscape, you will be asked if you wish to install/reinstall the repository into the designated database. Entering yes will destroy any existing repository information and leave the repository in a "clean" state. Entering no will leave the repository tables untouched. In most cases, you can enter no and keep your existing information.

7. At the "Data Source: JDBC Data Source JNDI Name" prompt, enter the name that will be used for a JDBC data source representing the JDBC pool you have just configured. This data source provides convenient access to the pool. In most cases, you can accept the default value.

8. At the "JDBC Pool: Driver Name" prompt, enter the class name of the JDBC driver for your database type. You should have collected this information in the "Server Environment Setup Worksheet". The setup utility gives some examples of JDBC driver class names for various database types. At the "JDBC Pool: URL" prompt, enter the JDBC URL for the database instance you designated above. You should have collected this information in the Preparing to Customize Your Server Environment. The setup utility gives some examples of JDBC URLs for various database types.

9. At the "JDBC Pool: User Name" prompt, enter the database user name to use when connecting to the database instance you designated above. You should have collected this information in the Preparing to Customize Your Server Environment.

10. At the "JDBC Pool: Password" prompt, enter the password for the database user name to use when connecting to the database instance you designated above. You should have collected this information in the Preparing to Customize Your Server Environment.

11. At the "JDBC Pool: Connection Properties" prompt, enter the database connection properties needed to make connections to the database instance you specified above. In most cases, you can accept the default value, which includes the user name and password you entered above. You should have collected this information in Preparing to Customize Your Server Environment.

12. At the "JDBC Pool: Initial Capacity" prompt, enter the number of connections that should be created when this pool is created. This number also serves as the minimum number of connections to be maintained in the pool.

13. At the "JDBC Pool: Maximum Capacity" prompt, enter the maximum number of connections to be maintained in the pool.

After completing these steps, the domain is configured to use the designated database instance for the WebLogic Integration repository and any other database related work. If you choose to deploy the DBMS adapter, you will need to verify that its event router also points to the proper database instance. See Rerunning the Setup Utility to Deploy Adapters for more information.

 

---

Rerunning the Setup Utility to Deploy Adapters

The Setup Utility allows you to deploy the DBMS adapter and the E-mail adapter. To deploy either adapter, complete the following steps. For detailed steps for running the setup utility, see The Setup Utility.

1. Run the setup utility as described in Accessing the Setup Utility. When "Use previous responses" displays, enter yes or no.

2. When asked if you want to deploy the given adapter, enter yes. Adapter specific configuration information is required when deploying an adapter. The setup utility prompts you for any required information.

For custom-developed adapters, see the BEA WebLogic Application Integration Adapter Development Guide for information on how to deploy the adapter.

This section provides information on the following subjects:

• Deploying the DBMS Adapter

• Deploying the E-mail Adapter

Deploying the DBMS Adapter

For the DBMS adapter event router, you may want to use the same database instance that you configured for the WebLogic Integration repository. This information will be displayed as the default values in the prompts displayed during the DBMS adapter deployment. To choose another database, specify the information for the new database. Use the worksheet in Preparing to Customize Your Server Environment as a guide in determining the required information for the database instance you will use with the DBMS adapter.

To deploy the DBMS adapter, complete the following steps.

1. Run the setup utility as described in Accessing the Setup Utility. When "Use previous responses" displays, enter "N".

2. Accept all defaults except where noted.

3. A "Deploy DBMS Adapter:" prompt displays. For first-time installs, accept the default. This will configure the DBMS Adapter with the information you have provided in previous prompts, and it will deploy the DBMS adapter to the Application Integration domain/server. For subsequent runs of the setup utility, you can bypass this step by entering no. Any previous deployment of the DBMS adapter is left intact. If you asked to deploy the DBMS Adapter, it is configured and deployed. In order to configure the event router for the DBMS adapter, you are asked to supply some information.

4. A "DBMS Adapter: DB User Name (EventRouter):" prompt displays. The default value is the user name you entered and should be good enough. If the specified user name is not allowed to execute DDL statements in the database, you may wish to enter the name of a user that is allowed to execute DDL.

5. A "DBMS Adapter: DB Password (EventRouter):" prompt displays. The default value is the password you entered above. If you changed the user name in the "DBMS Adapter: DB User Name (EventRouter):" prompt, you must change this password to be the password for the new user name.

6. A "DBMS Adapter: Catalog (EventRouter):" prompt displays. If you chose Cloudscape in the "Database Type" prompt, accept the default for Cloudscape because you must enter the name of the catalog into the "special" event tables for which the DBMS adapter were installed. This value varies by database type, so consult your database documentation. Some suggestions of possible catalog names are displayed.

7. A "DBMS Adapter: Schema (EventRouter):" prompt displays. If you chose Cloudscape at the "Database Type" prompt, accept the default for Cloudscape because you must enter the name of the schema into which the "special" event tables for the DBMS adapter were installed. This value varies by database type, so consult your database documentation. Some suggestions of possible schema names are displayed.

8. A "DBMS Adapter: Ping Table:" prompt displays. If you chose Cloudscape at the "Database Type" prompt, accept the default for Cloudscape because you must enter the fully qualified name of the table that the event router will select against to verify a live connection to the database. The default value given is constructed from your input values, and should be correct in most cases. However, the tables in any given database and their qualified names vary by database type, so consult your database documentation.

9. If you chose Cloudscape at the "Database Type" prompt, the SQL scripts for DBMS adapter-specific resources are executed to set up the proper resources in the Cloudscape database. You will see a large amount of text output as these scripts are executed. As in the main database the setup utility performed earlier, for first time setups, errors may be displayed in the output when "drop" statements are executed. This is normal. If you did not choose Cloudscape as your database type, no SQL scripts are executed.

10. Complete the rest of the setup as described in Accessing the Setup Utility.

To use the DBMS Adapter, you need to modify the startWebLogic.cmd file.

1. Open Notepad or another text editor.

2. Open startWebLogic.cmd located in the domain that you created to host BEA WebLogic Application Integration.

3. Change the port value to the port value you entered during setup (the default is 7001).

4. Save the file.

Deploying the E-mail Adapter

To deploy the E-mail adapter, complete the following steps.

1. Run the setup utility as described in Accessing the Setup Utility. When "Use previous responses" displays, enter yes or no.

2. Accept all defaults except where noted.

3. You are asked if you want to deploy the E-mail adapter. Enter "Y" to deploy the adapter.

4. An "Email User Name" prompt displays. Enter the name of the email user. The default user name is "Joe".

5. An "Email Password" prompt displays. Enter the password for the email account. The default password is "joepassword".

6. An "Email Server" prompt displays. Enter the address of the email server. The default is "joeisp.com".

7. An "Email Poll Interval" prompt displays. Enter the length of time the router should wait when checking for new email (in milliseconds). The default is "10000".

 

---

Configuring the Plug-In to Run in a Selected Domain

The initial installation process configures the plug-in in mydomain only if BEA WebLogic Process Integrator was installed prior to BEA WebLogic Application Integration. If you want to configure the plug-in in any other domain, or BEA WebLogic Process Integrator was not installed before BEA WebLogic Application Integration, you must run the setup utility to configure the plug-in in the new domain. You will need to manually create the tables for the Plug-In by submitting the DDL script matching your database found in:

<WLI_HOME>/processintegrator/ddl

Before running the setup utility, you must ensure that BEA WebLogic Process Integrator is configured in the new domain. Typically the new domain will be the domain for either WebLogic Process Integrator and WebLogic Collaborate (samples or mydomain).

This section provides information on the following subjects:

• Running the Setup Utility to Configure the Plug-In in a New Domain

• Starting WebLogic Process Integrator with the Application Integration Plug-in

• Verifying the Deployment of BEA WebLogic Application Integration and the Plug-In

Running the Setup Utility to Configure the Plug-In in a New Domain

To configure the plug-in in a new domain, complete the following steps. For detailed steps for running the setup utility, see The Setup Utility.

1. Run the setup utility as described in Accessing the Setup Utility. When "Use previous responses" displays, enter yes or no.

2. When prompted for a directory for your domain, enter the directory where the new domain resides.

3. When prompted for domain name, enter the new domain name.

4. When prompted for database name, enter the name of the database for which BEA WebLogic Process Integrator has been configured.

5. If this database is Cloudscape, enter yes if BEA Process Integrator is configured for Cloudscape. Otherwise, enter no.

6. An "Initialize/Reinitialize" prompt displays. Respond yes if you wish to start from scratch with clean BEA WebLogic Application Integration tables and a clean repository.

7. Continue to follow the prompts for Host Name, Port Number, User Name, and Password that are appropriate for the new domain.

   Note: Remember to use the password appropriate for your domain (for example, <WLPI_HOME>\config\mydomain. The password is `security'. In the <WLI_HOME>\applinteg\config\mydomain, the password is `system'.

8. A"Data Source:" prompt displays. For first time installs, accept the default. Otherwise, enter the JNDI name of the repository data source. This must be a valid JNDI name. In general, the default value is good enough. If this is a subsequent run of the setup utility, you may wish to include the database type in the data source name.

   Note: This is NOT the BEA WebLogic Process Integrator data source. It is the data source used by BEA WebLogic Application Integration.

9. Continue through the prompts to deploy the desired adapters.

10. You will be prompted for a directory in which Process Integrator is installed. This script then copies the appropriate configuration scripts into the Process Integration installation directory.

11. An "Update config.xml:" prompt displays. Accept the default response (yes). This will update your config.xml, preserving any prior information in it but merging the information you provided into it. If you really don't want to update config.xml, respond no, and a config.xml.wlai file will be written instead. You can manually merge the config.xml and config.xml.wlai files in this case.

12. The setup utility writes some final configuration files and exits.

Starting WebLogic Process Integrator with the Application Integration Plug-in

To start WebLogic Process Integrator with the Application Integration plug-in follow these steps:

1. Open an MS-DOS prompt session or UNIX shell.

2. Change the working directory to <WLPI_HOME>\config\<DOMAIN>.

3. For Windows, enter startWLPIwithWLAI.cmd. For UNIX, enter startWLPIwithWLAI.sh.

Note: If the plug-in was configured into mydomain during installation, you must run startWebLogic instead of startWLPIwithWLAI.

Note: Remember to use the password appropriate for your domain (for example, <WLPI_HOME>\config\mydomain. The password is `security'. In the <WLI_HOME>\applinteg\config\mydomain, the password is `system'.

Verifying the Deployment of BEA WebLogic Application Integration and the Plug-In

After you have installed BEA WebLogic Application Integration or the BEA WebLogic Application Integration plug-in for BEA WebLogic Process Integrator, you can check to make sure they are correctly deployed:

1. Open a browser.

2. In the Location or Address field, enter http://localhost:7601/console. This opens the WebLogic Server console.

3. Choose Deployments —> Web Applications.

4. Verify that the BEA WebLogic Application Integration plug-in for Process Integrator has been deployed.

5. Choose Deployments —> EJB

6. Verify that wlai-ejb-server and wlaiplugin-ejb.jar have been deployed.

7. Choose Deployments —> Startup&Shutdown.

8. Verify that TimeProcessor, WLAI_StartupClass, and WLPIInit have been deployed.

9. Choose Deployments —> Applications.

10. Verify that WLPI Application has been deployed.