Installing IBM® Rational® Project Conductor

Installing IBM Rational Project Conductor

Planning the installation

Installation roadmaps

Roadmap for installingRational Project Conductor and JazzTeam Server

1. Review the installation planning worksheet
2. Verify that the hardware and software requirements are met.
3. Install Rational Project Conductor and the JazzTeam Server.
4. Perform the post-installation tasks that are relevant to your installation environment:
   1. If you are using a database other than the default Derby database, set up the database to work with the Jazz Team Server
   2. Create database tables
   3. Start the server
   4. If you want to use the Websphere Application Server, set up and start the WebSphere Application Server
   5. Run the setup wizard to test the database connection, and to configure additional server options
   6. If you are using LDAP as the user registry, configure the LDAP connection parameters
   7. Create users and assign licenses
   8. Set up the project management environment

Roadmap for installingRational Project Conductor in an existing JazzTeam Server instance

1. Review the installation planning worksheet
2. Verify that the hardware and software requirements are met.
3. Install Rational Project Conductor in an existing JazzTeam Server instance.
4. Perform the post-installation tasks:
   1. Add database tables to the existing repository
   2. Start the server
   3. Create users and assign licenses
   4. Set up the project management environment

Installation planning worksheet

The following table lists the installation options, and the considerations for each option.

Installation requirements

For an up-to-date list of minimum hardware and software requirements, go to http://www.ibm.com/support/docview.wss?uid=swg27017169.

Verify that your user ID meets the following criteria before you install the product:

• Your user ID must not contain double-byte characters.
• For Microsoft® Windows® operating systems, you must have a user ID that belongs to the Administrators group.
  Important:
  For Windows Vista, you must log in to the Administrator account to install or update the product. To enable users who are not the Administrator to work with a product on Windows Vista:

  • Install the product into a package group (installation location) that is outside of the Program Files directory (C:\Program Files\).
  • Choose a shared resources directory that is outside of the Program Files directory.
• For Linux®: You must be able to log in as root.

Installing Rational Project Conductor

Installing Rational Project Conductor on a new Jazz Team Server instance

Before you begin

You can install Rational Project Conductor from the installation media, or from a download package on https://jazz.net. Before you start the installation, either obtain the installation media or download the installation package. To complete the download, you must register and obtain a user name and password from https://jazz.net.

About this task

To install Rational Project Conductor on a Windows or Linux operating system:

Procedure

1. If you are using the installation media, insert the media into the disk drive. If you are using the download package, extract the files from the downloaded .zip package to a temporary directory.
2. Click the launchpad program to start the installation:
   • On Windows: Click launchpad.exe
   • On Linux: Click launchpad.sh
3. Click Install Rational Project Conductor. This opens the Install Packages page. If you are installing the product for the first time and IBM Installation Manager is not detected on your system or an incompatible version is installed, then you must install the latest release of Installation Manager.
4. When you are ready to begin installing Rational Project Conductor, ensure that the product name and version check boxes are selected. Click Next.
5. Read the license agreement. If you agree with its terms, accept the license agreement, and click Next.
6. Accept the default installation location for Installation Manager, and click Next.
7. On the Install Packages page, select Create a new package group. Modify the default Installation Directory, if required.
8. Click Next.
9. The default application server is Apache Tomcat.
   • To install Rational Project Conductor into a Tomcat environment, you do not need to make changes. The Tomcat application server that is configured to host the Jazz Team Server is installed.
   • To install Rational Project Conductor into an IBM WebSphere Application Server environment, clear the Tomcat Application server check box. The .war files are copied to the JazzInstallDir/server folder. Later you can manually deploy the .war files into the WebSphere Application Server environment.
     Note:
     If you install in a directory with a name that contains spaces, you must replace each space with %20 in your WebSphere Application Server and DB2 database configuration steps.
   The IBM Rational Project Conductor Server Activation Keys check box is selected by default.
10. Click Next.
11. Click Install.
12. A message confirms the completion of the process.
    • To verify the installation, click View Log File. The installation log file for the current session opens in a new window. To close the log file window and return to the installation wizard, click Close.
    • To close the installation wizard without verifying the installation, click Finish.

What to do next

Complete the next steps in the installation:

• If you are using the default Apache Tomcat server and Derby database, no additional steps are required. You can proceed to start the server.
• If you are using a database other than the default Derby database, set up the database.
• To use Websphere Application server as the application server, see Setting up and starting a WebSphere Application Server.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Installing Rational Project Conductor on an existing JazzTeam Server instance

Before you begin

1. Obtain the installation media or download the installation package from https://jazz.net. To complete the download, you must register and obtain a user name and password from https://jazz.net
2. Stop the JazzTeam Server and back up the existing database to protect your environment against data loss during the installation. If the installation is unsuccessful, you can restore this database backup.

About this task

Complete the installation by using IBM Installation Manager, and then verify the installation.

To install Rational Project Conductor on a Windows or Linux operating system by using the launchpad:

Procedure

1. Ensure that the JazzTeam Server is stopped.
2. If you are using the installation media, insert the media into the disk drive. If you are using the download package, extract the files from the downloaded .zip package to a temporary directory.
3. Click the launchpad program to start the package installation:
   • On Windows: Click launchpad.exe
   • On Linux: Click launchpad.sh
4. Click Install IBM Rational Project Conductor. This opens the Install Packages page. If the Installation Manager version is outdated, then you must install the latest version of Installation Manager.
5. When you are ready to begin the installation of Rational Project Conductor, ensure that the product name and version check boxes are selected. Click Next.
6. Read the license agreement. If you agree with its terms, accept the license agreement, and click Next.
7. On the Install Packages page, ensure that the Use the existing package group radio button is selected. Select the existing JazzTeam Server package group name. Click Next and continue through the rest of the installation process without making changes.
8. To begin the installation, click Install.
9. A message confirms the completion of the process.
   • To verify the installation, click View Log File. The installation log file for the current session opens in a new window. To close the log file window and return to the installation wizard, click Close.
   • To close the installation wizard without verifying the installation, click Finish.

