Upgrade Roll-back Plan

When Upgrading Micromine Geobank from your current version to the latest version, as part of your due diligence it is prudent to prepare a roll-back plan specific to your system.

This topic is provided as a generic roll-back plan.

The plan should be customised to meet the specific needs of your environment. A database or systems administrator should take responsibility for ensuring that the roll-back plan meets those needs.

Micromine has made every effort to ensure that a roll-back will not be necessary. However, not every eventuality can be foreseen, and it is recommended that a roll-back plan be put in place, in the unlikely event that production-critical issues arise following a version upgrade and usage of the software.

A. Steps prior to installing Micromine Geobank 2023

  1. Take special backups of all configuration and content SQL databases which:
    1. Should be full, verified backups and should be stored for a period of at least 2 years. It is recommended that a central location is used to store all files and processes related to the roll-back. Additionally, a commentary about the installation and upgrade should be recorded and stored, including the date and time at which the upgrade was completed.
    2. May be used for an immediate roll-back if the initial upgrade fails; or to "restore for reference purposes" later when a roll-back is required after the new version has gone live and the new system already contains new and modified objects and data.
  2. Switch on full usage logging in Micromine Geobank.
    1. This is a Micromine Geobank Configuration Manager setting. If it is not already activated, tick the Usage tracking check boxes and save the changes. This will allow usage and editing data about configuration objects to be viewed. This information will assist in decision-making with regards to roll-back steps, should a roll-back be necessary. (As with all activity logging functionality; log size increases over time and, as required, should be managed by a database administrator.)
  3. Check your data model and if it does not have PROJECT and SITE_ID columns in the ST_DESPATCH_STANDARD table, add these columns using the same data type as in GB_SITE, and allow nulls.

    4. This step is necessary because Micromine Geobank 2017 and onwards uses these fields and will add data to them going forward. Existing data is not affected.

  4. Export all existing objects, datasource objects, profiles, task-lists, tasks and macros, to xml.
    1. This is as a secondary backup. Micromine Geobank 2023 will not change the configuration of any v10 or earlier objects, but having copies of the current macro and tasks (and task-lists and profiles which contain those tasks) means that these are available for re-import should the v10 or earlier configuration have been purged using the “Version and Upgrade Management tool”.
  5. Back-up copies of the following folders should be made so that they can be restored, or content from them be accessed, should it be required for a roll-back:
    1. <ProgramData>\MICROMINE\Geobank (stores licence files, config connection strings, sample data and deployment tool data)
  6. Customise Installation and upgrade plan:
    1. An understanding of what will occur during a version upgrade is required in order to identify any specific requirements, or any effects on the Micromine Geobank system and environment.
    2. The Installation and Upgrade process for version 2023, which is covered in detail in the "Getting Started" document for Micromine Geobank version 2023, should be reviewed (in the in the context of the client environment) prior to an actual upgrade.
    3. Any upgrade should first be undertaken in a test environment prior to an upgrade in a production environment.
  7. User information and training should be provided.
    1. Users should be informed of the schedule and the nature of any planned version changes and the effect this will have on their work processes.

B. Install and upgrade process

The Micromine Geobank 2023 installation and upgrade process is summarised here in the context of a “customised” installation and upgrade, with the possibility of a roll-back.

  1. A change freeze in relation to the Micromine Geobank system and all its related resources should be implemented.
  2. A customised installation and upgrade process should then be undertaken.
  3. The success of the upgrade will need to be verified. If the upgrade is deemed to have failed, an immediate roll-back plan should be invoked as described below.
  4. Once the upgrade is deemed to be a success, the change freeze should be lifted and users advised to continue production work using the upgraded system.

C. Immediate Roll-back Steps (if roll-back is invoked during or immediately after Install/upgrade)

These steps are relevant if users are still within the change freeze imposed during the install and upgrade process. If the change freeze has already been lifted and non-disposable production work has been carried out, then follow the steps under “D. Post Go-live Roll-back Steps (if roll-back is invoked after going-live)” (below).

  1. Uninstall Micromine Geobank 2023 On all client machines.
  2. If the previous version of Micromine Geobank was uninstalled, re-install the previous version.
  3. Backup and archive all upgraded configuration and content SQL databases.
  4. Restore all configuration and content SQL databases from the backups taken.
  5. Restore the folders from the backups taken.
  6. Advise users that the change freeze has been lifted, but that the system has not changed.

