This article gives an overview of the overall upgrade process to help you scope the efforts and resources needed to upgrade your Hyperscience instance.
The steps below 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.
Prerequisites
The steps outlined below assume that you have two Hyperscience environments: a lower one (e.g., development, staging, UAT) and a higher (production) one.
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:
Since the upgrade instructions start with upgrading your lower environment first, make sure that all flows in that environment are from the same application version (e.g., development environment on v37 with flows from v37). If that is not the case, and you are still using flows from previous versions in the lower environment, please make sure to update them to be from the same version as the application.
It is recommended that, in the beginning of any upgrade process, you align your lower and production environments to be on the same application version in order to ensure upgrade continuity and flow compatibility between both 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 v37 flows on a v37 instance),
you can proceed to the steps described below.
1. Start upgrading your lower environment to your target version, following the N-2 compatibility rule.
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 version and complete any necessary model training, all with no impact to your production environment.
In general, each version of Hyperscience supports flows and models created in that version, the version directly preceding it, and the version directly preceding that version. For example, v39 supports flows and models created in v39, v38, and v37.
This principle is also known as the N-2 compatibility rule.
Because of this rule, we recommend completing the upgrade in sequential steps, always following the N-2 compatibility.
N-2 compatibility means that, for multi-version upgrades, you will need to make sure to update your flows for each two new application versions, as described in the steps below.
The exception to this rule is the upgrade from v34 to a later version — you cannot skip v35 when upgrading your application, flows, or models.
To upgrade your lower environment, follow the instructions given for your target version on the Upgrade Process page.
As you upgrade your lower environment, be sure to keep your production environment within two versions of your lower environment. Submissions also follow the N-2 compatibility rule, meaning that they must be completed in the version they were created in, the version directly following it, or the version directly following that version. For example, submissions created in v37 can only be completed in v37, v38, or v39. By keeping your lower and production environments within two versions of each other, you will be able to import flows, models, and releases from your lower environment to production—and complete submissions with those artifacts—as you progress toward your target version.
2. Duplicate the live “Document Processing” flow included in the target 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.
To learn more, see Flow Settings.
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. 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:
There are some application versions that offer prolonged support for the same internal model version. For example, in order to save time and effort, for application versions between 37 and 39, you don’t need to train new Identification models, since the internal model version provides extended support. That is, an Identification model trained with a v37 trainer is compatible with v37, v38, and v39 flows).
4. 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.
5. Deploy the duplicated flow.
Deploy the duplicated “Document Processing” flow by following the steps in Managing Flows.
6. Test the duplicated flow.
To test the duplicated “Document Processing” flow, manually upload and process a few submissions through this flow.
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 by following the steps in Managing Flows.
8. Upgrade your production environment to your target version.
You can now begin upgrading your production environment to the desired target version.
9. Import the target version’s flows and models to your production environment.
After that upgrade is complete, you need to export the newly created flows and models from your lower environment and import them to your production environment.
10. Redirect incoming submissions to the imported flow.
Disable the flow you were using in your previous version. Doing so prevents new submissions from being created in that flow, but it has no impact on the flow’s current submissions that are still in progress. Those submissions will continue processing until their completion. After they’re complete, you can archive the flow.
By processing new submissions with your new flow, you ensure that no disruptions occur in your production environment while you complete the upgrade process.
11. Finish processing submissions created in previous versions.
Use your previous version’s flow to drain submissions created in previous versions of Hyperscience. Draining submissions with each upgrade prevents submissions from halting in your new version, as the N-2 compatibility rule applies to submissions as well as flows and models.