Upgrade Plan Overview and FAQ - Support and Troubleshooting

Upgrade Plan Overview and FAQ Summary Note: This article is for ServiceNow instances on Tokyo (or later) releases. Product documentation:- Upgrade Plan Overview

ServiceNow customers should be creating an Upgrade Plan for every major upgrade and/or patch update on their ServiceNow instance If you plan to upgrade from Tokyo to Utah, you will need to create it on a BUILDER (DEV) instance once so that it can be used for all the instances going on the same upgrade patch This feature is part of an OOB plugin that will be installed with your Tokyo upgrade com.glide.upgrade_to_customized This Upgrade Plan will reduce time consumed for post-upgrade activities as the below-listed activities will be automated by the upgrade engine using the AppRepo feature which is already on the instance as a base feature This might increase the total Upgrade time (as post-upgrade manual activities are implemented by the Upgrade Engine) Upgrade Plan focuses on automating the following, which are currently a manual task after completing an upgrade:

Upgrade installed applications (Custom or ServiceNow Store App). Install new applications (Custom or ServiceNow Store App). Install new ServiceNow Store application (Target upgrade Release specific). Automatically review=>Resolve your Post upgrade Skipped records for the instance release version upgrade (These will be captured as scope specific app updates. Anything not part of the instance release version upgrade won't be captured). Upgrade Plan High-Level Flow: Configure your DEV instance as a BUILDER instance. Upgrade your instance (e.g., Tokyo to Tokyo Patch*/Utah/Vancouver) Review and Resolve all your Skipped records records after the upgrade is complete. Note: If there are no action items for a skipped configuration and there is a new version coming in the upgrade, the file will be reverted to the base version (this can be revisited later). But it is recommended to address all the skipped items. Install new Plugins/applications (Custom or ServiceNow Store App) if any. Navigate to Upgrade Center > Upgrade Plan . Create an Upgrade Plan when ready (after making necessary changes). This will create a Global Scoped Application "Upgrade Plan – Target Version name". The Upgrade Plan can be retrieved on any CONSUMER (SUBPROD/TEST/PROD) instance by navigating to My Company Applications . Install the new version if you have made any changes to the Upgrade Plan. Any changes to the Upgrade Plan will create a new version and publish automatically. The name will be "Upgrade Plan – Version name". Note: It is recommended testing this on a CONSUMER instance before installing. Review the Upgrade Plan and the Related list. This will contain both installed and custom applications. If you do not want any of these apps to be excluded from the upgrade, mark them inactive. Administrators can compare the versions and mark them as per the organizational requirement/development plan. Create an upgrade change for your CONSUMER instance. Click Upgrade Preview . This will Preview the Upgrade with Upgrade Plan. During the upgrade, the Upgrade engine will take care of Application Updates/Commit Customizations/Resolve Skipped post upgrade files. Upgrade Monitor will show you the relevant information.

Things to keep in mind: Upgrade Plan is created as a Global Application with version incremented for each refresh. Upgrade plan is a Global application which holds config files which are in their own respective scope. Global application is to create/host/publish/transfer/install the config files in an easy way to CONSUMER instances. Upgrade Plan should be installed on your CONSUMER instance before the upgrade. The Upgrade Plan will include all Global customizations (there will be a new app created for this as "Global Customizations - Upgrade Plan"). This app will remain in your app repository as an app and will be used for future upgrades to new versions. For every family releases the version number will be incremented. All Skipped records post-upgrade when addressed/Resolved will be included in the sys_update_xml. These will be captured in the Upgrade Plan as customizations for respective Scope/Package. This will also create applications with versions as installed on your BUILDER instance. This will create new versions for Store installed apps/plugins if these are customized on that instance on their respective SCOPE. It will list the current version that is installed and the customized version if available. See Manage customizations to applications for more information. If you have multiple DEV instances publishing to AppRep and if the current DEV instance does not have up-to-date custom applications which were not installed (but published) on App Repo from other DEV, this will not be included in the Upgrade Plan. It will provide a warning saying there is a new version available in App Repo. The Upgrade Plan only contains the config. It does not contain any metadata. If there is a Scoped app update coming in via Upgrade Plan; the metadata is going to be a customized package even though the Upgrade plan is installed as an App from AppRep. Every time you refresh the Upgrade Plan, it will automatically get published to AppRepo. You will need to make sure the same version is installed on the CONSUMER instance. After the Upgrade Plan is installed on the CONSUMER, it will start downloading the individual components for the Upgrade Engine to Consume. These are stored in the Attachment table. During the Upgrade Preview, it will list out the number of records that get auto-resolved and records that will not. You need to take action on the records which say to be reverted. This happens if your CONSUMER instance has extra customizations which were not on your BUILDER instance. You can take note of these records and bring the customizations back to BUILDER and Refresh Upgrade Plan which will include the new customizations. Then this new version should be installed on the CONSUMER instance before the upgrade. The Upgrade Plan will be consumed during the upgrade and will do the activities which are captured. These config files will be updated to their metadata on that respective scope. Upgrade Plan will be considered for any schema changes and there will be only one online alter if there is a schema change coming in via upgrade and another one on the Upgrade Plan. If there are any items in an Error state during Upgrade validation on the CONSUMER instance, you can remediate the issue and reprocess the Upgrade Plan to rectify this before the Version Upgrade. There will be a Status column that will specify the issue to remediate.

Frequently Asked Questions (FAQs) 1. Which instance should I configure as BUILDER?

You should be making your DEV instance the BUILDER instance. If you have multiple DEV instances, you should configure the MASTER/MAIN DEV instance as your BUILDER instance.

By default, all instances are marked as CONSUMER, which is driven by property glide.upgrade.plan.instance_type . (This feature is only available from Tokyo and later.)

These instances should stay as a Consumer instance: TEST, SUBPROD, PROD

Once the instance is configured as a BUILDER; you cannot change it to CONSUMER and the clone preserves this setting.

2. Can I make my PROD a BUILDER instance?

You should not make your PROD instance a BUILDER instance.

The Upgrade Plan is linked to each upgrade. Once a plan is created, Global customizations will be linked to a "Global Customizations - Upgrade Plan" application.

3. What happens to the Store application installation on the Upgrade Plan for which we do not have entitlement on the CONSUMER instance?

Entitlement/Licensing issue (State will be Error) will not be auto-installed, and this should be addressed manually.

This will be the same for maint-only plugins.

4. What happens if I do not want to install an application/update which is already on a tested Upgrade Plan?

You have the option to make individual updates inactive before your actual Version upgrade on the target instance. So that these will be skipped.

5. Can I disable the Installed Upgrade Plan in case of any last-minute change of plans?

There is an option to create another Upgrade Plan (new version) and install it as an Update on the CONSUMER before the upgrade.

6. When we install the customization via the Upgrade Plan, will it leave an entry on sys_update_version and sys_update_xml?

If it is a new app installation without any customization, it will not leave an entry on sys_update tables. If it is a Store App/Plugin and is customized, it will have those customization records on sys_update tables on the CONSUMER instance.

7. Can I install a deactivated component from the Upgrade Plan at a later stage on the CONSUMER instance?

This will be dependent on if there is a new version in App Repo and if it was already upgraded on the instance from App Repo/Store.

8. What will happen to an application which is already in a newer version installed than the version coming in Upgrade Plan?

If the Upgrade Plan is having the same or an older version; it will not be consumed during the Upgrade.

9. How can I find out if the Upgrade plan was executed?

This will be listed on the sys_upgrade_history_log table "Auto resolved from" column.

10. Is this available for Self Hosted instances?

If the self hosted instance has AppRepo connectivity, they can utilize this feature.

11. What if there is a plugin/app dependency on an app/plugin on the Upgrade Plan?

The Upgrade Plan will not look into the dependencies and auto-install them. The dependent plugins should be a part of the Upgrade Plan.

12. Will this increase the time of the total upgrade?

This will increase the Upgrade change duration and increase the time to upgrade, but post-upgrade activities are managed by the Upgrade engine automatically.

13. Will the Upgrade Plan capture the Update Sets?

The Upgrade Plan does not capture all the updates made by the customer. While building we pick the skipped records and corresponding scopes will be included in the plan along with the customer installed/upgraded/published applications. There is no functionality for update set commits to be captured in the Upgrade Plan at the moment. Post-upgrade upgrade set commits will be manual.

14. Can I uninstall the Upgrade Plan after WAR upgrade?

From the instance where the Upgrade Plan is installed, it can be uninstalled if the instance is not yet upgraded (WAR version).

From the instance where the Upgrade Plan is installed and WAR upgraded, it cannot be uninstalled as the Upgrade Plan contains config records that will be copied over to the instance during Upgrade Plan installation as a Global App containing files in their respective scope. These will be consumed when the upgrade happens. During the upgrade these configs that came over via the Upgrade Plan would have been already consumed and changes made to sys_metadata of those respective updates in their respective scopes. An uninstallation on the Upgrade Plan after the WAR upgrade will not help here as the configuration record is already updated with/after the upgrade and this might disrupt the instance if attempted.

15. Why there are multiple Global scope entries on my sys_scope/sys_app table on the BUILDER instance?

This is expected behavior as the Upgrade Plan creates multiple Global apps with the same sys_scope(global) but with different sys_id's. The scope will remain Global even though there are OOB Global records linked to these newly created Global scopes.

16. Why OOB Global records are linked to "Global Customizations – Upgrade Plan" (Application) on my BUILDER and CONSUMER instance?

This is an expected behavior where this is a new Global scope created with the Upgrade Plan and any global updates that get added to the Upgrade Plan will be linked to the Application as "Global Customizations – Upgrade Plan". This is a cosmetic change and will not affect the functionality of the instance as the records will stay Global.

17. There is a new App "Global Customizations – Upgrade Plan" on the "Not installed" section of my company application list.

This is an expected behavior, and this will be auto-installed when the Upgrade Plan is consumed during the upgrade. You do not have to install manually, and you only need to install "Upgrade Plan RELEASE VERSION".

18. The WAR version for which the Upgrade Plan was created on the BUILDER instance is not available for selection on the CONSUMER instance Upgrade Change.

If there is a mismatch in the WAR version name on the Upgrade Plan, the Upgrade Plan will not be consumed.

For example, XP7HF1 Upgrade Plan will not be consumed during a XP7HF1a upgrade.

When a new Patch/HotFix#/HotFix #* is released to remediate security issues, the old version will be taken out of the available list for Upgrade selection. If the Upgrade Plan was already published from the old version, the remediation steps are as follows:

On the BUILDER version where the Upgrade Plan was published, upgrade to the new available Patch/Hotfix version via the NowSupport change. Publish the new Upgrade Plan once it is installed with the new WAR version. Install the new Upgrade Plan on the CONSUMER instance. 19. What issues can be anticipated if the Upgrade Plan was not consumed during an upgrade?

If it is not consumed, you can have sys_scope issues when trying to commit Global Update Sets captured from the BUILDER version on the CONSUMER instance as the new Global sys_scope records (see Question 16 above). It will not be committed as the Upgrade Plan was not consumed, which can give you preview errors for sys_scope as it is not found on the CONSUMER.

20. Why is there a customized version for the OOB/installed apps/plugins on the Upgrade Plan even though we haven’t made any customization?

The Upgrade Plan packages all the previous customizations you had on the instance and make it into a version. These records you see there will not be a recent one and they might have been updated before. The Upgrade Plan packages it as a 1.0.* version so that it will be hosted in AppRepo in its individual scope.

The next Upgrade Plan will have an incremented version from the current one.

You can use this feature to transfer updates to an OOB module/app/plugin by publishing them separately to AppRepo irrespective of whether it is linked to the Upgrade Plan by not using the Update Set feature. If you install them as packaged versions, uninstalling them will be easy instead of backing up an Update Set.

21. Why does the customization record show as Inserted/Unchanged in sys_upgrade history disposition?

When the Upgrade Plan is consumed during the upgrade, the customizations packaged for OOB/Store Apps/Plugins will be added to the instance sys_update_version linked to the new Packaged version of the application.

If it was previously brought over by an Update Set, there will be a new entry on sys_update_version and it will be the same file, but with a new entry. This should not be confused as the customizations were not skipped and you can check the sys_update_version table for the details.

22. Why am I getting cross-scope access issues for existing apps with the new "Global Customizations - Upgrade Plan"?

You might need to create a one-time cross-scope (sys_scope_privilege) for the Global/Scoped application config records with the error message, as the records are linked to "Global Customizations - Upgrade Plan” now from “global". The existing cross-scope access is created for Global (with the sys_id for the Global scope of "Global" itself), and these metadata records are changed to "Global Customizations - Upgrade Plan” with the Upgrade Plan. New sys_scope_privilege records should be recreated for the "Global Customizations - Upgrade Plan" scope to fix these issues, so there will be two entries: the first existing one for “Global” and the next new one created for "Global Customizations - Upgrade Plan".

Related Links Upgrade Plans - Creator Toolbox Video