Change Impact and Upgrade

ccppmop1593
HID_HID_release_info_change_impact_od
This
Change Impact and Upgrade
page highlights significant changes, required actions, known issues, and recommended options for customers upgrading from the previous release to
Clarity
15.9.3
. Plan your
Clarity
upgrade and determine the options that fit your business needs. Teams can also use this information to plan your new feature adoption, onboarding, and training efforts.
For compatibility related information see, Hardware and Software Compatibility Specifications
For installation and upgrade related information see Installing and Upgrading
For example, you are upgrading from
Clarity
Release 15.5 to
15.9.3
. Review the changes in releases 15.5, 15.5.1, 15.6, 15.6.1, 15.7, 15.7.1, 15.8, 15.8.1, and 15.9 before and after you upgrade. To switch to the
Change Impact and Upgrade
page for each release, click the
Versions
menu at the top of this page. Check back often for updated content, especially if you downloaded a PDF file. The English edition of this documentation is periodically updated with new information including new examples, explanations, corrections, and patch information.
To prepare for an upgrade to
Clarity
15.9.3
, review the supported upgrade paths, features, enhancements, and required upgrade actions. The following information summarizes how the new changes introduced in this release impact your upgrade experience.
Clarity
15.7 Onward - OracleJDK will be replaced with AdoptOpenJDK
Java Image
With effect from August 19, 2019,
Clarity
has discontinued product updates related to Oracle Java. This will allow our development team to focus on adding value to future product releases.CA Technologies, a Broadcom Company (CA), continues to support its products and stand by the terms and conditions set forth in the license agreements between CA Technologies and its customers.
Existing customers may continue to run and use releases that include Oracle Java components in production and non-production environments
. However, to address any future Java security and vulnerability issues that may arise, it may be necessary for customers to install a service pack or upgrade to a newer release of
Clarity
that supports AdoptOpenJDK. This change does not impact Jaspersoft, which will continue to support Java 8.
This page includes the following sections:
2
Introducing Visual Widgets for To Dos and Hierarchies
Linked
You can review and summarize the health of an investment in Clarity by using a series of predefined visual widgets in the following areas:
  • To Dos page
  • Risks, Issues, and Changes modules in Hierarchies
In this release of Clarity, the following widgets are available:
  • Progress Ring
  • Number Tile
  • Bar
  • Pie

You can use these widgets to display visual information associated with various attributes such as Completed and Open To Dos, Top Three Owners for ToDos, and Risks Above a Threshold.
Some of the key points to remember are:
  • The widgets are not customizable in this release of Clarity.
  • When you save a view, then your widget preferences are also saved.
  • The colors in the pie chart and bar widgets can be configured by configuring the display mapping of relevant attributes.
Upgrade Impact
: After you upgrade to this release, you can click
Add Widgets
to select and add widgets on your page.
To learn more about visual widgets, see Clarity: Track and Edit To Dos and Clarity: Create and Edit Hierarchies.
Clarity Rally Enhancements

Synchronize Lookups Between Clarity and Rally
Linked
The Import Integration Mappings job fetches the Milestones, Investment Categories, Date, and Project lookups from Rally and stores them in Clarity. These (4) dynamic lookups are now available as a part of the PMO Accelerator add-in and will be available to you when you install this add-in.
You can now perform the following actions to map lookups:
  • Leverage existing Rally Lookups imported into Clarity: Create custom attributes in Clarity that leverage the Rally Investment Categories, Rally Milestones, Rally Projects, and Rally States lookups. You can then use field mappings to map these custom attributes to the relevant lookups in Rally. For example, you can create a Clarity Project Milestone field that leverages the Rally Milestone lookup. You can then leverage Field Mappings to map the Clarity Project Milestone field to the Rally Milestone field in Rally.
  • Use the Lookup Mapping tab to configure other lookups: You can use the Lookup Mapping tab to map lookup values in Clarity with Lookup values in Rally enabling data synchronization control. For example, you can map the Investment Category lookup in Rally to the Cost Type lookup in Clarity. You can then define the field mapping to ensure these lookups are updated when their values are updated in Clarity or Rally.
Some of the key points to remember when you leverage the Lookup Mapping capability are:
  • The Administrator needs to install the new PMO accelerator to ensure that the four new lookups are available to users.
  • Administrators need to create dynamic lookups attributes, at either the Clarity Investment, Object, Idea, or Custom Investment levels depending on their requirements.
  • When you map the Rally Projects, Milestones, States, or Investment Categories lookup to a Clarity custom lookup, the administrator does not need to use the Lookup Mapping tables, but can directly synchronize the values to the target system.
  • It is recommended the Rally States, Projects, and Investment categories lookups are associated with a
    Clarity
    single-value lookup attribute and the Rally Milestones lookup be associated with a
    Clarity
    multi-value lookup attribute.
Upgrade Impact
: When you upgrade to this release, ensure you perform the following actions:
  • Run the Import Integration mapping job to fetch the relevant data from Rally.
  • Install the PMO accelerator to ensure that the four new lookups are available in Clarity.
  • Create dynamic lookups attributes, at either the Clarity Investment, Object, Idea, or Custom Investment levels depending on their requirements.
To learn more about mapping lookups, see Clarity Connections - Rally Integrations.
Bi-Directional Integration Support
Linked
The Field Mapping capability has been enhanced to support bi-directional data changes. When you are creating the field mapping, you can now select Both in the Direction column. This will ensure that whenever users update either Clarity or Rally, the values are synchronized between both systems. In previous releases, you could only define one-way mappings from Clarity to Rally or Rally to Clarity.
The Synchronize Mapped Information job has been enhanced to support bi-directional data changes.
The key points you need to remember are:
  • The "Both" option can only be used when you use
    Update
    in the Sync Option column.
  • You cannot include the same field in multiple mappings.
  • Review the Data Type compatibility table to ensure you are mapping supported field types.
Upgrade Impact:
When you upgrade to this release, you can update your field mappings to leverage the bi-directional integration capabilities.
To learn more about bi-directional integration support, see Clarity Connections - Rally Integrations.
Introducing the To Rally and To Clarity Staging Tables
Linked
A new staging table has been introduced that allows you to review all the data copied from Clarity to Rally after the Synchronize Mapping Information job is successfully executed. In the previous release, the Staging table showcased data that is copied from Rally to Clarity. In Clarity 15.9.3 and higher releases, you will now see the To Clarity and To Rally staging tables.
Some of the key points you need to remember are:
  • The administrative user must log out and log in to view the Staging Tables.
  • The staging table data is removed from
    Clarity
    every time the Synchronize Mapped Information job is run.
  • After the Synchronize Mapped Information job is run, the user will be auto-granted access to the To
    Clarity
    and To Rally tables.
  • The Integration Mapping (view, edit, and delete) Global Access rights are automatically added to the PMO System Administrator group. This back-end process enables access to the Staging Tables.
To learn more about staging tables, see Clarity Connections - Rally Integrations.
Clarity and Rally Name Fields Aligned
The Clarity Investment Name and Rally Portfolio Item Name are now aligned to support up to 256 characters. The following table lists the changes in Clarity.
Clarity Field Name Changes
Clarity Object
Clarity Attribute
Max Size (15.9.3)
Max Size (15.9.2)
Investment
Name
256
80
Roadmap Item
Roadmap Item
256
80
Portfolio Investment
Investment Name
256
80
Task
Name
256
150
Upgrade Impact:
You can now leverage field mapping to map these attributes in Clarity and Rally and without worrying about different character limits for both systems.
Staffing Enhancements

