Upgrading from Version 7.1.1.1 or earlier on WebSphere Application Server

Use this guide to upgrade from a version 7.1.1.1 or earlier of IBM® Rational® Asset Manager on IBM WebSphere® Application Server.

Before you begin

Important:

Because Rational Asset Manager, Version 7.5.1.2 and later does not support versions of WebSphere Application Server earlier than 7.0, to upgrade from Rational Asset Manager, Version 7.1.1.1 or earlier, you must first upgrade to Rational Asset Manager, Version 7.5.1.1.

Additionally, you must install IBM Rational Team Concert™, which requires its own application server instance – you cannot install Rational Team Concert to a cluster – and an additional database.

You must upgrade your license server and file a request for updated license keys. For more information about the required version of Rational License Server, see Installing Rational License Key Server.

You will also have to stop and restart your application server several times.

You can also configure an existing Rational Team Concert server to work with Rational Asset Manager. The server setup application handles the configuration. You must know the user name and password for the Rational Team Concert server administrator.

If you have Internet access, you can use IBM Installation Manager to locate and install the updates directly from the IBM update repository for Rational Asset Manager.

Important: When Rational Asset Manager installs, the location of its update repository is automatically embedded in Installation Manager. For Installation Manager to search the default update repository, the Search the linked repositories during installation and updates preference on the Repositories preferences page must be selected; this preference is selected by default.

To install the fix pack from a different repository location (for example, if the update is on a shared drive or HTTP or HTTPS server), add the repository location in Installation Manager. To add a repository location, see Setting installation repository preferences in Installation Manager.

To work with Installation Manager, you must use a graphical user interface (GUI). If you do not have access to a GUI, you must install silently over the command line with response files. For more information, see the IBM Installation Manager online help and Installing silently with Installation Manager.

About this task

This outline shows what you must do to upgrade to the latest version of Rational Asset Manager:

Prepare to upgrade by making backups and configuring your application server: steps 1–5.
If you are using a WebSphere Application Server Network Deployment cluster, create a stand-alone application server instance on your cluster for Rational Team Concert™: step 7.
If you are using Oracle, copy the additional JDBC .jar files: steps 6–7.
If you are using the embedded WebSphere Application Server, stop the server.
Upgrade your license server to Rational Common Licensing V8.1.2: step 8.
Retrieve the application files for the latest version of Rational Asset Manager and deploy the server setup application: steps 9–10.
Use the server setup application to update the other Rational Asset Manager applications: steps 11–14.
If you need Rational Team Concert, deploy Rational Team Concert to your server and create a database: steps 19–15.
Restart the application server: step 17.
Configure Rational Team Concert: step 18.
Log in to the Rational Asset Manager web client and migrate the repository: steps 19–20.
Update the Rational Asset Manager Eclipse application: step 21.

Procedure

Before you upgrade, create a full backup of your repository, databases, asset files, and application server settings per the instructions in Creating a backup of a Rational Asset Manager repository.
On Linux, AIX®, or Linux for zSeries, increase the number of file descriptors a process might have open at once to at least 65535:
1. To view the current number of descriptors that can be open at once, in the command line type: ulimit -n
2. If the limit is not at least 65535, increase the limit with the following command: ulimit -n 65535
If you have modified your theme or email messages, before you update the Rational Asset Manager server, download the current theme and mail message files (on the Administration > Tools page) and then, after you have updated the server, reapply the theme and your messages. For more information, see Migrating the theme.
Configure the application security and authentication settings for WebSphere Application Server:
1. In a web browser, log in to the WebSphere Application Server administrative console. By default, this is located at:
  - For WebSphere Application Server: http://localhost:9060/ibm/console
2. Click Security.
3. Click Global security.
4. In the Administrative Security section, if the Enable administrative security check box is selected, select the Enable application security check box.
5. Click Apply.
6. In the Messages window, click Save directly to the master configuration.
7. Stop, and then restart the server.
If you are using Rational Asset Manager, version 7.0.0.2 or earlier, verify that the job server is enabled. To enable the job server:
1. Log in to the Rational Asset Manager web client as a repository administrator.
2. Click Administration.
3. In the Repository Administration sidebar, click Tools.
4. In the address bar of the browser, replace tools.faces with advancedConfiguration.faces and go to that address. For example, http://example.com:9080/com.ibm.ram.repository.web/admin/repository/advancedConfiguration.faces
5. On the Advanced Settings page, in the Job Options section, select Enable job server.
6. Click Save.
7. Restart the application server.
Verify that all of the repository servers are set to the same current date, time, and time zone.
If you use a WebSphere Application Server cluster and you need to install Rational Team Concert, you must create a stand-alone application server instance on your cluster for Rational Team Concert. To do so, see Creating an application server instance for Rational Team Concert on a WebSphere Application Server distributed server cluster. If you are not using a cluster, you do not have to do this; Rational Team Concert and Rational Asset Manager can be installed on the same application server.

