Upgrade Clarity PPM

The following image shows how an administrator upgrades a cappm installation for single and clustered servers. As a SaaS administrator, you do not execute the upgrade steps yourself; however, you still need to perform pre-upgrade and post-upgrade steps. For example, you upgrade from a test instance to a production instance.
ccppmod154
The following image shows how an administrator upgrades a 
Clarity PPM
 installation for single and clustered servers. As a SaaS administrator, you do not execute the upgrade steps yourself; however, you still need to perform pre-upgrade and post-upgrade steps. For example, you upgrade from a test instance to a production instance.
This image shows how to upgrade CA PPM
This image shows how to upgrade CA PPM
How Long Does It Take to Upgrade? 
From the day our SaaS customers place a ticket to request an upgrade, the entire process only requires approximately 2 to 4 days to be completed, plus 4 to 7 days for production environments, for a combined time of about 10 to 15 days. (More time is often used to conduct additional testing or try new features. We have seen very complex customer requirements with upgrade validation windows as long as 30, 60, or even 90 days.)
  1. All non-production upgrades are processed in batches which start every week on a Monday or Tuesday. 
  2. Each SaaS upgrade ticket shows when the new live environment is ready for your users. The customer contact person on the upgrade ticket also receives an email notification. As the SaaS contact, you can then notify other individuals that require a status update for the upgrade.
    : To start a non-production SaaS upgrade, enter a ticket. When your team is finished testing, open a new ticket titled
    “Testing Complete, Upgrade Production”
    to request the production upgrade.
  3. Allow 5 to 7 business days of lead time for receiving and scheduling your production upgrade request. Even with a submitted production ticket, we cannot guarantee availability in the next upgrade cycle. Availability of the date requested as well as standard maintenance windows are considered prior to a confirmation of a date provided on the ticket from the SaaS upgrade team. 
  4. Production upgrades typically start on the next available Friday after close of business and typically finish by the end of the next day (Saturday). 
  5. Each SaaS upgrade ticket shows when the new live environment is ready for your users. The customer contact person on the ticket also receives an email notification. As the SaaS contact, you can then notify other individuals that require a status update for the upgrade.
: If you require immediate assistance with a major issue in your post-upgrade production environment, open a
Severity 1
ticket. If a rollback to the prior version is necessary, the whole process restores all your original pre-upgrade data.
As a
Clarity PPM
user, you enjoy seamless automated upgrades in the cloud. SaaS administrators can prepare for an upgrade, review the new features, and perform any required or optional changes post-upgrade.
Pre-Upgrade: Review the Requirements
Address the following important points before you begin an upgrade:
  • Days or weeks in advance, you can run a health report and examine any customizations that could interfere with a future upgrade. See Health Report, Job Monitor, Governor Settings, and Data Warehouse Audit Dashboard.
  • Review the Release Information including the Release Notes and Change Impact and Upgrade documentation. See the
    Known Issues
    for conditions that can affect the success of your upgrade. Take any required corrective actions. Read the Change Impact and Upgrade information for each release between your current one and the target release.
  • Verify that you are following a recommended upgrade path. Not all product releases and patch levels have supported upgrade paths between them.
  • Run the Delete Process Instance job in your current environment. 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.
  • 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.
  • Check any third-party software you might also be upgrading, or be required to update.
    For information about the versions of third-party software that this release supports, see the CA PPM 15.4 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 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. Review and fix all invalid transactions. Verify the following conditions: 
    • imp_transactionimport and ppa_transcontrol are clear.
    • WIP adjustments are approved.
  • 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.
  • (Optional) Clear the Datamart and recreate the data post-upgrade to improve the processing time of the upgrade. 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 the upgrade.
  • Turn off auditing on all objects before you start the upgrade process.