Introducing the New Staffing Page
Linked
The new Staffing page leverages the power of the common grid in Clarity to help you manage staffing requirements for all types of investments in Clarity. You need to have the Staffing - Navigate access right to view this page.
The existing Staffing page has been renamed as Staffing Plan. All existing users who have access to this page will automatically be granted the Staffing Plan - Navigate access right.
Some of the key features available on the Staffing page and missing from the Staffing Plan page are:
  • You can configure the Staffing page to show ETCs and Actuals and get greater visibility into the allocation and availability of resources. This capability is not available on the Staffing Plan page.
  • You can edit the allocation associated with investments by using the Staffing page. This capability is not available on the Staffing Plan page.
  • The Staffing Plan page only shows investments that fall within the telescope period configured by you. This limitation no longer applies to the new Staffing page.
Some of the key features available on the Staffing Plan page and missing from the Staffing page in this release are:
  • You can add staff to investments or associated an investment with a resource by using the Add Icon on the Staffing Plan page. This capability is not available on the Staffing page in the current release.
  • You can quickly know if a resource is over or under-allocated by looking at the color associated with each row on the Staffing Plan page. This capability is not available on the Staffing page in the current release.
  • You could see Non-project investment objects on NPIOs on the Staffing Plan page. These objects are not available on the Staffing page. You can only see Projects, Ideas, and Custom Investments on the Staffing page.
  • You could see investments that did not have any resources, roles, or teams assigned to them on the Staffing Plan page. You will not see such investments on the new Staffing page.
  • If you have resources that are not allocated to any investment, you will see them on the Staffing Plan page but not on the Staffing page.
  • The Forecast column available on the Staffing Plan page is not available on the Staffing page.
Upgrade Impact
: When you upgrade to this release, ensure you consider the following points:
  • The existing Staffing page has been renamed as the Staffing Plan page.
  • Users with access to the Staffing Plan page will automatically get assigned the Staffing - Navigate access right.
To learn more about the new Staffing page, see Analyze Resource Allocation and Staffing by Using the Staffing Grid.
Confirmation Message Before Deletions on the Staffing Plan Page
Linked
Clarity now asks you for confirmation when you use the “X” icon in the Investment to Resources view or the Resources to Investment view to delete the associations between resources, roles, teams, and investments.
In previous versions of Clarity, if you were on the Resources to Investment view and you clicked the “X” icon next to an investment associated with investment: the resource would be removed from the investment. In Clarity 15.9.3 and higher releases, when you click the “X” icon, you will see a confirmation message prompting you to confirm or reject your delete action.
Upgrade Impact
: After you upgrade to this release, users will see a warning when they use the "X" icon to remove a resource or an investment from the Staffing Plan page.
Field-Level Security Supported for Team Object
Linked
You can now secure fields associated with the team object by using the Attributes grid to enforce Field Level Security. Some of the key points you need to remember while implementing Field Level Security for the Team object are:
  1. You cannot secure any TSV fields associated with the Team object. Examples include Actuals, Allocation, and ETC.
  2. You will face issues on the Staffing page if you secure the following fields:
    1. Booking Status
    2. Default Allocation
    3. Open for Time Entry
    4. Requirement Name
    5. Role
Upgrade Impact
: After upgrading to this release, you can secure associated with the Team object.
Business Rules Enhancements

Use Business Rules to Set a Record as Read Only
Linked
You can now configure business rules to mark a record as read-only in Clarity if the conditions set in the business rule are satisfied. Consider an example where you want to record to be read-only when the Work Status attribute is set to Cancelled. You can set the relevant condition and use the Disable Editing Record action.
Some key points you need to remember are:
  • The business rule only prevents the record from being edited by using Clarity. You can still edit the record by using Classic PPM, XOG, REST APIs, or Processes.
  • Its recommended that you add an "Access Group" to your rule condition, just in case if you need certain users to make updates or re-open the record for editing.
  • You will be able to show and hide modules associated with a read-only record based on the business rules.
  • If a business rule makes a record read-only, even users with Field Level Security Edit access will not be able to edit the record.
  • A user with delete access can delete a read-only record.
  • If you use the multi-select edit option and select read-only records, they will not be available in the Bulk Edit dialog box.
Upgrade Impact
: After you upgrade to this release, users will see the Disable Editing Record action on the Rules tab in blueprints.
Dynamic Execution of Actions
In 15.9.3 and higher releases, business rules will execute an action as soon as conditions are met. Users do not need to navigate away or refresh the page for Clarity to execute business rules.
Upgrade Impact
: After you upgrade to this release, users no longer need to refresh their page to execute a business rule.
Enforce Required Attributes for Projects
Linked
In previous versions of Clarity, you could make it mandatory for users to populate an attribute while creating a project in Clarity. However, you could not ensure that the attribute would be required every time a user updated the project. In Clarity 15.9.3 and higher releases, you can use the Always True condition in Business Rules to add a Required Attributes action. This would ensure that Clarity would not allow you to update records if the required attribute is not populated.
If you select the Always True flag, you cannot specify any other conditions in the Business Rule. You can choose only the Required Attributes action and select the relevant attributes.
Some of the key points you need to remember are:
  • The Always True condition in business rules is only applicable to projects.
  • You cannot select read-only attributes and auto-numbered attributes in the Required Attributes section.
  • You cannot select the Blueprint attribute by using business rules.
  • If users create a project by using the New From Template option, Clarity will automatically add the required fields to the New Project window.
  • If users create a project by using the Add Row or Add Card option, Clarity will not force users to populate the attribute while creating a project.
  • When you update a required attribute and it has a non-null value, users cannot change its value to null. However, if an attribute has a null value before you enforced the business rule, users will not be prompted to add a value till they update the attribute.
  • You will not see any asterisk or visual indicator associated with attributes you select in the Required Attributes section. This applies to the grid layout, board layout, Details panel, and Properties module.
  • You cannot enforce this rule on the following data types:
    • Attachment
    • TSV
    • Calculated/Aggregated/Formula
    • Boolean
    • Read-only studio attributes
    • Auto Number fields
    • Rich Text fields
Upgrade Impact
: Only projects using a blueprint that has business rules for required attributes will be impacted. If the project is using a blueprint that has business rules for required attributes, then:
  • End-users can update the projects without entering a value for the attributes required by the business rule. Clarity will not force the end-user to enter a value for those attributes.
  • Once the end-user enters values for any attribute required by the business rule, Clarity will always require a value for that attribute.
Enhancements to Hierarchies

