These instructions are for upgrading from OpenClinica 3.0.x to version 3.1 or to a 3.1.x maintenance release on Linux systems running the essential software dependencies: Java 6, Tomact 6, and PostgreSQL 8.4. When you see v.x or v.x.x or similar in the instructions, use the version number you are upgrading to, e.g. 3.1 or 3.1.2.

The instructions apply only if you followed the upgrade instructions to get to 3.0.x; if you did not, you might need to do other things in order to upgrade your system. 

If you are running an earlier version of OpenClinica and/or its related software dependencies, make sure you upgrade these to the required versions before upgrading beyond OpenClinica 3.0.x. Please note that these instructions do not cover upgrading related software dependencies for 3.1.x. To upgrade these components, you’ll need to follow the instructions provided by those technologies. Make sure you back up everything so your existing files are not lost.

If you are upgrading from OpenClinica 2.5.x, you need to first upgrade to 3.0.x, and you will need to upgrade the software dependencies so they meets the requirements for OpenClinica 3.0.x. Perform a full backup of your 2.5.x instance, perform a fresh install of 3.0.x, and then restore your 2.5.x data. For information about backing up your 2.5.x instance, see the 3.0.x upgrade documentation that is included with the downloaded files for 3.0.x.

10.14.1 Overview of the Upgrade Process on Linux Systems

Follow this process to upgrade OpenClinica. In each step, click the link to view detailed instructions for the step:

  1. Back up OpenClinica.
  2. Upgrade OpenClinica.
  3. Configure OpenClinica:
    1. Make any changes needed to the datainfo.properties file as described here: Configure the OpenClinica Application.
    2. Ensure that OpenClinica is configured for optimum performance as described here: Configure OpenClinica for Optimum Performance.
    3. You may also need to configure OpenClinica for internationalization should you wish to utilize OpenClinica in different languages. Also, if you need to use some UTF-8 characters in your application, you may need to modify your default connecter configuration. For more information regarding configuring OpenClinica for internationalization and using UTF-8 characters, please refer to https://docs.openclinica.com/3.1/technical-documents/openclinica-and-internationalization
    4. Reboot the system by typing reboot.
  4. Make manual updates to the database.
  5. Start Tomcat by running the following command:
    /etc/init.d/tomcat start

10.14.2 Overview of the Upgrade Process for Web Services on Linux Systems

Follow this process to upgrade OpenClinica. In each step, click the link to view detailed instructions for the step:

  1. Upgrade OpenClinica Web Services.
  2. Configure OpenClinica:
    1. Make any changes needed to the datainfo.properties file as described here: Configure the OpenClinica Application.
    2. Ensure that OpenClinica is configured for optimum performance as described here: Configure OpenClinica for Optimum Performance.
    3. Reboot the system by typing reboot.
  3. Start Tomcat by running the following command:
  4. /etc/init.d/tomcat start

 

10.14.3 Back Up OpenClinica

Before upgrading, follow this process to back up the database and files needed by OpenClinica:

  1. Stop Tomcat by running the following command:
    /etc/init.d/tomcat stop
  2. Confirm Tomcat has stopped before continuing.
  3. Create the backup directory by running the following command:
    mkdir -p /usr/local/oc/backup/manual/`date +%b-%d-%Y`
  4. Make the backup directory become the current directory by running the following command:
    cd /usr/local/oc/backup/manual/`date +%b-%d-%Y`
  5. Run:
    /opt/PostgreSQL/8.4/bin/pg_dump -F c -U postgres openclinica > openclinica.backup
  6. When prompted for a password, enter the PostgreSQL database superuser password you specified when setting up the database as part of installing OpenClinica.
  7. Copy the files OpenClinica needs by running the following command:
    cp -rf /usr/local/tomcat/openclinica* .
    cp -rf /usr/local/tomcat/webapps/OpenClinica* .