D. Post Go-live Roll-back Steps (if roll-back is invoked after going-live)

In this scenario it will not be practical to roll back the actual content database (and throw away and then reload the accumulated geological data). Therefore, the strategy will be a software roll-back while retaining the current database (thus avoiding loss of data).

In the case of a roll-back after going live - in other words, an issue is identified at some point (e.g. a day/week/month) after the upgrade has been completed - and (after considering the alternatives to a roll-back, see E. below) it is deemed necessary to roll-back to the previous version of the software, do the following:

  1. Implement a change freeze in relation to your Micromine Geobank system and all its related resources. Uninstall Micromine Geobank 2023 on all client machines (but not yet on the administrator machine).
  2. If the previous version of Micromine Geobank was uninstalled, re-install the previous version.
  3. Backup all configuration and content SQL databases (as a reference version of the databases as of the time of roll-back).
  4. Create a special backup folder to store a copy of the current Micromine Geobank 2023 configuration objects, then, on the administrator machine, in the Micromine Geobank 2023 Configuration Manager:
    1. Select the top ‘User Interface’ node, then
    2. In the Ribbon, select ‘Export config’,
    3. Select ‘Configuration’ so that all four parts of the configuration are selected:
    4. Choose ‘Export as Individual files’
    5. Set Export location as the special backup folder you created and carry out the export:

    6. Repeat, but this time select ‘Export as a single file’ (having both types available means you can choose which is more convenient to use if you need to re-import any objects).
    7. Repeat, but this time just select the Forms and Datasets nodes under User interface and ‘Export as a single file’ – this is done as an extra backup of the current state of any Forms which have been built so that if needed these can be re-imported after the upgrade has been re-done, again as a separate set for convenience.
  5. Reinstall the previous version of Micromine Geobank on the administrator machine so that you can run Micromine Geobank 2023 and the previous version side by side. The purpose if this is to ascertain what, if any, changes need to be made to the Micromine Geobank configuration during the rollback change-freeze period.
  6. Because Micromine Geobank 2023 and the previous version have independent configuration sets, the recommended approach (a) is that the configuration data base is not removed and restored from the go-live backup; but that the Micromine Geobank 2023 configuration work done so far is left as it is so that configuration work can resume from where it left off once the upgrade has been reapplied. The alternative (b) is to revert to the configuration at go-live time and then, later, once the upgrade is re-applied, to import any Forms, dataset or other configuration objects created from the xml exports of these. If you anticipate a significant amount of configuration work happening between the roll-back and re-applying the upgrade, the approach (b) will be easier. Decide whether approach (a) or (b) is best for your scenario then proceed with (a) or (b) below:
    1. In the reinstalled (previous) version of Geobank analyse the Usage tracking data in the Geobank Configuration Manager to determine if any unwanted edits have been made to the previous version or earlier configuration objects since going-live with the latest version. It is unlikely any changes would have been made unless there are admin users who have been working in the previous version since go-live. If unwanted changes have been made, then use the xml file generated from pre-upgrade A step 4 with the configuration of the previous version at go-live time. From this xml file, just import the previous version objects which had unwanted changes.
    2. OR As you have already taken a backup of the Geobank configuration database in D step 4, you can now delete the configuration database and restore the configuration database from the backup taken in A Step 1.
  7. The original content database will not need to be reinstated (as this would result in data loss). As of version 10.0.0 (the initial release of Micromine Geobank 2017) the content database will have additional tables and columns as a result of the upgrade process, however the structure of the data will remain compliant with Micromine Geobank 2013. As a result, if you are rolling back to Micromine Geobank 2013, the following checks will be necessary as part of the roll-back (the checks are not required for Micromine Geobank 2017 of later):
    1. Identify any lab file formats which were created or changed in Micromine Geobank 2023 by opening SQL Server Management studio (or Micromine Geobank visual query builder) and executing: "SELECT * from GB.ST_FILE_FORMAT" and "SELECT * from GB.ST_FILE_FORMAT_FIELD".
    2. If any of the records have DATE_INSERTED or DATE_UPDATED greater that the date on which the go-live was completed, check the details to see what has changed.
    3. If changes or additions have occurred, consult with users or analyse the sub-tables to see if file format data changes or additions need to be re-applied in Geobank 2013 (because Geobank 2013 and earlier used different tables for this metadata the file formats and text rules will be in the state they were left in at the time of upgrade, so anything new will need to be applied in the Geobank 2013 version).
    4. If you are rolling back to Geobank 2020 or earlier and have not already done work on the Sample tracker metadata file format then it is recommended to drop the ST_FILE_TAG_RULE table so that the migration of the Micromine Geobank 2020 or earlier rules is repeated when the re-upgrade occurs.

    5. If rolling back from v22 sp 1 to a previous version , then as part of the roll back testing, the following error may be encountered when :

      The error message from the roll-back procedure

    6. Sample tracker metadata will fail to load in version 11.2 because it cannot parse the stored sample file with non-Windows format line endings.

  8. Using the previous version on the administrator machine, all processes should be tested to ensure that the application is behaving as expected. Address any issues that arise.
  9. Advise users that the change freeze has been lifted, but that the system has rolled-back to the previous version of Micromine Geobank and thus any Micromine Geobank 2023 functionality will not be available until the upgrade has been re-applied. If using Micromine Geobank 2013 or earlier, users should be instructed to report any changes they have made to file formats or text rules, so that these can be repeated after the upgrade has been re-applied.