Select the Custom Investments to be Included in Hierarchies
Linked
You can now use the INCLUDE IN HIERARCHIES flag, while creating a custom investment, to decide if it should be included in hierarchies. Remember that once you select this option, it can't be disabled.
Upgrade Impact
: When you upgrade to this release of Clarity, the INCLUDE IN HIERARCHIES flag for existing custom investments would automatically be selected. When you create a new custom investment, you would have the option to include it in hierarchies.
To learn more, see Create a Custom Investment.
Automatically Import Child Investments into Hierarchies
Linked
In Clarity, a new Parent field has been introduced that allows you to define the parent of an investment. You can define a parent for Custom Investments, Ideas, and Projects. The Parent field is available in the Column Panel, Details Panel, Filter, and the View Options panel.
After you have imported the parent into the hierarchy, you can import child investment manually or auto-populate children associated with the investment by using the Auto-Import Children option.
Some key points you need to remember are:
  • You have to import at least one investment manually for using the Auto-Import Children option.
  • You have to delete the child investments manually.
  • The Auto-Import Children option of an investment does not use the investment hierarchy defined in Classic PPM.
  • The Parent field does not prevent you from defining a cyclic relationship. The Auto-Import Children option will import the child investment based on the parent imported by you.
Upgrade Impact
: When you upgrade to this release of Clarity, you will need to define the parent-child relationship between investments before using the Auto-Import Children option in hierarchies.
Risks Issues and Changes Modules Available for Hierarchies
The risks, issues, and changes modules are now available with Hierarchies. You can open these modules to view risks, issues, and change requests associated with all the investments included in your hierarchy. You can now analyze them based on your requirements and work with individual owners to ensure they address them. Some of the key actions you can perform on this grid are:
  • Analyze the risks by using the filtering and group-by capabilities of the common grid. Remember that the Risks, Issues, and Changes grids are read-only grids. Hence, you can analyze the risks, issues, and changes, but you cannot update them.
  • Update risks, issues, and changes by using the Details panel.
Some key points you need to remember are:
Upgrade Impact
: The Risk, Issue, and Changes modules are not automatically visible in the Hierarchy blueprint. You need to manually configure them to add them to your blueprint.
Enhancements to Roadmaps

Introducing the New and Improved Roadmap Timeline
Linked
The Timeline layout has been enhanced to ensure that the user experience is consistent across the Tasks Timeline and the Roadmaps Timeline layouts. Some of the key benefits of the new and improved timeline are experienced when you:
  • Move roadmap items horizontally within a swim lane or vertically across swim lanes.
  • Create and manage dependencies.
  • Adjust the roadmap item start and end dates by using the drag handle.
  • Leverage the scenario comparison capability
Upgrade Impact
: After you upgrade to this release, you will be able to use the new Timeline layout for roadmaps.
Reintroducing the Scenario Comparison Capability
Linked
A scenario is a copy of the roadmap data with a unique name. Scenarios allow you to explore changes to the roadmap items in the context of a what-if scenario. For example, how can we maximize ROI? What if we add 50 resources? What if we increase the contractual price to our client and delay shipping for six months? You can create multiple scenarios for a roadmap and can indicate which is the plan of record and which is the baseline. When you report the portfolio performance, you can decide to use only one plan (for example, the plan of record). As you switch between scenarios, only the roadmap item data changes. Everything else remains the same including the view personalizations and the grouping.
Some key points you need to remember are:
  • A delta icon is displayed if there are differences between selected Roadmap Items.
  • Scenario differences are displayed in the Details flyout “Compare” tab.
  • If a roadmap item does not exist in either the “Compare From” or ”Compare To” scenario, the Details flyout Compare tab will display “Not in "Scenario Name".
  • The following items are validated for scenario differences:
    • Roadmap Item (Name)
    • Roadmap Item Start and Finish date
    • Swimlane
    • Color
    • Metric 1, Metric 2, and Metric 3
  • The zoom function has been removed for this release. You can use a combination of Periods, Start Period, and End Period to obtain the desired Roadmap Timeline perspective.
Upgrade Impact
: This capability was not available in Clarity 15.9.2. After you upgrade to this release, you should be able to leverage the Roadmap Comparison capability in Clarity.
Introducing Blueprints for Roadmaps
Linked
As an application administrator or PMO content designer, you can use blueprints to configure layouts for roadmaps. You can copy and configure blueprints that reflect the goals of each business unit in your organization. Let's consider an example where multiple product management teams in the organization are using roadmaps to achieve different business outcomes. They have created multiple custom attributes. Some attributes are relevant to the New Banking Application Product Management roadmap while others are relevant to the Next-Gen AI roadmap. The administrator can create different blueprints for these teams so each team would only see information relevant to them.
In this release, the Roadmaps blueprint includes the Investments and the Properties modules. Both modules will automatically be included in your blueprint. You can also create channels to embed content from another source, such as an external site, application, or Classic PPM context-sensitive investment reports into roadmaps.
Upgrade Impact
: When you upgrade to this release, you will see the standard blueprints for Roadmaps. The Properties module will be visible by default to users. In order to hide the Roadmap Properties module, you need to create a new default Roadmap Blueprint and remove the Properties module.
To learn more, see Blueprints for Roadmaps.
Enabling Field-Level Security for Roadmaps and Roadmap Items
Linked
Roadmap and Roadmap Item attributes can be secured using field-level security (FLS).  You can use FLS to provide access to specific attributes or fields for specific user groups. Roadmap and Roadmap Item field-level security apply only to Clarity and not Classic PPM.
Some of the key points you need to remember are:
  1. The administrator grants and revokes field access at the group level.
  2. The following items cannot be secured by FLS:
    1. Roadmap - ID, Name, Start Period, Start, Finish, Blueprint Active ID
    2. Roadmap Item - ID, Name, Start, Finish, Currency*, In Plan*, Per-period metrics (e.g., TSV)*
  3. FLS always has precedence over defined Roadmap or Roadmap Item Object security access rights. 
  4. From a third-party integration perspective, the "Integration User” will have access to secured attributes.
Upgrade Impact
: When you upgrade to this release, you will be able to secure attributes associated with the Roadmap and Roadmap Items objects.
To learn more, see Secure Field Level Access.
Synchronizing Additional Attributes between Roadmap Items and Linked Investments
Linked
You can sync the Roadmap Item Name with the "Name" of the linked investment. In prior releases, the Roadmap Item (Name) field could not be synced with the linked Investment name.
Some of the key points you need to remember are:
  • The Sync All Attributes option is selected by default when you open the SYNC LINKED ITEMS page.
  • The 'Roadmap Item’ (Name) is also selected by default. If you don't want to synchronize the Roadmap Item name, clear the checkbox.
Upgrade Impact
: When you upgrade to this release, you will see the Roadmap Name synchronization option.
Customer Requested Enhancements in Clarity

Access Rights Name Updated When You Rename Custom Investment Types or Custom Objects
Linked
When you change the name of Custom Investments or Custom Objects, you can use the Push Object Captions icon to update OBS access rights, Instance Rights, Global Rights, and Sub-object master object names to reflect the updated Custom Investment and Custom Object name.
Some of the key points you need to remember are:
  • The "Push Object Captions" functionality is limited to Custom Master Objects and is not available on Custom Sub Objects, nor Custom Sub Sub Objects. Due to this, the custom sub-object and custom sub-object-related rights may still be out of sync with the latest name of those objects. However, the combination rights generated on a Custom Master Object, like for example, <Master_Object> - Delete All - <Sub_Object>, will still reference the latest name of the Master Object and the Sub Object once the "Push Object Captions" functionality is used on the Master Object.
  • The Sub Page rights that get generated when the page is secured will also get updated.
  • When you push the object name change, it does not update the “Blueprint” name in Clarity.
  • The Object ID and Attribute ID do not get updated when you change the name of the Custom Investment or Custom Object.
