Upgrading from 4.2.x to 4.3.y

The following instructions explain how to upgrade an instance of OpenEMPI from a 4.2.x release to the 4.3.y release.

1. Shutdown your OpenEMPI server instance. Make sure the server has shutdown before moving on to the next step.

2. Backup your Postgres and OrientDB databases. You can find instructions on how to do that here.

3. Install the 4.3.y instance in its new OPENEMPI_HOME directory. Follow the installation instructions for installing a new instance of OpenEMPI from a distribution that can be found here. The recommended approach is to install new releases under the same parent directory so that openempi-4.3.x and openempi-4.3.y are in the same directory. On our installations, we follow the convention of installing new releases in the /sysnet/openempi directory so that the 4.2.x release would be installed in the /sysnet/openempi/openempi-4.2.x directory and the 4.3.y release would be installed in the /sysnet/openempi/openempi-4.3.y directory.

For the purpose of these instructions, we assume that OPENEMPI_OLD_HOME points to the installation directory of the 4.2.x release

4. First, compare the contents of the following configuration files between the 4.2.x and 4.3.y directories and if they include changes that you have made, then merge those changes into the new version of the file. If you have questions about specific differences between the two versions and are unsure how to proceed, don't hesitate to reach out to us through the customer support portal. We can perform the merge between the configuration files for you. For example, the openempi-extension-contexts.properties may have been changed to activate or deactivate specific modules in your instance of OpenEMPI and jdbc.properties may have changed to reflect a change in the database password for the relational or graph databases.

5. Copy the following configuration files from the 4.2.x to the 4.3.y directory.

NOTES: Please read and understand the information in these notes.

• We use the convention of naming file loader mapping files file-loader-map-{VARIABLE].xml where VARIABLE is a unique name that identifies the specific mapping file. You only need to copy mapping files that are unique to your installation.

• Starting with the 4.3.0 release of OpenEMPI the Postgres relational database is no longer used so as part of this upgrade the next few steps will migrate the data from the relational database into the embedded graph database and specifically in the configuration database instance (openempiConfig-db).

• Make sure you delete old or unneeded audit log and identifier update notifications before performing the migration otherwise the migration process may take too long or fail to complete. Some sites don’t delete old entries and they may have accumulated millions of records. You can do that using the appropriate scheduled task or you can open a ticket in the customer support forum and we can help you with that.

• The installation of 4.3.x creates an initial configuration database instance openempiConfig-db but if you are migrating from a 4.2.x version, you should replace the openempiConfig-db created by the installation with a copy of the openempiConfig-db from the data directory of your 4.2.x instance. If you are using the shared data directory as suggested in step 3, you can ignore this step since the new configuration database instance is created in the data sub-directory of the 4.3.x installation directory but make sure you have modified the data directory in the setenv.sh file before beginning the migration process as described in step 6.

• The migration code by default assumes that the Postgres database is on the same server as the OpenEMPI instance that is migrated. If the Postgres database is on another server, you need to modify the connection URL appropriately. The configuration file you need to change is shown below. The property you need to change is $jdbcUrl and has the default value of: jdbc:postgresql://localhost/openempi
  
  

6. You may need to modify the setenv.sh file in /sysnet/openempi/openempi-4.3.y/bin to set the location of the data directory for your site and should point to the data directory that includes the openempiConfig-db directory as one of its subdirectories along with database directories for the entities on your instance (for example: person-db).

Here is a sample configuration of the setenv.sh file.

7. Copy the license.txt from the ${OPENEMPI_OLD_HOME}/conf directory that contains the product key to the ${OPENEMPI_HOME}/conf directory.

8. Before running the migration process, you need to set the environment variable ORIENTDB_OPTS_MEMORY to the same value as the memory settings you are currently using for your OpenEMPI instance. Those settings are specified in the setenv.sh file. The migration process uses utilities from the embedded graph database to perform the migration and it is important that the memory configuration for those utilities can accommodate the size of your database.

Here is an example of how to set the environment variable.

The migration script assumes that the data directory for the 4.3.x instance is in the data directory under the installation directory (for example: /sysnet/openempi/openempi-4.3.0/data). If your directory is in a different location (for example /sysnet/openempi/data) then you should set the OPENEMPI_DATA_DIRECTORY environment variable to point to that directory before running the migration script. Here is an example but remember that you only need to do this if your data directory is not located in the default location.

9. Run the migration script. If you encounter any issues with the migration process please open a ticket in the customer support forum and provide the output of the migration process.

10. Start your instance of OpenEMPI using the startup script from the new release directory. If you are using a service startup script to automatically start your instance of OpenEMPI, make sure you update the script to reflect its new directory location (this is usually installed in /etc/systemd/system/openempi.service).

You can check on the startup progress of the application by looking at the openempi.log file using the following command. Note that the path may vary for your site and specific version you are using.