Determine Your Upgrade Path

Note: Upgrades from DocuPhase Forms 6.3.9 - 6.3.12 through v7.4.x are supported but these versions are not available for general release.

Migrating from HSQLDB

DocuPhase Forms does not support the use of HSQLDB for use beyond demo/trials of the DocuPhase Forms software. If by mistake you continued to use the demo/trial HSQLDB database for production use, you will need to first migrate your data to one of DocuPhase Forms supported production databases BEFORE you can upgrade to later versions of DocuPhase Forms.

Upgrading DocuPhase Forms 

Please read the following upgrade steps prior to starting the migration.

Prepare for the upgrade

1. Read and understand the Migration Considerations that may require your action before beginning (review Migration Considerations for all interim versions as well.)

2. Install OpenJDK (11.x)before beginning.

3. Stop DocuPhase Forms with one of the methods listed below:

   1. Stop DocuPhase Forms and the Insight Server through the Computer Management Services console if they are running as Window's services.
      OR

   2. Execute <frevvo-home>\stop-frevvo.[bat,sh]

   3. Stop the Insight Server by closing the window or if you are using the tomcat bundle by typing these commands in the <frevvo-home>\solr directory of your existing installation.
      bin\solr.cmd stop -all

4. Back up the forms database from your current DocuPhase Forms installation.

5. Back up the current DocuPhase Forms server's installation directory so that you have a copy of all custom configuration parameters.

Remove Services

Remove the old services, as you will reinstall them for the upgraded version.

1. To remove the frevvo service, run the <frevvo-home>/frevvo/Remove-Service.(bat) file (Windows)

2. To remove the Insight Server (Solr) services, open a command prompt and run the command:

   Code Block
   sc delete insightserver

   Replace ‘insightserver’ with the service name if you changed it. Verify the Insight Server service name by double clicking it in the Windows Services list.

Oracle DB Permission

Customers using Oracle DB should grand the following permission before upgrading.

GRANT EXECUTE ON SYS.DBMS_CRYPTO TO <DocuPhase Forms user>;

If you do not do this, you may see an error like "liquibase.exception.DatabaseException: ORA-00904: "DBMS_CRYPTO"."HASH": invalid identifier" in the log file while upgrading, and the upgrade will fail.

Install Upgraded Version

1. Download the latest v11.3.x software. The download is a zip file. Extract the contents to any folder of your choice. This folder will be referred to as <frevvo-home> (note that the zip already contains a top-level frevvo folder).

2. Install a JDBC Driver.

3. Ensure that Chrome or a Chromium browser is installed on the same server as the DocuPhase Forms installation for PDF Snapshot generation. See the related Installation Task for details.

4. If you increased Memory Settings in your previous installation, make those changes to the appropriate files in the new installation. Refer to Hardware and Memory Requirements for the details.

5. Navigate to the server.xml file in the <frevvo-home>\tomcat\conf directory of your v11.3.x installation

Configure the Database and Email

The following are the most common properties you need to update in your server.xml. However, you may have further customizations. Compare your backup and the new configuration file to ensure you copy all necessary properties.

1. Configure your Database. Comment out HQSQL and comment in your database type, and fill in your credentials and database URL. See this documentation for details.

   1. If you are using SQL Server, remember to add the sendStringParametersAsUnicode property with a value of false to your database connection URL if it is not already there.

2. Configure Email (Mail Resource) with your SMTP settings. See the Configure Email section for details.

3. Configure the Default Port (if not using the standard defaults.)

4. Configure SSL for tomcat if it was configured in prior version of DocuPhase Forms. If you keep the certificate in the frevvo installation directory, copy it from the old to the new.

5. Save the changes to the server.xml file. 

Copy Properties

See Installation Tasks for commonly used properties. Read the Detailed Release Notes to be sure that all properties you are using are valid in the upgraded version.

1. Edit the frevvo-config.properties file in your prior version. This file is usually located in the<frevvo home>/tomcat/conf directory.

2. Copy the properties you added or changed.

3. Edit the frevvo-config.properties file in the upgraded version, and paste the properties you copied from your prior version. 

4. Save the frevvo-config.properties file.

You may have also configured properties in other installation files. One common example is the sameSiteCookies attribute, configured in tomcat/conf/context.xml.

Connectors

Follow the links below to upgrade and configure your connectors. You must always use the latest compatible connector version for your DocuPhase Forms version; however, in many cases configuration files can be copied from your prior version.

• Database Connector

• Google connector (Legacy)

  • Note that on v11.3, a new Google Connector is built in! Consider migrating to the new connector as a part of your upgrade. The Legacy Connector is no longer supported and will be removed in a future release.

• Filesystem Connector