E. Alternatives to roll-back

A full-roll back is time-consuming and may impact on users. Here are some alternatives to consider:

  1. Raise an issue with Micromine Geobank Support and ask for a time-line for resolution - if the circumstances and time-line are suitable such that other processes can continue and the failing process can be delayed, wait for the service pack which addresses the issue.
  2. Consider re-installing the previous Micromine Geobank version for users affected, so that tasks failing in Micromine Geobank 2023 can be carried out in a previous version running side-by-side.

F. Re-applying the upgrade

Once a service pack or other fixes which resolve the reasons for roll-back are available:

  1. Apply and test the fix in a test environment using Micromine Geobank 2023.
  2. Repeat the steps listed under "A. Steps prior to installing Micromine Geobank 2023" to create a new roll-back point and reference file set.
  3. Carry out the steps described under "B. Install and Upgrade process" (above).
  4. If the re-apply is from Micromine Geobank 2013 or earlier, then identify whether there have been any changes to file formats, or text rules, since the roll-back occurred (based on information from users or an examination of the related tables). These file format or text rules changes will need repeating in Micromine Geobank 2023.
  5. If it was a post-upgrade roll-back, then depending on the approach chosen in D Step 6; either (a) or (b), follow steps (a) or (b) below respectively.
    1. The configuration of Micromine Geobank 2023 will be as it was when the roll-back occurred; thus, on the administrator machine:
      1. In the previous version of Micromine Geobank view the usage tracking, to determine if the design of any of the Configuration objects have been updated since the roll back. If just one or two objects have been updated, these can be exported to xml form the previous version then re-imported (with Replace) into Micromine Geobank 2023 to update the Micromine Geobank 2020 copies; however if there have been a substantial number of changes then is better to purge the Micromine Geobank 2023 configuration set and allow the upgrade process to re-copy all previous version configuration object to Geobank 2023 in their current state.(see details under “Version and configuration management”). The Geobank 2023 Forms and Datasets can then be reimported from the xml file created in D step 4 (g).
    2. OR because approach (b) in D Step 6 reverted to a previous-version-only configuration, then F step 3, will have created a copy of all previous version objects for Micromine Geobank 2023; so it will just be the Forms and Datasets exported to the special folder in D step 4 (g) which will need to be restored by using the Config Import tool and using the links resolver to match their links up to other objects as needed.
  6. Using Micromine Geobank 2023 on the administrator machine:
    1. Test the Forms and Datasets to check that behaviour is as expected.
    2. Test other objects to check that behaviour is as expected.
  7. Lift the change freeze and advise users to work in Micromine Geobank 2023.
  8. Monitor the system and if a roll-back is once again deemed necessary, implement the steps necessary to roll-back to your latest roll-back point.