Upgrade CA PPM

The following image shows how a system administrator upgrades a cappm installation for single and clustered servers. 
ccppmop152
The following image shows how a system administrator upgrades a 
CA PPM
 installation for single and clustered servers. 
This image shows how to upgrade CA PPM
This image shows how to upgrade CA PPM
2
Video: CA PPM Upgrade Assessment Utility
The following video is provided by CA Technologies. Learn how to use the Upgrade Assessment Utility to make upgrading 
CA PPM
 simple and quick:

To play this video in full screen, click the YouTube logo to the right of Settings at the bottom of the video. 
Perform the Pre-Upgrade Requirements
Address the following important points before you begin the upgrade:
  • A user account with administrator rights is required for the server or servers on which you intend to install.
  • Backup the existing installation directory and database. Verify that you have a consistent back-up of the database schema. Verify that you have sufficient disk space available on the server.
  • Run the Delete Process Instance job. A series of full scans on the BPM_ERRORS table can slow performance in Oracle and Microsoft SQL databases. For every query, the database flushes all buffer data to disk in order to load and read new rows. Run this job with date parameters to improve performance. For example, run in monthly time segments. See 
    Delete Process Instance Job 
    in CA PPM Jobs Reference.
  • Read the Change Impact and Upgrade information for each release between the one you are currently using and the release to which you are upgrading. Verify that you are following a recommended upgrade path. Not all product releases and patch levels have supported upgrade paths between them.
  • License key information is required to install some third-party software products. See the documentation or README file that is provided with your third-party installation media.
  • Disable any custom database triggers or antivirus scanners that can interfere with the upgrade or installation scripts.
  • Verify the configuration settings on the 
    CA PPM
     database server and note any changes that you want to make.
  • Upgrade the following third-party software (as needed) to work with this release.
    • Java SDK
    • Apache Tomcat (application server)
    For information about the versions of third-party software that this release supports, see Compatibilities in the CA PPM 15.2 Release Notes.
  • Verify that a standard calendar exists in the product by looking at the properties of existing calendars. A standard calendar has the Standard check box selected in the calendar properties. To view properties of calendars, open the Administration menu, and from Project Management, click Base Calendars.
  • If XDM was part of a previous version of 
    CA PPM
     that you are upgrading, an XDM step appears in the installation process. After you run this step, ensure that XDM is distributed to the other servers in the cluster.
  • We recommend that you turn off auditing on all objects before you start the upgrade process.
: When you are ready to start the specific steps to upgrade to this release, see CA PPM 15.2 Change Impact and Upgrade.
  • You must have the standard base calendar available in your 
    CA PPM
     application before you upgrade. If you deleted the shipped calendar named 
    Standard
    , create it before upgrading. Contact CA Support if your instance is missing the Standard base calendar.
  • Process all 
    In progress
     transactions into WIP. 
    Verify the following conditions: 
    • imp_transactionimport and ppa_transcontrol are clear.
    • WIP adjustments are approved.
    Review and fix all invalid transactions.
  • Review Time Slices. 
    Verify that the table is slicing out only the data that is required. If extra data is getting sliced, the database size increases and affects performance.
  • Clear the Datamart and recreate the data post-upgrade to improve the processing time of the upgrade.
For Release 15.1, the Datamart is automatically cleared for Oracle. Use
NBI_Clean_Datamart_sp
to clear the Datamart. The script does not clear the following tables:
The configuration table (NBI_CFG%)
Time facts tables that contain historical information (
NBI_PM_PT_FACTS
and
NBI_FM_PT_FACTS
)
  • After the upgrade, run the following jobs to repopulate the Datamart tables:
    • Datamart Extraction job
    • Datamart Rollup job
  • Complete and put all processes on hold.
  • Remove or delete process history, notifications, jobs, or logs. Look for items that you do not need to retain.
  • Pause all scheduled jobs. Take special note of the 
    Time Slicing
     job. Pause it before stopping the 
    CA PPM
     services before the upgrade.
  • To verify that all components are installed and functioning before and after the upgrade, run the Health Report that is available in 
    CA PPM
     System Administration (CSA).
  • Remove all 
    CA PPM
     services before running the upgrade using the following command: 
    service remove all
    .
  • Verify that no files or folders in the installation folder are in use anywhere.
  • Recommended:
     We recommend that you turn off auditing on all objects before you start the upgrade process.
    See the Known Issues for conditions that can affect the success of your upgrade. Take any required corrective actions.