Upgrade Impact
: When you upgrade to this release, you can use the Push Object Captions icon to update the access rights in Classic PPM.
Execute Actions in Clarity
Linked
You can use the Actions button to execute a process from projects, custom investments, ideas, roadmaps, and master objects in Clarity. Consider a scenario where you have specific custom attributes associated with a project. You want to conditionally set attributes by using a process when certain conditions are fulfilled.
In previous Clarity releases, you need to open Classic PPM and execute a process to lock these attributes. In Clarity 15.9.3 and higher releases, you can execute a process from the Properties module.
Some key steps you need to perform to execute a process from Clarity are:
  • Ensure that the relevant process is Active and associated with the relevant investment or custom master object. GEL script processes are available across all areas.
  • Edit the relevant blueprint and use the Add Process button on the Actions tab to associate the blueprint with the relevant processes. Save and publish your blueprint.
  • Ensure you have the Process Start or Process Manage access rights for the processes that were added by using the relevant blueprint.
  • Navigate to the Properties module and use the Actions button to execute the process.
Some key points to remember are:
  • You can only call processes where "Active=TRUE" and "Available for On-Demand Start=Yes.”
  • If you delete a process definition in Classic PPM, it will remove the generic action for all blueprints using that process definition.
  • When you execute a process in Clarity, you will see a message stating that the process has started successfully.
  • The Actions button is only available under the Properties module.
  • You can add a maximum of 50 processes to a blueprint.
  • If a process is on hold or disabled, you will get a run time error in Clarity.
  • Processes executed by using the Actions button will NOT enforce any partition logic configured on the process definition. If the user selects that generic action, a runtime error will be displayed.
  • All actions defined on the blueprint will display to the end-user, but the end-user will get a run-time error if the end-user selects an action and does not have the process start or process manage to start that process.
Upgrade Impact
: After you upgrade to this release, you can use the Actions button to execute a process from projects, custom investments, ideas, roadmaps, and master objects in Clarity.
Enhanced Lookup Display in Clarity
Linked
Dynamic query-based lookups in Clarity have been enhanced to use the auto-suggest settings in Classic PPM. You can define which attributes should be displayed when lookup values are presented. You can also control which attributes can be used in the search.
Some of the key points you need to remember are:
  • The Lookup field will auto-adjust to the width of the lookup column.
  • The capability is supported for out-of-the-box and custom dynamic query-based lookups in Clarity.
  • The dynamic lookups are supported in the Clarity common grid, the Details panel, and the Properties module.
Upgrade Impact
: When you upgrade to this release, you will be able to use the enhanced lookups in Clarity. 
Primary Key Length Increased in Clarity
From Clarity 15.9.3 and higher releases, all the primary keys have been updated to the type “Long” instead of a number. This is particularly beneficial to customers who have reached the maximum possible positive number for generating the primary key and are now getting a negative number as the primary key.
Upgrade Impact
: Updating the primary key type from number(10) to long could impact certain custom queries that are hardcoded to get number(10). Customers should evaluate if such hard-coding exists in their environment and mitigate its impact.
Task Owner Field Available in XOG
The Task Owner field is now available in the Project XOG. Some of the key information about this field are:
  • XOG Field name = owner
  • Optional - The Resource Code for a Labor Resource or Defined Team
  • Table and Column = PRTask.task_owner
  • Type = String
Upgrade Impact
: When you upgrade to this release, you can start using the Task Owner field in XOG.
Disable Auto Granting Instance Rights on Custom Objects when using XOG or API
Linked
A new parameter, "assignInstanceRights="false" has been added to prevent auto-assignment of instance rights when you create a new instance of a custom object by using XOG or Rest API. Instances created using the new parameter can only be seen using global or OBS rights. The new flag assignInstanceRights="false" needs to be included on each instance for XOG but it applies to all the instances in a bulk insert for REST API.
Upgrade Impact
: After you upgrade to this release, you can leverage this capability.
Relative Shifting of Dates and Drag Functionality
You can use the following features to effectively edit data in the grid:
  • Relative Date Shifting: You can use the + or - option to shift the values in the date field. For example, you can enter "+2" to increase the date by two days. The date shifting capability does not bypass business rules. You can also use the date shifting capability when you are performing Bulk Edits in Clarity.
    Linked
  • Using the Drag Functionality to Populate Data: You can populate data in the grid layout by dragging the previous value. This will work for the attributes that support copy and paste. You can drag multiple attributes together. The drag functionality supports number sequencing. To use this functionality, hover over a field and start dragging when the plus icon is displayed.
    This functionality only works vertically within a column. Clarity does not support horizontal drag-and-drop capability.
    Linked
Upgrade Impact
: After you upgrade to this release, you can leverage these features.
Enhanced Saved Views in Clarity
Linked
The Save Views functionality in Clarity has been enhanced. In previous versions, when you saved a view, it was available to other users. You can now create a saved view that will only be available to you. You can use the Shared check box to share it with other users. You can also clear this check box to make this view private again. The Saved Views also display the date on which they were last modified.
Some of the key points to remember are:
  • The creator of the saved view can only manage saved views that are not shared.
  • Suppose the end-user selects the Default option and does not check the "Shared" option. In that case, Clarity will automatically select the Shared option since setting a view as default automatically means the view has to be shared.
  • If a user with the "Views - Administer" access right clears the Default checkbox associated with a view, the Shared checkbox will not be automatically cleared.
  • If a user with "Views - Administer" access right clears the Shared checkbox associated with a view, the Default checkbox will be automatically cleared.
  • If you create a view and share it, then a user with the "Views - Administer" access right can make it a default view. You cannot edit or delete that view after it’s been made a default view if you don’t have the "Views - Administer" access right.
Upgrade Impact
: The Shared flag will be unchecked for all existing saved views. This means that you will not see any saved views under the Others option with the following exceptions:
  • Existing saved view marked as Default by someone other than the creator of the saved view.
  • If another user other than the creator has marked the saved view as a favorite.
  • Saved views for Roadmap Items and Hierarchies since the saved views are associated only with a specific instance.
To learn more, see Saved Views.
Introducing Custom TSVs in Clarity
Linked
You can now include custom TSVs in Clarity by API-enabling them in Classic PPM. You can also create new custom TSVs and include them in Clarity.
Some key points you need to remember are:
  • You can enable all three types (Number, Money, and Percentage) custom TSVs for Clarity.
  • You can add custom TSVs to the common grid by using the Column Panel.
  • You can choose to see Custom TSV data as Grand Total or Sum of Period just like you can view data associated with Soft Allocations, Hard Allocations, and other out-of-the-box TSVs.
  • You can spread the custom TSVs evenly over a selected time period.
  • You cannot add custom TSVs to the To Dos object.
  • Clarity will not display custom TSV data in Hierarchy’s grid view.
  • Custom TSV fields cannot be securing using FLS.
  • You can define custom TSVs of time-varying type as “Calendared” or “Fiscal.” However, custom TSVs will automatically be displayed in Clarity in fiscal periods.
  • Clarity will display Custom TSV of time-varying data unit of money without the currency symbol.