What to do next

Add the IBM Rational Project Conductor database tables to the existing JazzTeam Server repository. For more information, see Adding database tables to an existing repository.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Performing silent installations

Visit the Installation Manager information center at http://publib.boulder.ibm.com/infocenter/install/v1r2/index.jsp and search for performing silent installations.

To perform silent installation, you must configure a response file that contains the data required to perform the silent installation. The IBM Rational Project Conductor installation media contains a sample response file rpc.responsefile.xml that is available at disk1/sample_response_files. You can configure this response file by specifying your preferences.

Post-installation tasks

Setting up the databases

If you installed IBM Rational Project Conductor into an existing package group, you must upgrade the existing repository to include the Rational Project Conductor database schema.

Setting up a DB2 database

Before you begin

You must complete the following prerequisite tasks before you can configure DB2.

• Review the DB2 documentation to verify that your system meets the requirements and is configured correctly.
• Install DB2 on a machine that is the database server. DB2 and the JazzTeam Server can be installed on separate machines.
• Verify that you have system administrator permissions for the DB2 database.
  Tip:
  On Linux, to get system administrator permissions for the database, run the command sudo db2fenc1 (db2fenc1 is the DB2 user), and at the command prompt, type bash.

About this task

To set up a DB2 database:

Procedure

1. Create the database in the DB2 Command Window. The example commands create a database called JAZZ. These commands run in the DB2 Command Window. The Command Window can be opened from the Start menu under the DB2 Command Line Tools menu.
   • On Windows:

     db2 create database JAZZ on c: using codeset UTF-8 territory en PAGESIZE 8192

   • On Linux:

     db2 create database JAZZ using codeset UTF-8 territory en PAGESIZE 8192

   Note:

   To ensure proper handling of Unicode content, the database character set must be UTF-8 encoding. Because the AUDITABLE_LINKS table does not fit in the default page size of 4 K on Windows, set the page size to at least 8 K.

   If the database is not running, use the command db2start to start DB2.

2. Locate the file teamserver.properties in the directory JazzInstallDir/server/conf/jazz and rename it to teamserver.derby.properties.
3. Locate the file teamserver.db2.properties in the directory JazzInstallDir/server/conf/jazz and rename it to teamserver.properties.
4. Specify the database and connection details in the file teamserver.properties.

   The default connection specification connects to a DB2 database that runs on localhost on port 50000. The database is called JAZZ, and both the user name and password are db2admin. If the default values were used when setting up your database, the teamserver.properties file might already be configured correctly. If not, change this information to match your configuration.

   1. Open the file teamserver.properties in a text editor.
   2. Locate the following lines:

      com.ibm.team.repository.db.vendor = DB2
      com.ibm.team.repository.db.jdbc.location=//localhost:50000/JAZZ:user=db2admin;password={password};
      com.ibm.team.repository.db.jdbc.password=db2admin

   3. Edit the value of com.ibm.team.repository.db.jdbc.location for your DB2 server and database.
      Tip:
      In the DB2 Command Window, run the command db2 get dbm cfg, then find the line that contains SVCENAME, which indicates the DB2 port name or number. If this command displays a number, use it as the port number (in place of 50000 in the example above). If the command returns a non-numeric name, determine what port number was assigned for this name and use that port number. On Linux, the file /etc/services contains the mapping between port names and numbers,. and on Windows, the file C:\windows\system32\drivers\etc\services contains the mapping. For more information, ask your database administrator or consult the database documentation.
      Note:
      The DB2 user must have permissions to create tables, tablespaces, and modify the database configuration. DB2 users are created by the operating system.
   4. Specify the user password in the property com.ibm.team.repository.db.jdbc.password.
      Note:
      Do not change the password={password} text in the com.ibm.team.repository.db.jdbc.location property.
   5. If necessary, change the property com.ibm.team.repository.db.db2.content.tablespace.location to a path on your Jazz Team Server where the main table space can be created.
      Note:
      If this value is not changed from the default of content_tablespace, the table space is created under the database storage location. On Windows, if a new path is specified, it must be specified by using double backslashes, for example: com.ibm.team.repository.db.db2.content.tablespace.location=c:\\db2\\jazz\\content_tablespace.

What to do next

You have finished setting up your database and can continue with Creating database tables.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Setting up an Oracle database

Before you begin

Ensure that the following prerequisites are met. Consult your Oracle documentation or an Oracle database administrator (DBA) for help.

• Oracle is installed on a machine to be used as the database server. This machine can be a different one from that on which the JazzTeam Server runs.
• A default database exists on the Oracle server.
  Tip:
  When you install Oracle, you have the option to create a database automatically.
  Important:
  To ensure proper handling of Unicode content, the database character set must be UTF-8 encoding.
• The user who performs these instructions has system administration authority on the Oracle database.

When running JazzTeam Server on Oracle, create an Oracle tablespace to improve performance. You must create a user linked to that tablespace.

About this task

To set up an Oracle database:

Procedure

1. Create a tablespace. The tablespace location must be appropriate to the machine and disk drive.
   Note:
   The tablespace can have any of these properties:

   • A name other than oracle_tbs
   • A location in another directory
   • A size larger than 1GB. For large installations, you need to allocate more space.
   The example below shows a create statement executed on a Windows machine:

   CREATE BIGFILE TABLESPACE oracle_tbs DATAFILE 'D:\oracle_tbs\oracle_tbs.dbf' SIZE 1G AUTOEXTEND ON EXTENT MANAGEMENT LOCAL AUTOALLOCATE;

   Important:
   The directory path (in this example D:\oracle_tbs) must exist. It is not necessary to create a separate special tablespace. You can use the Oracle default USERS tablespace, but Oracle performs better with a pre-allocated space on the disk that it manages.