: Only on-premise customers can run a checkinstall utility before starting their upgrade. As a SaaS administrator, be advised the following process is taking place for you by CA SaaS Operations.
Clarity PPM
SaaS Ops runs the checkinstall utility for your On Demand PPM instance a few days in advance of the scheduled installation date. If a validation error is found, a Support case is opened and logged under your customer site ID for visibility.
Pre-Upgrade Steps
  1. You must have the standard base calendar available in your 
    Clarity PPM
     application before you upgrade. If you deleted the shipped calendar that is named 
    Standard
    , create it before upgrading. Contact CA Support if your instance is missing the Standard base calendar.
  2. Process all 
    In progress
     transactions into WIP.
    1. Verify the following conditions: 
      1. imp_transactionimport and ppa_transcontrol are clear.
      2. WIP adjustments are approved.
    2. Review and fix all invalid transactions.
  3. 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 system performance.
  4. Complete and put all processes on hold.
  5. Remove or delete process history, notifications, jobs, or logs. Look for items that you do not need to keep.
  6. Pause all scheduled jobs. Take special note of the 
    Time Slicing
     job. Pause it before stopping the 
    Clarity PPM
     services before upgrading.
Pre-Upgrade: Custom Processes, Scripts, and Other Customizations
Clarity PPM
 cannot upgrade any unsupported customized content. Customizations must be disabled and may need to be redesigned and re-implemented to work with changing product functionality.
! After an upgrade, unless you disable them, your customizations might result in errors or fail to work as expected.
Follow these steps
:
  1. Identify your custom content in your current release. For example, you have one or more custom processes with custom GEL scripts that modify timesheet status attributes.
  2. Acknowledge the customizations and recognize that the upgrade scripts might not support the custom content. Even if the custom content is upgraded, it may no longer work as expected. For example, your custom process references an object or attribute that has changed in the new release.
  3. As an on-premise administrator, the checkinstall script provides a warning for customizations that it detects pre-upgrade. As an on-demand administrator, you do not see these warnings or the referenced logs. To assist all administrators, we show the following example message in full to provide insight into the types of customizations that can negatively impact your upgrade experience: 
    WARNING: Possible schema customizations have been found. Any customizations to the system are the responsibility of the customer to maintain and are not supported by CA Technologies. To upgrade successfully, all customizations must be reviewed, changed, or removed as needed before the upgrade. After a successful upgrade, the customizations may be added back to the system. The possible customizations found are listed in the following log files:
    check‐logs/database_customization_triggers.txt check‐logs/database_customization_indexes.txt check‐logs/database_customization_tables.txt checklogs/database_customization_constraints.txt
  4. Turn off the customizations before the upgrade. After the upgrade, reintroduce the customizations and test them in the Classic PPM interface. Optionally, verify the impact of the customization behavior on the 
    New User Experience
    .
  5. In addition to database objects, also evaluate attribute values. Review the Oracle and Microsoft SQL database and data warehouse changes (see the 
    Reference
     section in the English documentation). Validate if any of your customizations depend on any dropped, changed, or new attributes.
: Some customers have experienced errors with legacy custom content. After disabling the custom process, script, or other legacy custom content, the
New User Experience
provided the functionality with no net loss to end users. We recommend that you perform an analysis comparing the value of
Clarity PPM
features in a complete COTS/SaaS solution against the value of developing your own unsupported customizations.
Complete the Post-Upgrade Steps
Post-Upgrade: Optimize Oracle 12c Performance
On local installations of Oracle 12c R1 or R2, you might detect a regression issue with Oracle 12c when ORDERED hint is used in structured queries. An Oracle bug in 12c R2 can degrade performance if the optimizer is set to 12.2.0.1.
  • For systems using Oracle 12c R1 (12.1.0.2), no further action is required.
  • For systems using Oracle 12c R2 (12.2.0.1), you can optimize performance by setting the optimizer to 12.1.0.2. We recommend applying this optional local fix.
