Installing and Configuring Rational RequisiteWeb

Copyright © 1998-2000 Rational Software Corporation. All Rights Reserved.

Rational, the Rational logo, Rational Rose, Requisite, RequisitePro, SoDA, ClearQuest and ClearCase are trademarks or registered trademarks of Rational Software Corporation in the United States and in other countries.

Microsoft, Windows, Windows NT, and Visual Basic are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The Tomcat software, which is distributed with Rational RequisiteWeb, is protected by the Apache Software License, Version 1.1, which is included in the top level of your jakarta-tomcat directory after installation. Copyright © 1999 The Apache Software Foundation. All rights reserved.

J-Integra is a trademark of Linar Limited. Sun, Sun Microsystems, Solaris, Java, JavaServer Web Development Kit, and JavaServer Pages are trademarks or registered trademarks of Sun Microsystems, Inc. UNIX is a registered trademark in the United States and other countries, exclusively licensed through X/Open Company, Ltd.

All other names are used for identification purposes only and are trademarks or registered trademarks of their respective companies.

Introduction

Rational RequisiteWeb allows clients to read, create, and modify Rational RequisitePro project requirements across an intranet. By utilizing browsers - Netscape Navigator or Microsoft Internet Explorer - RequisiteWeb provides platform-independent, thin-client access to RequisitePro project data.

This document contains the following sections:

RequisiteWeb System Requirements

Server Requirements

The following table summarizes the requirements for the RequisiteWeb server.


Item Web Server Requirements Server or Single Server
Operating System/
 Sun Microsystems Solaris 8

Red Hat Linux
One of the following:
  • Microsoft Windows 2000 Advanced Server
  • NT Server 4.0, Service Pack 6A or later; NT 4.0 Option Pack
HTTP Server
Apache Web Server

Note: SSL is not supported by RequisiteWeb.
One of the following:
  • Internet Information Server (IIS) 4.0 and Microsoft Transaction Server (MTS) 2.0
  • Internet Information Services (IIS) 5.0
Note: SSL is not supported by RequisiteWeb.
Processor Intel processor: 400 MHz or greater

For the Solaris OS: Sun SPARCstation		 400 MHz or greater
Memory 128 MB 128 MB. For projects with more than 10,000 requirements or Web sites with more than 10 concurrent users, 256 MB or more is recommended.
Disk space JSPs, Web DLLs, bitmaps -- 2 MB RequisiteWeb (includes system DLLs) -- 40 MB
Other products Sun Microsystems Java Development Kit (JDK 1.2.2)

ANSI-C compiler such as GNU's gcc package
  • WinZip utility.
  • Microsoft Word 2000
    Note: Microsoft Word licenses are required for all RequisiteWeb end users.
  • Oracle, version 7.3 or greater, client software (for accessing projects in an Oracle database).
  • Microsoft Internet Explorer 5,
    or Internet Explorer 4 with the XML parser available on the World Wide Web at msdn.microsoft.com/downloads/tools/xmlparser/xmldl.asp
  • Sun Microsystems Java Development Kit (JDK 1.2.2)

RequisiteWeb Security Requirements

After you have installed RequisiteWeb, you may need to alter security permissions on your server for reasons unrelated to RequisiteWeb. Use caution when modifying permissions on RequisiteWeb-related folders. For more information, see Editing the RequisiteWeb Configuration File and Configuring the RequisiteWeb Requirements Server.

Client Requirements

To access RequisiteWeb from client machines, you must install one of the following Web browsers on the client system. No additional client installation is required for use of RequisiteWeb.

Note: For proper RequisiteWeb operation, you must set your browser to allow cookies.

Key Components Overview

The following sections describe key components in the RequisiteWeb installation. They include components on both the Web server and the Requirements server.

Java Development Kit

The Sun Microsystems Java Development Kit (JDK) is a development and deployment environment that includes key components for your RequisiteWeb implementation. The Java Runtime Environment (JRE) contain binary libraries required for the execution of Java scripts and servlets. The Java Virtual Machine (JVM) interprets and implements the Java programming language in the Web server configuration.

Tomcat Servlet Engine

Tomcat is an implementation of the Java Servlet 2.2 and Java Server Pages (JSP) 1.2 Specifications. Tomcat is produced by the Jakarta Project, which is composed of members of the Apache Jserv Project, engineers from major corporations such as Sun and IBM, newer companies like Exoffice, and individual developers.

Tomcat is a servlet container with a JSP environment. A servlet container is a runtime shell that manages and invokes servlets on behalf of users. As an in-process servlet container, Tomcat is a combination of a Web server plugin and a Java container implementation. The Web server plugin opens a Java Virtual Machine (JVM) inside the Web server's address space and lets the Java container run in it. If there is a request to execute a servlet, the plugin takes control of the request and passes it to the Java container.

Note: This document assumes that you have not installed Tomcat on your server. If you are already running Tomcat, verify that you have version 3.1. If this is the case, note the path of your current Tomcat installation, and skip the Tomcat installation procedure in this document.

Microsoft Word 2000

In order to access RequisitePro requirements documents in RequisiteWeb, Microsoft Word 2000 must be installed on the single RequisiteWeb Server, as described in Single-Server Configuration Overview; or, when configuring an Apache Web server, Word must be installed on the Requirements server, as described in Dual-Server Configuration Overview. For Microsoft Word version information, see RequisiteWeb System Requirements.

Note: If you upgrade from Word 97 to Word 2000 on your RequisiteWeb Requirements server, be sure to delete the contents of the directory C:\Inetpub\wwwroot\ReqWebDoc\GenDoc before attempting to view documents in RequisiteWeb.

Single-Server Configuration Overview

When running Microsoft Internet Information Server (IIS), version 4 or 5, as your Web server, you can configure your entire RequisiteWeb implementation on a single server. This implementation requires the use of Windows NT 4.0 or Windows 2000 Server as your operating system.

The single RequisiteWeb Requirements server configuration requires the installation of the components described in Key Components Overview. In addition, it includes the RequisiteWeb components: RequisitePro Extensibility Interface (RPX), RequisiteWeb JSP and HTML files, a RequisitePro project catalog file, Microsoft Word, and access to a project database. The following figure shows the single-server configuration:


Note: The single-server configuration cannot be implemented on a Primary Domain Controller or Backup Domain Controller, because RequisiteWeb uses a local user to generate documents.

For instructions on configuring the single server, see Setting Up the Single-Server Configuration.

Dual-Server Configuration Overview

When using Linux or Sun Microsystems Solaris for the operating system on your Web server, you must configure RequisiteWeb on two servers:

The following diagram presents key components of the RequisiteWeb installation on two servers:


For instructions on implementing the dual-server configuration, see Setting Up the Dual-Server Configuration.

RequisitePro Proxy

RequisitePro Proxy is an executable file that is installed on the Requirements server with the other RequisiteWeb components. It receives requests from DCOM and instantiates the required RequisiteWeb component, such as the Requisite Extensibility Interface (RPX), the RequisitePro project catalog, and Microsoft Word. Proxy passes requests to the active component and processes the returned data collection, passing the data back to DCOM.

You will configure the Proxy Connector class (RqProxy.Connector) in Microsoft DCOM to assign proper permissions to the RequisiteWeb user (ReqWeb_RPXUser).

Configuring the RequisiteWeb Requirements Server

Note: Unless otherwise indicated, this entire section applies to both single-server and dual-server RequisiteWeb configurations.

These instructions assume that you have installed the Microsoft Internet Information Server (IIS) on your RequisiteWeb Requirements server and that it is running. For more information on IIS, see Microsoft Servers at www.microsoft.com/servers.

This section describes installation and configuration of the RequisiteWeb components on the Requirements server. Details for the following procedures are provided:

Installing RequisiteWeb on the Requirements Server

Note: For current RequisiteWeb users, be sure to uninstall any earlier version of RequisiteWeb prior to installing the current release of RequisiteWeb on your server. Do not remove your ReqWeb virtual directory; instead, redirect it to the components in your new RequisiteWeb installation. Refer to Removing RequisiteWeb for specific instructions. Be sure to retain your existing catalog.txt file.