2. Create an Oracle user.

   After the tablespace is created, a special Oracle user must be created for Jazz to use the Oracle database.

   In this example, the user has the name jazzDBuser and password (IDENTIFIED BY in Oracle terms) jazzDBpswd and exists in the tablespace created in 1.

   CREATE USER jazzDBuser IDENTIFIED BY jazzDBpswd DEFAULT TABLESPACE oracle_tbs;

   After the user is created, the user should be given the necessary permissions needed to initialize the Jazz database. The following SQL commands can be used to grant the appropriate permissions:

   GRANT CREATE SESSION TO jazzDBuser;
   GRANT CREATE TABLE, ALTER ANY TABLE, DROP ANY TABLE, CREATE ANY INDEX, ALTER ANY INDEX, DROP ANY INDEX TO jazzDBuser;
   GRANT INSERT ANY TABLE, UPDATE ANY TABLE, DELETE ANY TABLE TO jazzDBuser;
   GRANT CREATE PROCEDURE TO jazzDBuser;
   GRANT CREATE VIEW TO jazzDBuser;

3. Locate the file teamserver.properties in the directory JazzInstallDir/server/conf/jazz and rename it to teamserver.OtherDBProvider.properties.
4. Locate the file teamserver.oracle.properties in the directory JazzInstallDir/server/conf/jazz and rename it to teamserver.properties.
   Tip:
   Renaming the original teamserver.properties file enables you to restore the file to the previous working version. By default, the DB Provider is derby.
5. Configure the server
   1. Edit the server configuration file if you used a different user name, password, or db name, installed Oracle server on a different machine than JazzTeam Server, or are using a port other than the default. Open the file teamserver.properties in JazzInstallDir/server/conf/jazz directory, and change the information listed below to match your setup.

      com.ibm.team.repository.db.vendor = ORACLE

      com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@localhost:1521/ORCL

      Change jazzDBuser with the user created for Jazz to use the Oracle database. If you are using localhost, uncomment this line by removing # from the beginning of the line and comment the next location line. Localhost connection strings should not include the preceding //. Change 1521 with your Oracle server machine TCIP port. Change ORCL with your Oracle database name.

      com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@//oracleserver.example.com:1521/ORCL

      Remember:
      Oracle location URLs can take several forms. The examples here work under most circumstances. Consult the Oracle JDBC documentation for more details.

      If you are using a non-localhost connection, uncomment this line by removing the # from the beginning of the line and comment the previous location line. Non-localhost connection strings must include the preceding //.

      com.ibm.team.repository.db.jdbc.password=jazzDBpswd

      Change jazzDBpswd with the password of the user created for Jazz to use the Oracle database.

      Important:
      Do not change the {password} text in the property com.ibm.team.repository.db.jdbc.location. The user password must be specified in the property com.ibm.team.repository.db.jdbc.password.

      If you are using Oracle Express, use 1521 for TCIP port and XE for Oracle database name:

      com.ibm.team.repository.db.vendor = ORACLE
      com.ibm.team.repository.db.jdbc.location=thin:jazzDBuser/{password}@localhost:1521/XE
      com.ibm.team.repository.db.jdbc.password=jazzDBpswd

   2. In the same directory as the server scripts (JazzInstallDir/server), create a directory named oracle.
   3. Locate the Oracle JDBC driver JAR file, named ojdbc14.jar. The location can vary depending on the Oracle product and operating system. Copy this file to the directory named oracle.
      Note:
      If you are using WebSphere Application Server, configure a property named "ORACLE_JDBC"; then set it to the absolute file path (not URL) to the Oracle JDBC drivers. This task is described in the WebSphere Application Server setup instructions. Make a note of the file path for later use in these instructions.
6. Open a SQL plus window and type the following command:

   GRANT DBA TO jazzDBuser;

What to do next

You have finished setting up your database and can continue with Creating database tables.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Setting up a SQL Server database

This procedure assumes that the following prerequisites have been met:

• You have SQL Server installed
• SQL Server service is started
• You have the SQL Server JDBC drivers installed. For more information, go to the Microsoft Developer Network Web site at http://msdn.microsoft.com/ and search for "Microsoft SQL Server JDBC Driver".
• The TCP protocol is enabled for SQL Server
• The user who creates the DB table must have one of the following permissions:
  • A membership in the sysadmin fixed server role, or ownership of the database (dbo)

Setting up a database

This section describes how to set up the SQL Server database by using the command line tool sqlcmd, which is provided with the SQL Server installation. You can also use a visual tool, such as SQL Server Studio Management, which is also available for the Express™ version as SQL Server Studio Management Express. See the SQL Server documentation or an SQL Server database administrator (DBA) for more information.

To set up an SQL Server database by using the command tool sqlcmd:

1. Create a JazzTeam Server database. From the command line tool, type:

   CREATE DATABASE jazz 
   GO 

2. Create a user and password and change the ownership of the JazzTeam Server database. From the command line tool, type:

   CREATE LOGIN jazzDBuser
   WITH PASSWORD = 'jazzDBpswd';
   USE jazz;
   exec sp_changedbowner 'jazzDBuser'
   GO 

3. Change the collation of the JazzTeam Server database. From the command line tool, type:

   ALTER DATABASE jazz COLLATE SQL_Latin1_General_CP437_CS_AS 
   GO

Configuring the server