Upgrade Impact
: When you upgrade to this release of Clarity, you can update the API Attribute ID for stock and custom TSVs.
Support for Custom Login Message in an SSO Environment
Linked
In Clarity 15.9.2, administrators could display messages to users when they log into Clarity. However, login messages could only be displayed when users were using basic authentication. In this release, this capability has been enhanced to support:
  • Basic authentication login
  • SSO authentication login
  • Navigating from Classic PPM to Clarity
Upgrade Impact: Afte you upgrade to this release, you show display login messages to users using SSO authentication.
To learn more, see Specify Login Message.
Project Management Enhancements

New Access Right Introduced to Control Project Creation Behavior
The following changes have been introduced to the access rights involved in creating projects:
  • The Project - Create access right has been renamed to Project - Create and Create from Template. You can use this access right to:
    • Create a new project by using the "+" button in the Project Grid layout.
    • Create a project by using the Insert Row Below in the Project Grid layout.
    • Create a project by using the "New Card" button in the Project Board view.
    • Create a project by using the "New" button in Classic PPM.
    • Create a project by using the Create From Template button in Clarity and Classic PPM.
  • The Project - Create from Template access right has been introduced in this release. It allows you to perform the following actions:
    • Create a new project by using the Create From Template button in Clarity and Classic PPM.
    • Create a new project by using the Convert an Idea to Project button.
Upgrade Impact
: When you upgrade to this release, all existing users having the Project-Create right will now have the Project-Create and Create From Template access right. If you want certain users to only create projects from templates, you need to remove the Project-Create and Create From Template access right and provide them the Project - Create from Template access right.
To learn more see, Create a Project.
Manage Baselines for Projects in Clarity
Linked
Project baselines are snapshots of the total actual and planned effort and total actual and planned cost estimates for a project at the moment of capture. Baselines are static. As a project manager, the changes you make to your project after creating your baseline do not affect the current baseline. You explicitly update a baseline to reflect changes to project scope or cost. You can view baseline cost and work allocation information. Also, you can view other information, such as earned value (EV) and project performance, that is most relevant to your project and organization.
Create an initial baseline before resources enter time on a project. After the initial baseline, you can create additional ones at various intervals. You can create a baseline midway through the project when different phases are complete or at the end of the project.
In this release, Baselines is available in the project blueprint as a module. After your administrator adds it to the relevant blueprint, you will see all baselines defined in Classic PPM in the relevant projects in Clarity. Some of the key actions you can perform are:
  • View previously created baselines in Clarity
  • Create new baselines
  • Update an existing baseline
  • Delete a baseline
  • Mark a baseline as current
If you delete the current baseline, the latest baseline will automatically become the current baseline.
Some key points to remember are:
  • You need to have the Project - Modify Baseline (global, OBS, or instance) rights to work with baselines in Clarity and Classic PPM.
  • The Usage field is a work-effort unit field, and it will be displayed based on your Clarity settings.
  • You can add custom attributes to the baseline object and view them in Clarity.
  • Baselines are only available in the Project blueprint and can be controlled using business rules.
  • You cannot create baselines for custom investments and ideas.
  • The Baselines object does not support field-level security in this release.
Upgrade Impact
: The Baseline module will be available when you upgrade to this release. However, administrators need to add it to the relevant blueprints to ensure users can access them. The Baseline module will not be a part of the standard blueprint.
Introducing Project lock indicator in Clarity
Linked
You can now see a lock icon that illustrates that a project has been locked because a user is editing tasks by using a scheduler. This functionality was available in Classic PPM and is now available in Clarity. A new field, “Locked By,” is available in Clarity and Classic PPM, which displays the user who has locked the project.
You can also hover your cursor over the Lock icon to view who has locked a project. The Locked By field is available in the Attributes grid so that you can secure it if needed. However, if you secure the attribute, users will not see the lock icon in Clarity.
When a project is locked, some key points to remember are:
  • You cannot edit Project Properties.
  • You can create, edit, or delete the staff associated with the project. However, if your administrator has selected the 'Allow Edit of Allocations when Investment is Locked setting, you will edit the staff associated with the project.
  • You can edit other details such as financial plans, risks, issues, changes, documents, links, and conversations.
  • You can see the project lock icon on the Staffing page.
Upgrade Impact
: Users will see a lock icon for locked projects when they upgrade to this release. Users will also see the Locked By field in Clarity.
Enhanced Project Creation Experience
Linked
The following changes have been made to the project creation experience in Clarity:
  • On the Project Tiles page, the New Project button has been renamed to New From Template.
  • The Project Template selection has been changed from a carousel to a grid layout.
Upgrade Impact
: After you upgrade this release, you will use the New From Template button in Clarity. When you click this button, you can use the Select a Template grid to select the template for the project.
Edit Fields in Timeline Layout for Tasks
Linked
You can now edit data directly in the columns that are a part of your work breakdown structure in the Timeline layout. In previous releases, you had to use the Details panel to edit fields in the Timeline layout.
Some key points you need to remember are:
  • You cannot edit TSV’s directly in the Timeline Layout.
  • The fields in the grid will be colored based on display mapping defined in Classic PPM.
Upgrade Impact
: In previous releases, you could not edit fields in the columns that were in the work breakdown structure of the timeline You will be able to edit data in the columns after you upgrade to this release.
To learn more about the timeline layout, see Clarity: Project Phases, Milestones, Tasks, and To-Do Items.
Enhancements to Investments

Status Reports Available As An Investment Object
Linked
The Status module has been moved from projects to the Investment object. This means that the Status module is now available for Ideas and Custom Investments. You can manage status reports by using the common grid capability on the Status module.
Some key points you need to remember while using the Status Module for ideas and custom investments are:
  • You have to configure the blueprint for Ideas and Custom Investments to enable users to view the Status module.
  • The Preview and Publish to PDF capabilities are not available in this release.
Upgrade Impact
: The Status module will be available in the Idea and the Custom Investments blueprint. Administrators can configure the blueprints to expose this module to end users.
New Jaspersoft Report to Display Status Reports for Investments
Linked
A new Jaspersoft report, Investment Status Report List, is available to display status reports for Projects, Ideas, and Custom Investments. This report derives status report data for Projects, Ideas, and Custom Investments from the Investment Object.
Some key points you need to remember while using the Status Module for ideas and custom investments are:
  • The existing Jaspersoft report entitled “Project Status Report List” has been modified to derive Project status report data from the Investment Object.
  • The Project Management Domain query was updated to derive Project status report data from the Investment Object versus the Project Object
    • Status reports are only included when the Investment “Report Status” attribute is set to “Final”.
    • The most current Investment Status report is only included.
Accessibility Enhancements

Each of the accessibility improvements is needed to drive adoption because organizations demand compliance with accessibility standards to ensure their users have the proper tools to view and access company-specific details. Numerous foundational accessibility improvements have been incorporated encompassing:
  • Visual design (e.g., color, contrast, visible focus)
  • Responsive Design (e.g., pop-up windows, text areas, and browser zoom)
  • Keyboard (e.g., key input, tab order, and focus)
  • Screen readers (e.g., semantics, hierarchy, and pages structures)