Note: To install RequisiteWeb, you must have a Rational license key. You can acquire and import the Rational license keys before or after installing Rational RequisitePro. See the Administering Licenses for Rational Software manual for more information about licenses, including the procedure for obtaining a license key. If you install RequisiteWeb as part of a Rational Suite, you must select the appropriate Suite license usage order. In the Rational License Administrator, click Settings > License Usage Mapper.

  1. Log on to the RequisiteWeb Requirements server as an administrator.
  2. Insert the Rational Solutions for Windows CD into your system's CD drive. The setup program starts automatically. If autorun is disabled on your system, click Start > Run. Using the drive letter of your CD-ROM drive, enter drive:\SETUP.EXE.
  3. The Rational Software Setup wizard guides you through the software installation. On each screen, click the Next button to proceed to the next screen. The Rational Software Setup program writes a log of the installation activities. The log file is located, by default, in C:\Program Files\Rational\RSSetup\RSSetup.log
  4. At the Choose Product screen, select Rational RequisitePro on the drop-down list.
  5. At the Setup Configuration screen, click Custom/Full.
    Note: If your database server is running on an international operating system, be sure that the install path does not include folders with double-byte character names.
  6. At the Choose Features screen, select the Web Server Components check box.
  7. Select or clear the following optional check boxes:
    • If you plan to use this machine for creating and managing RequisitePro projects, leave the RequisitePro check box selected. If you plan to use this machine only for hosting RequisiteWeb, you can clear it.
    • Leave the Rational Synchronizer check box unmarked.
    • The Sample Projects option, under the expanded RequisitePro options, allows you to include the RequisitePro Learning Project and QuarterByte Bank example projects. These projects are helpful for testing and learning RequisiteWeb.
    • The Oracle Setup and SQL Server Setup options are required for database administrators who are configuring Oracle or SQL Server databases for RequisitePro projects.

Possible Reboot Required

If files that are required for the installation are in use during the installation procedure, the Rational Windows Setup program may require that you reboot your system to complete the installation.

After rebooting, log on as the same user to complete the installation procedure.

Creating the RequisiteWeb Users

RequisiteWeb requires that you create two administrative users:

Creating the RPX User on the Domain Server

Note: Be sure to log on to your domain server as an administrator for the following procedure.

Create the ReqWeb_RPXUser as a domain user on your domain server.


Step NT 4.0 Windows 2000 Server
1 On the domain server, click Start > Programs > Administrative Tools (Common) > User Manager for Domain. On the domain server, click Start > Programs > Administrative Tools > Computer Management.
2 Click User > New User. Expand Domain Users and Groups. Right-click on Users; select New User.
3 In the Username field, type ReqWeb_RPXUser
and enter a password of your choice.		 In the Username field, type ReqWeb_RPXUser
and enter a password of your choice.
4 Clear the check box User must change password at next login and select the check box Password never expires. Click Add; click Close. Clear the check box User must change password at next login and select the check box Password never expires. Click Create; click Close.
5 Close the User Manager application. Close the Computer Management application.

Adding the RPX User to the Requirements Server Administrators

Note: Be sure to log on to your RequisiteWeb Requirements server as an administrator for the following procedure.

Add the ReqWeb_RPXUser user to the Administrators group on your RequisiteWeb Requirements server.


Step NT 4.0 Windows 2000 Server
1 On the Requirements server, click Start > Programs > Administrative Tools > User Manager. On the Requirements server, click Start > Programs > Administrative Tools > Computer Management.
2 Click User > Select Domain and select your domain server. Expand Local Users and Groups. Select Groups. Right-click Administrators and select Add to Group. In the Administrators Properties dialog box, click Add.
3 Select the ReqWeb_RPXUser and click User > Properties. At the Look in field, select the domain.
4 Click Groups, and add the Administrators group to the Member of list. Click OK. Select the ReqWeb_RPXUser and click Add. Click OK.
5 Close the User Manager application. Close the Computer Management application.


Note: If any of your RequisitePro projects are located on a server other than the RequisiteWeb Requirements server, the ReqWeb_RPXUser must have Change or Modify permission for the directory containing the RequisitePro .rqs project file on the remote project server. For more information, see Managing RequisitePro Projects for RequisiteWeb.

Assigning DCOM Permissions for the RPX User

Note: If you are implementing a single-server configuration of RequisiteWeb, skip to Creating the Word User.

In this procedure, you set appropriate permissions in Microsoft Distributed COM (DCOM) for the RequisiteWeb in-process object server user (ReqWeb_RPXUser) to ensure necessary access to RequisitePro components and project databases. Specifically, you will allow this user access to the RequisiteWeb Proxy executable, which is required for processing RequisitePro project information on the Requirements server.

Use DCOM to give the ReqWeb_RPXUser user access, launch, and read permissions for RQProxy.Connector. Set the identity to the ReqWeb_RPXUser user. The following sections provide detailed instructions for these procedures.

Assigning Access Permissions for the RPX User

  1. On the Start menu, click Run, and type dcomcnfg
  2. In the list of applications, select RqProxy.Connector and click Properties. The RqProxy.Connector Properties dialog box appears.
  3. On the Security tab, click Use custom access permissions. Click the adjacent Edit button.
  4. At the Registry Value Permissions dialog box, click Add.
  5. At the Add Users and Groups dialog box, click the List Names From field and select your domain. Click Show Users.
  6. Select the ReqWeb_RPXUser entry and click Add.
  7. At the Type of Access field, select Allow Access. Click OK twice to return to the RqProxy.Connector Properties dialog box.
  8. Continue with the next procedure.

Assigning Launch Permissions for the RPX User

  1. On the Security tab of the RqProxy.Connector Properties dialog box, click Use custom launch permissions. Click the adjacent Edit button.
  2. At the Registry Value Permissions dialog box, click Add.
  3. At the Add Users and Groups dialog box, click the List Names From field and select your domain. Click Show Users.
  4. Select the ReqWeb_RPXUser entry and click Add.
  5. At the Type of Access field, select Allow Launch. Click OK twice to return to the RqProxy.Connector Properties dialog box.
  6. Continue with the next procedure.

Assigning Configuration Permissions for the RPX User

  1. On the Security tab of the RqProxy.Connector Properties dialog box, click Use custom configuration permissions. Click the adjacent Edit button.
  2. At the Registry Value Permissions dialog box, click Add.
  3. At the Add Users and Groups dialog box, click the List Names From field and select your domain. Click Show Users.
  4. Select the ReqWeb_RPXUser entry and click Add.
  5. At the Type of Access field, select Read. Click OK twice to return to the RqProxy.Connector Properties dialog box.
  6. Continue with the next procedure.

Assigning Identity for the RPX User

  1. At the RqProxy.Connector Properties dialog box, click the Identity tab.
  2. Click This user and click Browse. Click the List Names From field and select your domain. Select the ReqWeb_RPXUser entry. Click Add and OK.
  3. Enter and confirm the ReqWeb_RPXUser password that you defined when you created this user.
  4. Click OK again to return to the Distributed COM Configuration Properties dialog box.
  5. Close DCOM.

Creating the Word User

RequisiteWeb requires a local administrative user for launching Microsoft Word 2000 on the RequisiteWeb Requirements server. Create the ReqWeb_WordUser and add that user to the Administrators group, as described in the following instructions.


Step Windows NT 4.0 Windows 2000 Server
1 Click Start > Programs > Administrative Tools > User Manager. Click Start > Programs > Administrative Tools > Computer Management.
2 Click User > New User. Expand Local Users and Groups and right-click on Users; select New User.
3 In the Username field, type ReqWeb_WordUser and enter a password of your choice. In the User name field, type ReqWeb_WordUser and enter a password of your choice.
4 Clear the check box User must change password at next login and select the check box Password never expires. Click Add; click Close. Clear the check box User must change password at next login and select the check box Password never expires. Click Create; click Close.
5 At the User Manager dialog box, select the ReqWeb_WordUser and click User > Properties. Select Users. Right-click the ReqWeb_WordUser entry and select Properties.
6 At the User Properties dialog box, click Groups. At the Member Of tab, click Add.
7 At the Group Memberships dialog box, add the Administrators group to the Member Of list. Click OK. Select the Administrators group, and click Add. Click OK.
8 Close the User Manager dialog box. Close the Computer Management dialog box.

Assigning DCOM Permissions for the Word User

RequisiteWeb uses the Distributed Component Object Model (DCOM) and a local user with Administrator permissions to launch Microsoft Word.

Use DCOM to give the ReqWeb_WordUser user access and launch permissions for Microsoft Word and Microsoft Word Basic, if it appears in your DCOM application list. The following sections provide detailed instructions for these procedures.