If you are using Oracle, copy the additional JDBC .jar files to the WebSphere_install_directory/profiles/profile_name/config/cells/cell_name/ram_jdbc directory for your application server:

Table 1. JDBC .jar files by WebSphere Application Server and Oracle versions
WebSphere Application Server version	Oracle version	JDBC .jars
WebSphere Application Server version 6	Oracle version 10	`ojdbc6`
WebSphere Application Server version 7	Oracle version 11	`ojdbc6`

You can download the appropriate .jar files from Oracle. If you are using Oracle 10g, download a package for Oracle 11 to obtain the appropriate .jar files.

If you are using Oracle and you are using AIX, Linux, or Linux for zSeries, set the appropriate permissions for the new JDBC .jar file as described in Enabling database connectivity for non-root users (Linux and AIX). The user who accesses the Oracle database from Rational Asset Manager must be given the appropriate privilege to complete the migration.
- If you are using the RAMSCHEMA user, grant CREATE VIEW privilege to RAMSCHEMA user. Example: GRANT CREATE VIEW TO RAMSCHEMA
- If you are using a different user, grant CREATE ANY VIEW privilege to that user. Example: GRANT CREATE ANY VIEW TO User
If you are not using the embedded WebSphere Application Server and you are using WebSphere Application Server V8.0, you must install the interim fix to your server: http://www-01.ibm.com/support/docview.wss?uid=swg24023024. This interim fix prevents an issue where WebSphere Application Server is unable to release connections with Rational Team Concert.
If you use the embedded WebSphere Application Server, stop the embedded WebSphere Application Server.
Note: Do not stop your server if you are using a network deployment cluster or if you installed onto an existing WebSphere Application Server.
If issuing the Rational Asset Manager Stop the server command does not stop the server, run the stopServer command from a command line in the Install-directory\ram\ewas\bin directory, and specify a server administrator user name and password by using the -username and -password options.
Migrate your Rational Licensing Server to Rational Common Licensing V8.1.2 or later. For more information, see Migrating from Rational Licensing Server v7.1.x or earlier to Rational Common Licensing.
Rational License Key Server is included with the Rational Asset Manager installation media. You can also retrieve the latest version of Rational License Server through your Passport Advantage account, or through the IBM Support Portal.