10.14.4 Upgrade OpenClinica

  1. Download the OpenClinica software from the OpenClinica website, using this location: https://community.openclinica.com/project/openclinica. To download the software, use your free community account; you will be required to log in to the account to download the OpenClinica software. If you do not have an account, you may get one here.

    After downloading the OpenClinica software, move it to:

    /usr/local/oc/install

  2. Run the following commands:
    cd /usr/local/oc/install
    unzip OpenClinica-v.x.y*
    cd OpenClinica-v.x.y*/distribution
    unzip OpenClinica.war -d OpenClinica
    rm -rf /usr/local/tomcat/work/Catalina/localhost/OpenClinica*
    rm -rf /usr/local/tomcat/webapps/OpenClinica*
    cp -rf OpenClinica* /usr/local/tomcat/webapps
    rm -f /usr/local/tomcat/webapps/OpenClinica.war

10.14.5 Upgrade OpenClinica Web Services

Run upgrade for OpenClinica Web Services only if you are currently using Web Services 

  1. Download the OpenClinica Web Services package from the OpenClinica website, using this location: https://community.openclinica.com/project/openclinica. To download the software, use your free community account; you will be required to log in to the account to download the OpenClinica software. If you do not have an account, you may get one here.

    After downloading the OpenClinica Web Services, move it to:

    /usr/local/oc/install

  2. Run the following commands:
    cd /usr/local/oc/install
    unzip OpenClinica-ws-v.x.y*
    cd OpenClinica-ws-v.x.y*/distribution
    unzip OpenClinica-ws.war -d OpenClinica-ws
    rm -rf /usr/local/tomcat/work/Catalina/localhost/OpenClinica-ws*
    rm -rf /usr/local/tomcat/webapps/OpenClinica-ws*
    cp -rf OpenClinica-ws* /usr/local/tomcat/webapps
    rm -f /usr/local/tomcat/webapps/OpenClinica-ws.war

10.14.6 Manual Database Updates

Now, you’ll need to make database updates for your database: either PostgreSQL or Oracle. The instructions apply to upgrading OpenClinica on Linux and Windows systems:

PostgreSQL

  1. Open the file README_Instructions_for_Duplicate_Row_Fix.txt, located at
    /usr/local/oc/OpenClinica-v.x.y/config/databases/v.x/PostgreSQL

  2. Follow the instructions in the README file.

Oracle

  1. At the location /usr/local/oc/OpenClinica-v.x.y/config/databases/v.x.y/Oracle/upgrade, open the file README_Instructions_for_Duplicate_Row_Fix.txt, and follow the instructions in the README file.
  2. As the sysdba user, run the Grant_View.sql script located in /usr/local/oc/OpenClinica-v.x.y/config/databases/v.x.y/Oracle/upgrade.
  3. The script prompts you for a user name: provide the user name for the database user OpenClinica is set up to use, as specified in the datainfo.properties file that you configured during installation. Run this script before starting Tomcat. There is no risk in running this script on a database that has already been upgraded to 3.1.y.

10.14.7 Verify the Upgrade

  1. Test the database connection and basic authentication:
    1. Point your web browser to
      http://<<server url>>:8080
    2. Verify that Tomcat is running. If the URL loads Tomact is running.
    3. Point your web browser to the OpenClinica login page:
      http://<<server url>>:8080/OpenClinica
      The OpenClinica Log In page should display.
    4. Log in to OpenClinica.
  2. Verify the version number is v.x.x-Community, where v.x.x is the version number you upgraded OpenClinica to. The version number is displayed in the lower right corner of the page.

10.14.8 Verify the Upgrade for OpenClinica Web Services

  1. Point your web browser to the OpenClinica Web Services welcome page: http://<<server url>>:8080/OpenClinica-ws. The OpenClinica Web Services Welcome page should be display.
  2. Verify the version number is v.x.x-Community, where v.x.x is the version number you upgraded OpenClinica Web Services to. The version number is displayed in the lower right corner of the page.

Web Services should have the same version as OpenClinica application.