Hello,

This message provides more details on how the Pega Upgrade tools functions. I hope that it will provide some insight into how manifest files are used, and what applications would be available to inspect. We are working on making this content part of the available documentation.

Selecting application to upgrade:

The upgrade tool allows for the selection of an application that the user wants to upgrade. This drop down is populated with the list built-on applications and component application for the current application context. From your screenshot the "Graduation" application is a built-on application for the upgrade application you are running the tool against. 

Once an application is selected from the drop down, the upgrade tool will look for manifest files for the selected application.  A manifest file includes metadata defining the rules that are included in a particular version of that application. The Pega Upgrade tools ships with manifest files for the applications that ship with the Pega Infinity platform. 

Partial listing:

• PegaRULES - All released minor and patch releases
  • 8.1, 8.2, 8.3, 8.4 and 8.5
  • 8.1.1 - 8.1.9, 8.2.1 - 8.2.8, 8.3.1 - 8.3.5, 8.4.1 - 8.4.4, 8.5.1 - 8.5.2

• UIKit 13.1.1, 14.1.1, 15.1.1
• Theme-Cosmos 

If a selected application does not have any manifest files available, you will see the message "There are no rule manifests available for the selected application." If the selected application has manifests that outlines the rules that have been updated in a newer version, you will be able to select the version to which you want to upgrade. As your Graduation application does not have any manifest files created for it, you are seeing this message. 

Checking for Overrides:

Once the new application version has been selected, the option to "Show overrides" will become enabled. When you click on "Show overrides" each rule in your application rulesets will be compared against the assemble rule information from the manifest files to determine if it is overriding a rule that will be updated on upgrade.  

Given an application built on PegaRULES 8.2.2 . When a user chooses to show overrides for an upgrade to PegaRULES 8.5.2, the tool will assemble the rule meta data for the versions between the current version and the requested version. Each manifest file defines any manifest files it builds upon. This hierarchy information allows the tool to assemble the list of manifest files that represent the rules that will be available after the upgrade. In the scenario provide (-> denotes dependency) 8.5.2 -> 8.5.1 -> 8.5.0 -> 8.4.0 -> 8.3.0 -> 8.2.0. The starting version in the scenario is 8.2.2, and the tool would exclude anything below that version.  Meaning rules in 8.2.0 would not be included in the rule information assembly.

With the rule information assembled for future version, the highest version of each rule in the implementation application's rulesets will be inspected to determine if it is overriding changes made in a newer version of the selected built on. Only the highest version of a new rule is considered. If a rule was updated in 2.3.0 and 2.4.0 only the 2.4.0 rule would be considered. 

The details of each override detected is included in the report shown on the home page.

How to use tool on applications that are built on framework layers?

If your application is not built directly on one of the shipping Pega Platform applications. You will need to either generate manifests for the built-on framework layer applications or include the platform application as a direct built-on to your application. For example: you would add the current version of PegaRULES to the applications built-ons in the application rule.

Adding PegaRULES, UIKit, or Theme-Cosmos as a direct built-on: This is a simple change to the upgrade application, that we recommend you create in the instructions. While this process will give you information about any possible overrides your implementation layer employs, it will not consider any rules in your framework layer. If the implementation is overriding a rule in a framework layer, which in turns overrides the Pega version of the rule. This will be reported as an override of PegaRULES in the implementation layer, when it is truly overriding the framework.

If you desire to get insights on conflicts for rules that are defined in a built-on layers, there are a few options. 

• Option 1 - Generating a manifest file:  Instructions are attached on how to generate a manifest file. When creating the manifest files for your built on applications, you will want to define them to have a dependency on the version of the Pega Platform application to which you want to migrate.  This will cause the conflict detection process to consider the rules in the new versions of the Pega Platform.  If this is not done, they will not be considered in the evaluation.
• Option 2 - Update upgrade application's rulesets to match implementation application structure: As each ruleset in the implementation application's stack will be a ruleset defined on the upgrade application, the upgrade tool will evaluate all the rules from the rulesets on the application. The upgrade application should be built directly on PegaRules or another shipping Pega Application.

I hope this provides you with some more detail on the tool and its usage.  We are working on getting this detail into the documentation for the tool.  Please let me know if you have any feedback on the tool or this content.

Thank you,

Brian