This process requires that you shut down all applications that use Rational Licensing Server, uninstall your existing Rational Licensing Server, update your license files, and install Rational Common Licensing server. For Windows, see Configuring a license server for Windows; for AIX or Linux, see Configuring a license server for UNIX.
For Linux for zSeries, continue to use Rational License Server for UNIX and Linux 7.0.0.1.
Retrieve the appropriate Rational Asset Manager applications:
- If you use WebSphere Application Server and you used Installation Manager to deploy Rational Asset Manager to your server, use Installation Manager for the upgrade process. See the instructions Installing Rational Asset Manager server by using Installation Manager and note these differences:
  1. Start Installation Manager. On Windows Vista, run Installation Manager as an administrator (Right-click the program shortcut and select Run as administrator.
  2. Installation Manager might need to update to a later version. To configure Installation Manager so that it checks for updates: on the Start page click File > Preferences; then click Updates. In the Updates page, select Search for Installation Manager updates.
  3. On the Start page of Installation Manager, click Update.
  4. If a more recent version of Installation Manager is available, a window appears that asks you to update. Click Yes. Once the update process completes, click OK to restart Installation Manager, then click Update again.
  5. On the Update Packages page, select IBM Rational Asset Manager; then click Next. Expand and select the latest version of Rational Asset Manager server and click Next.
  6. Follow the instructions in the Update wizard.
    1. On the Context Root page, Installation Manager detects the context roots for your current Rational Asset Manager web applications. Note the context root for Rational Asset Manager Setup Server; you need the context root to access the server setup application. Then click Next.
    2. If application server security is enabled (it likely is) or the security settings for WebSphere Application Server have changed since you installed the product, on the Administrative security page of the Features section, select Yes and type the user name and password for the application server administrator. Then click Next.
  7. After the update process finishes:
    1. If you use the embedded WebSphere Application Server, the embedded WebSphere Application Server has been updated to the appropriate fix pack level and the server setup application .ear file has been updated. Start the embedded WebSphere Application Server. Go to step 11.
    2. If you use an existing WebSphere Application Server, the server setup application .ear file has been updated. Go to step 11.
    3. If you use an existing WebSphere Application Server ND Cluster, go to step 11. If you are upgrading from version 7.5 or later and that was the first version of the product that you installed, the server setup application has been updated on the application server that you specified when you originally installed the product. If you installed any version earlier than 7.5, the server setup application will be updated on the Deployment Manager server for your cell.
- If you deployed the Rational Asset Manager .ear and .war files to your application server, retrieve the latest version of the Rational Asset Manager application files. For more information, see Retrieving the server application files directly from the installation media. After you have the application files, proceed to step 10.
Deploy the Rational Asset Manager server setup application to your application server:
- If you are using a WebSphere Application Server cluster and deployed the server setup application to the Deployment Manager server (this describes most environments on a cluster before V7.5), you must use a script to uninstall the existing server setup application, and then install the latest server setup application. For more information about using the deployClusterSetup.py and UninstallSetup.py scripts, see Deploying the server setup application to the Deployment Manager on a WebSphere Application Server cluster. Alternatively, you can deploy the server setup application to the cluster instead of directly to the Deployment Manager; you wont need to run a Jython script if you deploy the application in this manner. After you deploy the server setup application to the Deployment Manager, go to step 11.
- If you have deployed the Rational Asset Manager server setup application directly to an application server, update com.ibm.ram.repository.setup.web.ear to the latest version that you retrieved:
  1. Launch the WebSphere Application Server administrative console and log in as an administrator.
  2. Update the Rational Asset Manager server setup application:
    1. Click Applications > Application types.
    2. Click WebSphere enterprise applications.
    3. Select com.ibm.ram.repository.setup.web.ear; then click Update.
    4. Browse to or type the path and file name of the Rational Asset Manager server setup enterprise archive file (com.ibm.ram.repository.setup.web.ear).
    5. On the next three pages, click Next.
    6. On the Summary page, click Finish.
    7. When the com.ibm.ram.repository.setup.web.ear file installs, click Save to Master Configuration. The server setup application is now updated and deployed. You use the server setup application to update all the other applications. Go to step 11.
  Note: If you used Rational Asset Manager 7.1.0.1 or earlier, the default context root for the server setup application has changed from com.ibm.ram.repository.setup.web to ram.setup. If you bookmarked the server setup application, your bookmark might not work after you update the server setup application. For more information, see the WebSphere Application Server documentation on context roots for Web modules.
- If you use WebSphere Application Server and do not have the server setup application (com.ibm.ram.repository.setup.web.ear) deployed, deploy the com.ibm.ram.repository.setup.web.ear application by completing the instructions in Deploying the server setup application to WebSphere Application Server. If you are deploying to a cluster, see Deploying the server setup application to a Websphere Application Server cluster. You use the server setup application to update all the other applications. After you deploy the server setup application, go to step 11.
After you have deployed the most recent version of the server setup application, in a web browser, open the server setup application by using the URL: http://host:port/setup-server-context-root. The default context root for the server setup application is ram.setup. If security is enabled on the application server, type the user ID and password for an application server administrator. For the embedded WebSphere Application Server, the default user ID and password are admin and admin.
In the Step 1: Locate Installation Files section, click Provide the location of the files on the server and type the directory on the file system on the server that is running the server setup application where the new web application files are located. If you used the Update wizard in Installation Manager, the files are in the package_group_location/ram/apps/was directory. These files must be in that directory:
- com.ibm.ram.repository.web_runtime.ear
- RTC-Server_401.zip
- ramhelp_war.ear
- rmcabdgovernprocess_war.ear
Note that the rlsclients_rlsibmratl_812.zip file is in the package_group_location/ram/SharedLibs directory.

If you deployed the server setup application to an application server that is part of a cluster and you are accessing that application server, to upload the files to the server that is running the server setup application, click Upload the files to the server; then click Browse and select each of the required files.
To verify that all required application files are in the directory, or to upload them to the server, click Verify Location. If you uploaded the application files, the server setup application saves them to a temporary directory. A message verifies if all the required files are present.
Click Update. The server setup application updates all other Rational Asset Manager application files to the latest versions and maintains their context roots, a process that can take several minutes. The Introduction page opens.
Rational Team Concert is required for the enhanced lifecycle process. Next:
- If you need Rational Team Concert: Rational Asset Manager includes a limited version that you can install.
  1. On the Introduction page, from the Install Rational Team Concert? list, select Yes, install a new RTC server.
  2. Click Next.
  3. Proceed to step 20
- If you already have Rational Team Concert and want to configure it to use with Rational Asset Manager:
  1. On the Introduction page, from the Install Rational Team Concert? list, select No, work with an existing RTC server.
  2. Proceed to step 16.
On the Deploy Rational Asset Manager page:
1. In the Deploy Rational Team Concert section, confirm the application server in the Servers list – you cannot deploy Rational Team Concert to a cluster – and click Deploy Applications. The operation to deploy Rational Team Concert can take several minutes. The Deploy Rational Asset Manager page reopens when the process completes.
2. When the operation completes, click Next.
Create a database for asset lifecycles for Rational Team Concert
- For DB2®: The server setup application can create the database for you:
  1. On the Create or Locate a Database for Rational Asset Manager page, select You need to create the Lifecycle database and click Next.
  2. If you are installing a new Rational Team Concert, in the Create a database for RTC's CCM field, type a name for the Change and Configuration Management (CCM) lifecycle management database (for example, CCMDB). In the Create a database for RTC's JTS field, type a name for the Jazz Team Server (JTS) lifecycle management database (for example, JTSDB). If you are using an existing Rational Team Concert, you do not need to create a new database.
  3. Click Create database(s).
- For Oracle or SQL Server: To create the database manually, see Creating databases for asset lifecycles. After you have created the database, select You have already created both databases and want to modify the settings and then click Next.
On the Configure Database page, enter and test the connection to the database for lifecycle management:
1. In the Database name for Lifecycle field, type the name of the database that you created in step 21.
2. To test the connection, click Test Connection.
3. If the connection succeeds, click Next.
Configure the Rational Team Concert database. Under Step 6: Configure Rational Asset Manager Lifecycle Database:
1. Click Populate the Database.
2. A message asks you to verify that you want to configure the lifecycle database. Click OK.
3. After the process completes, click Next.
Optional: Continue through the server setup application to configure or adjust your database and application server settings until you get to Part 4: Configure Lifecycle management settings.
On the page for Part 4: Configure Lifecycle management settings, click Restart the Server. You must enter the user ID and password for the application server administrator. After the server has stopped and restarted, the Configure Lifecycle management settings page opens.
In the Configure Lifecycle management settings page, type the path and login information for the Rational Team Concert application:
1. In Step 1, In the Rational Team Concert server field, type the path to the Rational Team Concert location. In the Jazz Team Server field, type the path to the Jazz Team Server location.You must use a secure (https://) connection. By default, these values are:
  - For an existing WebSphere Application Server: https://server_host:9443/ramccm and https://server_host:9443/ramjts for the Jazz Team Server.
  - For an external Rational Team Concert server: https://url:port/ccm and https://url:port/jts for the Jazz Team Server.
2. In Step 2, in the Jazz Administrator ID field, type the user ID of the administrator for the Rational Team Concert server (the default is admin); then, in the Password field, type the password for that user (by default, this is admin). If you just installed the Rational Team Concert with the server setup application, type the user name and password for the application server administrator.
3. In Step 3, in the Project Area Name field, type a descriptive name for the project area that will be created for lifecycles (for example, Rational Asset Manager lifecycles). Then, in the Project Area Administrator ID field, type the user ID for the user that you want to be the project area administrator. Then, type the Password for that user. If you are using an external Rational Team Concert server, the Project Area administrator will probably be a different user from the Jazz server administrator. If you are installing a new Rational Team Concert, the server setup application will suggest using the Jazz Administrator ID as the Project Area Administrator ID.
4. Click Configure server. This process might take a few minutes. After the configuration, the Summary page appears.
On the Summary page, click Start using Rational Asset Manager. or click Finish. The web client opens.
Migrate the Rational Asset Manager repository to the newest version:
1. In a web browser, open the Rational Asset Manager web client. The first time that you open the web client after the upgrade, a message is displayed that indicates that you must migrate the repository.
2. If necessary, log in with a user ID that has repository administrator authority.
  Note: For SQL Server, if an existing Rational Asset Manager database does not have the collation set to a sequence that ends with _BIN2 (for example, Latin1_General_BIN2) then the Manual Configuration Required page appears with a message. You can either recreate the database and set the collation option to be case-sensitive to work correctly with Rational Asset Manager or you can accept that there might be unexpected case-sensitivity conflicts.
3. Click Migrate. On large repositories, the migration might take several minutes; until the migration is complete, some information about the repository might not be available.
4. After the migration process completes, click Home.
After you migrate the repository, stop and then restart your application server.
To upgrade, you must file a request for a new license key. You must acquire a new server license and new user authorized licenses. Go to the Rational License Key Center: http://www-01.ibm.com/software/rational/support/licensing/ If you see an error about Rational License Server, adjust your license configuration:
1. Click Administration
2. On the Administration page, click Configuration.
3. In the License and Version section, to select what type of server license this repository uses, select either Standard edition, Enterprise edition, or Repository administrator use only. Licenses are not required for users who are repository administrators. Repository administrators have authority to perform any activity with the Rational Asset Manager web application. Do not assign repository administrator privileges to typical users. If you select Repository administrator use only, users who are not repository administrators cannot view asset details and cannot submit or update assets.
4. At the bottom of the page, click Save.
5. You might see the License Server error again. Click Retry connection to license server.
After configuration is complete, manually remap shared library references for the previous version of Rational Asset Manager to the RAM1WebApplication.
If you open the help application and it shows an older version of the help or you see errors, clear the cache for the Rational Asset Manager help application. See the documentation for your application server for instructions on clearing the cache. On a cluster, you must to stop every application server and clear the cache for every node and server in the cluster. For the embedded WebSphere Application Server, to clear the cache:
1. Stop the server.
2. Delete this directory: Rational_Asset_Manager_install_location/ram/ewas/profiles/profile1/temp/node_name/server_name/ramhelp_war/.
3. Restart the server.
Optional: Update the Rational Asset Manager Eclipse application by using the same method that you used to install it. For more information about installing the Eclipse client, see Installing the Rational Asset Manager Eclipse client.
Note: Before you install the latest version of the Rational Asset Manager Eclipse client, uninstall the Rational Asset Manager Eclipse client plug-in.
If you installed the Rational Asset Manager V7.0.0.2 Eclipse client into an existing Eclipse V3.3 application by using Installation Manager, use Installation Manager to uninstall the client. You cannot use the Eclipse Configuration Manager to uninstall Rational Asset Manager from the Eclipse client.

If you installed the Rational Asset Manager Eclipse client plug-ins by using the Eclipse update manager, before you install the latest version of Rational Asset Manager, use the Eclipse configuration manager to remove any features that are named Rational Asset Manager. To use the Eclipse configuration manager, in Eclipse, click Help > Software Updates > Manage Configuration.

What to do next

For Rational Asset Manager version 7.5.1 and later, the URL for the internal Rational Team Concert server changed from https://host:port/jazz to https://host:port/ramjazz. If you are upgrading from a Rational Asset Manager release earlier than 7.5.1, revise the URL references and tell your users which changes they must make.

Update the URLs in these locations:

The Rational Team Concert Eclipse IDE repository connections that use the previous URL. To update a repository connection:
1. Open the Team Artifacts view.
2. Expand Repository Connections.
3. Right-click the Rational Asset Manager connection and select Properties.
4. Select Jazz repository connection.
5. In the URI location, change the URL to http://host_name/ramjazz.
6. Click OK.
The advanced properties in the Rational Team Concert server that use the previous URL. To update the advanced properties:
1. Open Rational Asset Manager in a web browser by using the revised URL: http://host_name/ramjazz/admin
2. Log on as the administrator.
3. Click Server > Configuration > Advanced Properties.
4. Update the properties that include the previous URL. For example: com.ibm.ram.repository.service.internal.RepositoryRemoteService
The Rational Asset Manager links that are stored in bookmarks in web browsers.

Feedback