Upgrade an Apache Tomcat Single Server
Follow these steps:
  1. Stop and remove all services. Run the following commands:
    service stop app bg nsa beacon service remove app bg nsa beacon
  2. Set up the application server by installing or upgrading needed third-party software. See 
    Configure the Tomcat Application Server
     in Install CA PPM.
  3. From the command prompt, navigate to the directory where you want to unpack the 
    CA PPM
     installer file.
  4. Run the following commands: 
    mkdir temp cd temp
  5. Run the following command to extract install.jar from the installation media:
    jar -xvf <path of the installation media>/install.jar
  6. Run the installation script:
    UNIX
    chmod +x ./install.sh sh ./install.sh
    Windows
    install.bat
  7. To complete the command-line upgrade, follow the prompts. 
    During the upgrade, default values from the existing 
    CA PPM
     installation are automatically entered as responses to the prompts.
    See the following list for upgrade property descriptions:
    • CA PPM
       Home Directory
      Specifies the directory in which to install 
      CA PPM
      . This directory is created if it does not exist.
    • CA PPM
       Target Directory (upgrade only)
      Specifies a new install directory for the upgrade process that is different from the current install directory. The default value is the current install directory.
    • JDK 1.8.0 Home Directory
      The Java JDK home directory (1.8.0_40 or higher).
    • Beacon Multicast Address
      The multicast address that the Beacon and 
      CA PPM
       System Administration use for service discovery. Each 
      CA PPM
       cluster requires a unique IP address. The multicast address must be in the Class address range between 224.0.0.0 and 239.255.255.255. Each server within a cluster must use the same address and port. 
      Default value: 230.0.0.1
      We recommend an IP address in the 239.x.x.x subnet.
    • Beacon Multicast Port
      The port that the Beacon and 
      CA PPM
       System Administration use for service discovery. Each 
      CA PPM
       cluster requires a unique IP address. Each server within a cluster must use the same address and port.
      Default value: 9090
    • Beacon Client Port
      Defines the server port number that the Beacon service uses.
    • Super User Command Prefix
      (UNIX only) The optional command prefix utility, such as sudo, to execute root-level commands. An example where you could implement a root-level command is when choosing a socket port below 1024 because root-level access is required to allocate it.
    • Super User Name
      (UNIX only) The optional replacement for the 
      root superuser
       name. This name can be used alone or with the superuser command prefix. For example, if used with sudo, specify the user to which sudo rights are given here.
    • J2EE Server Vendor
      Specify the J2EE server vendor: Apache Tomcat (default).
    • Install 
      CA PPM
       System Administration (CSA) Locally
      (Apache Tomcat only) Enter one of the following values:
      • If you are installing 
        CA PPM
         System Administration on this server, enter 
        true
        .
      • Otherwise, enter 
        false
        .
    • Tomcat 8 Home Directory
      (Apache Tomcat only) Defines the Apache Tomcat home directory.
    • CSA Web Port
      (Apache Tomcat only) Defines the web port number that 
      CA PPM
       System Administration uses. For a UNIX system, this value must be greater than 1024, or the service must be run as root.
    • Enter password
      (Apache Tomcat only) Specifies the 
      CA PPM
       System Administration password.
      Default value: admin
    • Operator User Name
      Specifies the user name of the operator who is running the installation script. This information is kept as a record in the installation log.
    • Operator Email Address
      Specifies the email address of the operator who is running the installation script. This information is kept as a record in the installation log.
    • Acknowledge reviewing Install Guide and Change Impact & Upgrade Guide
      This prompt records a response from installing users that they have read both 
      Installing and Upgrading
       and 
      Change Impact and Upgrade.
  8. Start the 
    CA PPM
     System Administration application.
  9. Update the properties of the server:
    1. In the left navigation panel, click Servers and select the server.
      The Properties tab for the server appears.
    2. Click each subtab on the Properties tab and complete the fields necessary for your configuration.
      For complete information about all of the fields on the subtabs, see
      CA PPM
      System Administration (CSA) Server Properties
      .
  10. Start all services.
    1. Click All Services.
    2. Select the services and Click Start.
  11. To verify that 
    CA PPM
     is accessible from a browser, connect using the configured Entry URL value.
    The Entry URL is configured in 
    CA PPM
     System Administration on the Application subtab. If you have multiple application servers, the Entry URL points to the load balancer. If you have a single-server installation, the Entry URL points to the application server. 
