Upgrade Plan module FAQ (Tokyo+) - Support and Troubleshooting

Upgrade Plan module FAQ (Tokyo+) Summary This module will replace the below section on Instance upgrade FAQ - Frequently Asked Questions from the T+ release

15. How to use an Update Set to capture reverted customisations made after an upgrade?

Product documentation:- Upgrade Plan Overview

This feature can only be used from the Tokyo release. The customer should be creating an Upgrade plan for every upgrade on the instance from X to Y/XPatch* to XPatch*/XPatch* to YPatch*. If the customer plan to upgrade from T to U; they need to create it on their BUILDER instance once so that it can be used for all their instances going on the same upgrade patch where all other instances except the builder instance will be CONSUMER. If the customer is going from UP1 to UP6; another plan should be created. 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 the time and man-hours 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 focus on automating the following which is currently a manual task after an upgrade.

1. Upgrade installed applications ( Custom or Store)

2. Install new applications ( Custom or Store)

3. Install new Store application ( Target upgrade Release specific)

4. 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)

Related Links The High-Level Data flow is as follows-

Configure your DEV instance as a BUILDER instance. Upgrade your instance (T==> TPatch*/U/V) Review and Resolve all your Skipped records ( POST upgrade)*** This is very important. 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 Store) if any. Upgrade Centre=> Upgrade Plan Created upgrade plan when ready ( after making necessary changes) should be published which will create an app for your AppRepo. This will create a Global Scoped Application "Upgrade Plan – Target Version name" Upgrade plan can be retrieved on any Consumer instance from " My Company Applications" Install the new version if you have made any changes to the upgrade plan. Any changes to the upgrade plan ( Refresh) will create a new version and publish Automatically. The name will be "Upgrade Plan – Version name". *** We recommend testing this on a SUB PROD consumer instance before installing this. Review the Upgrade plan and the Related list ( Individual versions for each application). This will contain installed apps as well as custom apps. If you do not want any of these apps to be excluded from the upgrade ( please mark them inactive).Instance Administrators can compare the versions and mark them as per the organisational requirement/development plan Create an upgrade change for your CONSUMER instance. "Upgrade Preview" and this will Preview the Upgrade with Upgrade Plan. Predictions will give you the count. It says how many are Automatically resolved. During upgrade, the Upgrade engine will take care of App Updates/Commit Customisation/Resolve Skipped post upgrade files( as you did in the BUILDER instance) Upgrade Monitor will show you the relevant information.

Points to remember

Upgrade Plan is created as a GLOBAL AppRepo Application with version incremented for each of Refresh( link) Upgrade plan is a GLOBAL application which hold 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 your Global customizations ( there will be a new app created for this as "Global Customizations - Upgrade Plan"). This app will remain on 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 customisations for respective Scope/Package and will be included in Upgrade Plan 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 customised on that instance on their respective SCOPE. It will list the current version that is installed and the Customised version if available. Product doc: Manage customizations to applications If you have multiple DEV instances publishing to AppRep and if the current BUILDER 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 give 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. So if there is a Scoped app update coming in via Upgrade Plan; the metadata is going to be its customised 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. We need to make sure the same version is installed on the CONSUMER instance. Soon 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 customisations which were not on your BUILDER instance. You can take note of these records and bring the customisations back to BUILDER and Refresh Upgrade Plan which will include these NEW customisations. 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; the customer 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.

FAQ

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" Driven by property glide.upgrade.plan.instance_type ( only available from T+)

These instances should stay as a Consumer instance

TEST

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. So once there is a plan created; your Global customisations will be linked to a "Global Customisations - Upgrade Plan" Application. You do not want that in PROD

3. What happens to the Store application installation on the upgrade plan for which we do not have entitlement on the Consumer ( PROD)

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

This will be the same for MAINT-only plugins. This will be changed to Error.

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

We have the option to make individual updates Inactive before your Actual Version upgrade on the target instance. So these will be skipped.

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

We can disable the upgrade plan together. Also, there is an option to create another upgrade(Refresh) plan ( new version) and install it as an Update on the consumer before the upgrade

6. When we install the customisation 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 customisation; it will not leave an entry on sys_update* tables. If it is a Store App/Plugin and is customised; it will have those customisation 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?

This is not possible at the moment and it will be there from U+. This will again dependent on if there is a new version in App Repo/was it 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 customers?

If the self-hosted customer has AppRepo connectivity they can utilise 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.

We do not have any support for update set commits to capture in the upgrade plan at the moment. Post-upgrade update-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 is a bunch of configuration 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. So, 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 mess up 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 behaviour 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 behaviour 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 behaviour, 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.

Eg: XP7HF1 upgrade plan WILL NOT be consumed during a XP7HF1a upgrade.

When a new Patch/HotFix#/HotFix #* gets 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 will be as follows:-

On the builder version where the Upgrade plan was published; please 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 (Point 16) 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 customised version for the OOB/installed apps/plugins on the Upgrade plan even though we haven’t made any customisation?

What the Upgrade plan does is package all the previous customisations you had on the instance and make it into a version. So these records you see there will not be a recent one and they might have been updated before(maybe years back). The upgrade plan basically 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 customisation record show as Inserted/Unchanged in sys_upgrade history disposition?

When the upgrade plan is consumed during the upgrade; the customisations packaged for OOB/Store Apps/Plugins will be added to the instance sys_update_version linked to the new Packaged version of the application.

So 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 customisations 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 of the Global/Scoped application config records with the error message as they will be linked to "Global Customizations - Upgrade Plan". The existing cross-scope access created for Global ( with the sys_id for the global scope of "global" itself) should be recreated for the "Global Customizations - Upgrade Plan" scope as well to fix this. There is a STRY created for fixing this as an enhancement but this is the workaround in the meanwhile.

Additional Related links

Upgrade Plans - Creator Toolbox Video