Upgrading the server configuration on z/OS

This topic describes the steps required to upgrade a server for IBM® Engineering Lifecycle Management (ELM) applications that use Db2® for z/OS.

1. Stop all previous version servers and back up the earlier repositories using the DB2® 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 ELM 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.2 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/jazz502, for version 7.0.2 use /etc/jazz702. Similarly, for the work directory, use /u/jazz702.

   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 ELM applications in SBLZSAMP

   ELM 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 (ENI)	BLZCPRELM
   Link Index Provider (LDX)	BLZCPLDX
   Lifecycle Query Engine (LQE)	BLZCPLQE
   Report Builder (RS)	BLZCPRS

5. If you are using WebSphere® Liberty profile, skip to step 9.
6. If you are using WebSphere Application Server, uninstall the earlier version applications by completing the following steps:
   1. Log on to the WebSphere Application Server Integrated Solutions Console at: https://example.com:9043/ibm/console/logon.jsp
   2. Click Applications > Application Types > WebSphere enterprise applications.
   3. Stop and uninstall the following applications deployed for the earlier version, which might include:
      • jts.war
      • ccm.war
      • qm.war
      • rm.war
      • clmhelp.war
      • lqe.war
      • ldx.war
      • rs.war
      • relm.war
      • dcc.war
      • gc.war
   4. Save the changes to the master configuration when prompted.
7. If you are using WebSphere Application Server, update JAZZ_HOME and log4j.configuration custom properties by completing the following steps:
   1. Log on to the WebSphere Application Server Integrated Solutions Console at: https://example.com:9043/ibm/console/logon.jsp
   2. Click Servers > Server Types > WebSphere application servers.
   3. Click the server name to open it. The default server name is server1.
   4. Under Server Infrastructure section, select Java and Process Management > Process definition.
   5. Under Process definition, select Servant.
   6. Under Additional Properties, select Java Virtual Machine.
   7. Under Additional Properties, select Custom properties.
   8. Select JAZZ_HOME and update its value to: file:///<7.0.2_configuration_dir>. For example, file:///etc/jazz702.
   9. Select log4j.configuration and update its value to: file:///<7.0.2_configuration_dir>/startup_log4j.properties. For example, file:///etc/jazz702/startup_log4j.properties.
   10. Save the changes to the master configuration when prompted.
   For additional information, see Setting up WebSphere Application Server.
8. If you are using WebSphere Application Server, stop the server and delete the WebSphere temporary files and directories and clear the cache by completing the following steps:
   1. Go to the temporary directory under your WebSphere Application Server profile, typically something like <WAS_profile_root>/temp/<node_name>/<server_name> and delete any <application>.war directories.
   2. Go to the <WAS_profile_root>/temp/wscache and delete the <application>.war if it exists.
9. 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.
10. 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.
11. 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.2, 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 ELM application servers

    ELM 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 (ENI)	BLZRELMU

12. 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.
13. Additional steps are needed to complete the upgrade for the Lifecycle Query Engine, Link Index Provider, and Report Builder applications if they are deployed.
    1. Copy the contents of the old configuration directories to the new configuration directories.
       For example:

       • cp -R /etc/jazz604/rs/* /etc/jazz702/rs or
       • cp -R /etc/jazz604/lqe/* /etc/jazz702/lqe
    2. Copy the contents of the work directories for each application.
       For example:

       • cp -R /var/jazz604/rs/* /var/jazz702/rs or
       • cp -R /var/jazz604/lqe/* /var/jazz702/lqe
    3. Examine the new configuration directory members to ensure that paths match the new configuration.
       For example, check the DBLocation property in the rs app.properties file.
14. 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 ELM 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/jazz702. You can recursively copy these files to a new location and modify the teamserver.properties file. This is not required.

15. Upgrade the Jazz Team Server database. Use repository tools to add 7.0.2 database tables to the JTS repository by modifying and submitting a copy of the version 7.0.2 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. However, there is an operational consideration that 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.
    • If the com.ibm.team.repository.db.db2.dsn.reorg property is not set, the userid that runs the BLZADDTB job 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.
16. Upgrade the databases for other applications you have installed. If you configured an application, use repository tools to add 7.0.2 database tables to the repository for the application by modifying and submitting a copy of the version 7.0.2 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

    ELM 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 (ENI)	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.
17. 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.2 SBLZSAMP sample member BLZDWHUP. Follow the instructions included with the sample member and carefully review the job output.
18. If you are upgrading from version 5.0 or 5.0.1 to version 6.0.x, you must run the mergeLPAJTS command to migrate the Lifecycle Project Administration storage areas, indexes, and registration. Follow the instructions in SBLZSAMP member BLZADMU to modify and submit this JOB. Carefully review the JOB output.
    Prior to version 5.0.2, Lifecycle Project Administration was a separate application. Starting in version 6, the application is part of Jazz Team Server.
19. If you are upgrading from version 5.0.2, modify and run BLZJTSU2 to ensure consistent front side URLs as part of the upgrade process.
20. Start the server. If you are using WebSphere Liberty, skip to step 22.
21. If you are using WebSphere Application Server, deploy the new version war files by completing the following steps:
    1. Log on to the WebSphere Application Server Integrated Solutions Console at: https://example.com:9043/ibm/console/logon.jsp
    2. Open the Enterprise Applications page by selecting Applications > Application Types > WebSphere enterprise applications.
    3. Install the following new version war files for the applications you are using:
       • jts.war
       • ccm.war
       • qm.war
       • rm.war
       • clmhelp.war
       • dcc.war
       • gc.war
       • lqe.war
       • ldx.war
       • relm.war
    4. Map the security roles for the following new version applications according to what you noted when you uninstalled the old applications in a previous step:
       • jts.war
       • ccm.war
       • qm.war

       Note: This step is only necessary if you are not using RACF® EJBROLEs for security and had previously mapped security roles.
22. If you are using WebSphere Application Server, start the applications from the WebSphere Application Server Integrated Solutions Console:
    • jts.war
    • ccm.war
    • qm.war
    • rm.war
    • clmhelp.war
    • dcc.war
    • gc.war
    • lqe.war
    • ldx.war
    • rs.war
    • relm.war
23. 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.
24. For the version 6.0.x release, you need version 6.0.x 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.
25. It is highly recommended to run the Db2 RUNSTATS utility against the upgraded repositories.