The Entry URL has the following format:
http://<server name>:<port>/niku/nu
The default user ID and password are admin/admin. If the default HTTP port value of 80 is used, you do not have to specify the <port> value.
Upgrade an Apache Tomcat Clustered Server
Follow these steps:
  1. Remove all services in the cluster.
  2. Set up all servers by installing or upgrading needed third-party software. See 
    Configure the Tomcat Application Server
     in Install CA PPM.
  3. Open a command prompt on the server, and navigate to the directory where you want to unpack the 
    CA PPM
     installer file.
  4. Run the following commands:
    mkdir temp cd temp
  5. From the directory, run the jar command to extract install.jar from the installation media:
    jar -xvf <path of the installation media>/install.jar
  6. Run the installation script:
    UNIX
    chmod +x ./install.sh sh ./install.sh
    Windows
    install.bat
  7. To complete the command-line upgrade, follow the prompts. 
    During the upgrade, default values from the existing 
    CA PPM
     installation are automatically entered as responses to the prompts.
    See the following list for upgrade property descriptions:
    • CA PPM
       Home Directory
      Specifies the directory in which to install 
      CA PPM
      . This directory is created if it does not exist.
    • CA PPM
       Target Directory (upgrade only)
      Specifies a new install directory for the upgrade process that is different from the current install directory. The default value is the current install directory.
    • JDK 1.8.0 Home Directory
      The Java JDK home directory (1.8.0_40 or higher).
    • Beacon Multicast Address
      The multicast address that the Beacon and 
      CA PPM
       System Administration use for service discovery. Each 
      CA PPM
       cluster requires a unique IP address. The multicast address must be in the Class address range between 224.0.0.0 and 239.255.255.255. Each server within a cluster must use the same address and port. 
      Default value: 230.0.0.1
      We recommend an IP address in the 239.x.x.x subnet.
    • Beacon Multicast Port
      The port that the Beacon and 
      CA PPM
       System Administration use for service discovery. Each 
      CA PPM
       cluster requires a unique IP address. Each server within a cluster must use the same address and port.
      Default value: 9090
    • Beacon Client Port
      Defines the server port number that the Beacon service uses.
    • Super User Command Prefix
      (UNIX only) The optional command prefix utility, such as sudo, to execute root-level commands. An example where you could implement a root-level command is when choosing a socket port below 1024 because root-level access is required to allocate it.
    • Super User Name
      (UNIX only) The optional replacement for the 
      root superuser
       name. This name can be used alone or with the superuser command prefix. For example, if used with sudo, specify the user to which sudo rights are given here.
    • J2EE Server Vendor
      Specify the J2EE server vendor: Apache Tomcat (default).
    • Install Clarity System Administration (CSA) Locally
      (Apache Tomcat only) Enter one of the following values:
      • If you are installing 
        CA PPM
         System Administration on this server, enter 
        true
        .
      • Otherwise, enter 
        false
        .
    • Tomcat 8 Home Directory
      (Apache Tomcat only) Defines the Apache Tomcat home directory.
    • CSA Web Port
      (Apache Tomcat only) Defines the web port number that 
      CA PPM
       System Administration uses. For a UNIX system, this value must be greater than 1024; otherwise, the service must be run as root.
    • Enter password
      (Apache Tomcat only) Specifies the 
      CA PPM
       System Administration password.
      Default value: admin
    • Operator User Name
      Specifies the user name of the operator who is running the installation script. This information is kept as a record in the installation log.
    • Operator Email Address
      Specifies the email address of the operator who is running the installation script. This information is kept as a record in the installation log.
    • Acknowledge reviewing Install Guide and Change Impact & Upgrade Guide
      This prompt records a response from installing users that they have read both 
      Installing and Upgrading
       and 
      Change Impact and Upgrade.
  8. Start the 
    CA PPM
     System Administration (CSA) application.
  9. Update the properties for each server in the cluster.
    1. In the left navigation panel, click Servers and select the server.
      The Properties tab for the server appears.
    2. Click each subtab that is listed on the Properties tab and complete the fields necessary for your configuration.
      For complete information about all of the fields that are found on the subtabs, see CSA: CA PPM System Administration.
  10. Verify that the database is accessible.
    To verify, open the Database subtab for a server and in the Internal Connection section verify that the status is Available.
  11. Start the Beacon service on all servers in the cluster.
    The Beacon service is required to distribute the upgraded content remotely to servers in the cluster.
  12. In the left navigation pane, select Distribute All.
    The Distribute All process is typically used to upgrade other servers in a cluster. However, if you are upgrading to 
    CA PPM
     from a version earlier than Release 8.1.1, you are required to upgrade each server individually.
    Use the following steps if you are upgrading from a release earlier than Release 8.1.1:
    1. Use FTP or otherwise transfer the install.jar file to the other servers in your distributed installation.
    2. Stop the local Beacon service before installing the new package.
    3. Install on each server using the install.jar file.
    4. Restart the Beacon service when all servers are installed.
  13. After the Distribute All process is complete, stop the Beacon service.
  14. Manually copy the following JAR files from the administration server that runs 
    CA PPM
    System Administration (CSA) to all the remaining servers in the cluster. The JAR files replace the existing files in the $CLARITY_HOME/bin AND $CLARITY_HOME/lib directories. This extra step avoids any issues that might arise from distributing while files are in use on the administration server.
    <install_dir>/bin/wrapper.jar<install_dir>/lib/commons-logging.jar<install_dir>/lib/jgroups-all.jar<install_dir>/lib/log4j.jar<install_dir>/lib/nsa.jar <install_dir>/lib/union.jar
     
  15. To verify that the installation steps completed successfully, click Installation Overview in the left navigation pane.
  16. Review the server 
    admin.log
     file for general errors or custom Studio Query (NSQL) validation errors.
  17. Start all services.
    1. Click All Services.
    2. Select the services and Click Start.
  18. To verify that 
    CA PPM
    is accessible from a browser, connect using the configured Entry URL value. The Entry URL is configured in CSA on the Application tab. If you have multiple application servers, the Entry URL points to the load balancer. If you have a single-server installation, the Entry URL points to the application server. The Entry URL has the following format:
    http://<server name>/niku/nu
    The default user ID and password are admin/admin.