Follow these steps
  1. From a command prompt in Oracle, enter the following lines:
    sqlplus / as sysdba ALTER SYSTEM SET "_fix_control" = '17800514:0'; Exit;
  2. Run the following command:
    ALTER SYSTEM SET OPTIMIZER_FEATURES_ENABLE= '12.1.0.2' SCOPE=BOTH;
  3. Verify that your Oracle 12c R2 initialization file parameters appear similar to the following example:
    *._fix_control='17800514:0' *._optimizer_multi_table_outerjoin=FALSE *.audit_file_dest='/fs0/oracle/12201/12c/admin/niku/adump' *.audit_trail='DB' *.cluster_database=FALSE *.compatible='12.2.0.1' *.control_files='/fs0/oracle/12201/12c/oradata/niku/CONTROL01.CTL','/fs0/oracle/12201/12c/oradata/niku/CONTROL02.CTL' *.cursor_sharing='FORCE' *.db_block_size=8192 *.db_name='niku' *.diagnostic_dest='/fs0/oracle/12201/12c/admin/niku/udump' *.dispatchers='(PROTOCOL=TCP) (SERVICE=nikuXDB)' *.local_listener='LISTENER_NIKU' *.nls_comp='BINARY' *.nls_date_format='YYYY-MM-DD HH24:MI:SS' *.nls_language='AMERICAN' *.nls_sort='BINARY' *.nls_territory='AMERICA' *.open_cursors=1000 *.optimizer_adaptive_plans=false *.optimizer_adaptive_reporting_only=TRUE *.optimizer_adaptive_statistics=FALSE *.optimizer_features_enable='12.2.0.1' *.optimizer_inmemory_aware=FALSE *.pga_aggregate_target=4G *.processes=1000 *.remote_login_passwordfile='EXCLUSIVE' *.session_cached_cursors=1000 *.sessions=1536 *.sga_target=80G *.streams_pool_size=536870912 *.trace_enabled=TRUE *.undo_tablespace='UNDOTBS1'
Post-Upgrade: Trending Data Backups 
After the upgrade, if you use the new trending jobs to generate your own custom analytics data, we recommend that you make specific backups. A common troubleshooting technique for on-premise administrators involves dropping the data warehouse schema. If you have used that technique in the past or might in the future, exercise caution. Data warehouse data can be restored; however, without a backup, your custom trending data would be lost.
Post-Upgrade: Final Steps to Complete Your Upgrade
The following post-upgrade steps are required:
  • To verify that all components are installed and functioning after an upgrade, run the Health Report.
Post-Upgrade: Verify NSQL Queries
During the post-upgrade process, the CheckInstall utility automatically runs the NSQL validator script to verify your 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
The following output represents a typical log file at this phase of the upgrade:
[04:15:25] : [exec] validateNSQL: [04:15:25] : [exec] Validating NSQL [04:15:25] : [exec] JVM args ignored when same JVM is used. [04:15:25] : [exec] Working directory ignored when same JVM is used. [04:15:28] : [exec] Failed to instrument com.niku.union.utility.caching.CacheController [04:15:28] : [exec] Failed to initialize instrumentation: access denied ("javax.management.MBeanTrustPermission" "register") [04:15:30] : [exec] Validating 181 NSQL grid/graph queries... [04:15:47] : [exec] Error validating NSQL [04:15:47] : [exec] Query name=Schedule Performance : Query ID=cop.schedulePerformance : Content Source=csk.niku.com : cmn_nsql_queries.id=5018009 [04:15:47] : [exec] Query name=Upcoming Milestones : Query ID=cop.upcomingMilestones : Content Source=csk.niku.com : cmn_nsql_queries.id=5018010 [04:15:47] : [exec] Query name=Open Milestones : Query ID=cop.openMilestonesLinkable : Content Source=csk.niku.com : cmn_nsql_queries.id=5018032 [04:15:47] : [exec] Query name=Upcoming Key Tasks & Milestones : Query ID=asp.upcomingkeytasksmilestones : Content Source=customer : cmn_nsql_queries.id=5074025 [04:15:47] : [exec] You must correct invalid NSQL queries. In PPM Studio, go to the NSQL tab for each failing NSQL query. Click the 'Preview' button to view the error details. [04:15:47] : [exec] Total execution time: 0H:0M:18.796S [04:15:47] : [exec] perform-check: [04:15:47] : [exec] report-result: [04:15:47] : [exec] script name = check-invalid-nsql.xml [04:15:47] : [exec] check.result = WARNING [04:15:47] : [exec] _output-log-info: [04:15:48] : [exec] Trying to override old definition of task checkIfDWHInstalled
Database schema changes can also impact your custom portlets. See Oracle and MS SQL Database Schema Changes.
Correct any invalid custom 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 
Clarity PPM
.
Follow these steps:
  1. Click
    Administration, Studio, Queries
    .
  2. Open each failing query and click the
    NSQL
    tab.
  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
    .
: If the query is in use by active portlets and cannot be edited in Studio, use the XML Open Gateway (XOG):
  1. Export the failing query.
  2. Correct the broken query constructs or fields.
  3. Use XOG to import the corrected query. Perform the steps above this tip to preview and verify the query.
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.