To configure the server:

1. Rename the following files:
   • Rename the JazzInstallDir/server/conf/jazz/teamserver.properties file to teamserver.OtherDBProvider.properties
   • Rename the teamserver.sqlserver.properties file to teamserver.properties
   Tip:
   Renaming the original teamserver.properties file enables you to restore the file to the previous working version. By default, the DB Provider is derby.
2. Edit the server configuration file if you used a different user name, password, or db name, installed SQL server on a different machine than JazzTeam Server, or are using a port other than the default. Open the file teamserver.properties in JazzInstallDir/server/conf/jazz directory, and change the information listed below to match your setup.

   com.ibm.team.repository.db.vendor = SQLSERVER
   com.ibm.team.repository.db.jdbc.location=//SQL SERVER MACHINE IP:SQL SERVER TCIP PORT;databaseName=JAZZ DATABASE NAME;user=JAZZ USERNAME;password={password}
   com.ibm.team.repository.db.jdbc.password=JAZZ LOGIN PASSWORD

   Important:
   Do not change the password={password} text in the property com.ibm.team.repository.db.jdbc.location. The user password must be specified in the property com.ibm.team.repository.db.jdbc.password.

To specify the jar file location for JDBC:

1. In the same directory as the server scripts (JazzInstallDir/server), create a directory named sqlserver.
2. Locate the SQL Server JDBC driver JAR file, named sqljdbc.jar. The location can vary depending on where the drivers were installed, as noted in the prerequisites section. Copy the file into the newly created sqlserver directory.
3. Specify the JDBC JAR file location for JDBC by completing the following task:
   • Set up the environment variable SQLSERVER_ABSPATH to point to the directory that contains the JAR file. If the path contains space characters, you must include them with quotations.
     Tip:
     If you use WebSphere Application Server, configure a property named SQLSERVER_JDBC; then set it to the absolute file path (not URL) to the SQL Server JDBC drivers directory. For more information, see the WebSphere Application Server setup instructions. Note the file path for later use in these instructions.

What to do next

You have completed setting up your database. Now, create the database tables. For more information, see Creating database tables.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Troubleshooting

If the repotools command does not succeed, check the log file named repotools_createTables.log, located in the JazzInstallDir/server directory.

Also, verify the following:

• The SQL Server is configured to allow connections using the TCP/IP protocol. If required, restart the SQL service.
• The SQL Server machine host name, and the port is correctly reflected in the teamserver.properties file.
• The login name, password, and database name are properly reflected in the teamserver.properties file.
• A firewall does not prevent you from accessing the SQL Server. Use a telnet command to telnet to the machine using hostname and port from the teamserver.properties file.
• The created user has proper permissions in the JazzTeam Server database.

Creating database tables

Before you begin

Before you can run this command, stop the database server.

About this task

The repotools file is located in JazzInstallDir/server.

The command uses the configuration properties in teamserver.properties for the connection and size settings. By default, the command looks in the current directory. The parameters in the teamserver.properties can be modified to reference the appropriate database.

To create the database tables:

Procedure

1. Run the command repotools -createTables to create the database tables for a Rational Project Conductor repository.
   • On Windows:

      repotools -createTables

   • On Linux:

     ./repotools.sh -createTables

2. After the database tables are created, stop and restart the database.

What to do next

• If you are using the default Apache Tomcat server, your installation is complete, and you can now proceed to start the server.
• If you want to use the WebSphere Application Server, set up and start the WebSphere Application Server

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Adding database tables to an existing repository

Before you begin

Before you can run this command, stop the database server.

About this task

The repotools file is located in JazzInstallDir/server.

The command uses the configuration properties in teamserver.properties for the connection and size settings. By default, the command looks in the current directory. The parameters in the teamserver.properties can be modified to reference the appropriate database.

To add the database tables to an existing repository:

Procedure

1. Run the command repotools -addTables to add the database tables for Rational Project Conductor to the existing repository:
   • On Windows:

      repotools -addTables

   • On Linux:

     ./repotools.sh -addTables

   Note:
   There may be exceptions displayed when this command is run. You can ignore these exceptions since the database is created successfully.
2. After the database tables are added, stop and restart the database.

What to do next

You can now proceed to start the server.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Setting up and starting the server

About this task

If you plan to use the included Apache Tomcat application server, you are ready to start the Jazz Team Server. If you plan to use the WebSphere Application Server, set up your server environment as described in Setting up and starting a WebSphere Application Server.

Starting the Apache Tomcat server

Before you begin

Before you start the server, review the following requirements:

• If you installed IBM Rational Project Conductor into an existing package group, or updated an existing installation, clear the Apache Tomcat cache. To clear cache, delete the catalina folder from the path JazzInstallDir/server/tomcat/work.
• If you want to run the start and stop scripts from any other directory, you must change the profiles.ini file in JazzInstallDir/server/provision_profiles to use an absolute path.
• Apache Tomcat is configured to use the ports 9080 and 9443 in the JazzInstallDir/server/tomcat/conf/server.xml file. If necessary, change them as appropriate for your system. You cannot install Rational Project Conductor on a server when you have other Jazz-based products running. Ensure that you change the connector on a different port. Also, if necessary, update the configuration settings of Jazz server Repository HTTP ports in the Advanced Properties configuration page of the Jazz Admin Web UI.
• The directory JazzInstallDir/server/tomcat/logs contains the server log files. If you have trouble starting the server, check the log files.

Starting the server on Windows

About this task

To start the server:

Procedure

1. From the JazzInstallDir/server directory, run the following command:

   server.startup.bat

   Note:
   A separate Apache Tomcat console window opens. Do not close this window or the server will stop working. Also, several informational messages launch, including a message about the Apache Tomcat Native Library. These informational messages do not affect the IBM Jazz Team Server functionality.