Complete the Post-Upgrade Tasks
The following post-upgrade tasks are required:
  • If you are upgrading with XDM, ensure that the XDM is distributed to other servers in the cluster.
  • Run the Oracle Table Analyze Job from 
    CA PPM
     after the upgrade is done to gather schema statistics. The expected time for this job to complete depends on the size of the database. We recommend that you run this job right after the upgrade and at off peak hours thereafter. If you use a custom statistics job, refer to the updated Oracle Table Analyze Job procedure in the 
    CA PPM
     schema in Release 14.2 (CMN_JOB_ANALYZE_SP) and make necessary corrections in the custom statistics job.
  • To help ensure the correct functionality and accuracy of data in 
    CA PPM
     and all jobs, including the Load Data Warehouse Job, verify the following:
    1. The server time is the same (preferable, down to the second) on the 
      CA PPM
       application server, 
      CA PPM
       database server, and Data Warehouse database server.
    2. The timezone, date, and time is the same on the 
      CA PPM
       application server and database servers in the same environment. Do not have any differences. This synchronization is necessary because the Load Data Warehouse job imports data into the Data Warehouse database based on the last_updated_date field on the object's instances. If the date and time on the servers do not match, data may not be loaded into the Data Warehouse. For other jobs, if the date and time do not match, the job may not start. Or, the job may start later than expected, leading to inaccurate data.
  • Review the post upgrade report that the checkinstall utility generates. 
    The files are zipped into an archive that has a timestamp-encoded name (for example, checkinstall-results_2018-12-17_16-48-31.zip). This file is located in the checkinstall/check-logs directory, and if possible, the file is copied into the <target runtime dir>/logs/checkinstall directory.
  • Gather the schema statistics by running the Oracle Analyze job at the end of the upgrade.
  • Verify the performance metrics. During the upgrade, performance metrics are collected and the following files are written to the Logs folder:
    • ScriptMetrics.xml
    • Bootstrap.xml
    The files contain the following information:
    • A list of all upgrade scripts executed
    • The row count of every table that is processed by preupgrade and postupgrade processing
    • The execution time and results for each script or object
  • Verify that Beacon is always running to manage services and view logs.
  • Ask your functional experts to review your upgraded test system side-by-side with a working preupgrade system.
    Tip
    : Use dual monitors for side-by-side comparison.
  • Review the 
    app-ca.log
     after the functional experts have used the test environment and look for new errors.
  • Review any customizations: Customer-added database triggers, custom indexes and constraints, any file system changes, and custom interfaces. Review anything that did not come out-of-the-box. Adjustments may be necessary for customizations to work with this release.
  • Review the system log file sizes. The log file size for all service system log files is set to 5 MB and to keep five rolling logs (for example, app-system.log, app-system.log.1).
  • GEL Tag Restrictions: Release 13.1 gave the ability to restrict certain GEL tags in an environment. See Upgrade Considerations for Release 13.1.
  • Register any Portfolio Investment attributes that you want to display in portfolio pages. Although the required attributes display by default, you must register any other attributes (stock or custom) that you want to display.
  • Remove the 
    Resource - Edit Financial
     access right.
  • If your company policy does not allow resource managers access to the Financial Properties subpage for the resources they manage, you can remove that capability.
  • Run a post installation script to perform the following actions:
    • Remove the 
      Resource - Edit Financial
       access right from all current resource managers.
    • Clear the setting for the financial option that automatically grants the access right to new resource managers.
    To maintain existing behavior, this right is granted during the upgrade. This right replaces the automatic right that was removed as part of the Financially Enabled Roles feature.
    Follow these steps:
    1. At the command line on the 
      CA PPM
       server, navigate to the <clarity_home>/bin directory.
      The directory contains the dbpatch script.
    2. Refer the knowledge base article here to disable the Resource - Edit Financial access right.
  • Upgrade any add-ins that you intend to use with this release. See Add-Ins and Integrations.
  • Identify the 
    CA PPM
     views that were upgraded automatically and the views that you must upgrade manually.
  • Configure portlets and portlet pages as appropriate to expose or hide the new functionality after the upgrade.
  • Update rights assignments for users, groups, or OBS instances with new or updated security rights that are introduced in this release.
  • If your users run the Schedule Connect clients, Microsoft Project (MSP) or Open Workbench (OWB), and the XOG client, each user needs to install the newest version of the XOG client that ships with 
    CA PPM
    . Also verify your version of MSP or OWB with the Compatibilities section of the Release Notes. Do not automatically update MSP or OWB. Sometimes the newest version is not compatible. 
    Note
    : Review these steps after installing a patch to verify any changes in functionality.
  • After upgrading, run the following jobs in the listed order:
    1. Load Data Warehouse (select the Full Load option)
    2. Load Data Warehouse Access Rights
  • Do not use the following views to build new reports. The views were created to support the existing reports that were based on the deprecated tables. The existing reports will still work, but you may experience slow performance:
    DWH_INV_SECURITY
    DWH_RES_SECURITY
  • Use the following views to build new reports:
    DWH_INV_SECURITY_v
    DWH_RES_SECURITY_v
