Upgrade Plan overview

  • Release version: Yokohama
  • Updated January 30, 2025
  • 5 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Upgrade Plan overview

    The Upgrade Plan feature in ServiceNow automates application installation and post-upgrade tasks during instance upgrades, enabling a seamless and efficient upgrade experience. It allows you to define applications and target versions to install, reducing manual effort and downtime associated with upgrade-related activities.

    Show full answer Show less

    To use Upgrade Plan, you need two types of instances:

    • Builder instance: Used to create the upgrade plan, recommended to be a development instance upgraded to the target version.
    • Consumer instance: Implements the created upgrade plan to perform the upgrade.

    Before upgrading a consumer instance, you must install the corresponding Upgrade Plan application matching the target version on that instance.

    Key Features

    • Automation of post-upgrade tasks: Tracks and replays actions such as committing update sets, installing plugins, and applying customizations, reducing manual work and downtime.
    • Handling skipped records and customizations: By default, skipped records and customizations are excluded from the Upgrade Plan, but you can include them by enabling the glide.upgrade.plan.include.skips property.
    • App Repository integration: Upgrade Plan packages skipped records and customizations into global and scoped applications stored in the App Repository for consistent deployment.
    • Scope-level operation: Captures all changes at the application scope and publishes them as upgrade plan applications for installation on consumer instances.
    • Version matching requirement: Upgrade Plan must be built on a builder instance with the exact target version and installed on consumer instances with the same version.
    • Exclusions and limitations: Upgrade sets and maintenance-only plugins cannot be included; only one builder instance is supported; partial rollback of upgrade plans is not possible.

    Advantages over Update Sets

    • Tracks both skipped record resolutions and app/plugin installations together.
    • Optimizes table alterations during upgrade using batch bootstrapping.
    • Provides a more robust and automated upgrade process compared to manual update sets.

    Design Considerations

    • Each instance upgrade requires a separate Upgrade Plan; plans are not reusable across different upgrade versions.
    • Configure and use the builder instance before applying new apps, plugins, or resolving skipped records to ensure actions are captured.
    • Only upgrade plan items with State=Ready and Active=true are installed on consumer instances.
    • The scope of files moved to the global customizations application remains global.
    • You cannot view a consolidated list of customizations in the Upgrade Plan items view but must verify them in respective tables.

    Background Operations

    When building an Upgrade Plan, skipped records and customizations are packaged into global and scoped applications and uploaded to the App Repository. Applications and plugins installed during the plan creation are tracked but not pushed to the repository, as they are lifecycle items.

    When consuming an Upgrade Plan, it is validated, downloaded from the repository, and moved to a ready state before installation. Only ready and active items are applied to the consumer instance.

    Practical Guidance for ServiceNow Customers

    • Use Upgrade Plan to streamline and automate your instance upgrades, especially if you manage active application development via the App Repository.
    • Build a new Upgrade Plan for each upgrade version to ensure precise version matching and avoid issues.
    • Consider enabling the property to include skipped records and customizations if your upgrade requires it.
    • Plan your upgrade process to include setting up a dedicated builder instance configured to capture all necessary changes.

    Accelerate your upgrades using the Upgrade Plan that automates the installation of applications during upgrades, giving you a seamless upgrade experience. It helps you define applications and target versions to be installed in your instance.

    Navigate to All > Upgrade Center > Upgrade Plan.

    You will need the following instances to use Upgrade Plan.
    • Builder instance: Build your upgrade plan
    • Consumer instance: Implement your created upgrade plan
    Note:
    Ensure that your instance is upgraded to the desired version to build the upgrade plan. It is recommended to configure your dev instance as your builder instance. You are required to install the upgrade plan before upgrading your consumer instance. For example, to move from Yokohama to Zurich Patch 1, you must first install the Upgrade Plan - Zurich Patch 1 from the applications page. Once installed, you can then start the upgrade process to Zurich Patch 1. See Upgrade Plan Properties for more details.
    When you upgrade an instance, resolutions are skipped, and customizations are often loaded post upgrade. This causes temporary breakdown of features until fully loaded. Tasks like committing update sets, installing new plugins and applications, and multiple update are also time consuming. Use the Upgrade Plan feature to automate these post-upgrade tasks by tracking your actions and replay the steps on all the required instances. You don’t have to manually apply post-upgrade tasks which helps in reducing downtime.
    Note:
    After upgrading to the latest version, you will see some skipped records. Some of those records will already be marked as reviewed and some of them will need to be reviewed.
    Starting Yokohama release, customizations and skipped records are not a part of the Upgrade Plan, by default. You can choose to include the customizations and skipped records along with the app installations within the Upgrade Plan by enabling the glide.upgrade.plan.include.skips property. This property controls about when skips and customizations are included when you build or refresh an Upgrade Plan.
    • When glide.upgrade.plan.include.skips property is TRUE, skips and customizations are included when an Upgrade Plan is built or refreshed
    • When glide.upgrade.plan.include.skips property is FALSE, skips and customizations aren't included when an Upgrade Plan is built or refreshed. This property has been set to False by default.
    You will see one of the following modal messages depending on the scenario:
    • First time user: When you are building your Upgrade Plan for the first time (the property is disabled by default)

      Screenshot showing first time user for Upgrade Plan

    • Building the upgrade plan with the property enabled

      Screenshot showing building of Upgrade Plan with property enabled

    • Refreshing the Upgrade Plan with the property disabled (default)

      Screenshot showing refreshing of the Upgrade Plan with property disabled

    • Refreshing the Upgrade Plan with the property enabled

      Screenshot showing refreshing of the Upgrade Plan with property enabled

    Advantages of Upgrade Plan over Update Sets

    You can achieve the following using Upgrade Plans:
    • Along with the skipped record resolution, you can also track app and plugin installation
      Note:
      You won’t be allowed to choose the skipped records that are captured by the upgrade plan. Upgrade plan captures all the skipped records regardless of whether they are reviewed or not and modified or not. If the customizations are coming from different instances, then the skipped records are required to be reviewed.
    • Optimizing the table alters using batch bootstrapping
    • Manage your customizations using the App Repository
    Note:
    It is recommended to build an Upgrade Plan for each instance upgrade. When you build an upgrade plan on a builder instance, it gets created to the exactly same as the builder instance version (including patches and hot fixes). You can’t use the previously created Upgrade Plan for the new instance upgrade. In case of consumer instances, when you install the upgrade plan, its version should match exactly the consumer instance version.

    Persona

    If you are using the app repository for active application development, use Upgrade Plan to accelerate your upgrades.
    Note:
    If you are currently using the Update Sets and want to catapult your upgrade process, use the Upgrade Plan feature.

    Design considerations

    The following are the important considerations while working with Upgrade Plan:
    • Each new instance upgrade requires its own upgrade plan. It can't be shared across upgrades.
    • Only one builder instance is supported to build the Upgrade Plan
    • Upgrade Plan can’t be uninstalled on a consumer instance. You can rollback the entire upgrade but not partially.
    • The scope of the files moved to Global Customizations - Upgrade Plan application by upgrade plan is still global
    • During an upgrade, only the upgrade plan items with State=Ready and Active=true are installed on the consumer instances. The rest of the items are skipped.
    • Upgrade sets can’t be included in the Upgrade Plan
    • Maint only plugins are not allowed in Upgrade Plan
    • Configure your instance as a builder instance before installing new applications and plugins or during skip resolutions. Otherwise, the actions are not captured by the Upgrade Plan.
    • You can’t view the list of customizations in the Upgrade Plan items view. You can navigate to the respective tables to ensure if the customization has been captured.

    See KB1271313 for more information.

    Upgrade Plan background operations

    During the building of the upgrade plan, the following operations are done at the background:
    • Skipped records are packaged and uploaded to the App Repository in the form of Global Application and App customization. The following are the 3 types of apps created by Upgrade Plan on your instance and App Repo.
      Note:
      After the packaging is done, you can choose the items from the Upgrade Plan. An Upgrade Plan works at the scope level, so it captures everything and publishes it to the repository.
      • The global records are packaged into the global customization upgrade plan app and published to the app repo
      • The scoped skipped records are packaged into the respective app customization packages
      • When the upgrade plan is published, a global application is created, for example, Upgrade Plan - release name
    • Existing ServiceNow features like Global Application and App customization are used as application containers that can be installed in all the required instances. See and Application scope for more information.
    • If you install any applications or plugins, they are also captured in the Upgrade plan. But, since they are application life cycle items, they are never pushed to the App Repository.
    During the consumption of the upgrade plan, the following operations are done at the background:
    • At first the upgrade plan is validated and then the source from the app repo is downloaded
    • Once the source is downloaded, the app is moved to the ready state
      Note:
      Only the upgrade plan items with State=Ready and Active=true are installed on the consumer instances. The rest of the items are skipped.
    • Auto-generation of the preview for the upgrade plan