API Server 6.x to 7.x

API Server 6.x to 7.x

Migrating your deployment from a 6.x version into a 7.x version is not complicated, but there are a few things that you should be aware of to ensure that your transition goes smoothly. The 7.x version of the Enterprise Server introduces a number of new features that you will certainly want to take advantage of, which are as follows.

7.x Features

Feature	Description
New Licensing System	This allows you to manage all of your licenses with the Form.io platform in one single location. It also streamlines how licenses are applied to both the Enterprise Server as well as the PDF Server. In addition to this, both PDF and Enterprise Servers now manage their licenses and configure their licenses in the same way. For more information, see the License Management section of our help docs.
Group Permission Levels	With the 7.x Server release, you can now configure the Group permissions to be categorized into different levels. For example, you can now configure users to be Admins of a group, or members of a group and then assign permissions separately based on their role within the group. For more information, please see the Group Roles section in our user guide.
User Session Management	The 7.x Server release adds additional levels of security around user session management and ensures that any outstanding JWT token can no longer be utilized once a user has logged out of their current "session". This ensures that each JWT token can only be associated with a "current" session and JWT tokens associated with invalid sessions (through logout) can no longer be used. For more information, see our User Session Management user guide.
Audit Logging	The audit logging system allows you to add additional logging capabilities that logs ever action taken by all users within the Form.io system. See Audit Logging for more information.
Simplified PDF Setup	In addition to the 7.x Enterprise Server, this release also includes the 3.x Enterprise PDF server, which introduces a number of improvements to the management and configuration of how the PDF server is connected to the API Server.
Isomorphic Validation	The new Isomorphic validation utilizes the Form.io core renderer found @ https://github.com/formio/formio.js as the mechanism for validating submissions within the server logic. This ensures that any validation that occurs on the front end form, is the exact same validation that occurs within the server validation system.

Before you begin your migration, it is recommended that you first create complete backups of your existing environment. Once this is completed, you can now spin up a replica environment and point this environment to the SAME database as your current 6.x environment. This should not cause any problems because the 7.x upgrade does not introduce any changes to database schemas as well as does not perform any update hooks (as of version 7.0.0). Before this environment is launched, however, you will need to ensure that you change the following environment variables for this cloned deployment.

Enterprise Server Environment Variable Changes

6.x variable	7.x variable	Action
PRIMARY	PORTAL_ENABLED	Change name. Same value.
LICENSE		Delete this environment variable
	LICENSE_KEY	Set value as new license key
FORMIO_FILES_SERVER	PDF_SERVER	Change name. Same value.

PDF Server Environment Variable Changes

2.x variable	3.x variable	Action
FORMIO_PROJECT		Delete this environment variable
FORMIO_PROJECT_TOKEN		Delete this environment variable
FORMIO_PDF_APIKEY		Delete this environment variable
FORMIO_PDF_PROJECT		Delete this environment variable
	MONGO	Add same value as provided to enterprise server.
	LICENSE_KEY	Set value as the new license key. Same as API Server

For the PDF Server (3.x version), you will also need to ensure that this container has access to the same database as the API Server. In some cases, this may require you to add a --link to the mongo container. Please read the PDF Server Deployment User Guide for detailed instructions on how to accomplish this.

After your two environments are up and running, you can now perform necessary tests against your replica environment. Once it is determined that all features are working to your expectation, you can then flip a DNS switch over to your replica environment, making it become the new production, while at the same time keeping the old 6.x environment running as a fail safe if anything should happen (where you can then DNS switch back to the old environment).

Fixing Deployed (remote) Projects

In some cases, you may have been using the Hosted Portal (found at https://portal.form.io) to connect to your remote environment, which was running 6.x. Once you upgrade your deployments to the version 7.0.0 or greater it must be known that you can not use any portal version less than version 7.1.0. This version can be found at the footer of the hosted portal. If the hosted portal is not yet on that version, then one option is to enable the deployed portal within your environment. This can be accomplished by following the Enable the Developer Portal user guide.

One other thing that should be noted is that, in some cases, the License will erroneously register your "stage" projects within your deployment as "licensed" projects. This occurs because your projects within your deployed environment do not contain the correct "project" property associating them with the correct licensed project. To fix this, you must do the following.

• Determine the Project ID of the "main" project that is licensed. This can be found within the License Manager or by clicking on the main project in your hosted portal and taking note of the Project ID within the Url of the browser.

• Once you have the Project ID, you will need to connect your terminal to your MongoDB instance and perform the following command to set the correct "project" property values on your remote projects.

db.projects.updateMany({}, {$set:{project:ObjectId('LICENSED_PROJECT_ID')}});

Of course, you will replace the LICENSED_PROJECT_ID with the ID of your "main" project. Once you do this, any projects within your new remote environment will register as "stages" within the main project and will not erroneously count against your license.