· Sep 5, 2022 5m read


Note: ********* The following is just a guideline! Every customer is different and will have different points ***************

Through our experience in Support helping customers, we have seen a lot of cases where not having a reasonable upgrade plan (documented) leads to unexpected problems with a Crisis priority. In some cases, we can fix the problem during the upgrade window, but not always, as some situations may require further investigation that can take days or even months!

It is essential to document the upgrade process, covering the steps to do before, during and after the upgrade, even on small servers and applications! Furthermore, an upgrade document plan is helpful when involving third-party actors like software or hardware vendors. Handing this document to an external vendor (like InterSystems) will speed up understanding of the whole context.

After working with different documents, I would like to share some general guidelines to help create or update yours. Of course, I count on missing things. I am sure some of you will have a lot of experience and can add ideas and suggestions, so feel free to comment!

Note: ********* The following is just a guideline! Every customer is different and will have different points ***************



Every major upgrade should have some essential steps and strategies similar to the ones described here. Our customer experience shows that a detailed plan will produce a successful upgrade with documented tests and actions. 



Include a brief description of the upgrade without details. Including the goal and current status


1. Infrastructure

Include a table with essential data and detailed documents (ready to be sent). It should cover the current architecture and the future (if it applies).

CURRENT Architecture (overview example)

Server IP ROLE HW Desc Product OS
PROD1 MIRROR 10 cores 20 RAM Caché 2017.2 Windows 2012
PROD2 MIRROR 10 cores 20 RAM Caché 2017.2 Windows 2012 VIP      
ARB Arbiter 2 cores 4 RAM Caché 2017.2 Windows 2012
BCK DR 24cores 10 RAM Caché 2017.2 Windows 2012

 Extract the following data and keep it in a shared place, ready to be sent:

  • ^Buttons or ^SystemCheck report for every server.
  • ^pButtons or ^SystemPerformance reports for every server. The data should cover a few days, including the busiest day.
  • Hardware details (vendor, specs, etc.)

FUTURE Architecture (if planned also to upgrade)

Getting similar data to the Current Architecture


2. Contacts

It may seem common sense, but it's essential to know who has authority to make upgrade decisions, who is in charge of what and who should be contacted in case of emergency. A simple table attached to the upgrade document is essential.

Name Role Company Phone Email
John Administrator ACME +34222222
Gary Developer ACME +34222222
Susan Manager ACME +34222222
WRC ISC Support InterSystems +112321321
Dell Dell Support Dell +1xxx


3. Test Plan & Details

Include a description of the tests currently done and planned. The tests should cover a complete upgrade with a similar environment. The upgrade tests should help to fill the following upgrade sections. If there are no tests or not completed, it should be noted and get prepared to cross your fingers! ;-)


4. Main Upgrade steps

This should cover a simple summary of the different steps. Example:

  1. Stop instances (Prod1 and Prod2)
  2. Copy database folders to new systems (NewProd1 and NewProd2)
  3. Start NewProd1
  4. Compile classes on new Prod1, run update data scripts
  5. Start NewProd2
  6. Check Mirror synch
  7. Assign old IPs
  8. Allow users to connect


5. Detail Plan

Detail the previous steps and how to accomplish them, including commands to execute, files to import, etc. Most of the steps are not helpful for external companies not knowing the applications, and it may not be necessary to include them when sending the plan to external parties.


Upgrades, including application changes, usually require tasks to be done before, during and after. You can create a simple task table to control all the steps, timing, etc.

As an example of the detailed plan, you may see things like:

Tasks Before the upgrade (example)

(Detail all the tasks needed before the upgrade)

Task Date Status Responsible Notes
Update Indices 07/09/22 Done Integration Update indices on X to support XY
Upgrade IIS 08/09/22 Pending Web Admin Upgrade web servers before the final upgrade
Get Integrity report 07/09/22 Done Iris Admin Get an integrity report of all databases


Tasks During the upgrade (example)

(Detail of tasks and step-by-step upgrade plan)

Task Time (Planned) Time (Real) Status Responsible Notes
Stop users 06:00 06:10 Pending Integration Call X to stop connections
Get ^SystemCheck 06:10   Pending Iris Admin  
... ..   ... ...  
Allow connections 09:10   Pending Iris Admin  


Tasks After the upgrade

(Detail all the tasks needed after the upgrade)

Task Date Status Responsible Notes
Enable ^SystemPerformance 01/01/22 Pending Iris Admin Run the performance for a few days


5. Issues/Problems during the upgrade

Write down the problems found during the upgrade. Especially problems that do not prevent the upgrade. This list may include a lack of commands, new error messages, etc. This list will help to improve future upgrade documents and not to forget to fix current problems.


6. Disaster Recovery Plan / Go Back

Describe the plan in case the upgrade fails. This should involve returning to the old servers, stopping new ones, starting X, Z, etc. It is constructive to have all the steps to return to a safety scenario written. Note that the disaster recovery plan is usually performed under stress, and it's easy to miss steps and forget how to do it or where are the files, configurations, etc.


The primary purpose of this guide is to be aware of the difficulties of the upgrade process and think beforehand. Test, document and test again will guarantee a successful upgrade!

Discussion (1)2
Log in or sign up to continue