In this release, the following Clarity components are compliant with the four aspects of compliance in the form of Visual, Responsive Design, Keyboard, and Screen Reader support:
  • Login page
  • Page ‘SKIP’ link
  • Implemented Custom Toolbar controls for the Action Bar
  • Timesheets grid - Advanced filtering, Money and Number decimal display, Select All / Deselect All, Export to CSV
  • Section component - Properties and Links modules
  • Investment module tabs
  • Overall UX improvements
    • Icon updates, Toast messages styles, Checkbox  and Radio styles
Upgrade Impact
: You can leverage all the accessibility enhancements after you upgrade to this release. To learn more, see Accessibility Features in Clarity.
Datawarehouse Enhancements

Additional Attribute Added To Improve Synchronize Job Performance
In previous releases, if some records were updated, while the Load Datawarehouse job is executing then that updated record does not get synchronized with the Datawarehouse tables. This is because the sync job relies on the last updated date. The Created Date attribute has been added for certain tables. Clarity uses the following table to determine when to use the created date:
Table
Attribute
Description
DWH_META_TABLES
USE_CREATED_DATE
Stores the value 0 or 1 to define if the created date should be used for that table when synchronizing the data. If the record is no longer in the data warehouse, then the created date will be used when it is less than the job run date. This flag is seeded.
SRC_DATE_CREATED_COLUMN
Stores the name of the column in the Clarity transactional database where created date is defined.
inv_investments.created_date
DWH_DATE_CREATED_COLUMN
Stores the name of the column in the DWH database where created date is defined.
Eg. dwh_inv_investment.clarity_created_date
Clarity uses Created Date to determine what to synchronize and will only review the data that is modified when the synchronize job is running. Clarity does not review the newly created data while the Load Datawarehouse is executing.
Upgrade Impact
: After you upgrade to this release, Clarity will synchronize the records that were updated when the Load Data Warehouse job is being executed.
Actuals Synchronization Procedure Updated
You can sum up WIP transactions to the financial cost plan details. The following time slices will be populated when the “Update Financial Plan Actuals” is executed:
  • odf_ssl_cst_dtl_accost
  • odf_ssl_cst_dtl_aunits
  • odf_ssl_cst_dtl_arev
Time slicing can then be used to improve performance when populating the Datawarehouse cost plan tables.
Some key points you need to remember are:
  • The Update Plan Actuals feature directly affects the number of rows in dwh_fin_plan and dwh_fin_plan_ln tables. It will increase the number of rows as the virtual rows will now be actual rows.
  • The dwh_x_plan_per_act_facts table is no longer needed.
  • The following columns will be populated from the time slices:
    • dwh_fin_plan_period_facts.actual_cost
    • dwh_fin_plan_period_facts.actual_units
    • dwh_fin_plan_period_facts.actual_revenue
Upgrade Impact
: When you upgrade to Clarity 15.9.3, this functionality is toggled off by default. Customers can contact the Clarity support team to enable this feature. After you enable this functionality, you should execute the Update Financial Plan Actuals job and then run the Load Data Warehouse job at full load.
Enable Auditing to Three Reporting Tables
The following tables have been enabled for auditing its synchronizing time:
  1. rpt_calendar
  2. rpt_inv_hierarchy
  3. rpt_res_skills_index
When you execute the Load Data Warehouse job, Clarity will populate the load start and end date fields in the cmn_cfg_audit table.
Upgrade Impact
: After you upgrade to this release, you can use the cmn_cfg_audit table to audit the reporting tables discussed in this feature.
Risks, Issues, and Changes Report Updated
The Risk, Issues, and Changes Investment report was updated in Clarity 15.9.2. The following changes have been made in this release:
  • The Investment Type input was updated to only show investments (Projects, Ideas, and Custom Investment Types) that support Risks, Issues, and Changes in Clarity.
  • Investment Manager and Investment input will only show investment types supported in this report
Upgrade Impact
: After you upgrade to this release, you will see that the Risk, Issues, and Changes Investment report only displays investments supporting RICs.
Create New Labels for Stock and Custom Attributes in
Clarity
Linked
You can now use the Attributes grid in
Clarity
to create labels for stock and custom attributes. This functionality allows you to use labels relevant to your organization and make sense to your employees versus using generic Clarity labels. These labels are only applicable in
Clarity
and do not impact Classic PPM. Suppose you change your language to any of the six supported languages (French, German, Spanish, Brazilian Portuguese, Italian, Japanese). In that case, you can enter the label in that language and use it in
Clarity
.
To update a label for a target language, ensure that the Account Settings associated with your username are set to the same language.
Some key points to remember are:
  • You can only provide labels for objects that are supported on the attributes grid. The simplest way to validate the objects supported on this grid is to add an Object filter and view the list of available objects.
  • If you change the attribute label for an attribute associated with the abstract investment object, you cannot change the label associated with the inherited attribute.
  • Clarity will not apply the new labels to the following scenarios:
    • When you create a cost plan in the Financials and Financial Plans Modules, the grouping attribute will not display the changed labels.
    • When using Filter parameters on the Project Tiles and "My Tasks" pages.
    • When viewing attribute labels on the cross-object task grid.
    • When viewing the Conversation Notification Modal.
    • When viewing the Work Progress and Work Stage attributes on Custom Investment Types.
    • When viewing the Integration Field Mappings and the Lookup Mapping popover.
Upgrade Impact
: After you upgrade to this release, you can use the Attributes grid to create labels for stock and custom attributes.
To view the various database schema changes made in this release, see Database Schema Changes.
Upgrade Script Updates NK_Curve Oracle Database Tables
If you are using the Oracle database with Clarity, the upgrade script will remove columns from specific database tables that are of type NK_CURVE. It will then recreate them again with an updated version of the NK_CURVE user data type. After the upgrade is completed, ensure that the Time Slice Sync job runs in order to recreate the data. This is necessary only if you are using SQL curves in your environment.
Internet Explorer 11 Not Supported for
Clarity
Features
Classic PPM
still supports IE 11; however,
Clarity
cannot extend backward compatibility with any old browser technology, including IE 11.
This is not a known issue with
Clarity
. Instead, it is a known issue with IE 11. Microsoft has invested in a new browser, Microsoft Edge.
If users ignore the support requirements and attempt to use IE 11 with
Clarity
, the following problems could occur:
  • Defective features or memory leaks (with no scheduled fixes from Microsoft)
  • Missing browser framework support for new REST API capabilities
  • Poor appearance or slow performance with HTML 5 and new Angular components
  • Links to other sites stop working or show messages indicating you need to update your browser