2. To stop the server, from the JazzInstallDir/server directory, run the following command:

   server.shutdown.bat

What to do next

These tasks run the start and stop scripts directly from the directory JazzInstallDir/server. Also, you can run the commands from the Jazz Team Server Windows start menu.

After the server is started, proceed to Testing and configuring the server.

Starting the server on Linux

About this task

To start the server:

Procedure

1. From the JazzInstallDir/server directory:
   • If you are logged in as the root user, run the following command:

     ./server.startup

   • If your user ID has administrator access, run the following command:

     sudo ./server.startup

   A separate Apache Tomcat console window is not visible. You can check the server startup progress by viewing the log file at JazzInstallDir/server/tomcat/logs/catalina.out.
2. To stop the server, from the JazzInstallDir/server directory:
   • If you are logged in as the root user, run the following command:

     ./server.shutdown

   • If your user ID has administrator access, run the following command:

     sudo ./server.shutdown

   This example runs the start and stop scripts directly from the directory JazzInstallDir/server. If you installed IBM Jazz Team Server by using JazzTeam Server, you can also run the commands from the Start menu in the JazzTeam Server application.

What to do next

After the server is started, proceed to Testing and configuring the server.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Setting up and starting a WebSphere Application Server

Before you begin

Ensure that the following criteria are met:

• Verify that a supported version of WebSphere Application Server is installed. For information about supported versions, see Installation requirements.
• Ensure that the database is created and the teamserver.properties file is updated with your database settings.
• Ensure that the WebSphere Application Server security setting "Use available authentication data when an unprotected URI is accessed" is selected. If you are using the WebSphere Integrated Solutions Console, perform the following steps:
  • Navigate to Security -> Secure administration, applications, and infrastructure -> Web Security - General Settings.
  • Select the check box for Use available authentication data when an unprotected URI is accessed.
• If you installed Rational Project Conductor into an existing package group, or updated an existing installation, clear the server cache. To clear cache, delete the folders temp and wstemp from the path WASInstallDir\profiles\AppSrv01\.On Windows, also clear the contents at the directory location C:\Documents and Settings\<User name>\Local Settings\Application Data\IBM\IBM Information Server console.

About this task

You can configure WebSphere Application Server as your application server even if you have installed Rational Project Conductor with the default Tomcat application server option. In this scenario, the steps for setting up WebSphere Application Server are the same, except that when the jazz.war file is deployed, you must navigate to the jazz.war file that is located within the Tomcat installation directory.

To set up a WebSphere Application Server:

Procedure

1. Verify or update the WebSphere Application Server level.

   Rational Project Conductor requires WebSphere Application Server Version 6.1 with the IBM Java™ SDK 1.5 SR5 or later fix pack applied. Use the IBM Java SDK 1.5 SR6 SDK update that is available from http://www-01.ibm.com/support/docview.wss?rs=180&uid=swg27009393 and select fix pack V6.1.0.25 or later. With WebSphere 6.1 and the GA IBM Java SDK, Rational Project Conductor starts to report "proxy errors" after some number of operations.

   You must obtain the corresponding WebSphere Application Server interim fixes for fixes to IBM Java SDK 1.5 SR9 or IBM Java SDK 1.6 SR4 that are necessary for Rational Project Conductor to run correctly. Otherwise, some services in the server might not start correctly. The interim fixes are available under their corresponding WebSphere Application Server APARs. For IBM Java SDK 1.5/WebSphere Application Server 6.1, the APAR is PK85942 and you can download the files from ftp://ftp.software.ibm.com/software/websphere/appserv/support/fixes/PK85942/. Install at least WebSphere Application Server 6.1 fix pack 25 before installing the JRE interim fix.

2. Update the JVM arguments which can be set to control some aspects of the server behavior. The following list contains the specifics of setting these JVM properties in the administrative console, substitute JazzInstallDir with your Rational Project Conductor installation directory:
   1. Click Servers -> Application Servers.
   2. Click server1.
   3. Click Java and Process Management -> Process Definition.
   4. Click Java Virtual Machine.
   5. Add the value 100 to the Initial Heap.
   6. Add the value 1500 to the Maximum Heap Size.
   7. Click Apply.
   8. Click Custom Properties.
   9. Add the following properties: Click New, enter the Name and Value, and then click OK.

      Name: java.awt.headless. Value: true

      Name: org.eclipse.emf.ecore.plugin.EcorePlugin.doNotLoadResourcesPlugin. Value: true

      Name: JAZZ_HOME Value: file:///JazzInstallDir/server/conf

   10. Click Save directly to the master configuration.
3. Set up the required global WebSphere Application Server instance properties, and activate the proper security settings.
   1. In the WebSphere Application Server Admin Console, in the left menu, expand the Security group, and click Secure administration, applications, and infrastructure Servers.
   2. Ensure that the following security settings are configured as shown below:
      • Enable administrative security is "on"
      • Enable application security is "on"
      • Java 2 security is "off" for all three options
   3. Save the master configuration.
4. Set up LDAP as the user authentication method. Rational Project Conductor requires that LDAP authentication is configured to perform authorization and personalize the application.
   • To configure WebSphere Application Server for LDAP-based configuration, see http://jazz.net/library/technote/96.
5. Restart WebSphere Application Server.

   On Windows, the default value for WebSphere installation directory is:

   C:\Program Files\IBM\WebSphere\AppServer

   You can restart the server with the following commands on Windows:

   cd WASInstallDir\bin 
   stopServer.bat server1 [for a secure server, include: -username {LDAP_User} -password {LDAP_Password}] 
   startServer.bat server1

   On Linux, the default value for WebSphere installation directory is:

   /opt/IBM/WebSphere/AppServer

   You can restart the server with the following commands on Linux:

   cd WASInstallDir/bin 
   ./stopServer.sh server1 [for a secure server, include: -username {LDAP_User} -password {LDAP_Password}] 
   ./startServer.sh server1