Assigning Access Permissions for the Word User

  1. On the Start menu, click Run, and type dcomcnfg
  2. On the Applications tab, select Microsoft Word Document on the list of applications and click Properties.
  3. On the Security tab, click Use custom access permissions. Click the adjacent Edit button.
  4. At the Registry Key Permissions dialog box, click Add.
  5. At the Add Users and Groups dialog box, click the List Names From field and select your local server. Click Show Users.
  6. Select the ReqWeb_WordUser entry and click Add.
  7. At the Type of Access field, select Allow Access. Click OK twice to return to the Word Document Properties dialog box.
  8. Continue with the next procedure.

Assigning Launch Permissions for the Word User

  1. On the Security tab of the Microsoft Word Document Properties dialog box, click Use custom launch permissions. Click the adjacent Edit button.
  2. At the Registry Value Permissions dialog box, click Add.
  3. At the Add Users and Groups dialog box, click the List Names From field and select your local server. Click Show Users.
  4. Select the ReqWeb_WordUser entry and click Add.
  5. At the Type of Access field, select Allow Launch. Click OK twice to return to the Word Document Properties dialog box.
  6. Continue with the next procedure.

Assigning Identity for the Word User

  1. At the Microsoft Word Document Properties dialog box, click the Identity tab.
  2. Click This user and click Browse. Click the List Names From field and select your local server. Select the ReqWeb_WordUser entry. Click Add and OK.
  3. Enter and confirm the ReqWeb_Word User password that you defined when you created this user.
  4. Click OK again to return to the Distributed COM Configuration Properties dialog box.
    Note: You must return to this dialog box before continuing with the next procedure.

Assigning Word Access Permissions for Administrators

  1. On the Applications tab of the Distributed COM Configuration Properties dialog box, select Microsoft Word Document on the list of applications and click Properties.
  2. On the Security tab of the Microsoft Word Document Properties dialog box, click Use custom access permissions. Click the adjacent Edit button.
  3. At the Registry Value Permissions dialog box, click Add.
  4. At the Add Users and Groups dialog box, click the List Names From field and select your local server.
  5. Select the Administrators entry and click Add.
  6. At the Type of Access field, select Allow Access. Click OK.
  7. Click OK several times to close the DCOM dialog boxes.
  8. Repeat the assigning access, launch, and identity procedures, described above, for the Microsoft Word Basic entry, if it appears in your DCOM application list.
  9. Reboot your system.

Creating a Document Directory on the Requirements Server

In order to display RequisitePro documents, RequisiteWeb creates temporary directories that contain copies of the project documents on the RequisiteWeb Requirements server.

To support these documents, create the following directory:

C:\Inetpub\wwwroot\ReqWebDoc\GenDoc

IIS 5.0 on Windows 2000 Advanced Server automatically creates a virtual directory that is associated with the GenDoc physical directory. In IIS 4.0 on Windows NT 4.0, use the following procedure to manually create a ReqWebDoc virtual directory.

Note: RequisiteWeb creates a word.tmp file in GenDoc while converting a Word document to HTML for viewing in the browser. While this file is present, no other users can convert documents. This file is deleted when the conversion is complete. In the case of a system crash, you may need to delete this file manually.

Creating a ReqWebDoc Virtual Directory on Windows NT 4.0

To create a virtual directory for RequisiteWeb on your RequisiteWeb Requirements server:

  1. Click Start > Programs > Windows NT 4.0 Option Pack > Microsoft Internet Information Server > Internet Service Manager.
  2. Right-click the Default Web Site and select New Virtual Directory.
  3. In the Virtual Directory Creation Wizard, click Next and type an Alias: ReqWebDoc.
  4. Click Next and browse to and select C:\Inetpub\wwwroot\ReqWebDoc\GenDoc.
  5. Click Next, accept the default settings, and click Finish to complete the wizard.
  6. Close the Internet Service Manager.

Installing the Oracle Client

In order to access RequisitePro projects that are stored in an Oracle database, you must configure Oracle client software on the Requirements server. Refer to the section "Setting Up PCs for Oracle Access" in the guide Installing Rational RequisitePro. That section refers to RequisitePro installation on a client PC; you must perform that procedure on the RequisiteWeb Requirements server.

Important: When implementing a single-server RequisiteWeb configuration, you must install the Oracle client software before installing the JDK if you are using a version of Oracle that is earlier than 8.1.7.

Setting Up the Single-Server Configuration

This section presents procedures for installing and configuring Web Server components on a single IIS Server. Perform the procedures described in Configuring the RequisiteWeb Requirements Server before doing the following procedures. Be sure to log on as an administrator before you begin the installation process. These instructions assume that you have installed the Microsoft Internet Information Server (IIS) on your system and that it is running. For more information on IIS, see Microsoft Servers at www.microsoft.com/servers.

This section contains the following procedures:

  1. Installing Java Components
  2. Installing the Tomcat Servlet Engine
  3. Configuring the ISAPI Redirector
  4. Configuring Jakarta Virtual Directory on IIS
  5. Adding a JSP Filter
  6. Configuring the Environment Variables
  7. Starting Tomcat
  8. Testing Tomcat
  9. Creating a ReqWeb Virtual Directory on IIS
  10. Configuring the ReqWeb Directory
  11. Editing the RequisiteWeb Configuration File
  12. Final Steps

Note: The instructions in this document assume that you are installing Windows applications on your C:\ drive. Substitute the appropriate drive, if necessary, when performing all procedures.

Installing Java Components

Continue your configuration of the RequisiteWeb server by installing the Sun Microsystems Java Development Kit (JDK 1.2.2), which includes the Java Runtime Environment (JRE).

If you already have the JDK installed on your system, check the version by entering the following at the MS-DOS shell command line: java -version
If your version is older than 1.2.2, you must upgrade to 1.2.2.

To install the JDK:

  1. Download the JDK executable file from the Sun Microsystems site at http://java.sun.com/products/jdk/1.2/download-windows.html. The self-extracting file you download is jdk-1_2_2_006-win.exe.
    Note: This Web site lists this product as the Java 2 Software Development Kit (SDK), Standard Edition, Version 1.2.2_006 for Microsoft Windows.
  2. Execute the self-extracting JDK file at the root level on the Web server's local hard drive. By default, the JDK creates files at the following locations:
    • C:\jdk1.2.2
    • C:\Program Files\JavaSoft\JRE\1.2
  3. You can verify your Java installation by entering the following at the MS-DOS shell command line: java -version

Installing the Tomcat Servlet Engine

To install Tomcat on your RequisiteWeb server:

  1. Locate the jakarta-tomcat.zip file on the Rational Solutions for Windows CD, at the following location: \RequisitePro\ReqWeb\tomcat
  2. Use WinZip to extract the jakarta-tomcat.zip file into the root (C:\) directory of your RequisiteWeb server. In the Extract dialog box, select the Use folder names check box. By unzipping this file into the C:\ root directory, WinZip creates the directory C:\jakarta-tomcat and its subdirectories.
    Note: Be sure you extract the contents of this file into the C:\ directory -- not a subdirectory.
  3. Copy the ReqWeb.war Web archive file from the RequisiteWeb installation directory. By default, this is: C:\Program Files\Rational\RequisitePro\ReqWeb.
    Paste the ReqWeb.war file into the directory: C:\jakarta-tomcat\webapps

Copying the server.xml and uriworkermap.properties files

Tomcat uses two configuration files: server.xml and uriworkermap.properties. These files must be modified in order to run RequisiteWeb.

Your RequisiteWeb installation includes preconfigured copies of the server.xml and uriworkermap.properties files at the following default location:
C:\Program Files\Rational\RequisitePro\ReqWeb\tomcat

  1. Copy and paste those files to the following location: C:\jakarta-tomcat\conf\
  2. Overwrite the existing versions of those files unless you are already running Tomcat on your system. In this case, see Previous Tomcat Installations, below.

Note: Tomcat includes a Web server running on port 8080, which is not required for RequisiteWeb. You can disable this Web server by editing the Tomcat server.xml file. For more information, refer to the Tomcat documentation that is included in the Tomcat installation.

Previous Tomcat Installations

If you already have a previous installation of Tomcat, do not overwrite your current server.xml and uriworkermap.properties files; however, in this case you must add the following entries to those files:


