The Upgrade Process

This article gives an overview of the upgrade process to help you scope the efforts and resources needed to upgrade your Hyperscience instance. It also describes the specific steps required to upgrade your lower and production environments.

Prerequisites

As a reminder, the steps outlined here assume that:

you’ll be upgrading sequentially and not skipping any versions between your current version and target version. This approach ensures that you keep all of your artifacts (i.e., flows, models, and training data) up to date, preventing the need to recreate flows and retrain models in the new version.
you have two Hyperscience environments: a lower one (e.g., development, staging, UAT) and a higher one (production).

While we recommend completing your production upgrade by performing certain steps in a lower environment, you can upgrade your production environment without the use of a lower environment. When doing so, follow the process described in this article, but skip the steps that involve importing and exporting flows, models, or releases.

Note the following important caveats and recommendations:

The instructions assume the artifacts (flows, models) are built on the same version as the application to simplify explaining X+2 compatibility. You can upgrade with your artifacts on older versions, but you’ll need to be mindful of when to upgrade those artifacts as you progress through each application upgrade.
In the beginning of any upgrade process, we recommend you align your lower and production environments to be on the same application version. This alignment reduces the event of encountering an unforeseen issue in your production environment, and it allows for easier interoperability of artifacts between environments.

Once you have:

both of your environments on the same application version, and
all of your flows are up to date with that version in your lower environment (e.g., you are using v40 flows on a v40 instance),

you can proceed to the steps described below.

Upgrade your lower environment

As a best practice, we recommend upgrading a lower environment before upgrading your production environment. Doing so allows you to ensure the compatibility of your models and flows with your target or intermediate version and complete any necessary model training, all with no impact to your production environment.

1. Upgrade your lower environment to your target or intermediate version, following the X+2 compatibility rule.

For instructions, see Upgrading the application.

2. Duplicate the live “Document Processing” flow included in the target or intermediate version.

Duplicating your application version’s “Document Processing” flow guarantees that you will always have a clean flow to return to in case you need it.

For application versions 38 and earlier

On the Flows page in your lower environment, find the latest “Document Processing” flow (which is the flow from the latest available application version), and click on the flow's menu ( ).
Click Duplicate Flow.
Configure the duplicated flow with the settings and notifications of the “Document Processing” flow you are using to process submissions in your production environment.

For application versions 39 and later
You can take advantage of the subflows drop-down list in the flow’s settings, which eliminates the need to configure new blank flows from scratch:

On the Flows page in your lower environment, find the flow that you are currently using to process submissions.
Click on the flow's menu ( ) , then click Duplicate Flow.
In the newly duplicated flow, make sure that the selection in the Flow Identifier drop-down list in the Block Details section of the flow settings is set to the latest available flow version:

Doing so ensures that any configuration options that you’ve set up previously are carried over to the new flow version, and you won’t have to complete the configuration options described in the above scenario.

3. Assign a release to the newly created flows.

Assign a release to the “Document Processing” flow that you have created in step 2 by following the steps in Assigning a Release to a Flow.

4. Train new models on the new application version.

Before beginning any training activities, make sure that your latest training data and releases are available on your lower instance. If needed, export any training data or releases from production into your lower environment, as described in Importing and Exporting Training Data, Exporting a Release, and Adding a New Release.

Train a new model for each Identification, Classification, or Transcription model that is in use in the previous flow by clicking the Run training button on the model details page for each model. Doing so ensures that those models are trained on the target version of the application and are compatible with the new version's flows. To learn more about model management and training, see the following articles:

5. Deploy the duplicated flow.

Deploy the duplicated “Document Processing” flow.

6. Perform an end-to-end test of the duplicated flow.

To test the duplicated “Document Processing” flow, process a few submissions through this flow using a variety of expected documents. Below are recommendations:

Assess if performance is within expectations when compared to prior models.
Test the upstream integration that creates the submissions.
Test the downstream integrations that consume the processed data.
If you use an integration to upload submissions, change your integration’s target flow UUID to the UUID of the duplicated “Document Processing” flow. You can copy the UUID of your duplicated “Document Processing” flow by clicking the Copy link at the bottom of the Flow Settings sidebar on the left-hand side of the Flow Studio.

7. Disable any “Document Processing” flows from previous application versions.

Once you ensure that your newly created “Document flows” are working correctly, disable any flows from previous versions.

8. Export the target or intermediate version’s flows and models.

You will need to import them to your production environment.

Upgrade your production environment

1. Finish processing submissions and complete QA tasks if necessary.

If your next application upgrade is beyond the X+2 compatibility for your components, drain your submissions and QA tasks in Hyperscience to prevent submissions from halting in your new version. You should also stop new submission creation in this environment.

2. Upgrade your production environment to your target or intermediate version.

You can now begin upgrading your production environment to the desired target or intermediate version. The environment should be upgraded sequentially with each version between your current and target or intermediate version (v40 to v41 to v42, for example). Proceed until the version in this environment mirrors your lower environment.

For instructions, see Upgrading the application.

3. Import the updated flows and models from your lower environment to your production environment, if necessary.

If the upgraded application is beyond the X+2 compatibility of your existing components, you need to update them to be compatible with the new application version. Export the newly created flows and models from your lower environment and import them to your production environment.

4. Perform an end-to-end test of the flow.

Similar to testing your lower environment, process a few submissions through the flow using a variety of expected documents. Below are recommendations:

Assess if performance is within expectations when compared to prior models.
Test the upstream integration that creates the submissions.
Test the downstream integrations that consume the processed data.
Verify all dependencies are available in this environment, including releases and flow dependencies.
If you use an integration to upload submissions, change your integration’s target flow UUID to the UUID of the duplicated “Document Processing” flow. You can copy the UUID of your duplicated “Document Processing” flow by clicking the Copy link at the bottom of the Flow Settings sidebar on the left-hand side of the Flow Studio.

5. Redirect incoming submissions to the flow.

If you updated your flow, disable the flow you were using in your previous version. Doing so prevents new submissions from being created in the older flow without impacting any of its current submissions that are still in progress. Those submissions will continue processing until their completion. After they’re complete, you can archive the flow.

6. If you stopped the upgrade at an intermediate version, repeat the steps in “Upgrade your lower environment” and steps 1-5 above until you reach your target version.

Stopping the upgrade procedure at an intermediate version may be beneficial in cases where you need to resume processing. We recommend finishing the upgrade to your target version during your next available maintenance period.

Upgrading the application

1. Ensure your application version is v35 or later.

If you are using v34 or earlier, upgrade to v35. See Upgrading to v35 for instructions for your current version.

2. Upgrade sequentially until you reach your target or intermediate version.

After your upgrade to v35, you must install each subsequent major application version one by one. In this case, if you're on v35 upgrading to v42, you must install v36, v37, v38, v39, v40, v41, and then v42. To do so:

Download the new version bundle and expand it in a dedicated folder.
Copy the “.env” file from the current version directory to the new one.
Run run.sh init on one of your application machines.
- You do not need to start the application for intermediate versions (e.g., if you’re upgrading from v39 to v42, you do not need to start the v40 or v41 application).
Delete the expanded bundle and move to the next version.

For more information, see Technical Installation / Upgrade Instructions.