6. Now, install the Rational Project Conductor application.
   1. Open the Admin console for your WebSphere Application Server.
   2. Click Applications -> Install New Application.
   3. Under Path to new Application, click Local file system.
   4. Under Full path, browse to the location of the jazz.war in your file system. For example, JazzInstallDir/server/jazz.war. If Tomcat is already set up as the Rational Project Conductor application server, then browse to the jazz.war file at JazzInstallDir/server/tomcat/webapps/jazz.war
   5. Set Context Root as /jazz.
   6. Select the option Show me all installation options and parameters.
   7. Click Next and continue until Step 6: Map virtual hosts for Web modules.
   8. In step 6: Map Virtual Hosts, select the Mapping to the default host check box. Click Next, and continue until Step 8: Map Security roles to users or groups.
   9. In Step 8: Map Security roles to users or groups, map the Jazz roles to the WebSphere user groups.
      • Select the check box for the Jazz group you want to map.
      • Click Look up groups. If the WebSphere users are not mapped to groups, then click Look up users, and map the roles to users.
      • Search for the available groups or users. To search for groups, you can use wildcard characters to search for Jazz*
      • Click the >> button to select the corresponding group, and click OK.
      • Perform these mapping steps for all the Jazz roles.
   10. Click Next and then click Finish.
   11. Click Save directly to the master configuration.
7. Deploy the help.war file for the Rational Project Conductor online help to be available. The steps are a subset of the procedure to deploy the jazz.war detailed in step 6 :
   1. In the Admin console, click Applications -> Install New Application
   2. Under Path to new Application, click Local file system.
   3. Under Full path, browse to the location of the help.war in your file system. For example, JazzInstallDir/server/help.war.
   4. Set Context Root as /help.
   5. Click Next and continue through the remaining Install New Application steps.
   6. Click Finish.
   7. Click Next and then click Finish.
   8. Click Save directly to the master configuration..
8. Start the applications you installed.
   1. Click Applications -> Enterprise Applications.
   2. Select the check boxes for jazz_war and help_war, and click Start.

      A green arrow should appear indicating the application started successfully.

What to do next

After the server is started, proceed to Testing and configuring the server.

Alternatively, return to the Installation roadmaps to review the next steps in the installation.

Testing and configuring the server

Before you begin

To verify that the IBM Jazz Team Server is connecting to the database, look at the server log or console output. The connection and database information are echoed on its first access. The directory JazzInstallDir/server/tomcat/logs is used for the server log files.

This procedure assumes that your server is available using the host name localhost and the default port 9443. If necessary, replace localhost with your server host name.

The server setup wizard is available at https://localhost:9443/jazz/setup. If the server setup wizard does not load, check the following items:

• Verify that the application server has started. Use the URL http://localhost:9080.
• Verify that the JazzTeam Server has started by logging in to the JazzTeam Server Admin Web UI using the URL https://localhost:9443/jazz/admin. If the page does not load or the server has errors, the server did not start correctly.
• The URI root for the JazzTeam Server path must be /jazz. For example, https://example.com:9443/jazz must be used rather than https://example.com:9443.

About this task

To configure and test the server:

Procedure

1. Open the setup wizard by typing the URL https://localhost:9443/jazz/setup.

   The default user name and password are case sensitive:

   • User name: ADMIN
   • Password: ADMIN

   If you configured the LDAP directory Web container, log in with a JazzAdmin user that is defined in your LDAP directory.

2. Choose a setup path. The setup wizard has the following two main paths
   • The Fast Path Setup uses the default configuration. If you want to get the server running quickly, use the Fast Path Setup option. You can use the Fast Path Setup to specify the LDAP connection parameters. For more information on specifying the LDAP paramaters, see Setting up the LDAP connection parameters
   • The Custom Setup guides you through the detailed server configuration, including the ability to enable e-mail notifications. During the Custom Setup, you can set up the following items:
     • Database
     • E-mail notification
     • User registry
3. By default the Disable default ADMIN access check box is selected. After you create a new user with JazzAdmin rights, the default ADMIN user is disabled. This is a security feature. Disable this check box if you want to retain the default ADMIN user.
   Note:
   If you retain the default ADMIN user, you must assign a IBM Rational Project Conductor Client Access License to the user. If no license is assigned, the default ADMIN user cannot perform any project management tasks. For information about assigning licenses, see Creating users and assigning licenses.
4. When the initial setup is complete, additional options can be configured from the JazzTeam Server Admin Web user interface by using the URL https://localhost:9443/jazz/admin.

Setting up the LDAP connection parameters

About this task

Use the setup wizard to perform this task. For more information about the setup wizard, including troubleshooting options if the setup wizard does not load, see Testing and configuring the server.

Procedure

1. Start the setup wizard to perform this task. Use the URL https://localhost:9443/jazz/setup.

   You can log in with the default user name and password:

   • User name: ADMIN
   • Password: ADMIN

   If you configured the LDAP directory Web container, log in with a JazzAdmin user that is defined in your LDAP directory.

2. Click Fast Path Setup.
3. In the Setup User Registry page, select LDAP as the user registry type. Enter the LDAP configuration parameters. For more information, see Managing users with Lightweight Access Directory Protocol (LDAP) in the IBM Rational Team Concert Information Center.
   Important:
   By default, the "Disable default ADMIN access" check box is selected. After you create a new user with JazzAdmin rights, the default ADMIN user is disabled. This action is a security feature. Disable this check box if you want to retain the default ADMIN user.

