Determine Your Upgrade Path

Note: Upgrades from DocuPhase Forms 6.3.9 - 6.3.12 through v9.0.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. 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

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

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

5. Install OpenJDK (21.x).

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:

   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.

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 (databases other than SQL Server).

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.

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. Navigate to the server.xml file in the <frevvo-home>\tomcat\conf directory of your v11.3.x installation.

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

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

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

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

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

Open

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 or status 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

Insight Server Configuration Error

If you start DocuPhase Forms before the Insight server, you will see this message when you browse the DocuPhase Forms login URL. Stop both services and follow the steps above to start the servers in the correct order.

Open

Logs

Tail the catalina log file during start up to observe any start-up errors. Tail the frevvo.<date> log file to observe any errors running the upgrade processes. See Tomcat Logfiles for more info.

Applying a Minor Patch Update

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

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