Verify NSQL Queries
During the upgrade process, the checkinstall utility automatically runs the NSQL validator script to verify the NSQL queries. The validator writes the results to the admin.log file in the check-results.html file inside the checkinstall-results.zip file.
Look for the following information in the log:
  • Query name
  • Query ID
  • Content Source
  • Query ID from CMN_NSQL_QUERIES of the query that failed validation
Database schema changes can impact your custom portlets. See Oracle and MS SQL Database Schema Changes.
Correct any invalid NSQL queries. If a query is associated with a portlet, clear the
Available for User Portlets
check box on the query properties page to edit the query. You cannot edit system queries that are provided by 
CA PPM
.
Follow these steps:
  1. Open Administration, and from Studio, click Queries.
  2. Open a query.
  3. Clear the Available for User Portlets check box.
  4. Click Save and Continue.
  5. Review the errors and repair the broken query constructs or fields.
  6. Click the Preview button.
  7. Confirm that the NSQL query is valid.
  8. Click the General tab.
  9. Select the Available for User Portlets check box.
  10. Click Save and Return.
Some NSQL queries are delivered with add-ins. Applying an update for an add-in makes fixes for the NSQL queries that pertain to the add-in available for an update on the server.
If the query is in use by active portlets and cannot be edited in Studio, complete these steps:
  1. Use the XML Open Gateway (XOG) to export the failing query.
  2. Correct the broken query constructs or fields.
  3. Use XOG to import the corrected query.
  4. In Studio, go to the NSQL tab for the imported query and click the Preview button.
  5. Confirm that the NSQL query is valid.