Creating users and assigning licenses

Before you begin

You must be logged in to the Admin Web UI and be a member of the JazzAdmins group.

About this task

When creating a user, you assign a name, user ID, e-mail address, repository groups, and client access licenses to the user. Optionally, you can add a photo of the user. Regardless of where you create the user, the user resides in the repository and is available to be added to any project area or team area in the repository.

To create a user:

Procedure

1. In the Admin Web UI, click the User Management tab.
2. Select the Active Users page; then click Create User.
3. Complete the following fields:
   • In the User Name field, type a user name.
   • In the User ID field, type a unique user identifier.
   • In the E-mail Address field, type an e-mail address.
4. In the Repository Permissions section, select the appropriate user permissions: You can assign one or more following repository groups to the user:
   • JazzAdmins: Administrators of a Jazz repository with full read-write access.
   • JazzDWAdmins: Administrators of a Jazz repository with specific permissions to control the data warehouse on a Jazz Server.
   • JazzGuests: Users with read-only access to the Jazz repository.
   • JazzUsers: Users with regular read-write access to the Jazz repository.
5. In the Client Access Licenses section, select the appropriate license type. You can assign the following licenses:
   • IBM Rational Project Conductor- Project Manager
   • IBM Rational Project Conductor- Project Team
   • RTC family Rational Team Concert- ClearQuest Connector
   Remember:
   You must assign the Project Manager license to atleast one user, for that user to log in and complete the project management environment setup. For more information about setting up the project management environment, see Setting up the project management environment.
6. You can also create users first, and assign licenses later. To assign licenses to existing users (including the default ADMIN user), in the User Management page, click Client Access License Management.
   1. To assign the Project Team license, click the IBM Rational Project Conductor- Project Team tab, click Assign Project Team License. Select the user, and click Add.
   2. To assign the Project Manager license, click the IBM Rational Project Conductor- Project Manager tab, click Assign Project Manager Licenses, select the user, and click Add.
7. Click Save.

Setting up the project management environment

Before you begin

1. You must complete the server setup.
2. You must be a member of the JazzAdmins group.
3. You must have a IBM Rational Project Conductor - Project Manager license assigned.

Procedure

1. Log in to https://localhost:9443/jazz/epmWeb with the admin user credentials. If you are logging in as the default admin user, use the following credentials:
   • User name: ADMIN
   • Password: ADMIN
2. The Set up project management environment page opens. Click Configure environment. The process takes a few minutes to complete. This deploys the project management process templates, and creates the Project Management Administration area where you can configure project management options such as calendars, rates, skills, and competencies.
   Note:
   You perform this step only once in an installation instance. After you complete this step, the same URL takes you to the Rational Project Conductor login page.
3. Log out from the server.

What to do next

To configure users, roles, and permissions, and to set up project management data, log in to the JazzTeam Server Admin interface. Use the URL https://localhost:9443/jazz/rpc/admin. To get started with creating programs and projects, log in to Rational Project Conductor. Use the URL https://localhost:9443/jazz/epmWeb.

Upgrading to a new release

Before you begin

If you want to upgrade your installation by using the installation package, download the package from https://jazz.net. To download the package, you must register and obtain a user name and password from https://jazz.net.

Procedure

1. Stop the Jazz Team Server.
2. Export the database by using repotools. In the command prompt window, change the directory to JazzInstallDir/server. Type the following command:

   repotools.bat -export toFile=./file_name.tar

3. Update the installation by using either of the following options:
   1. To update the installation by using the Installation Manager update option:
      1. Start Installation Manager. Click Update.
      2. Select the Jazz Team Server instance on which Rational Project Conductor is installed. Click Next. Installation Manager searches for and displays the available updates.
      3. Click Update. A message confirms the completion of the process.
   2. To update the installation by using the download package:
      1. Extract the contents of the upgrade package to a folder in your computer or to a shared location.
      2. Start Installation Manager. Click File -> Preferences.
      3. In the left menu bar, ensure that Repositories is selected. Click Add Repository, and specify the repository location as Upgrade folder location/disk1/diskTag.inf. For example, C:/Documents and Settings/User name/My Documents/ProductRelease_nn/disk1/diskTag.inf. Click OK. Close the Preferences window.
      4. In Installation Manager, click Update .
      5. On the Update Package page, select the existing package group name, click Next, and then click Update. A message confirms the completion of the process
4. From the JazzInstallDir/repotools/eclipse/configuration directory, remove the folders org.*. Multiple folders are deleted.
5. Import the repository data from the exported file by using repotools. In the command prompt window, change the directory to JazzInstallDir/server. Type the following command:

   repotools -import fromFile=./file_name.tar

   When you are prompted to decide whether you want to drop the existing database and overwrite it, click Yes. A message confirms the successful completion of the process.
6. Clear the server cache.
   • On Tomcat, delete the folder catalina from the path JazzInstallDir/server/tomcat/work
   • On WebSphere Application Server, from the path WASInstallDir/profiles/AppSrv01, delete the folders temp and wstemp. On Windows, also clear the contents of the directory location C:\Documents and Settings\<User name>\Local Settings\Application Data\IBM\IBM Information Server console\
7. Start the Jazz Team Server.

Installing or upgrading to Version 1.0.0.1

Installation resources

To complete the installation, you need the download packages and Installation Manager. Installation Manager is installed when you install Rational Project Conductor 1.0.

The download packages are available as .zip archives at https://jazz.net/downloads/rational-project-conductor/.

Directly installing version 1.0.0.1

If you are installing Rational Project Conductor for the first time, you can directly install version 1.0.0.1 by using any of the following installation options:

