Upgrading from 4.3.x to 4.4.y
The following instructions explain how to upgrade an instance of OpenEMPI from a 4.3.x release to the 4.4.y release.
1. Shutdown your OpenEMPI server instance. Make sure the server has shutdown and has shutdown cleanly before moving on to the next step.
/sysnet/openempi/openempi-4.3.x/bin/shutdown.sh2. Backup your databases. Keep in mind that version 4.3.0 or newer only use the Graph database and no longer use Postgres or another relational database. You can find instructions on how to do that here.
3. Install the 4.4.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.4.y are in the same directory.
For the purpose of these instructions, we assume that OPENEMPI_OLD_HOME points to the installation directory of the 4.3.x release
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. In order to use file mapping files in the 4.4.0 release or newer, you must import them through the UI using the User Files page and mark them as mapping files.
On our installations, we follow the convention of installing new releases in the /sysnet/openempi directory so that the 4.3.x release would be installed in the /sysnet/openempi/openempi-4.3.x directory and the 4.4.y release would be installed in the /sysnet/openempi/openempi-4.4.y directory. We also maintain the data directory under /sysnet/openempi so that the databases do not need to move when upgrading to a new version. If you have installed OpenEMPI for the first time, the data directory will be placed under the root directory of the installation (e.g. /sysnet/openempi/openempi-4.4.0/data) so it is suggested that you move it up one level and modifying the setenv.sh script to point to the correct location of the data directory).
4. First, compare the contents of the following configuration files between the 4.3.x and 4.4.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.
bin/setenv.sh
openempi-entity-4.3.x/conf/openempi-extension-contexts.properties
openempi-entity-4.3.x/conf/jdbc.properties (more likely to have local changes for your environment)
openempi-entity-4.3.x/conf/applicationContext-resources.xml (more likely to have local changes for your environment)
openempi-entity-4.3.x/conf/applicationContext-services.xml (not likely to have local changes for your environment)
openempi-entity-4.3.x/conf/orientdb-server-config.xml (not likely to have local changes for your environment)5. Copy the following configuration files from the 4.3.x to the 4.4.y directory.
openempi-entity-4.3.y/conf/file-loader-map-*.xml6. You may need to modify the setenv.sh file in /sysnet/openempi/openempi-4.4.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.
export OPENEMPI_HOME=/sysnet/openempi/openempi-4.4.0/openempi-entity-4.4.0/
CLASSPATH=$CATALINA_HOME/log4j2/lib/*:$CATALINA_HOME/log4j2/conf
export ORIENTDB_HOME=/sysnet/openempi/openempi-4.4.0/orientdb-3.2.45
VMPARAMS="-Xms1g -Xmx8g -XX:+UseG1GC -XX:MaxDirectMemorySize=1g -Dlog4j.configurationFile=${OPENEMPI_HOME}/conf/log4j2.xml -Djava.util.logging.config.file=${OPENEMPI_HOME}/conf/orientdb-logging.properties"
export JAVA_OPTS="${VMPARAMS} -Dopenempi.home=${OPENEMPI_HOME} -Dopenempi.data.directory=/sysnet/openempi/data"7. Copy the license.txt from the ${OPENEMPI_OLD_HOME}/conf directory that contains the product key to the ${OPENEMPI_HOME}/conf directory.
8. If you have moved your data directory one directory level up from the OpenEMPI version-specific directory (to /sysnet/openempi/data from /sysnet/openempi/openempi-4.3.7/data for example), then you may need to copy the latest database plugins to the data directory. Compare the contents of the plugins directory between the current version and the new version and make sure you have the latest versions in the plugins directory of your data directory.
# We simply delete the version in the plugins directory and use the latest plugins
rm /sysnet/openempi/data/plugins
cp /sysnet/openempi/openempi-4.4.y/data/plugins /sysnet/openempi/data/plugins9. 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 changes to the configuration of the service such as the installation directory of the recent version and the version of the JDK used (this is usually installed in /etc/systemd/system/openempi.service).
/sysnet/openempi/openempi-4.4.y/bin/startup.shYou 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.
tail -f /sysnet/openempi/openempi-4.4.0/openempi-entity-4.4.0/logs/openempi.logIf you have any questions, please open a ticket through our customer support portal.