There are several scenarios you can follow to upgrade from
previous versions to Rational Team Concert™ for System z® 2.0.0.2.
In general, you can upgrade Rational Team Concert for System z
clients and servers either from a .zip file or using IBM Installation
Manager on platforms other than z/OS.
The process for upgrading to Rational Team Concert for System z 2.0.0.2 is similar
to
upgrading to Rational Team Concert 2.0.0.2 except
for the following considerations:
- Upgrading from Rational Team Concert for System z 1.0.1 on z/OS
is documented below.
- Upgrading from Rational Team Concert for System z 2.0.0.1 on z/OS
is documented in the ++HOLD information for the PTFs
that must be installed to complete the upgrade.
- The edition and version information for Rational Team Concert
does not directly correspond to Rational Team Concert for System z.
- You can upgrade from Rational Team Concert to Rational Team Concert
for System z but doing so requires a repository migration.
You can upgrade to Rational
Team Concert for System
z 2.0.0.2 in several ways, including the following scenarios:
- Scenario 1: Upgrading from a previous
version of Rational
Team Concert or from Rational Team Concert for System z 1.0.1 to Rational Team Concert for System z 2.0.0.2.
- Scenario 2: Upgrading from Rational Team Concert for System z 1.0.1 to Rational Team Concert for System z 2.0.0.2 on z/OS®
- Scenario 3: Upgrading from Rational Team Concert for System z 2.0.0.1 to Rational Team Concert for System z 2.0.0.2
- Scenario 4: Upgrading from Rational Team Concert for System z 2.0.0.1 to Rational Team Concert for System z 2.0.0.2 on z/OS
Installing additional languages while upgrading: If you use the IBM® Installation
Manager to install Rational Team Concert for System z 2.0.0.2 on a
computer where Rational Team Concert for System z is not currently
installed, the Installation Manager prompts you to select the languages
you want to install. However, if you update from an earlier version
to Rational Team Concert for System z 2.0.0.2, the Installation Manager
assumes that you want to use the current languages and does not prompt
you to select languages. To select additional languages, after you
update to 2.0.0.2, select
Modify from the main
screen in the Installation Manager, then select the offering. The
window that opens next displays the list of supported languages. Select
the ones you need.
If you start the Jazz™ Team
Server for System z after
you update to 2.0.0.2 and before you select
Modify to
add or remove languages, you must reset the server as follows:
- In a Web browser, navigate to https://server-host:9443/jazz/admin.action=com.ibm.team.repository.admin.serverReset.
- Click Request Server Reset.
- Shut down the server.
Then you can select Modify in the
Installation Manager to add or remove languages.
Upgrading a Rational Team Concert for System z client
for Eclipse IDE
Any Eclipse integrated development environment
(IDE) client must be v2.0.0.1 or higher to be able to connect to
a v2.x server. Although a Rational Team Concert for System z 2.0.0.1
client will connect to a 2.0.0.2 server, we recommended that you install
the Rational Team Concert for System z 2.0.0.2 client to connect to
your Rational Team Concert for System z 2.0.0.2 server. You can install
this client using a .zip file, or you can update your prior IBM Installation
Manager installations.
Note: Rational Team Concert 2.0 clients
can connect to Rational Team Concert for System z 2.0 servers; however, Rational Team Concert clients
cannot perform Rational Team Concert for System z-specific functions.
Upgrading a server from a trial release to a permanent
release
From the 2.0 trial release, you can make your server
permanent by purchasing and installing the Server Activation Kit for
your edition from the Rational License Key Center. Details are available
here: http://www.ibm.com/software/rational/support/licensing. The activation kit consists of a .jar file
that contains the permanent server key. It is installed using the
License Key Management page of your server's administrative Web
interface.
Scenario 1: Upgrading a server from Rational Team Concert or
Rational Team Concert for System z 1.0.1
You can upgrade
directly to the 2.0 release of Rational Team Concert for System z
from previous releases of Rational Team Concert or Rational
Team Concert for System z. A database migration is required.
Note: Before
you begin upgrading a WebSphere® Application
Server, reset the server by navigating to https://servername:9443/jazz/admin#action=com.ibm.team.repository.admin.serverReset and
clicking Request Server Reset.
If
you installed the previous release from a .zip file (for example,
on Linux® for System z), then there is no intersection
with the previous installation. You can install the 2.0 release from
a .zip in a new location, or you can use the IBM Installation Manager to install an instance
of 2.0.
If you used IBM Installation
Manager to install the previous release, you can either install 2.0
as a separate instance or update the previous instance to 2.0. If
you install a separate instance of the server for the 2.0 release,
select Create a new package group on the Install
Packages page of the installation wizard.
Note: To upgrade
a WebSphere Application
Server deployment of the Jazz Team Server for System z, remove the
previous jazz.war file and deploy the 2.0 jazz.war file.
To
complete the upgrade, see Copying the required configuration files from a previous server installation and Installing 2.0 activation keys.
Scenario 2: Upgrading from Rational Team
Concert for System z 1.0.1 on z/OS
Structural
changes have been made to the repository database in version 2.0 that
will prevent you from reusing the database from Rational Team Concert
for System z 1.0.1 on z/OS.
The process for upgrading to 2.0 from Rational Team Concert for System z v1.0.1 consists of
the following steps:
- Export the v1.0.1 database contents using repotools.
- Install and configure the Jazz Team
Server for System z v2.0
on the desired target platform. A new database will be created during
this step. See Installing Rational Team Concert for System z on z/OS for details
on installing the Jazz Team
Server for System z 2.0
on your target platform.
- Import the .tar file that was created in step one into the v2.0
repository database using repotools.
- Exporting the Rational
Team Concert for System
z 1.0.1 repository database
- Use member BLZEXPOR in hlq101.SBLZSAMP to export the contents
of the repository database. The sample JCL in this member uses the repotools export
command to create a .tar file containing your repository content.
Configure BLZEXPOR by following the instructions in the sample
JCL. Submit the modified JCL and check the job log. The job has run
successfully only if it ends with return code 300.
The export
file will be placed in the HFS location specified by @jazzExport@.
The name of the file will be @dbexport@.tar, as defined in BLZEXPOR.
- Importing the exported database to Jazz Team
Server for System z v2.0
on z/OS
- Importing to a Derby database on z/OS
- Use member BLZIMPO2 in hlq200.SBLZSAMP to import the v1.0.1
.tar file to your Jazz Team
Server for System z v2.0
Derby database. Configure BLZIMPOR as described in the JCL comments,
specifying the .tar file exported from the v1.0.1 database.
Submit
the modified JCL and check the job log to verify that repotools completed
successfully.
- Importing to a DB2® database
on z/OS
- Use member BLZIMPOR in hlq200.SBLZSAMP to import the v1.0.1
.tar file to your Jazz Team
Server for System z v2.0 DB2 database. Configure BLZIMPOR
as described in the JCL comments, specifying the .tar file exported
from the v1.0.1 database.
Submit the modified JCL and check the
job log to verify that repotools completed successfully.
To complete the upgrade, see Copying the required configuration files from a previous server installation.
Scenario 3: Upgrading a Rational Team Concert for System z server from 2.0.0.1
to 2.0.0.2
You can upgrade directly to the Rational Team Concert for System z 2.0.0.2 release from
previous releases. Additional actions for repository updates might
be required, see the Rational
Team Concert for System
z Release Notes® page
on Jazz.net for details.
Note: Before
you begin upgrading a WebSphere Application
Server, reset the server by navigating to https://servername:9443/jazz/admin#action=com.ibm.team.repository.admin.serverReset and
clicking Request Server Reset.
If
you installed the previous release from a .zip file (for example,
on Linux for System z), then there is no intersection
with the previous installation. You can install the new release from
a .zip in a new location, or you can use the IBM Installation Manager to install an instance
of 2.0.
If you used IBM Installation
Manager to install the previous release, you can either install 2.0
as a separate instance or update the previous instance to 2.0. If
you install a separate instance of the server for the 2.0 release,
select Create a new package group on the Install
Packages page of the installation wizard.
Note: To upgrade
a WebSphere Application
Server deployment of the Jazz Team Server for System z, remove the
previous jazz.war file and deploy the 2.0 jazz.war file.
To
complete the upgrade, see Copying the required configuration files from a previous server installation and Installing 2.0 activation keys.
Scenario 4: Upgrading from Rational Team
Concert for System z 2.0.0.1 to Rational Team Concert for System z
2.0.0.2 on z/OS
The SMP/E installation package contains RTCz
2.0.0.1. You need PTFs to upgrade the z/OS components to 2.0.0.2.
The PTFs are available from
ShopzSeries,
IBM Support Portal, Jazz.net, or your regular
service channel.
Search for the following APARs and order the corresponding
PTFs: PM04798, PM04800, PM04802, PM05340, PM05341, PM05342, and PM05701.
You
must apply these PTFs to the base Rational Team Concert for System
z 2.0.0.1 installation using SMP/E. Additional information on the
steps to apply the PTFs are included with the PTFs.
Additional
configuration steps are required to update your existing configuration
after you apply the PTFs.
Additional steps for upgrading an existing Tomcat
configuration on z/OS from Rational Team Concert for System z 2.0.0.1
to 2.0.0.2
To redeploy thejazz.war to Tomcat
on z/OS, make sure that the new jazz.war exists in
the catalina_base/webapps directory and that
any temporary jazz.war expansion directories have
been removed. On z/OS, the new sample JOB BLZCP221 copies the jazz.war to
your work directory in the catalina_base/webapps subdirectory.
You
must also delete the directory where the jazz.war was
previously expanded. This directory will be named "jazz" and will
be found in the same webapps directory (@workPath@/catalina_base/webapps).
Finally, you should also delete the Tomcat working directory. On z/OS,
delete the contents of the catalina_base/work directory
in your @workPath@ directory.
Restart Tomcat
and the new jazz.war will be deployed with the new
plug-ins provisioned.
Run repotools -addTables after
deployment
When upgrading a Rational Team Concert for System
z server from 2.0.0.1 to Rational Team Concert for System z 2.0.0.2,
you must run the repotools -addTables command.
Create
a new JCL member in hlq200.SBLZSAMP called BLZADDT. If you
are using DB2, copy sample member BLZEXPOR into BLZADDT. If you are
using Derby, copy BLZEXPO2.
Change:
//MAINARGS DD *
-clean
-configuration @workPath@/eclipse/configuration
-application com.ibm.team.repotools.rcp.repotools_application
-export
teamServer.properties=@confPath@/jazz/teamserver.properties
logFile=@workPath@/logs/exportDb.log
toFile=@jazzExport@/@dbexport@.tar
to:
//MAINARGS DD *
-clean
-configuration @workPath@/eclipse/configuration
-application com.ibm.team.repotools.rcp.repotools_application
-addTables
teamServer.properties=@confPath@/jazz/teamserver.properties
logFile=@workPath@/logs/addTables.log
Customize
the new JOB according to the JCL comments.
Note: You can ignore the
JCL comments for @jazzExport@ and @dbexport@ updates.
Submit
this job when the server is not running. The job should complete with
return code 0.
Tip: You can also copy and modify
sample JCL to run other repository tools functions on z/OS.
Additional upgrade information
The following
sections contain additional information relevant to all upgrade scenarios.
Upgrading a server from one Rational Team Concert for System z edition to another
The Rational Team Concert for System z editions (Starter,
Standard, and Enterprise) are all shipped in trial mode. To upgrade
from one edition to another, you must load a combined set of trial
activation keys for your target edition. These combined trial keys
can be downloaded from https://jazz.net/downloads/rational-team-concert-z/.
The
combined trial activation keys are included in a .zip file for your
target edition. This combined .zip file is installed using the License
Key Management page on your server's administrative Web interface.
Rational Team Concert for System z is shipped as Starter
Edition trial mode only for installation on z/OS in version 2.0.0.1 and Standard Edition
in version 2.0.0.2. If you need to upgrade to another Rational Team Concert for System z edition on z/OS, you must first upgrade to
the edition you need, and then load permanent Server Activation kits
and Client Access Licenses for your edition.
WebSphere Application
Server configuration updates
The following steps are required
to properly configure WebSphere Application
Server in Rational
Team Concert for System
z 2.0.
- Ensure that the latest fix packs for WebSphere Application Server and the associated Java™ SDK are installed. If you deploy
in WebSphere Application
Server 7.0, it is critical that you install at least WebSphere Application Server 7.0.0.3. With WebSphere Application Server
6.1, it is critical that you install at least WebSphere Application Server 6.1.0.25.
- Remove the previous custom JVM properties:
- com.ibm.team.repository.provision.profile
- com.ibm.team.server.configURL
- log4j.configuration
- If it is not already available, add the new custom JVM property JAZZ_HOME and
set the value to:
file:///<JazzInstallDir>/server/conf
on
systems other than z/OS. On z/OS, set the value to:
file:///@confPath@
where
@confPath@ is
configuration path set in BLZCPDIR.
- Ensure that you select the WebSphere Application Server setting Use
available authentication data when an unprotected URI is accessed.
If you are using the WebSphere Application
Server Integrated Solutions Console, you can do this by following
these steps:
- Navigate to .
- Select Use available authentication data when an unprotected
URI is accessed.
- Ensure that you have deployed the Rational Team Concert for System
z jazz.war file. The jazz.war should
be updated to the latest Rational Team Concert for System z version.
Copying the required configuration
files from a previous server installation
Copy the following
files and directories from the source server to the target server.
First, rename the original files in the upgraded server installation
to create backups. If you used the IBM Installation
Manager to update to Rational Team Concert for System z 2.0, a backup
directory containing your 1.0.1 configuration files was created with
a name like backup-config-<timestamp> in
the server subdirectory of the installation location.
If you are upgrading to the Standard or Enterprise Edition
and you have purchased the Developer Client Activation Kit for the
Starter Edition, purchase and install the Developer Client Activation
Kit for the Standard or Enterprise Editions so that you can use those
client licenses. Your developer license assignments will still be
in effect, but the developer licenses will be deactivated until you
install the correct activation kit.
Note: Additional configuration
update instructions for Jazz Team Server for System z running on z/OS
are available in the PTF packages.
Installing 2.0 activation
keys
The Rational Team Concert for System z 2.0 release
uses the Rational Team Concert for System z 2.0 activation keys. If
a server is upgraded from 1.0.1 to 2.0, or from Rational Team Concert to Rational
Team Concert for System z, it reverts to a trial license after the
upgrade, and you must obtain the Rational Team Concert for System
z 2.0 activation keys from the Rational License Key Center. Below are the
names of the applicable keys for each kit:
- IBM Rational Team Concert
for System z Starter Edition - Server License Activation Kit V2.0
Multiplatform (jazz_team_server_starter_zSeries-release.jar)
- IBM Rational Team Concert
for System z Starter Edition - Developer Client License Activation
Kit V2.0 Multiplatform (rtcz_starter_developer_unlocked.jar)
- IBM Rational Team Concert
for System z - Contributor Client License Activation Kit V2.0 Multiplatform
(rtcz_all_contributor_unlocked.jar)
- IBM Rational Team Concert
for System z Standard Edition - Server License Activation Kit V2.0
Multiplatform (jazz_team_server_standard_zSeries-release.jar)
- IBM Rational Team Concert
for System z Developer Client License Activation Kit V2.0 Multiplatform
(rtcz_standard_developer_unlocked.jar)
- IBM Rational Team Concert
for System z Floating Developer Client License Activation Kit V2.0
Multiplatform (rtcz_std_floating-developer_unlocked.jar)
- IBM Rational Team Concert
for System z - Floating Contributor Client License Activation Kit
V2.0 Multiplatform (rtcz_std_floating-contrib_unlocked.jar)
- IBM Rational Team Concert
for System z Enterprise Edition - Server License Activation Kit V2.0
Multiplatform (jazz_team_server_enterprise_zSeries-release.jar)
Verifying that you have successfully upgraded
There
are two key requirements of a successful Jazz Team Server upgrade
to Rational Team Concert for System z 2.0.0.2:
- The Jazz Team Server jazz.war Web application
from Rational Team Concert for System z 2.0.0.2 must be installed.
- The Jazz Team Server must be provisioned with the new plug-ins
for Rational Team Concert for System z 2.0.0.2
To be sure that both requirements were successful, complete
the following steps:
- Step 1:
- First, to verify that the jazz.war has been successfully
updated, access the Jazz Team Server Administrative Web UI as an administrator
(typically at a URL like: https://yourhost:9443/jazz/admin).
The
initial Status Summary Installed Products section should show the
Jazz Foundation Jazz Team Server as 1.0.0.2 and Rational Team Concert
as 2.0.0.2.
If the
Installed Products section
does not show these levels, you can redeploy the
jazz.war.
The new
jazz.war can be found in the
tomcat/webapps subdirectory
of the installation directory.
- WebSphere
- To redeploy the jazz.war to WebSphere Application
Server, use the WebSphere Application Server administration console
to uninstall or update the existing jazz.war and replace with the
new jazz.war.
- Tomcat
- To redeploy the jazz.war to Tomcat, make sure
that the new jazz.war exists in the tomcat/webapps directory
and that any temporary jazz.war expansion directories
have been removed. The new jazz.war is copied to
the tomcat/webapps directory by Installation Manager on platforms
other than z/OS. On z/OS, the new sample JOB BLZCP221 copies the jazz.war to
your work directory in the catalina_base/webapps subdirectory.
Note: On
z/OS, both of these steps are required for Tomcat. Also, you must
delete the directory where the jazz.war was previously
expanded. This directory will be named "jazz" and will be found in
the same webapps directory (tomcat/webapps
or catalina_base/webapps). If you had customized the jazz web.xml,
you should make a copy before you delete the expansion directory,
so that you can integrate your changes with the new web.xml.
Finally, you should also delete the Tomcat working directory. On platforms
other than z/OS, delete the contents of the server/tomcat/work
directory. On z/OS, delete the contents of the catalina_base/work directory
in your @workPath@ directory.
Restart Tomcat. You can recheck the status after the
restart.
- Step 2:
- To verify that the Jazz Team Server has been provisioned with
the new plug-ins, you can view the Server Provision Status,
which shows when the server was provisioned and with which plug-ins.
You can accessServer Provision Status using
a URL similar to:
https://yourhost:9443/jazz/admin#action=com.ibm.team.repository.admin.provisionStatus
You
should see that the server provisioning date and time is after the
application of the upgrade to Rational Team Concert for System z 2.0.0.2.
If the server has not been reprovisioned since you updated, you can
request a server reset via a URL similar to:
https://yourhost:9443/jazz/admin#action=com.ibm.team.repository.admin.serverReset
Click
the Request Server Reset button. Restart Tomcat
or WebSphere Application Server and verify that the Server
Provisioning Status has been properly updated.
Setting a project timeline
In Rational Team Concert 1.0.1
or Rational Team Concert for System z 1.0.1, projects could have multiple
timelines (previously called "development lines"), and all of these
timelines were considered equal.
In Rational Team Concert for
System z 2.0, projects can still have multiple timelines, but only
one of them can be marked as the "project timeline." When you migrate
your database to 2.0, the primary project timeline is not known, so
your projects will not have a project timeline set. You can manually
update your projects to set the project timeline after you upgrade
to 2.0.
Configuring the Source Control Management snapshot
The
Source Control Management (SCM) snapshot for the data warehouse collects
data on streams, including information about the size of streams and
the activity (change set and file/folder changes) within it. In version
1.0.1, this snapshot automatically collected information about all
streams. As this can be a costly operation, in version 2.0, the configuration
options are added to the SCM snapshot to let you decide for which
streams the data should be collected. The immediate impact of this
change is that, unless you configure it, no data is collected.
To
configure the SCM snapshot, perform the following steps:
- You must have Write permissions for the stream for which you want
to collect data.
- Go to the Reports page in the Rational Team Concert for System z Web interface.
- In the left navigation panel, select Administer SCM
Snapshot. A list of streams is displayed.
- Select One or more streams, then select Save
Changes.
Data will be collected for the selected streams in all
subsequent snapshots.
Incompatible changes to BIRT reports
If
you used the BIRT report designer to create your own report templates,
you might encounter problems when you try to use these reports in
version 2.0. You should be aware of the following issues:
- Changes to the order in which Java and JavaScript™ classes are resolved: If
you have written JavaScript code
in your BIRT report that uses the importPackage() statement
to import the java.lang package, be aware that unqualified
references to Object in the code, which previously referred
to the Java class, might now
refer to the JavaScript class
and, as a result, will not work properly. Other classes that are identically
named between JavaScript and Java, such as java.util.Date,
might have the same problem. The solution is to fully qualify your
reference to the Java class
and remove the importPackage() statement.
- Changes to data set processing: In the past, the act of
binding an element (such as a label) to a data set caused the data
set to be processed in its entirety when the element was rendered.
This was useful because it meant you could enforce an order to data
set processing by using hidden labels bound to the data sets in the
order they should be processed. Now, such a binding will process only
the first row of the data set. To apply the previous behavior, use
a Dynamic Text element and invoke any JavaScript code, which will force processing
of the entire data set. Total.count() is a good choice.
- BIRT report designer bugs can cause loss of data: These
problems occur when you open a BIRT report design file created in
BIRT 2.2.2 (Rational
Team Concert 1.0) with the BIRT 2.3.2 (Rational Team Concert 2.0)
report designer. The following issues have been observed:
- When you edit a data set for the first time with BIRT 2.3.2, on
the Parameters page, the Default Value and Report Parameter fields
might be lost. The workaround is to reenter the values, or to copy
and paste the values from a previous version of the editor. After
you save the file with the new values, the problem will not recur.
- When you edit a report design file for the first time with BIRT
2.3.2, the default value for report parameters might be lost. This
might also occur when you edit a data set for the first time with
BIRT 2.3.2. The workaround is to reenter the values, or to copy and
paste the values from a previous version of the editor. After you
save the file with the new values, the problem will not recur.
Note: These issues can be very serious if you do
not monitor them, as the data gathered by the report could be incorrect.
Check each data set and each report parameter when you edit a report
for the first time with the BIRT 2.3.2 report designer. These problems
do not occur for new reports that are created with the BIRT 2.3.2
tools.
The above changes are made to all Rational Team Concert
for System z 2.0 out-of-the-box reports. No action is required on
your part. However, if you have manually created report templates
in your project area using Rational Team Concert for System z 2.0 out-of-the-box
reports, and you have not specified an appropriate identifier (consistent
with Rational Team
Concert for System z usage),
your report template will not be refreshed when it is migrated. That
is, the content will be out of date and will not work. In that case,
you should upload new content for the affected templates, using the
appropriate out-of-the-box .rptdesign file.
Import of the Work Items data in the data warehouse
In Rational Team Concert for System z 2.0, there are several
schema changes to the work items tables in the data warehouse. As
a result, when you migrate from 1.0.1 to 2.0, the importer will ignore
any warehoused work items data. As a result, when you start the 2.0
server for the first time, your work items reports might not function
correctly. The workaround is either to wait for the work items snapshot
to run for the first time, or to manually force it to run after you
start the server. On the first run after migration, the work items
snapshot will reconstitute the entire historical work items information
in the data warehouse. This also means that the first run of the snapshot
after migration is likely to take much longer than an average nightly
run.
Discovering new reports
In Rational Team Concert for System z 2.0, several new reports
are added. While these reports appear in the new process templates
that ship with the Rational
Team Concert for System
z, they are not automatically added to the existing project areas
when you migrate your data to Rational Team Concert for System z 2.0. To discover and
deploy these new report templates in your existing project areas after
migration, perform the following steps:
- In the Eclipse client, open the Team Artifacts view.
- Expand your project area, expand Reports.
- Right-click Report Templates and select Deploy
New Templates.
The dialog that opens will help you to discover any report
templates that are available but not already deployed to your project
area. You can select one or more of them and they will be created.
After creation, you can create new reports from those templates using
the available menu actions.
Customizations
Changes that you make to
work item types, attributes, workflows, roles, and event handlers
are preserved when you upgrade from 1.0.1 to 2.0. If you customized
a predefined process template (such as Scrum), be aware that
if you redeploy the predefined template (in the Process Templates
view), you will overwrite your customizations. If you need to redeploy
the predefined template, you should first change the name and ID of
the predefined template that you customized so that it will not be
overwritten.