Upgrading the server configuration on z/OS

This topic describes the steps required to upgrade a server for IBM® Engineering Lifecycle Management , applications when the server uses WebSphere Liberty and Db2 for z/OS .

Before you begin

Before you begin to upgrade the server, read the following notes:
  • Additional information about upgrade is available in the Upgrading section of the Jazz.net Deployment wiki.
  • Carefully review the compatibility reports and system requirements to ensure the upgrade configuration meets the new version requirements, with special attention to application server and Java support. Go to Software product compatibility reports and system requirements (https://www.ibm.com/software/reports/compatibility/clarity/softwareReqsForProduct.html). In this interface, enter the product name and click the search icon. Select the relevant product in the search results and select the values of the required fields. Then, submit the search.
  • Get the product installation media. You can download server installation files from jazz.net or Passport Advantage.
  • Upgrading from version 5 to version 7 is a two-step process. You must first upgrade your server to the latest fix pack of version 6 release, start the server and make sure your upgrade to version 6.x was successful, and then upgrade to version 7. For instructions on upgrading from version 5 to version 6.0.x, see the latest version 6 documentation.
  • Understand the upgrade process. See Deployment and upgrade process.
  • Plan for your applications to be unavailable: Your applications will be unavailable for a brief period while you back up everything and update your applications to version 7.0.3. All of the applications that are connected to Jazz® Team Server will be offline while Jazz Team Server is offline. Be sure to provide time to completely back up your existing applications.
  • Learn about licensing: Go to Step 15 to learn about licenses in this release.
    Important: You can download your token or term license key files from IBM License Key Center and your perpetual license key files from Passport Advantage.
  • Check the client and server compatibility. Jazz Team Server must be at the same level as or newer than the applications that are registered with it, but the applications cannot have a newer version than Jazz Team Server. See Client and server version compatibility.
  • Make copies of the SBLZSAMP JCL members so you can review the original files if necessary. Review the job logs of the samples after the jobs are submitted. The expected return code for every step is 0.
  • Do not run jts/setup. The upgrade process configures the new installation based on your previous installation. To view or change the setup, use jts/admin.
  • The upgrade process uses your existing Engineering Lifecycle Management databases. The addTables and upgradeWarehouse commands will update the databases to the new version formats.
  • If you are using Java ETLs in your current version, install the Data Collection Component in the new version. See Collecting data with the Data Collection Component. To install and configure Data Collection Component on z/OS , do the following:
    1. Install FMID HRRS703.
    2. Use the configuration utility, or directly create directories to support DCC using sample member BLZCPDCC and create database tables using sample member BLZCREDB.
    3. Register the DCC application using jts/setup.
  • If you want to perform online migration for the Change and Configuration Management application, see Online migration for Engineering Workflow Management.
  • If you installed multiple Jazz applications on the same application server profile, you must upgrade those applications at the same time. If you deployed each application into a separate application server profile, you can upgrade the applications independently.
  • Before you upgrade your production environment, set up a test environment to avoid issues. For more information, see Staging a test environment for the upgrade process. Be sure to isolate the test environment from the production environment.

About this task

The following steps will migrate the configuration from the earlier to the new version configuration.

Procedure

  1. Stop all previous version servers and back up the earlier repositories using the Db2 for z/OS UNLOAD and LOAD utilities provided.
    For details, see Running UNLOAD and LOAD processes on Db2 to create a backup database. You can use other tools for making backup copies if the tools have been tested and verified. For JTS, CCM, QM, RM, RELM, DCC, or GC applications, pay special attention to the handling of the PACKAGE_MAP and TABLE_MAP tables. The PACKAGE_MAP and TABLE_MAP tables contain references to other database tables. An exact copy of these tables in the same database subsystem might reference other production data. The procedures described in Running UNLOAD and LOAD processes on Db2 to create a backup database helps to prevent collisions.
    Important: You must make backup copies of your repositories before proceeding with an upgrade because the upgrade process makes repository model changes that cannot be rolled back. You should also back up the configuration and working directories of the existing server environment. Verify the backups before proceeding with the upgrade.
    1. To verify the backup and restore procedures, complete the steps for UNLOAD and LOAD to a new database and new schema prefix.
    2. Use the BLZCREDB sample job from the earlier version to create the tables in the new databases.
    3. To fully test the database backup and restore procedures, create additional databases for each repository and the data warehouse. The newly created databases must have the same permissions as the existing databases.
    4. Use repository schema prefixes that have the same number of characters.
    5. Verify the new repositories were created successfully before proceeding with the upgrade steps.
  2. Install the new version of the Engineering Lifecycle Management package to a new SMP/E environment using SMP/E installation. The new version installation and configuration locations must be different from the earlier version locations.
    Note: The FMIDs for the new version and release are new, so there are no PTFs for upgrading to a newer version or release.
  3. Configure the new Jazz Team Server (JTS) by modifying and submitting the version 7.0.3 SBLZSAMP sample member BLZCPJTS to set up the server configuration structure and work directories, including the Lifecycle Project Administration application.
    Note: The configuration (JAZZ_HOME) and work directories you create for the new version and release must be different from the previous directories, so that the upgrade utilities can merge the two versions. For example, if the default configuration directory for the earlier version is /etc/jazz701, for version 7.0.3 use /etc/jazz703. Similarly, for the work directory, use /u/jazz703.
    Follow the instructions in the sample member or see Creating directories for Jazz Team Server and the Engineering Lifecycle Management applications.
  4. If you are upgrading any of the applications in Table 1, modify and submit the new version SBLZSAMP sample member to set up the new server configuration and work directory structure with CCM definitions.
    Follow the instructions in the sample member or see Creating directories for Jazz Team Server and the Engineering Lifecycle Management applications.
    Note: These jobs are creating new default application definitions. Later steps in the upgrade process will merge the existing data with this new default configuration.
    Table 1. Sample members for Engineering Lifecycle Management applications in SBLZSAMP
    Engineering Lifecycle Management application SBLZSAMP sample member
    Change and Configuration Management (CCM) BLZCPCCM
    Quality Management (QM) BLZCPQM
    Requirements Management (RM) BLZCPRM
    Global Configuration Management (GC) BLZCPGC
    Data Collection Component (DCC) BLZCPDCC
    IBM Engineering Lifecycle Optimization Engineering Insights (Engineering Insights) BLZCPRE
    Link Index Provider (LDX) BLZCPLDX
    Lifecycle Query Engine (LQE) BLZCPLQE
    Report Builder (RS) BLZCPRS
  5. If you are using WebSphere® Application Server Liberty, use sample member BLZCPWLP to create a new Liberty instance and configure it as with the previous version. Merge the jvm.options, server.env and server.xml from the previous Liberty server and the new one.
  6. Migrate the JTS server configuration. Use repository tools to merge the previous version configuration file settings into the new version configuration files for JTS by modifying the new version SBLZSAMP sample member BLZJTSU. Before you submit the BLZJTSU job, replace the variables in the sample member following the instructions in the comments. Submit the BLZJTSU job and review the job output and updated properties files.
  7. Migrate the server configurations for other applications you have installed. Use repository tools to merge the previous version configuration file settings into the new version configuration files for the application by modifying the new version SBLZSAMP sample job listed in Table 2. These jobs also delete the full text indices. So, when you upgrade to version 7.0.3, you must rebuild the indices by using repotools -rebuildTextIndices offline or by starting the server to allow the server to rebuild these indices after start-up.
    Table 2. Sample SBLZSAMP jobs for migrating Engineering Lifecycle Management application servers
    Engineering Lifecycle Management application SBLZSAMP sample job
    Change and Configuration Management (CCM) BLZCCMU
    Quality Management (QM) BLZQMU
    Requirements Management (RM) BLZRMU
    Global Configuration Management (GC) BLZGCU
    Data Collection Component (DCC) BLZDCCU
    IBM Engineering Lifecycle Optimization Engineering Insights (Engineering Insights) BLZRELMU
    Link Index Provider BLZLDXU
    Lifecycle Query Engine BLZLQEU
    Report Builder BLZRSU
  8. Before you submit a job, update the variables according to the instructions in the comments. Submit the sample job and review the job output and updated properties file.
  9. Review the index file locations for each application. Adjust the locations and copy index files if you prefer.
    Note: After running the update configuration files repository tools commands for Jazz Team Server and Engineering Lifecycle Management applications, some of the directory references in the teamserver.properties files point to the prior version work directory. You can keep the indices in the prior version directory, if you do not plan to delete or clean up that directory.

    You could also copy the indices to a new location in the new work directory and modify the teamserver.properties file. For example, suppose the updated Jazz Team Server teamserver.properties file includes com.ibm.team.jfs.index.root.directory=/u/jazz/jts/indices but your new work directory is /u/jazz703. You can recursively copy these files to a new location and modify the teamserver.properties file. This is not required.

  10. Upgrade the Jazz Team Server database. Use repository tools to add 7.0.3 database tables to the JTS repository by modifying and submitting a copy of the version 7.0.3 SBLZSAMP sample member BLZADDTB. The application variables @appl@ should be set to jts. Follow the instructions included with the sample member and carefully review the job output. Use @ctxt@ in the JCL if you have a different context root than the application name.
    Note: In Db2 for z/OS version 12, a new Db2 ZPARM option called DDL_MATERIALIZATION was added. It has the following possible values and meanings:
    • (ALWAYS_IMMEDIATE)

      For applicable requests, changes are materialized at the time that the request is run, and the containing table space is placed in AREO* or REORP status. If there are any existing unmaterialized pending changes, the request fails.

    • (ALWAYS_PENDING)

      For applicable requests, changes are not materialized at the time that the request is run, and the affected objects are available until it is convenient to implement the changes.

    More details can be found in DDL MATERIALIZATION field (DDL_MATERIALIZATION subsystem parameter).

    If you set DDL_MATERIALIZATION to ALWAYS_PENDING, then there are some considerations that you need to be aware of when you use repository tools to run addTables on jts or any of the other applications. Historically, when addTables ran and tables were altered, changed, or new columns were added, entries were added to the SYSPENDINGDDL table. addTables continued and then attempted to create any required new indices. However, the creation of the index failed because of the pending DDL changes. The pending DDL changes could not be materialized until a REORG was run on the affected tablespace.

    In Engineering Workflow Management 7.0.1, the code was changed to run an inline REORG on any affected tablespaces. This inline REORG occurs only if the upgrade path includes altering existing table columns, which does not happen in every case of application upgrade. However, if an inline REORG is invoked, an operational consideration needs to be acted upon.

    By default, the inline REORG uses a template for the copy data set that has a template pattern of &SS..JAZZ.T&HO.&MI.&SC..&DB..&TS..&UQ. It uses the Db2 job and object variables. There are three possibilities to avoid index creation failures during addTables if DDL_MATERIALIZATION is set to ALWAYS_PENDING:
    • In the teamserver.properties file, specify the new property com.ibm.team.repository.db.db2.dsn.reorg with the template you wish to use. For example: com.ibm.team.repository.db.db2.dsn.reorg=MYHLQ.JAZZ.T&HO.&MI.&SC..&DB..&TS..&UQ. The user specified on the JDBC connection URL needs to have SAF authority to allocate this data set.
    • If the com.ibm.team.repository.db.db2.dsn.reorg property is not set, the userid that is specified on the JDBC connection must have a SAF profile to be allowed to create these data sets. For example, if the Db2 subsystem is DSNA, then a DSNA.JAZZ.** profile must be created.
    • Run the upgrade with DDL_MATERIALIZATION=ALWAYS_IMMEDIATE and then fall back to DDL_MATERIALIZATION=ALWAYS_PENDING after the upgrade.
    Furthermore, you must be aware of the following considerations:
    • The name that is generated by the template completion must not exceed 44 characters, which is the maximum data set name length allowed.
    • The user ID that is specified on the JDBC connection needs EXECUTE authority for SYSPROC.DSNUTILU.
    • During the upgrade, additional security considerations might apply to the Workload Manager (WLM) started task that runs the DSNUTILU procedure, depending on the security specification of the started task. The user ID under which the REORG runs needs DBADM authority for the database that is being upgraded and authority to any data sets that are referenced by the WLM started task.
    • If DDL_MATERIALIZATION is not set to ALWAYS_PENDING, you might see a failed REORG attempt, but the overall successful completion of the upgrade will not be impacted.
  11. Upgrade the databases for other applications you have installed. If you configured an application, use repository tools to add 7.0.3 database tables to the repository for the application by modifying and submitting a copy of the version 7.0.3 SBLZSAMP sample member BLZADDTB. Set the application variable @appl@ to the value in listed in Table 3.
    Table 3. Application values for @appl@ variables in SBLZSAMP sample member BLZADDTB
    Engineering Lifecycle Management application @appl@ value
    Change and Configuration Management (CCM) ccm
    Quality Management (QM) qm
    Requirements Management (RM) rm
    Global Configuration Management (GC) gc
    Data Collection Component (DCC) dcc
    IBM Engineering Lifecycle Optimization Engineering Insights relm
    Follow the instructions included with the sample member and carefully review the job output.
    Note: The upgrade process of the Quality Management application to the new version might take longer than usual based on database vendor, latency, and number of artifacts. Before you proceed, calculate the estimated migration time with your administrative team. More information is provided at Migrating To Version 6.
  12. If you previously configured the data warehouse, use repository tools to upgrade the data warehouse repository by modifying and submitting a copy of the version 7.0.3 SBLZSAMP sample member BLZDWHUP. Follow the instructions included with the sample member and carefully review the job output.
  13. Start the server.
  14. If necessary, activate licenses by completing the following steps:
    1. Log in as an administrator to the new Jazz Team Server.
    2. Navigate to the Server Administration > License Key Management page and activate licenses.
      Note: You do not need to run setup on the new system since everything is already set up.
  15. For the version 7.0.3 release, you need version 7.0.3 licenses. Version 6.0.x licenses are compatible with earlier version applications, but version 6.0.x applications do not work with earlier version licenses. For more information, see Managing licenses.
  16. It is highly recommended to run the Db2 RUNSTATS utility against the upgraded repositories.