Prepare for Upgrading From a Pre-1.10 to 1.10 or Later Version

There are several database changes that are likely to fail while attempting to upgrade from a pre 1.10 to a 1.10 or later version if an implementation has orders stored in the database. Below are some key conditions that need to be satisfied before attempting an upgrade because they are guaranteed to halt the upgrade if they are not.

All existing free text drug order dose units and frequencies have been mapped to concept ids via the order_entry_upgrade_settings.txt file, you can use the Prepare For Upgrade To 1.10 Module to set the mappings.
All orders have start_date and encounter_id column values set
All drugs with a dose_strength specified have the units field set too.
If there any other any order types other than drug order, the order_type table is up to date i.e has the new columns java_class_name(required) and parent(optional), we will see later how to manually update the order type manually if there are other order types.
All discontinued orders should have the discontinued_date and discontinued_by fields set.
All users that created orders(orders.orderer) have provider accounts
If there any orders with no orderers, you are required to create a ~~provider whose name is 'Unknown Provider' i.e provider.name column is set to Unknown Provider and not the name of the linked person record so that it is set as the default orderer~~ a provider to serve as the "Unknown Provider" and set the global property "provider.unknownProviderUuid" to the uuid of this provider. (You will most likely need to create this global property, since it isn't added until 1.10.x)If you don't want it to default to Unknown Provider, you can manually set the values prior to the upgrade.

Preparing for the upgrade

Make sure you have imported or already have frequency and units of measurement concepts in your dictionary, if you are running the latest version of the CIEL dictionary these should be present, if you are running an older version you might need to upgrade to a later version that contains these concepts. If you are not using CIEL dictionary and do not have the necessary concepts set up, you can add them by importing Order Entry Concepts for OpenMRS Platform 1.10 and Later Versions
Add Setting (formerly Global Property from 1.8 downwards) for drug dosing units with name order.drugDosingUnitsConceptUuid and the value should be the uuid of the concept set where its members represent the possible drug dosing units. In CIEL version 1.9.7_20140608 the concept id is: 162384AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA (Dose unit). It is used too validate the dose units mappings made via the order_entry_upgrade_settings.txt file.
If you have other order type row entries in the order_type table other than the one for Drug orders, then add the java_class_name and parent columns using the sql below:
```
ALTER TABLE `order_type`
ADD COLUMN `java_class_name` VARCHAR(255) DEFAULT NULL,
ADD COLUMN `parent` INT(11) DEFAULT NULL;
```
The java_class_name column is required, the upgrade scripts will set a not null constraint on the column and will set the java_class_name column for the drug order type row as long as its uuid has never been changed from 131168f4-15f5-102d-96e4-000c29c2a5d7.
The scripts will also add a foreign key constraint on order_type.parent column which references the order_id column

For all order types that are not Drug order, set their java_class_name column values, the values should match a valid fully qualified java class name which must be available at runtime, see an example SQL script below for how to set it for each row:
```
UPDATE `order_type` SET `java_class_name` = 'org.openmrs.TestOrder' WHERE name ='Lab test';
```
Create the mappings file to concepts for all existing free text frequencies and dose units, this can be done via either of the options below:
1. Using the 1.10 upgrade helper module
- - See Prepare For Upgrade To 1.10 Module
1. Manually create the mapping file
  1. Create a file in the application data directory named order_entry_upgrade_settings.txt
  2. Get all the existing frequencies and dosing units for existing drug orders in the database using the SQL queries below:
    Get all free text dose units
    SELECT DISTINCT units FROM drug_order WHERE units IS NOT NULL
    Get all free text frequencies
    SELECT DISTINCT frequency FROM drug_order WHERE frequency IS NOT NULL
  3. Set the contents of the file in a properties file format as shown below and save the changes. You might want to leave no trailing white space characters at the end of each line and also to escape white spaces in the frequencies as shown below.
    Example
    mg=13 ounces=46 once\ a\ day=65

Upgrading from an earlier platform like 1.6.x

The above guide may demand either upgrading from an earlier version such as 1.6.6 to 1.9.x (which creates the providers table) and then from 1.9.x to 1.10.x or 1.11.x

The MoH Rwanda upgrade lead has written a module that handles all these requirements/steps so that the user only has to install it before upgrading and do nothing else as suggested by this page but go straight to the upgrade steps.

This module supports upgrading from 1.6.x on which it has been tested to 1.11.x

Now you are ready to upgrade to 1.10 or later!