These instructions are for upgrading from OpenClinica 3.0.x to version 3.1 , 3.1.x maintenance release or to a 3.2 on Windows 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 OpenClnica 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.15.1 Overview of the Upgrade Process on Windows Systems

  1. Ensure your system complies with software dependencies and system requirements.
  2. Back up OpenClinica.
  3. Upgrade OpenClinica.
  4. Configure OpenClinica:
    1. Ensure that OpenClinica is configured for optimum performance as described here: Configure OpenClinica for Optimum Performance.
    2. 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
  5. Verify the upgrade.
  6. Make manual updates to the database. The instructions are the same as for upgrading OpenClinica on Linux systems, except the README file on Windows systems is located at:
    c:ocinstallOpenClinica-
    v.x.yconfigdatabasesPostgreSQL

10.15.2 Software Dependencies and System Requirements

To upgrade to OpenClinica 3.1.x, you need the following:

  • Operating system must be either of these:
    • Windows XP
    • Windows Server 2003
  • Browsers supported in this release:
    • Internet Explorer 11
    • Mozilla Firefox 30
  • Software versions must be:
    • Java JDK 1.7.065
    • PostgreSQL 8.4.1
    • Tomcat 7.0.33.0 application server
      Note: In most cases, minor maintenance releases of the above products will also work (but not major releases)

10.15.3 Back Up OpenClinica

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

  1. Stop Tomcat. (See instructions, which are included in Start Tomcat.)
  2. Back up the database (instructions here).
  3. Back up the file
    CATALINA_HOMEwebappsOpenClinicaWEB-INFclassesdatainfo.properties
  4. Back up the folder
    CATALINA_HOMEwebappsOpenClinica
  5. Back up the CRFs and datasets, which are located in
    CATALINA_HOMEwebappsopenclinica.data

10.15.4 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
    c:ocinstallOpenClinica-v.x.xconfigdatabasesPostgreSQL
  2. Follow the instructions in the README file.

Oracle

  1. At the location c:ocinstallOpenClinica-v.x.xconfigdatabasesOracleupgrade, 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 c:ocinstallOpenClinica-v.x.xconfigdatabasesOracleupgrade
  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.x.

10.15.5 Verify the Upgrade

  1. Test the database connection and basic authentication:
    1. Verify that Tomcat is running. If the URL loads Tomcat is running.
    2. Point your web browser to the OpenClinica login page:
      http://<<server url>>:8080/OpenClinica
      The OpenClinica Log In page should display.
    3. 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.15.6 Upgrade OpenClinica

  1. Undeploy OpenClinica:
    1. Delete the directory
      CATALINA_HOMEwebappsOpenClinica
    2. Delete the file
      CATALINA_HOMEwebappsOpenClinica.war if exists
    3. Delete the directory
      workCatalinalocalhostOpenClinica
  2. Create the following directory, if it does not already exist:
    c:ocinstall
  3. Download the OpenClinica software, OpenClinica-v.x.x.zip, from the OpenClinica website:  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, extract the files to:
    c:ocinstall.
  4. Copy the file
    c:ocinstallOpenClinica-
    v.x.xdistributionOpenClinica.war
    to
    c:octomcatwebapps
  5. Start Tomcat. (See instructions at Start Tomcat.)
  6. In about five minutes, Tomcat will be fully started. Verify it is fully started by opening the file
    c:octomcatlogscatalina.out
    and looking for this line:
    INFO: Server Startup in XXXXX ms
  7. Stop Tomcat. (See instructions, which are included at Start Tomcat.)
  8. Wait about two minutes for Tomcat to stop, then delete the file
    c:octomcatwebappsOpenClinca.war
  9. Using WordPad, make any changes to the configuration file
    1. Open the file
      CATALINA_HOMEwebappsOpenClinicaWEB-INFclassesdatainfo.properties
    2. Make changes to any values for the properties: see more information at Description of datainfo.properties File.
    3. When you finish making changes, save the file.
  10. Move the backed up CRF and dataset files from the openclinica.data directory to the new openclinica.data directory.
  11. Start Tomcat. (See instructions at Start Tomcat.)

10.15.7 Back Up OpenClinica Web Services

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

  1. Stop Tomcat. (See instructions, which are included in Start Tomcat.)
  2. Back up the database (instructions here).
  3. Back up the file
    CATALINA_HOMEwebappsOpenClinica-wsWEB-INFclassesdatainfo.properties
  4. Back up the folder
    CATALINA_HOMEwebappsOpenClinica-ws

10.15.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.

10.15.9 Upgrade OpenClinica Web Services

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

  1. Undeploy OpenClinica Web Services:
    1. Delete the directory
      CATALINA_HOMEwebappsOpenClinica-ws
    2. Delete the file
      CATALINA_HOMEwebappsOpenClinica-ws.war if exists
    3. Delete the directory
      workCatalinalocalhostOpenClinica-ws
  2. Create the following directory, if it does not already exist:
    c:ocinstall
  3. Download the OpenClinica software, OpenClinica-ws-v.x.x.zip, from the OpenClinica website: 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, extract the files to:
    c:ocinstall.

  4. Copy the file
    c:ocinstallOpenClinica-ws-
    v.x.xdistributionOpenClinica-ws.war
    to
    c:octomcatwebapps
  5. Start Tomcat. (See instructions at Start Tomcat.)
  6. In about five minutes, Tomcat will be fully started. Verify it is fully started by opening the file
    c:octomcatlogscatalina.out
    and looking for this line:
    INFO: Server Startup in XXXXX ms
  7. Stop Tomcat. (See instructions, which are included at Start Tomcat.)
  8. Wait about two minutes for Tomcat to stop, then delete the file
    c:octomcatwebappsOpenClinca-ws.war
  9. Using WordPad, make any changes to the configuration file
    1. Open the file
      CATALINA_HOMEwebappsOpenClinica-wsWEB-INFclassesdatainfo.properties
    2. Make changes to any values for the properties: see more information at Description of datainfo.properties File.
    3. When you finish making changes, save the file.
  10. Start Tomcat. (See instructions at Start Tomcat.)