An Upgrade Plan packages the applications, plugins and skipped-record fixes from a builder instance so they can be installed on a consumer instance during an upgrade. You build it in Upgrade Center, check the predicted outcome in the Upgrade Preview module, then review the results after the upgrade.
Why an Upgrade Plan exists
An upgrade tends to cause trouble in the same few places. Customized records are skipped so your changes are not overwritten, which leaves reconciliation work for after the upgrade. Installing new plugins and applications takes time after an upgrade, and customizations often load after the upgrade, so features can be temporarily broken until they finish loading.
An Upgrade Plan moves that work forward. It tracks the changes you make on a builder instance and replays them on each consumer instance, so the post-upgrade tasks do not have to be repeated by hand everywhere. When you build the plan, skipped records are packaged and uploaded to the App Repository. Global records go into a global customization package, and scoped records go into the package for their own application. Publishing the plan creates a global application named after the release, for example Upgrade Plan followed by the release name. Installed applications and plugins are captured too, but they are not pushed to the App Repository.
Teams developing through the App Repository, or moving changes with update sets, can both use the plan to resolve skipped records and track installs in one place. For the wider planning work around a release, the upgrade readiness hub sets out the surrounding tasks.
Setting up the builder and consumer instances
An Upgrade Plan involves two instance roles. The builder instance is where the plan is created, and a single builder is supported. Consumer instances are where the finished plan is installed. The recommended setup makes your development instance the builder.
Two version rules apply. Upgrade the builder to the latest available version before building. The plan’s target version must also match the instance exactly, including patches and hot fixes. Each instance upgrade needs its own plan, which cannot be reused for a later upgrade. On a consumer, the installed plan must match the consumer’s version exactly.
Set the builder role before you install new applications or plugins and before you resolve skipped records. Actions taken before that are not captured by the plan.
Decide next how customizations and skipped records should be handled. From the Yokohama release, neither is part of the plan by default. The controlling property is glide.upgrade.plan.include.skips, which defaults to false. When it is true, skipped records and customizations are included whenever the plan is built or refreshed. You find it under Upgrade Center, then Administration, then Properties, then Upgrade Plan Properties.
Building and publishing the plan
Building a plan requires the admin role. Check the Upgrade Plan Properties, then open Upgrade Center and select Upgrade Plan. If you are on the Upgrade Monitor page, select Manage Upgrade Plan instead. Select Build to start.
By default a build takes application installations alone and publishes them to the App Repository. Make sure each application on the instance is in a ready state before you start, and let any in-progress changes finish. A final confirmation appears first. When the include-skips property is enabled, it also warns you to finish reviewing skipped records. Select Build Upgrade Plan to begin.
When the build completes, select Go to Upgrade Plan. If a warning appears, open View Details to find the errors. You can add an item with New, but a manually added application or plugin must already be installed and active. To leave an item out, set it to false. Refresh picks up recent changes to items already in the plan, and a published plan must be republished after each refresh.
Install the applications and plugins you need before you publish. If the include-skips property is true, resolve the skipped records first. Publishing makes the plan ready for installation on the consumer. A plan can be deleted while it is unpublished, and one Upgrade Plan can exist at a time.
Previewing the upgrade before it runs
The Upgrade Preview module shows how an instance may be affected before the real upgrade, for several release versions. The target versions offered depend on whether the instance is eligible for each one. If it is eligible for none, the drop-down is empty.
A status message at the top links to the Execution Tracker record, which shows the preview’s progress.
The current version card shows the upgrade date and a link about end of life. The previewing version card shows when the preview was created and links to the Upgrade Preview form. Refresh preview regenerates the skipped list. Records you reverted stay reverted, but records you reviewed and retained are replaced on refresh. The scheduled upgrade card shows the next upgrade and an estimated duration, which is not shown on a first upgrade.
After a preview, a Find out what’s new section links to problem fixes, personalized release notes and known error articles. The release explainer covers how releases are planned.
The application upgrade preview counts apps that will be upgraded or installed, showing ten by default. Each row gives the action, the from version (blank for new installs) and the to version. The predicted schema changes section lists new columns, tables and indexes. The Automated Test Framework card shows the percentage of passing tests from the last 30 days. Finished, passing tests are the ones counted, and a test that ran more than once is counted by its latest run.
Reading the predicted skipped records
The total record changes figure includes the records predicted to be skipped. The skipped list prediction card divides them into predicted skipped records, to review, reviewed and resolved. The resolved count appears once skipped record rules have run. Otherwise the card links you to create a rule. Skipped record rules and upgrade plans cannot be implemented together.
The module ranks skipped records by file type:
| Priority | File types |
|---|---|
| 1 | UI pages, UI macros and similar |
| 2 | Business Rules, Security ACLs and similar |
| 3 | Reports and similar |
| 4 | Form Sections, Choice Sets and similar |
| 5 | Everything else |
Each record carries a predicted disposition. A predicted insert creates a new record, and a predicted update changes one. A reverted record has been returned to its base version and will not be skipped on the next upgrade. A predicted skip leaves the record alone to protect your customizations. A predicted skip (manual merge) needs a person to intervene, as covered in the guide to skipped customer updates. A predicted skip (apply once) means the record already received an update from an XML file in the apply once folder.
Each record also carries a resolution. Not reviewed means nobody has looked at it yet. Reviewed means it has been looked at but no action taken. Review not needed means the file needs no review. Reviewed and retained keeps your customization without the upgrade update. Reviewed and reverted discards the customization and updates the record to the upgrade version.
Customization is a frequent cause of a predicted skip, and the preview flags these before the upgrade so you can address them early. The Upgrade Preview form shows the detail. Select View preview details on the previewing version card to see the source version, the target version, the preview status (Pending, In Progress, Complete, Cancelled or Failed) and the start and finish times.
With a plan in use, the card is titled Skipped list prediction with plans and shows the same counts as the standard card: total, to review, reviewed and resolved.
The plan captures the skipped records in scope whether they are reviewed or modified, so you cannot choose individual records to exclude. Records from different instances still need review.
Installing the plan and reviewing the results
Go to All, then Upgrade Plan, and select the installed plan. Items under Upgrade Plan Items must be in the Ready state.
On the Upgrade Monitor page, the Target version card shows a Review upgrade plan link once the plan is implemented. The Upgrade duration card shows the implementation date and time, and its review link lists installed and failed items. With include-skips enabled, the monitor also reports skipped records as total, resolved and to review. The plan cannot be uninstalled from a consumer, so backing out means rolling back the whole upgrade. During the upgrade, items in the Ready state that are also active are installed, and the rest are skipped. Upgrade sets cannot be included, and maintenance plugins are not permitted.
Frequently asked questions
Can I reuse an Upgrade Plan for the next upgrade?
No. The plan must match the instance version exactly, including patches and hot fixes, so each upgrade needs a new plan.
Does an Upgrade Plan include my customizations?
Not by default. From Yokohama, they are excluded unless glide.upgrade.plan.include.skips is true.
Can I choose which skipped records the plan captures?
No. The plan captures all skipped records in scope. Records from different instances still need review after the upgrade.
Where do I check whether the plan was applied?
On the Upgrade Monitor page. The Target version card links to the plan review once it is implemented, and the Upgrade duration card shows the date, time and any failed items.
Who can build an Upgrade Plan?
Building a plan requires the admin role. You start the build from Upgrade Center by selecting Upgrade Plan and then Build.