For example, using IE 11, you could cause your roadmap timeline to stop working, the staffing pages might not load all resources, and other problems could occur that appear to be
random
until users realize they are using old unsupported browser technology to access a completely new drag-and-drop feature-rich web application interface. For best results when viewing the modern user experience pages in
Clarity
, switch to a new browser such as Edge, Firefox, or Chrome.
JAXEN Enhancements in Clarity
Clarity 15.9.2 and higher releases include the JAXEN 1.2.0 library. This has impacted the syntax for certain GEL scripts. Read the following Knowledge Base article for more information.
Telemetry Enhancements
Telemetry is a capability that is integrated into
Clarity
to send product usage and system configuration data to Broadcom. This data helps Broadcom gain insights into customers' product usage, understand their software needs, and focus on the features and platforms that are most commonly used. Telemetry DOES NOT collect any personally identifiable information (PII).
The Opt-In capability is no longer available when you configure the Subscription Compliance Setup section in the General System Settings.
Clarity
will send telemetry data to Broadcom for all your
Clarity
production servers. To learn more about the Telemetry capability, see Configure General System Settings
Dashboards Not Available in Google Cloud Platform
The Project Management Schedule Dashboard and Project Management Cost and Effort Dashboard portlets have been deprecated in the Google Cloud Platform. Please review this KB article for more information.
Microsoft Project Integration Upgrade Details
You should uninstall and upgrade your
Clarity
Microsoft Project Integration software using the version available after upgrading
Clarity
in Account Settings-> Software Downloads. Note that the Microsoft Project Interface bit level installed should match that of Microsoft Project. Microsoft Project Interface (x86) should be installed for 32 bit versions of Microsoft Project and Microsoft Project Interface (x64) version should be installed for 64 bit versions of Microsoft Project.
Updated Logout Behaviour for SAML Users
In previous releases,
Clarity
would redirect users to the errorURL when it receives SAML request that it could not process. In
Clarity
15.9 and higher releases,
Clarity
redirects users to the logout URL when it receives a valid SAML request with the following issues:
  • Clarity
    cannot find the user in its user store or
  •   The user is inactive in
    Clarity
    .
Users that use Spanish (Peru) locale will now have the period symbol as a decimal separator.
Change
: Users that use the "Spanish (Peru)" locale will now have the period "." symbol as the decimal separator instead of the comma "," symbol.
Impact
: If the user keeps the Peru locale and tries to use the comma as the decimal separator the symbol will be ignored and it will cause entered values to be saved as large integers instead of the expected value with decimal digits. If desired, the user can choose a different locale in account settings that uses the comma as the decimal separator.
More Details
: The Official Institute of Taxation of Peru uses "." as its decimal separator. Therefore Java (JDK 11.0.5) has been fixed to honor the period symbol instead of a comma. For more details on the Java fix reference their KB article.
Cannot Upgrade on Oracle Until Security License and MD5 Package Are Enabled
  1. Contact your database administrator or Oracle to obtain the advanced security license (OAS) required only if using DBMS_CRYPTO.
  2. Enable and grant explicit permissions to dbms_obfuscation_toolkit.md5 (also provided with your Oracle installation).
  3. Start the upgrade.
Known Issue Due to Dropped Support for Languages
This release no longer supports the following languages:
Catalan
Czech
Danish
Finish
Hungarian
Dutch
Norwegian
Polish
Russian
Swedish
Turkish
Chinese-Simplified
Chinese-Traditional
Korean
As a result, a user might see a raw text label or English text in the user interface instead of the translated text.
Workaround
: Switch your
Clarity
account settings to one of the supported languages listed in the Release Notes.
Clarity
help will be available only in English for a couple of months after release. The Help link in
Classic PPM
will automatically redirect you to the English site. The help link in
Clarity
currently defaults to the localized site and displays a blank page since the content is not localized. Broadcom will fix this issue in future releases.
Export to CSV Shows No Per-Period Metric Data Unless Totals Column is Present
The project STAFF and ASSIGNMENTS grids use the Totals and Per-Period Metrics columns for ETC, ETC Cost, Actuals, and Actual Cost.
  • If the Totals column and the Per-Period Metrics columns are configured on the grid, the Export to CSV file feature works as expected.
  • If you don't have the Totals column configured in the grid, the export does not work as expected (all per-period metric columns are blank).
Workaround
: In the grid, click Column Panel and add the Totals column to the grid layout before using Export to CSV.
Known Issue with Fresh Installations of Jaspersoft 7.1
In on-premise environments, you might observe the following
Failed to execute: create index
entry in the installation logs during a new installation of Jaspersoft 7.1.0 on Oracle 11g R2 or 12c:
[exec] [exec] init-js-db-pro:
[exec] [exec] [echo] For JDBC driver the artifactId and version properties are set:
[exec] [exec] [echo] maven.jdbc.artifactId=ojdbc8
[exec] [exec] [echo] maven.jdbc.version=12.2.0.1.0
[exec] [exec] [echo] Specified JDBC driver jar exists
[exec] [exec] [advanced-sql] Executing resource: /fs0/clarity1/install_cd/ca_ppm_jaspersoft_7.1.0/buildomatic/install_resources/sql/oracle/js-pro-create.ddl
[exec] [exec] [advanced-sql] 0 rows affected
[exec] [exec] [advanced-sql]
Failed to execute: create index
idx46_jiresfldr_hidden_idx on JIResourceFolder(hidden)
[exec] [exec] [advanced-sql] java.sql.SQLException: ORA-01408: such column list already indexed
[exec] [exec] [advanced-sql] 0 rows affected
[exec] [exec] [advanced-sql] Executing resource: /fs0/clarity1/install_cd/ca_ppm_jaspersoft_7.1.0/buildomatic/install_resources/sql/oracle/quartz.ddl
You can ignore this entry. The warning appears to be alerting you about a duplicate index creation scenario; however, it is not a valid warning.
  • This warning has no impact on your installation and does not affect any Jaspersoft 7.1 functionality.
  • CA Engineering teams confirmed that all the DDL commands are successfully executed after the reported warning.
  • The warning only appears on new Oracle installations; it does not occur with supported versions of Microsoft SQL Server
Review Cancelled Jobs After Upgrade
Please review any
Clarity
jobs that are in the Canceled state after your upgrade is complete. Please pay special attention to any canceled jobs that were previously recurring jobs. Sometimes, after an upgrade, job parameters change and the jobs move to a canceled state. If you don't proactively review canceled jobs, you will only notice them after you receive escalations from the business.
Installation and Upgrade Dependencies
The install and upgrade scripts in this release introduce the following dependencies in the listed chronological order:
Install/Upgrade of This Component:
Requires This Component:
Upgrade
Classic PPM
  • Data Warehouse Configured
  • Load Data Warehouse Job Completed
Clarity
  • PMO Accelerator Add-in Installed
Install PMO or APM add-ins
  • Data Warehouse Configured
Supported Upgrade Paths for Clarity
15.9.3
Please review the table to identify the minimum supported release from which you can upgrade to the latest version of
Clarity
.
Clarity Version
Minimum Supported Version for Direct Upgrade
15.9.3
15.8.0
15.9.2
15.7.0
15.9.1
15.7.0
15.9
15.6.1
15.8.1
15.6.1
15.8.0
15.3
15.7.1
15.3
15.7.0
15.2
15.6.1
15.0
15.6.0
15.0
15.5.1
14.3
15.5.0
14.3
15.4.1
14.1
15.4.0
13.2
15.3
13.2
15.2
13.2
15.1
13.2
  • If you have Release 14.3 or older, your release is no longer supported. Upgrade to Release 15.4 first, and then upgrade to
    15.9.3
  • You cannot upgrade to Release
    15.9.3
    directly
    from Release 14.2 with Jaspersoft 5.6.1 or from Release 14.3 with Jaspersoft 6.1.0. The Jaspersoft 6.4.2 or 7.1 upgrade does not support those configurations. Your
    indirect
    upgrade is still supported. For example, upgrade to 14.3 and Jaspersoft 6.4.2 first. Then upgrade to 15.8 and upgrade to Jaspersoft 7.1.
  • You can upgrade from a previous release even if you have no Jaspersoft reports environment configured. The data warehouse is required; however, reporting is not required. You can elect to upgrade from 14.x and perform a fresh installation of your reports environment.
  • To upgrade from earlier 13.x releases, it often helps to upgrade to 14.3 or 14.4 first and skip the Advanced Reporting component. This approach simplifies the troubleshooting and restart process if an upgrade step fails. Then, from 14.x, you can upgrade to 15.6 and install Jaspersoft 7.1 for Advanced Reporting.