File New Entries
server.xml Add the following lines between the two XML tags <ContextManager ...> and </ContextManager>: <Context path="/ReqWeb" docbase="webapps/ReqWeb" debug="0" reloadable="false" > </Context>
Note: Be sure to enter this value without using carriage returns within the XML element. This entry is case-sensitive; enter it exactly as shown.
uriworkermap.properties Add the following lines to the end of the file: # Mount ReqWeb
/ReqWeb/*.jsp=ajp12

Note: Review the contents of the RequisiteWeb server.xml and uriworkermap.properties files for additional information.

Configuring the ISAPI Redirector

  1. Locate and copy the isapi_redirect.dll file at the following default location:
    C:\Program Files\Rational\RequisitePro\ReqWeb\tomcat
  2. Create a directory named "jakarta" under the C:\Inetpub\wwwroot\
  3. Paste the isapi_redirect.dll file into the new directory:
    C:\Inetpub\wwwroot\jakarta
  4. Locate the tomcat-iis-W2K.reg file in the following default directory:
    C:\Program Files\Rational\RequisitePro\ReqWeb\tomcat
    Note: This file assumes that you have configured the default Tomcat directory, C:\jakarta-tomcat. If you specified a different drive or installation directory, you must edit the tomcat-iis-W2K.reg file.
  5. Double-click the tomcat-iis-W2K.reg file. This creates the following Registry keys under the HKEY_LOCAL_MACHINE/SOFTWARE/:
    • /Apache Software Foundation
    • /Apache Software Foundation/Jakarta ISAPI Redirector
    • /Apache Software Foundation/Jakarta ISAPI Redirector/1.0
    Executing the tomcat-iis-W2K.reg file also adds the following String Values at the 1.0 Registry key:

String Value Value
extension_uri /jakarta/isapi_redirect.dll
log_file C:\jakarta-tomcat\logs\isapi.log
log_level error
worker_file C:\jakarta-tomcat\conf\workers.properties
worker_mount_file C:\jakarta-tomcat\conf\uriworkermap.properties

Note: If Tomcat is not installed in the default location shown in the table above, you must modify the registry keys shown above to reflect the correct path. If you are installing RequisiteWeb on an international operating system, make sure that the Tomcat registry entries match your Tomcat installation paths.

Configuring Jakarta Virtual Directory on IIS

To configure a virtual directory for Jakarta Tomcat on your RequisiteWeb server:

  1. Launch the Internet Services Manager by doing one of the following:
    • In Windows NT 4.0, click Start > Programs > Windows NT 4.0 Option Pack > Microsoft Internet Information Server > Internet Service Manager.
    • In Windows 2000 Server, click Start > Programs > Administrative Tools/Internet Services Manager.
  2. Expand the entry for the IIS <server name> on the tree.
  3. Expand the Default Web Site folder.
  4. Right-click the jakarta virtual folder and select Properties.
  5. Do one of the following:
    • In Windows 2000, in the Properties dialog box at the Virtual Directory tab, click the Execute permissions drop-down list and select Scripts and Executables.
    • In Windows NT, in the Properties dialog box at the Directory tab, click the Execute (including script) Permissions option.
  6. Click OK to close the dialog box. Leave the Internet Services Manager open.

Adding a JSP Filter

The following filter setting instructs IIS to process JSP pages using Tomcat.

  1. Right-click on the Default Web Site and select Properties.
  2. At the ISAPI Filters tab, click Add.
  3. Type the filter name: jakarta
  4. Browse to and select: C:\Inetpub\wwwroot\jakarta\isapi_redirect.dll
  5. Click OK to close the dialog boxes.
  6. Close the Internet Services Manager.

Configuring the Environment Variables

  1. On the Start menu, click Settings > Control Panel. In the Control Panel, double-click the System icon. The System Properties dialog box appears.
  2. Do one of the following:
    • In Windows 2000, at the Advanced tab, click Environment Variables.
    • In Windows NT, click the Environment tab.
  3. Add or modify the following system environment variables with the corresponding values, as shown. The PATH entry must be added to the existing PATH values on your system.
    Note: The path for the following applications may vary on your system. Be sure to use the correct value when specifying the path for these environment variables.


Variable Value
JAVA_HOME C:\jdk1.2.2
TOMCAT_HOME C:\jakarta-tomcat
TOMCAT_OPTS -DJINTEGRA_NATIVE_MODE
-DJINTEGRA_COINIT_VALUE=0
Note: This is a single-line entry.
PATH <existing PATH>;%JAVA_HOME%\bin

Starting Tomcat

  1. In the MS-DOS shell, type the following: cd C:\jakarta-tomcat\bin
  2. Type the following: tomcat start
  3. Leave the MS-DOS shells open. Closing the shells terminates the Tomcat process.

When Tomcat starts, the ReqWeb.war file expands to create a full directory structure for the RequisiteWeb components.

Note: You must restart Tomcat whenever the Web Server is rebooted. The user who starts Tomcat must remained logged on to the server as long as Tomcat and RequisiteWeb are in use. This user must have write permissions to the directories containing the RequisitePro .rqs project files, whether they are on the local machine or a remote server. If you have security questions related to this condition, contact Rational Software Technical Support.

Testing Tomcat

To verify that Tomcat is installed and configured correctly:

  1. Open a browser on your RequisiteWeb Requirements server and enter the following URL address: //<servername>:8080/examples/
    A list of JSP examples should appear. If it does not, check the steps for installing Tomcat, above; or, refer to the documentation in the /jakarta-tomcat/doc directory.
  2. Click the link to jsp. On the page that appears, click the Execute link to right of NumberGuess. A guessing game should appear.

Creating a ReqWeb Virtual Directory on IIS

Note: If you have a previous instance of a ReqWeb virtual directory on this server, do not add another one. In Internet Service Manager, right-click on the ReqWeb virtual directory and select Properties. At the Virtual Directory tab, enter the following at the Local Path field: C:\jakarta-tomcat\webapps\ReqWeb. Then go to step 7 in the following procedure.

To create a virtual directory for RequisiteWeb on your RequisiteWeb Requirements server:

  1. Launch the Internet Services Manager by doing one of the following:
    • In Windows NT 4.0, click Start > Programs > Windows NT 4.0 Option Pack > Microsoft Internet Information Server > Internet Service Manager.
    • In Windows 2000 Server, click: Start > Programs > Administrative Tools/Internet Services Manager.
  2. Expand the Default Web Site and verify that you do not have a ReqWeb virtual directory. If you do, refer to the note above.
  3. Right-click the Default Web Site and select New Virtual Directory.
  4. In the Virtual Directory Creation Wizard, click Next and type an Alias: ReqWeb.
  5. Click Next and browse to and select C:\jakarta-tomcat\webapps\ReqWeb
  6. Click Next and Finish to complete the wizard.
  7. Right-click the Default Web Site and select Properties.
  8. Do one of the following:
    • On Windows 2000, click the Web Site tab.
    • On Windows NT, click the Performance tab.
  9. Clear the HTTP Keep-Alives Enabled check box. Click OK to close the dialog box.

Configuring the ReqWeb Directory

Use the Internet Services Manager to configure the ReqWeb virtual directory. Make the entries as shown in the following table. Be sure to follow the instructions in the column that corresponds to your operating system.


Step Windows NT 4.0/IIS 4.0 Windows 2000 Server/IIS 5.0
1 Right-click the ReqWeb virtual directory (located under the Default Web Site) and select Properties. Right-click the ReqWeb virtual directory (located under the Default Web Site) and select Properties.
2 At the Properties dialog box, click the Virtual Directory tab. Select Read permission; clear Write permission. Be sure that the Application Settings section contains the Name "ReqWeb". Clear the box Run in separate memory space. At the Permissions list, select Script. Click Configuration. At the Properties dialog box, click the Virtual Directory tab. Select Read permission; clear Write permission. Clear the Directory Browsing check box. Be sure that the Application Settings section contains the Application Name "ReqWeb". Accept Medium Application Protection. Click Configuration.
3 At the Application Configuration dialog box, click the App Options tab. Select Enable session state. Set ASP Script timeout to at least 90 seconds. Click OK. At the Application Configuration dialog box, click the App Options tab. Select Enable session state. Set ASP Script timeout to at least 90 seconds. Click OK.
4 At the Properties dialog box, click the Directory Security tab. In Anonymous Access and Authentication Control, click Edit. At the Properties dialog box, click the Directory Security tab. In Anonymous access and authentication control, click Edit.
5 At the Authentication Methods dialog box, select Allow Anonymous Access and click Edit. At the Authentication Methods dialog box, select Anonymous Access and click Edit.
6 In the Anonymous User Account dialog box, at Username field, replace the default entry by typing: ReqWeb_RPXUser Clear the check box Enable Automatic Password Synchronization. Click OK twice. In the Anonymous User Account dialog box, at Username field, replace the default entry by typing: ReqWeb_RPXUser Clear the check box Allow IIS to control password. Click OK twice.
7 At the Properties dialog box, click the Documents tab. Select the Enable Default Document check box. Click Add. At the Add Default Document dialog box, type index.html. Click OK. At the Properties dialog box, on the Documents tab, select the index.html entry in the default document list. Use the up arrow to move that entry to the top of the list. Click OK. At the Properties dialog box, click the Documents tab. Select the Enable Default Document check box. Click Add. At the Add Default Document dialog box, type index.html. Click OK. At the Properties dialog box, on the Documents tab, select the index.html entry in the default document list. Use the up arrow to move that entry to the top of the list. Click OK.
8 Close the Internet Service Manager Close the Internet Services Manager.

Editing the RequisiteWeb Configuration File

To configure RequisiteWeb, execute the RWConfig Java utility as follows:

  1. Open an MS-DOS shell and navigate to the following directory: C:\jakarta-tomcat\webapps\ReqWeb\WEB-INF\classes
  2. Type the following at the MS-DOS prompt:
    set classpath=%classpath%;.
  3. Type the following command to execute the RWConfig Java utility: 
    java RWConfig
  4. For each setting (shown in the table below), accept the default or modify the value, as necessary.
    Note: You must enter the RequisiteWeb server name in the RPXHTTP value. Other entries are provided by default; check to see whether they are correct for your installation.

Setting Switch Value
User ID /uid Press Enter to accept the default setting of <Blank>. If another value is shown, type DEL to set the entry to blank.
Password /Password Press Enter to accept the default setting of <Blank>. If another value is shown, type DEL to set the entry to blank.
Server Name /RPXhost Press Enter to accept the default setting of <Blank>. If another value is shown, type DEL to set the entry to blank.
Domain /RPXdomain Press Enter to accept the default setting of <Blank>. If another value is shown, type DEL to set the entry to blank.
RPXHTTP /RPXHTTP HTTP://<server name>/ReqWebDoc/GenDoc/
Note: This case-sensitive entry is the URL to the directory for Microsoft Word temporary files. You must replace the <server name> entry with the correct RequisiteWeb server name.
RPXDocPath /RPXDocPath C:\Inetpub\wwwroot\ReqWebDoc\GenDoc\
Note: This is the default location of temporary files generated by Microsoft Word. Modify this value if you have a different configuration.
RPXCatalog /RPXCatalog C:\Program Files\Rational\RequisitePro\
ReqWeb\Projects\catalog.txt
Note: This is the default location of the RequisitePro projects catalog file on the server. Modify this value if you have a different configuration.
Language /Language Press Enter to accept the default setting of "en" for English. Do not change this value unless your version of RequisiteWeb has been translated into your local language. This value is based on ISO639 language code standards. If you are using a Japanese version of RequisiteWeb, use the value "ja".
Country /Country Press Enter to accept the default setting of "US" for United States. Do not change this value unless your version of RequisiteWeb has been translated into your local language. This value is based on ISO3166 country code standards. If you are using a Japanese version of RequisiteWeb, use the value "jp".

Note: To set an individual parameter, run the RWConfig Java utility with one of the switches shown in the table above. For example, to change the path of the catalog file, enter the following at the command line in the classes directory:
java RWConfig /RPXCatalog

Note: The values you enter are stored in the following file: C:\jakarta-tomcat\webapps\ReqWeb\WEB-INF\classes\config.txt

Maintaining RequisiteWeb Service

You must restart Tomcat whenever the Web Server is rebooted. The user who starts Tomcat must remain logged on to the server as long as Tomcat and RequisiteWeb are in use. This user must have write permissions to the directories containing the RequisitePro .rqs project files, whether they are on the local machine or a remote server. If you are done configuring RequisiteWeb, press Ctrl-Alt-Delete and lock your computer. If you have security questions related to this condition, contact Rational Software Technical Support.

Final Steps

To finish configuring your RequisiteWeb installation, refer to the following sections:

Setting Up the Dual-Server Configuration

Configuring the Web Server

This section contains procedures for configuring your HTTP Web server for hosting RequisiteWeb on Sun Microsystems Solaris and Linux. Be sure to log on as an administrator before beginning your installation process. This installation assumes that you have installed the Apache Web server on your system. For more information on installing the Apache Web server, see Apache HTTP Server Project at www.apache.org.

Note: Samples in this section use the BASH shell (GNU Bourne-Again Shell) in the UNIX operating system. For example, the instructions for setting environment variables use the export command. Modify the samples with appropriate syntax for your OS shell.

Note: The paths and file names for your installation of the JDK, Apache Web server, and Tomcat may vary from the examples shown. Be sure to provide the correct paths and file names.

This section contains the following procedures:

  1. Installing Java Components
  2. Testing the Apache Web Server Shared Object Handling
  3. Configuring the Apache Web Server
  4. Installing Tomcat
  5. Installing Jserv
  6. Configuring Apache for Tomcat
  7. Installing RequisiteWeb Components on the Web Server
  8. Editing the RequisiteWeb Configuration File

Installing Java Components

Begin your configuration of the RequisiteWeb HTTP server by installing the Java Development Kit (JDK 1.2.2), which includes the Java Runtime Environment (JRE).

  1. If you already have the JDK installed on your system, check the version by entering the following at the system command line: java -version
    If your version is older than 1.2.2, you must upgrade to 1.2.2.
  2. Download and install the appropriate JDK (1.2.2 or higher) for your system's hardware and operating system. The JDK is available from Sun Microsystems at http://java.sun.com.
    Note: Your distribution of the JDK may create a jdk1.2 directory. The following instructions refer to a jdk1.2.2 directory.
  3. Set the environment variable JAVA_HOME to the name of your JDK directory: 
    export JAVA_HOME=/usr/local/jdk1.2.2
  4. Add the JDK bin directory to your PATH environment variable: 
    export PATH=$PATH:$JAVA_HOME/bin
  5. Add all of the JAR files in your JDK's lib directory to your CLASSPATH environment variable. For example: 
    export CLASSPATH=.:$JAVA_HOME/lib/tools.jar
    Note: Make the environment changes permanent by adding the export commands, above, to your login script, such as the /etc/profile file.

Testing the Apache Web Server Shared Object Handling

Verify that Apache can load shared objects, which are necessary for RequisiteWeb.

  1. Navigate to the directory that contains Apache's binary files; typically, this is /usr/local/apache/bin.
    Note: Your Apache installation may be in /usr/apache.
  2. Type the following command: /usr/local/apache/bin/httpd -l

If this command prints a line containing "mod_so.c" or "mod_so" then your installation will work for RequisiteWeb. Otherwise, use a different distribution or compile the Apache source files on your system.

Configuring the Apache Web Server

Perform the following configuration tasks for your Apache Web server installation.

In order to configure the Apache Web server for RequisiteWeb, you must copy the configuration files in /usr/local/apache/conf to new file names. This creates copies of the originally distributed example configuration files.

  1. Navigate to the Apache configuration directory by typing the following:
    cd /usr/local/apache/conf
  2. Rename the sample configuration files using the copy command:
    cp access.conf-dist access.conf
    cp httpd.conf-dist httpd.conf
    cp srm.conf-dist srm.conf
    Note: Your Apache distribution may use .conf-example or another extension rather than the .conf-dist extension for these files.
  3. Edit the httpd.conf text file as needed:
    The ServerRoot entry and subsequent lines, shown below, contain the path to your Apache Web server installation directory. Be sure that this path is correct. 
    ServerRoot      /usr/local/apache
DocumentRoot    /usr/local/apache/htdocs
Alias /icons/   "/usr/local/apache/icons/"
<Directory "/usr/local/apache/icons">
	 Options Indexes MultiViews
	 AllowOverride None
	 Order allow,deny
	 Allow from all
</Directory>
ScriptAlias /cgi-bin/ "/usr/local/apache/cgi-bin/"
<Directory "/usr/local/apache/cgi-bin">
	 AllowOverride None
	 Options None
	 Order allow,deny
	 Allow from all
</Directory>
    Important: You will need to supply the path (shown in the value of the ServerRoot entry) when installing Jserv in a subsequent procedure.
  4. Find the line defining the variable ServerName and set it to the host name your Web site visitors will use. This might be a host name, such as reqweb.rational.com, or an IP address, such as 192.168.1.1. 
    ServerName reqweb.rational.com
  5. Optionally, make additional performance, security, and application changes to httpd.conf. By default, the httpd.conf file assigns the Apache Web server the same permissions that are assigned to the "nobody" user and group, as indicated by the following entries: 
    User nobody
Group nobody
    See the file: /usr/local/apache/htdocs/manual/misc/security_tips.html
    for more security information. If you encounter problems, there is abundant documentation on installing and configuring Apache at the Web site: http://www.apache.org.

Starting and Verifying the Apache Web Server

  1. To start Apache, type the command: 
    /usr/local/apache/bin/apachectl start
  2. Open your Web browser and enter an address for your server name (http://<servername>/) or local host (http://localhost/). Apache's "Test Page for Apache Installation" should appear. If you receive an error message, check the logs in /usr/local/apache, double-check httpd.conf, and check the process list to see if Apache is really running. Enter one of the following:
    • ps -Af | grep httpd (on Solaris)
    • ps -auwwx | grep httpd (on Linux)
    If this command prints a list of processes, Apache is running. Otherwise, Apache did not start.

Installing Tomcat

  1. Locate the jakarta-tomcat.tar.gz file on the Rational Solutions for Windows CD, at the following location: cd /cdrom/RequisitePro/ReqWeb/tomcat
  2. Copy this file into a directory where you want to install Tomcat. This documentation uses /usr/local as the parent directory for the Tomcat installation. Therefore, your file should be saved as /usr/local/jakarta-tomcat.tar.gz.
    cp jakarta-tomcat.tar.gz /usr/local
  3. Change to the /usr/local directory:
    cd /usr/local
  4. Extract the Tomcat binaries: 
    gunzip -c jakarta-tomcat.tar.gz | tar -xvf -
  5. Set the TOMCAT_HOME environment variable to the directory where you installed Tomcat: 
    export TOMCAT_HOME=/usr/local/jakarta-tomcat
    Note: Make the environment changes permanent by adding the export command, above, to your login script, such as the /etc/profile file.

Starting and Testing Tomcat

  1. To start Tomcat, type the following: 
    /usr/local/jakarta-tomcat/bin/startup.sh
  2. To test Tomcat, enter the following address in your browser: http://<servername>:8080/examples
    You should be able see example Web applications, including pages that run Java Servlets and JSPs. If not, check the following:
    • Your current PATH must contain the path to the "java" executable; for example $JAVA_HOME/bin
    • Your JAVA_HOME environment variable must be assigned to the JDK installation directory; for example /usr/local/jdk1.2.2
    • Your TOMCAT_HOME environment variable must be assigned to the Tomcat installation directory; for example /usr/local/jakarta-tomcat
    • Tomcat should have exclusive access to its ports. If there are one or more other programs "listening" to Tomcat's ports, you should see a Java BindException message when starting Tomcat. By default, Tomcat uses the TCP/IP ports 8007 and 8080 on your machine. If there is a conflict, you can change which ports Tomcat uses by editing the file: /usr/local/jakarta-tomcat/conf/server.xml.
    • Tomcat must be running. To verify this, type one of the following: 
      ps -Af | grep tomcat    (on Solaris)
ps -auwwx | grep tomcat (on Linux)

Note: You must restart Tomcat whenever the Web server or the Requirements server is rebooted.

Installing Jserv

Jserv is an executable shared object that Tomcat uses to communicate with the Apache Web server. For Linux systems, use the compiled shared object, described in Installing Jserv on Linux, below. For Solaris systems, you must compile Jserv on your system; refer to the section Compiling Jserv on Solaris, below.

Installing Jserv on Linux

  1. Locate the mod_jserv.so file on the Rational Solutions for Windows CD, at the following location: cd /cdrom/RequisitePro/ReqWeb/tomcat
  2. Copy the mod_jserv.so file into Apache's libexec directory in the ServerRoot directory, which is specified in the httpd.conf file, by typing the following: 
    cp mod_jserv.so /usr/local/apache/libexec
    Refer to Configuring the Apache Web Server to identify the ServerRoot directory.
  3. Assign root ownership and executable permission: 
    cd /usr/local/apache/libexec
chown root:root mod_jserv.so
chmod +x mod_jserv.so

Compiling Jserv on Solaris

Prior to installing Jserv on the Solaris operating system, you must compile it. In order to compile Jserv, you must have the following utilities:

ANSI-C Compliant Compiler

Check whether you have an ANSI-C compiler such as GNU's gcc installed. Solaris machines often do not have an ANSI-C compiler; if not, install the GNUgcc package for your version of Solaris. Make sure this compiler is included in your path: 

export PATH=$PATH:<GNUgcc path>/bin

To create a link to the compiler (on Solaris systems only):

  1. Find the cc program in your file structure: 
    which cc
  2. Navigate to that directory. 
    cd /usr/ucb
  3. Rename the cc program to a backup copy, such as cc.old. 
    mv cc cc.old
  4. Create a link to gcc. 
    ln -s /usr/local/bin/gcc cc

Perl Script Interpreter

Most Solaris machines have a pre-installed Perl interpreter. Use the following command to locate your executable Perl interpreter: 

which perl

This outputs the full path and name of the interpreter program, for example: 

/usr/bin/perl

Apache Extension Tool Perl Script (apxs)

The apxs script is a Perl script that allows you to compile programs that extend Apache. By default, it is located in /usr/local/apache/bin. Verify that you can run this script; for example, type: /usr/local/apache/bin/apxs

Note: If you cannot run apxs, check that the line at the top of the apxs file matches the location of your perl interpreter; for example #!/usr/bin/perl

  1. Navigate to the directory containing the Jserv source code: 
    cd /usr/local/jakarta-tomcat/src/native/apache/jserv
  2. Compile mod_jserv.c: 
    /usr/local/apache/bin/apxs -c -o mod_jserv.so *.c
    Be sure to enter this command exactly as shown, including spaces. This produces an executable called mod_jserv.so.
  3. Copy the mod_jserv.so executable into Apache's libexec directory in the ServerRoot directory, which is specified in the httpd.conf file. Refer to Configuring the Apache Web Server to identify the ServerRoot directory. 
    cp mod_jserv.so /usr/local/apache/libexec

Configuring Apache for Tomcat

Tomcat generates a configuration file that enables Apache to communicate with Tomcat. You must edit this configuration file to ensure this communication:

  1. To stop Apache and Tomcat, type the following: 
    /usr/local/apache/bin/apachectl stop
/usr/local/jakarta-tomcat/bin/shutdown.sh
  2. Open the following file in an editor: 
    /usr/local/apache/conf/httpd.conf
  3. Add the following line to the end of the file: 
    Include /usr/local/jakarta-tomcat/conf/tomcat-apache.conf
  4. Start Tomcat: 
    /usr/local/jakarta-tomcat/bin/startup.sh
    Tomcat generates the tomcat-apache.conf configuration file.
  5. Start Apache: 
    /usr/local/apache/bin/apachectl start
    Apache reads the configuration file.
  6. If Apache does not start, check for the following conditions:
    • There is a typographic error in the file: /usr/local/apache/conf/httpd.conf
    • Apache cannot find the file: /usr/local/jakarta-tomcat/conf/tomcat-apache.conf
    • Apache cannot find the file: /usr/local/apache/libexec/mod_jserv.so
    • Apache cannot read and execute the file: /usr/local/apache/libexec/mod_jserv.so
    • There are duplicate or conflicting configuration entries in the following files: /usr/local/apache/conf/httpd.conf /usr/local/jakarta-tomcat/tomcat-apache.conf
  7. If Apache still does not start, examine the Apache log files in the following directory: /usr/local/apache/logs

Installing RequisiteWeb Components on the Web Server

  1. Navigate to the directory that contains the ReqWeb.war file on the Rational Solutions for Windows CD:
    cd /cdrom/RequisitePro/ReqWeb/
  2. Copy the ReqWeb.war file into Tomcat's Web applications directory: 
    cp ReqWeb.war /usr/local/jakarta-tomcat/webapps
  3. Locate the preconfigured server.xml file from the following default location:
    cd /cdrom/RequisitePro/ReqWeb/tomcat/
  4. Copy it into the following location: /usr/local/jakarta-tomcat/conf/
    cp server.xml /usr/local/jakarta-tomcat/conf/
    Note: If you already have a previous installation of Tomcat, do not overwrite your current server.xml file; however, you must make the following addition to that file:
    Add the following lines between the two XML tags <ContextManager ...> and </ContextManager>: 
    <Context path="/ReqWeb" docbase="webapps/ReqWeb" debug="0" 
reloadable="false" > </Context>
    Note: Be sure to enter this value without using carriage returns within the XML element. This entry is case-sensitive; enter it exactly as shown.
  5. Optional step: Tomcat includes a Web server running on port 8080, which is not required for RequisiteWeb. You can disable this Web server by editing the Tomcat server.xml file. For more information, refer to the Tomcat documentation that is included in the Tomcat installation.
  6. Stop Tomcat: 
    /usr/local/jakarta-tomcat/bin/shutdown.sh
  7. Stop Apache: 
    /usr/local/apache/bin/apachectl stop
  8. Start Tomcat: 
    /usr/local/jakarta-tomcat/bin/startup.sh
    Note: This may take a few moments longer than usual because Tomcat must extract and decompress ReqWeb.war.
  9. Create the following folder: 
    mkdir /usr/local/jakarta-tomcat/webapps/reqweb
    Note: This new reqweb directory is in addition to the existing ReqWeb directory.
  10. Copy the index.html file from the ReqWeb directory to the reqweb directory: 
    cp /usr/local/jakarta-tomcat/webapps/ReqWeb/index.html 
/usr/local/jakarta-tomcat/webapps/reqweb
  11. Start Apache: 
    /usr/local/apache/bin/apachectl start

Editing the RequisiteWeb Configuration File

To configure RequisiteWeb, execute the RWConfig Java utility as follows:

  1. Open a shell and navigate to the following directory: /usr/local/jakarta-tomcat/webapps/ReqWeb/WEB-INF/classes
  2. Type the following at the shell prompt:
    export CLASSPATH=$CLASSPATH:.
  3. Type the following command to execute the RWConfig Java utility: 
    java RWConfig
  4. For each setting, accept the default or modify the value, as necessary.
    Note: You must enter the RequisiteWeb server name in the RPXHTTP value. Other entries are provided by default and may be correct for your installation.

Setting Switch Value
User ID /uid Enter the user ID: ReqWeb_RPXUser
Note: This is the user that RequisiteWeb uses to log on to the Requirements server.
Password /Password Enter the password for the ReqWeb_RPXUser.
Server Name /RPXhost Enter the Requirements server name. Depending on your network configuration, you may need to enter the server IP address instead of the server name. Contact your system administrator for more information.
Domain /RPXdomain Enter the domain name for the Requirements server. If the domain name is not valid, DCOM searches for the user ID on the local server. If there is no domain, enter a placeholder value, such as RequisiteWeb.
RPXHTTP /RPXHTTP HTTP://<server name>/ReqWebDoc/GenDoc/
Note: This case-sensitive entry is the URL to the directory on the Requirements server for Microsoft Word temporary files. You must replace the <server name> entry with the correct server name.
RPXDocPath /RPXDocPath C:\Inetpub\wwwroot\ReqWebDoc\GenDoc\
Note: This is the default location of temporary files generated by Microsoft Word on the Requirements server. Modify this value if you have a different configuration.
RPXCatalog /RPXCatalog C:\Program Files\Rational\RequisitePro\
ReqWeb\Projects\catalog.txt
Note: This is the default location of the RequisitePro projects catalog file on the Requirements server. Modify this value if you have a different configuration.
Language /Language Press Enter to accept the default setting of "en" for English. Do not change this value unless your version of RequisiteWeb has been translated into your local language. This value is based on ISO639 language code standards. If you are using a Japanese version of RequisiteWeb, use the value "ja".
Country /Country Press Enter to accept the default setting of "US" for United States. Do not change this value unless your version of RequisiteWeb has been translated into your local language. This value is based on ISO3166 country code standards. If you are using a Japanese version of RequisiteWeb, use the value "jp".

Note: To set an individual parameter, run the RWConfig Java utility with one of the switches shown in the table above. For example, to change the path of the catalog file, enter the following at the command line in the classes directory:
java RWConfig /RPXCatalog

Note: The values you enter are stored in the following file: /usr/local/jakarta-tomcat/webapps/ReqWeb/WEB-INF/classes/config.txt

Managing RequisitePro Projects for RequisiteWeb

While RequisiteWeb provides features for accessing and editing requirements and documents in projects, you must use the full RequisitePro PC client application to create projects and documents. RequisitePro offers project templates and other management tools for creating and modifying project structure and security. For more information refer to the guide Using Rational RequisitePro or the RequisitePro online help.

Using the RequisiteWeb Project Catalog

RequisiteWeb uses a catalog text file to provide access to RequisitePro projects. By default, the file contains entries for the RequisitePro Learning Project and another sample project. The projects that are listed in your catalog file appear in the Projects drop-down list on the RequisiteWeb logon page.

To add your own projects to the catalog, you must enter the full path for the project file, which has a .rqs extension. For instructions on modifying the catalog, see Editing the RequisitePro Projects Catalog.

Accessing Projects on Different Servers

If you are using Microsoft Access for your RequisitePro project database, the database file must be located on the RequisiteWeb Requirements server. By default, local projects are created in the following directory:
\Program Files\Rational\RequisitePro\ReqWeb\Projects.

RequisiteWeb can open SQL Server- and Oracle-based projects that are not physically located on the RequisiteWeb Requirements server; however, in this case the ReqWeb_RPXUser domain user must have Change or Modify permission for the directory containing the RequisitePro .rqs project file on the remote project server.

In order to access RequisitePro projects that are stored in an Oracle database, you must configure Oracle client software on the Requirements server. Refer to the section "Setting Up PCs for Oracle Access" in the guide Installing Rational RequisitePro. That section refers to a RequisitePro installation on a client PC; you must perform that procedure on the Requirements server.

Important: When implementing a single-server RequisiteWeb configuration, you must install the Oracle client software before installing the JDK if you are using a version of Oracle that is earlier than 8.1.7.

After installing or upgrading RequisiteWeb, the projects that are not located on your RequisiteWeb Requirements server may not be visible in the Projects drop-down list, even though they are listed in your catalog file. To refresh the project list, run the DCOM configuration application by typing dcomcnfg at the Start > Run command line. The DCOM application appears; close it. Check your projects list in RequisiteWeb.

Editing the RequisitePro Projects Catalog

To edit the catalog, perform the following procedure on the RequisiteWeb server in the single-server configuration or on the Requirements server in the dual-server configuration:

  1. Navigate to the directory:
    C:\Program Files\Rational\RequisitePro\ReqWeb\Projects
  2. Using a text editor, open the catalog.txt file.
  3. Create an entry on each line with the full path to the RequisitePro project file. Copy the format of default project entries.
    Note: Use a full path for local projects on the Requirements server. To access projects on another server, you must specify a Universal Naming Convention (UNC) path to the shared folder containing the RequisitePro .rqs file.
  4. Save and close the catalog.txt file.

Note: In order to view updates to the catalog.txt file, users must log off RequisiteWeb and then select a project at the initial RequisiteWeb entry page.

Configuring E-mail for Discussions

To configure e-mail for RequisitePro discussions, refer to the guide Installing Rational RequisitePro. You use the same Rational E-mail Reader session for both RequisitePro and RequisiteWeb; however, note the following requirements when configuring the Rational E-mail Reader for both RequisitePro and RequisiteWeb:

Starting RequisiteWeb

To access a RequisitePro project in RequisiteWeb:

  1. Open your browser.
  2. Set the URL address to the full path to the logon page in the RequisiteWeb virtual directory; for example: http://<server name>/reqweb
    Note: Be sure to use the server name rather than an IP address.
  3. Navigate to that address. The RequisiteWeb logon page appears.
  4. Select a RequisitePro project from the Project list. If your project does not appear on the list, refer to the procedure Managing RequisitePro Projects for RequisiteWeb.
  5. Type your RequisitePro User name and Password and click Log on.

Removing RequisiteWeb

This section describes how to remove RequisiteWeb from a RequisiteWeb Requirements server. Prior to removing RequisiteWeb from your system, make sure that no one is using RequisiteWeb or any associated files. You will not be able to remove files that are in use.

RequisiteWeb installs a new project catalog containing paths to new sample projects. Be sure to make a copy of your existing catalog.txt file before removing RequisiteWeb. If you are upgrading from an earlier release of RequisiteWeb, the catalog.txt file should be located in the following default directory: C:\Inetpub\wwwroot\reqweb

Add your previous catalog.txt entries to the new catalog file that is installed with the new version of RequisiteWeb in the default directory:
C:\Program Files\Rational\RequisitePro\ReqWeb\Projects

For more information, see Managing RequisitePro Projects for RequisiteWeb.

Removing RequisiteWeb on Windows with IIS

To remove RequisiteWeb from a Windows NT or Windows 2000 server, you must have Windows administrator privileges on that machine. Use the following instructions to:

Removing or Redirecting the ReqWeb Virtual Directory

  1. Launch the Internet Services Manager by doing one of the following:
    • Click Start > Run, and type inetmgr. Click OK.
    • In Windows NT 4.0, click Start > Programs > Windows NT 4.0 Option Pack > Microsoft Internet Information Server > Internet Service Manager.
    • In Windows 2000 Server, click Start > Programs > Administrative Tools/Internet Services Manager.
  2. Select the Default Web Site and click the Stop button on the toolbar.
  3. Right-click on the ReqWeb virtual directory and select Properties. The ReqWeb Properties dialog box appears. Click the Virtual Directory tab.
  4. Depending on whether you are upgrading or simply removing RequisiteWeb from your system, do one of the following:
    • If you are upgrading to a new version of RequisiteWeb, do not delete your ReqWeb virtual directory. After you have installed your new version of RequisiteWeb, you will redirect the ReqWeb virtual directory to the new path, as described in Creating a ReqWeb Virtual Directory on IIS.
    • If you are not upgrading, but simply removing all RequisiteWeb components from your system, click Remove and click OK to close the dialog box.

Stopping the IIS Admin Service

Perform the instructions in the following table. Refer to the column that corresponds to your operating system.


Step Windows NT 4.0 Windows 2000 Advanced Server
1 Close the Internet Service Manager. In the Internet Services Manager, right-click on the server name.
2 At the Start/Run command line, type cmd. Select Restart IIS.
3 In the MS-DOS window, type the following:
net stop iisadmin /y
and press Enter. 		At the Stop/Start/Reboot dialog box, select Stop Internet Services on <server name>.
4 The following message appears: "The IIS Admin Service was stopped successfully." The C:\ prompt appears after the command is successfully executed. Type exit to close the MS-DOS window. Click OK to close the dialog box. Close the Internet Services Manager.

Removing the RequisiteWeb Program

Use the Add/Remove Programs function in the Windows Control Panel to select and remove RequisitePro. After the uninstall process is complete, check to see if the C:\Program Files\Rational\RequisitePro\ReqWeb directory is still present on the server. If so, delete the ReqWeb directory and its subdirectories.

Restarting the Web Publishing Service

Perform the instructions in the following table. Refer to the column that corresponds to your operating system.


Step Windows NT 4.0 Windows 2000 Advanced Server
1 In the MS-DOS window, type the following:
net start w3svc
and press Enter.		 In the Internet Services Manager, right-click on your server name.
2 The following message appears: "The World Wide Web Publishing Service was started successfully." The C:\ prompt appears after the command is successfully executed. Select Restart IIS. At the Stop/Start/Reboot dialog box, select Restart Internet Services on <server name>.
3 Type exit to close the MS-DOS window. Click OK to close the dialog box and close the Internet Services Manager.

Removing RequisiteWeb from a Unix Web Server

To remove RequisiteWeb components from your Solaris or Linux Web Server, you need to remove directories and environment variables.

Warning: Be sure that you only delete those components that are not required for other applications on your server.

Note: When removing environment variables, check the /etc/profile file to ensure that the environment variables are cleared for all sessions.

Removing the Java Development Kit on Unix

Remove the following directory and its subdirectories from the server:

/usr/local/jdk1.2.2

Remove the JAVA_HOME and CLASSPATH environment variables.

Removing Tomcat on Unix

Remove the following directories and their subdirectories from the server:

Remove the following environment variable from the server:

Known Issues

Note that many of the issues listed below include "workarounds" that you should implement when configuring your RequisiteWeb Requirements server or client browsers.

Accessing RequisiteWeb Pages and Projects

Viewing and Downloading Documents

Download vs. View

RequisiteWeb gives you the ability to download requirements documents and save them to disk in Microsoft Word format. On the Documents page in RequisiteWeb, click a file name in the Download File column.

When downloading a document using Microsoft Internet Explorer, you have the options of opening or saving the document. Opening the document at this point may cause a program failure or erroneous display. Be sure to save the document to disk, and then open it using Microsoft Word. After saving the document, if a "Navigation Canceled" page or blank page is displayed, click the Back button or the Documents icon to return to the documents list.

Note: To view the document immediately in your browser, click the document name in the Document column. The requirements document is converted to HTML and displayed in RequisiteWeb.

If you cancel a document download operation from the download dialog box, and then select the download option in RequisiteWeb again, the document may be displayed in the browser and RequisiteWeb fails to present the download dialog box. To fix this condition, refer to Microsoft Knowledge Base article Q162059 at http://support.microsoft.com/support/kb/articles/Q162/0/59.asp (8740)

When downloading a document in Netscape, spaces and other HTML special characters in the document name are replaced by HTML character codes. These characters are a result of the URL encoding that RequisiteWeb applies to the address of the document. Netscape displays the HTML character codes in the file name field of document Save As dialog box. When you save the document, the characters are replaced by the original spaces and/or special characters. (7186)

Viewing Project Documents

You cannot view RequisitePro documents in RequisiteWeb unless they are stored in the same directory as the RequisitePro project (.rqs) file. To access a document in RequisiteWeb, relocate the document in the project directory:

  1. In the RequisitePro Tool Palette, click Project > Properties. The Project Properties dialog box appears.
  2. At the General tab, note the full project path in the Directory field. Click OK to close the dialog box.
  3. Click Document > Open. Select a document and click OK. The document opens in the Word Workplace.
  4. Click Document > Properties. The Document Properties dialog box appears.
  5. On the General tab, click Browse. The Browse for Folder dialog box appears.
  6. Select the folder that contains your RequisitePro project (.rqs) file, as noted in step 2, above. Click OK to close both dialog boxes.

To remove this limitation, download the RequisiteWeb 2001.03 Service Release 1 at www.rational.com/support. (15803)

Other Document Viewing Conditions

The following are other conditions that may prevent successful viewing of project documents in RequisiteWeb:

Security for RequisiteWeb Documents

Documents that are viewed or downloaded using RequisiteWeb are converted from RequisitePro format to Microsoft Word or HTML formats. Therefore, these copies can potentially be viewed by unauthorized users on the RequisiteWeb Requirements server using MS Word or an HTML browser.

If document security is an issue, be sure to limit access to the GenDoc directory on the RequisiteWeb Requirements server.

Note: The ReqWeb_WordUser and ReqWeb_RPXUser users must have create/read/write permissions for the GenDoc directory.

RequisiteWeb Discussions

RequisiteWeb Requirements

Modifying Requirement Traceability in RequisiteWeb

If you create a circular traceability relationship, RequisiteWeb displays an appropriate error message. To continue editing the requirement, you must view a different requirement or log out of the project and log on again. (13860)

Filtering Views in RequisiteWeb

You can filter a view on Trace To or Trace From criteria, but not both; if you attempt to do so an error message is displayed. (15373)

RequisiteWeb Pages Do Not Display on UNIX

If your UNIX version of Netscape Navigator does not display RequisiteWeb pages, clear the HTTP Keep-Alives Enabled setting for the Default Web Site on your RequisiteWeb Requirements server. Refer to Creating a ReqWeb Virtual Directory on IIS, above.

Running RequisiteWeb on International Operating Systems

Contact Information

Rational Software Corporation

Corporate Headquarters:

Rational Software Corporation
18880 Homestead Road
Cupertino, CA 95014
Toll-free: 1-800-728-1212
Telephone: 408-863-9900
Fax: 408-863-4120
E-mail: ratlinfo@us.ibm.com

Technical Support:

Telephone: 1-800-433-5444 or 408-863-5000 (outside the U.S. and Canada)
Fax: 408-863-4300
E-mail: support@rational.com
Web site:www.rational.com

Visit our Web site for more information about us!