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 ***************
 

MANUAL FOR SUCCESSFUL UPGRADE

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. 

Introduction

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)

Details
 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.

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.

6. Related tasks

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)

Tasks During the upgrade (example)

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

Tasks After the upgrade

(Detail all the tasks needed after the upgrade)

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!