The installer detects how many incremental upgrade steps are required to update your installation to the latest release. If two or more, you are prompted to decide if you would like the installer to save automated backups at each step. For example, from 15.4 to 15.5, from 15.5 to 15.5.1, from 15.5.1 to 15.6, from 15.6 to 15.6.1,  from 15.6.1 to 15.7, from 15.7 to 15.7.1, from 15.7.1 to 15.8, from 15.8 to 15.8.1, and from 15.8.1 to
15.9.3
.
If you have installed any patches on the base version, verify that you applied the latest supported cumulative patch before and after you upgrade. Patch maintenance before and after upgrades is important for troubleshooting, security fixes, and general system health.
Follow these steps
:
  1. Select your current release from the
    Versions
    menu at the top right of that help page.
    For example, select 15.1 and verify you installed the 15.1.0.9 patch or select 15.3 and verify that you installed the 15.3.0.5 patch before starting your upgrade to 15.8. After the upgrade, install the latest 15.8 patch.
You might experience issues if you attempt to upgrade directly from an unsupported patch level. For best results, follow a supported upgrade path. To learn more, contact CA Support. You can also visit the
Clarity
Community
to collaborate with other community members about your specific questions.
Pre-Upgrade: Run the Installation Checker (On-Premise Only)
The Installation Checker (checkinstall) utility assesses any installation or upgrade. The utility runs automatically at the start of an installation or upgrade and at the end of an upgrade attempt. You can also run it manually. The utility produces a report results file (precheck-results.html) in the <install-root>/checkinstall/check-logs directory.
Upgrade Action
: For best results, run the Installation Checker before starting the full installation and upgrade process. Carefully evaluate and resolve warnings before proceeding.
Follow these steps:
  1. Extract the
    Clarity
    installer to the
    Clarity
    application server.
  2. Open a command prompt and navigate to the checkinstall directory located in the directory to which you extracted the installer.
  3. Invoke the checkinstall command:
    UNIX
    :
    sh checkinstall.sh
    Windows
    :
    checkinstall.bat
    You are asked for the Operator Username and Operator Email. This information refers to the user who is upgrading or installing and the email of the user. This information is stored as a record in the installation log.
  4. Verify the results.
    The results contain any warnings and errors and also indicate any customizations that you have made. Review the customizations and make adjustments for the upgrade as necessary.
Make Third-Party JAR Files Accessible to the Installer  (On-Premise Only)
Because of licensing restrictions for some third-party library JAR files (currently the jgroups-all.jar and the xinclude.jar), changes were made in how these files ship. The JAR files are shipped separately from the
Clarity
image in the installation media. The install.jar image does not contain the files mentioned. Any install packages for a previous version included in the install.jar also exclude the JAR files. For each release of
Clarity
, the JAR files are bundled into a folder on the installation media containing third-party libraries JAR file. For Release 15.x, the file is named
thirdparty.libs.15.x.0.jar
.
Upgrade Action
: Retrieve the
thirdparty.libs.15.x.0.jar
file from the installation media. Place the file in a location in your file system so that it is accessible to the installer.
Tip
: To keep the installer from prompting you for the file location, place the JAR file in the installation root directory. If you place the file in another directory, the installer prompts you for the file location.
Upgrade Large Data Sets  (On-Premise Only)
If your
Clarity
upgrade processes a large volume of data, we recommend that you override the default memory settings that are used by the upgrade.
You can override the default memory settings this release. Create a
memory.properties
file and place it in the $cappm/config directory. Set the desired memory values in that file.
Here are the default values that the upgrade uses:
defaultScriptMaxMem=1024m defaultScriptPermGenMem=128m
Here are some sample settings in the
memory.properties
file:
defaultScriptMaxMem=2560m defaultScriptPermGenMem=512m
MS SQL Server Database Compatibility Level
If you are using SQL Server 2016 for this release, set the compatibility level to 130 from SQL Server Management Studio or use the following command:
EXEC SP_DBCMPTLEVEL <database>, 130
Custom Processes, Scripts, and Other Customizations
Clarity
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. For example, you have one or more custom processes with custom GEL scripts that modified timesheet status attributes in a previous release.
  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. You can see these warnings or the referenced logs for insight into the types of customizations that can negatively impact your upgrade experience. For example:
    WARNING: Possible schema customizations have been found. Any customizations to the system are the responsibility of the customer to maintain and are not supported. To upgrade, 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. As a SaaS administrator, you do not see these warnings or the referenced logs. These example messages provide insight into the types of customizations that can negatively impact your upgrade experience.
  5. In on-premise or SaaS environments, turn off your 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
    Clarity
    .
  6. 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,
Clarity
provided the functionality with no net loss to end-users. We recommend that you perform an analysis comparing the value of
Clarity
features in a complete COTS/SaaS solution against the value of developing your own unsupported customizations.
Pre-and-Post-Upgrade: Preserve Your File Directory Customizations  (On-Premise Only)
During the upgrade, you are prompted for the target installation directory. New pre-upgrade and post-upgrade steps let you copy files to and from
Clarity
directory using ant-based scripting. Use ant scripts to automate preserving and restoring customization in
Clarity
directories.
Templates are provided in release-specific upgrade folders that are located in the installer root directory (at the same level as the install.bat file). The templates are:
preprocess-upgrade.xml
and
postprocess-upgrade.xml
.
Example of preprocess-upgrade.xml script
<project name="content" default="upgrade" basedir="."> <target name="upgrade"> <echo>Preserving customer specified files prior to upgrade from install.dir = ${install.dir}</echo> <if fileexists="${install.dir}" not="true"> <fail>Install dir not specified = ${install.dir}</fail> </if> <delete dir="upgrade_temp"/> <mkdir dir="upgrade_temp" /> <!-- Uncomment the copy below and list the files to be included for preservation --> <!--<copy todir="upgrade_temp"> <fileset dir="${install.dir}" > <include name="myfiles/my*.*"/> <include name="abb/*01.jar"/> <include name="a*01.jar"/> </fileset> </copy>--> </target> </project>
Example of postprocess-upgrade.xml script
<project name="content" default="upgrade" basedir="."> <target name="upgrade"> <echo>Restoring customer specified files after upgrade to install.dir = ${install.target.dir}</echo> <if fileexists="${install.target.dir}" not="true"> <fail>Install dir not specified = ${install.target.dir}</fail> </if> <!-- Uncomment the copy task below and list the files to be restored that were preserved in the preprocess-upgrade.xml script.--> <!--<copy todir="${install.target.dir}"> <fileset dir="upgrade_temp" > <include name="myfiles/my*.*"/> <include name="abb/*01.jar"/> <include name="a*01.jar"/> </fileset> </copy>--> </target> </project>
Post-Upgrade or Post-Install: Optimize Oracle 12c Performance (On-Premise Only)
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'