• SharePoint Connector (Legacy)

  • Note that on v11.3, a new SharePoint Connector is built in! Consider migrating to the new connector as a part of your upgrade. The Legacy Connector is no longer supported and will be removed in a future release.

Starting the New Version

Install Services

Follow the guides to install Solr and frevvo services.

• Install Solr Service

  • Note that you may already have the nssm downloaded from your previous installation.

• Install DocuPhase Forms Service (run <frevvo-home>/Install-Service.bat)

Start the Insight Server

Start the Insight server BEFORE starting DocuPhase Forms by starting the Solr/insightserver Service.

Browse http://<your server:port>/ solr to verify the Insight server is running. The <server:port> default values are localhost:8983. Change localhost to the server name and 8983 to the port the Insight server is running on if they are different than the defaults. Do not include the angle brackets <>. You will see the Insight server (Solr) dashboard with the current status.

Start DocuPhase Forms

Start DocuPhase Forms service. Optionally, start the application manually by running the start-frevvo.bat or start-frevvo.sh files (depends on your Operating system) in the <frevvo-home>\frevvo directory.

Then follow these instructions to login and enter your upgrade license key.

Log in, Apply License, and Check Configuration

1. Verify that any DocuPhase Forms Connectors are up and running. Installed connectors will have a health URL you can browse to check their status.

2. Login as a the superuser admin (admin@d)

   1. Apply license if prompted (upgrades from versions prior to v11.x)

   2. Verify that the Refresh Searchable Items process ran and completed successfully.

   3. Click on the Configuration Checklist link to verify that all configurations are complete.

3. Login as the tenant admin. Click on the Reports link. Click on one of the Reports to verify that submission data is displayed.

4. Login as a tenant designer user

   1. View and edit a form/flow

   2. View Submissions and verify submissions are displayed.

   3. Test forms/flows 

Troubleshooting

Warning

If you start DocuPhase Forms before the Insight server, you will see this message when you browse the DocuPhase Forms login URL. Follow these steps to start the servers in the correct order: Navigate to your <frevvo-home> directory. Run the stop-frevvo.bat or stop-frevvo.sh file depending on your Operating system to stop DocuPhase Forms. Open a command prompt. Navigate to <frevvo-home>\solr-6.6.2 Start the Insight server. Refer to Start the Insight Server above for the instructions. Browse http://<your server:port>/solr to verify the Insight server is running. The <server:port> default values are localhost:8983. Change localhost to your server name and 8983 to the port the Insight server is running on if they are different from the defaults.Do not include the angle brackets <>. Start DocuPhase Forms.

Applying a Minor Patch Update

If you're applying a minor patch update, for example, applying patch v11.0.x to your installed v11.0.2 DocuPhase Forms server, you can follow these simple steps instead of the more lengthy upgrade steps.  

Note
The latest major DocuPhase Forms version and the compatible DocuPhase Forms connectors are available from the DocuPhase Forms Software Downloads Directory.

1. Unzip the downloaded build zipfile to a temp directory. 

2. Copy the \temp\frevvo\tomcat\webapps\frevvo directory.

3. Stop DocuPhase Forms.

4. Delete the frevvo.war and/or frevvo directory file from your <frevvo-home>\tomcat\webapps directory.

5. Paste the frevvo directory copied above in your <frevvo-home>\tomcat\webapps directory. 

6. Delete everything inside \frevvo\tomcat\temp directory of your installation.

7. Start DocuPhase Forms. 

Apply a Patch with Tomcat Upgrade

If you are applying a patch release that includes an Apache Tomcat upgrade to your installed v11.0 DocuPhase Forms server, follow these modified upgrade instructions. Refer to the sections above for detailed steps.

1. Stop DocuPhase Forms.

2. Back up the current DocuPhase Forms server's installation directory so that you have a copy of all custom configuration parameters.

3. Install the Upgraded Version.

   1. Download the latest v11.0.x software. The download is a zip file. Extract the contents to any folder of your choice. This folder will be referred to as <frevvo-home> (note that the zip already contains a top level frevvo folder).

   2. Install a JDBC Driver.

   3. If you increased Memory Settings in your previous installation, make those changes to the appropriate files in the new installation. Refer to Hardware and Memory Requirements for the details.

   4. Navigate to the server.xml file in the <frevvo-home>\tomcat\conf directory of your v10.1.x installation

4. Configure the database and email.

5. Install any Upgrade Guide#Connectors that were installed in your previous version.

6. Restore the contents of the <frevvo-home>\data\solr directory from the previous installation directory backup that you made in Step 2 to your latest version's <frevvo-home>\data directory. Then, start the Insight Server.

7. Start DocuPhase Forms.