• Installing versions 1.0 and 1.0.0.1 from locally available download packages (offline)
• Installing version 1.0 from a locally available download package or media, and installing version 1.0.0.1 by using the IBM Update site (offline and online)

During the installation, you can also select the option to install Rational Project Conductor, Version 1.0.0.1 in an existing Rational Team Concert, Version 2.0.0.2 instance.

Installing versions 1.0 and 1.0.0.1 from locally available download packages

1. Download the Rational Project Conductor 1.0 and 1.0.0.1 installation packages, and extract the files to separate directories.
2. Start Installation Manager. Click File -> Preferences.
3. In the left menu bar, ensure that Repositories is selected. Click Add Repository, and specify the repository location as 1.0 folder location/disk1/diskTag.inf. Repeat this step to add a repository location for the 1.0.0.1 folder. Click OK.
4. Install versions 1.0 and 1.0.0.1.
   Note:
   To install Rational Project Conductor into an existing Rational Team Concert, Version 2.0.0.2 instance, on the Install Packages page, select the option to install in an existing package group, and select the IBM Jazz Team Server instance for Rational Team Concert.

Installing version 1.0 from a locally available download package or media, and installing version 1.0.0.1 by using the IBM Update site

1. Download the Rational Project Conductor 1.0 installation packages, and extract it to a local directory. If you are using the 1.0 media, ensure that the media contents are on your computer.
2. From the 1.0 package directory or media, start the installation by clicking the launchpad file. If Installation Manager is not already installed on your computer, it is installed.
3. On the Install Packages page, click Check for Other Versions and Extensions. Version 1.0.0.1 is shown as available for installation from the IBM Update site.
4. Select Version 1.0.0.1 and complete the installation.
   Note:
   To install Rational Project Conductor into an existing Rational Team Concert, Version 2.0.0.2 instance, on the Install Packages page, select the option to install in an existing package group, and select the IBM Jazz Team Server instance for Rational Team Concert.

Upgrading to version 1.0.0.1

If you have an installed Rational Project Conductor, Version 1.0, you can upgrade your installation to Version 1.0.0.1. For information about upgrading to Version 1.0.0.1, see Upgrading to a new release.

Upgrading to Rational Project Conductor, Version 1.0.0.1, and Rational Team Concert, Version 2.0.0.2

If you installed Rational Project Conductor, Version 1.0 in an Rational Team Concert, Version 2.0 instance, you can upgrade both installations.

• Upgrade by using locally available download packages (offline)
• Upgrade by using the IBM Update site (offline and online)

Upgrading by using locally available download packages:

1. Download the Rational Project Conductor, Version 1.0.0.1 and Rational Team Concert, Version 2.0.0.2 installation packages, and extract the files to separate directories.
2. Start Installation Manager. Click File -> Preferences.
3. In the left menu bar, ensure that Repositories is selected. Click Add Repository, and add repository locations for the Rational Project Conductor and Rational Team Concert upgrade package folders. Click OK.
4. Click Update, and select Rational Team Concert for update. If the Rational Project Conductor update is selected, clear the selection.
   Note:
   You must update the Rational Team Concert installation first because the Rational Project Conductor update process checks for a compatible version of Rational Team Concert.
5. After the Rational Team Concert update is complete, select the Rational Project Conductor update, and complete the update.

Upgrading by using the IBM Update site

1. Start Installation Manager. Click Update.
2. Select Rational Team Concert for update. If the Rational Project Conductor update is selected, clear the selection.
3. After the Rational Team Concert update is complete, select the Rational Project Conductor update, and complete the update.
4. From the JazzInstallDir/repotools/eclipse/configuration directory, remove the folders org.*. Multiple folders are deleted.

Logging in to Rational Project Conductor

About this task

To log in to Rational Project Conductor:

Procedure

1. In your Web browser, type https://localhost:9443/jazz/epmWeb.
2. Enter your user name and password. Click OK.
3. You can now work with programs and projects. For assistance, click the Help icon and click Help Contents.

What to do next

To manage your work items or access the change management area:

1. In your Web browser, type https://localhost:9443/jazz/web
2. Enter your user name and password. Click OK.
3. Select your project area. You can now query and retrieve your work items and create new work items.

Uninstalling Rational Project Conductor

Before you begin

Stop the server before you start the uninstallation.

About this task

With the Uninstall Packages option in IBM Installation Manager, you can uninstall the packages from a single installation location.

To uninstall Rational Project Conductor

Procedure

1. Log in to the computer using the same user account that you used to install the product packages. To start the uninstallation, use any of the following options:
   • Start Installation Manager, and click Uninstall.
   • From the JazzInstallDir/uninstall directory, double-click uninstall.bat.
2. Select the packages that you want to remove.
   • If you installed Rational Project Conductor into a Jazz Team Server package group, then ensure only the Rational Project Conductor check box is selected.
3. Click Next and then click Uninstall.
4. After the successful uninstallation page is displayed, to view the log file, click View Log file.

What to do next

The installer does not remove the user-created data. You must delete this data manually. Do not delete the data if you want to point to the same data during reinstallation of the product.

• If you are uninstalling a stand-alone instance of Rational Project Conductor, delete the JazzInstallDir.
• If you are uninstallingRational Project Conductor from a JazzTeam Server package group, then from the JazzInstallDir/server directory, delete the following folders:
  • RPC-cal-license-update-site
  • RPC-update-site

You can uninstall Installation Manager if you do not have any other product packages installed.

Notices

© Copyright IBM Corporation 2009, 2010. All Rights Reserved.

U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject to change before the products described become available.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

Copyright license

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. 2009, 2010.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Trademarks and service marks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.shtml.

• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
• Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.
• Other company, product, or service names may be trademarks or service marks of others.