This article calls out key changes introduced in v39 that affect the upgrade process. It also tells you how to upgrade to v39, based on the version you’re upgrading from, as well as what to expect after upgrading.
What’s changed in v39
License keys — When upgrading to v39, you need to enter a license key issued to you by your Hyperscience representative. Without a license key, the application cannot be used. A System Admin can enter a license key after logging in to the application after the upgrade process is complete. To learn more, see License Keys.
Automatic transmission of Usage Bundles — If your instance is connected to the internet, it will send a Usage Bundle to Hyperscience each day by default. Depending on your organization’s security measures, additional steps may be required to allow these automatic transmissions to occur. If your instance is not connected to the internet, you will need to disable this feature after upgrading to v39. To learn more, see Automatic Transmissions of the Usage Report.
Upgrading from v35 or earlier
1. Upgrade to v35.
If you are using v34 or earlier, upgrade to v35. See Upgrading to v35 for instructions for your current version.
The same set of prerequisites applies to v39, as does the content of the “What to expect after upgrading” section unless otherwise noted in this article.
2. Update flows on v35.
In v35, upgrade any custom flows to use v35 blocks, if you haven’t already. If you’re using “Document Processing” flows from v34 or earlier, migrate to “Document Processing V35.”
3. Retrain all of your models.
4. Update Python packages to 3.9.
If you've installed external Python packages, update them to versions that use Python 3.9.
To learn how to update packages, see Developing Flows.
5. Complete submissions from v34.
Using "Document Processing V35” or a custom flow upgraded to v35, complete any submissions created in v34 or earlier.
Do not use flows or models from v34 or earlier to process these submissions. These flows and models will not work in v35 or later. If you try to process submissions with them, the submissions will halt.
There is no filter in the application to determine which submissions were created in which versions, but you can look for older submissions by using the submission date and the dates in your upgrade history as a guide. For example, each submission created in v34 or earlier has a Submission Date that predates your upgrade to v35.
Make sure submissions from v34 or earlier have a Completed status before upgrading to v37. If they are not completed before you upgrade to v37, they will be halted, and you will need to resubmit or recreate them in order to be processed.
6. Install v36 on your instance.
Copy the v36 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
7. Install v37 on your instance.
Copy the v37 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
8. Update flows on v37.
In v37, upgrade any custom flows to use v37 blocks. If you’re using “Document Processing V35,” migrate to “Document Processing V37.”
9. Retrain all of your models.
10. Complete submissions from v35.
Using “Document Processing V37” or a custom flow upgraded to v37, complete any submissions created in v35 or earlier.
Ensure submissions from v35 or earlier have a Completed status before upgrading to v38. If they are not completed before upgrading to v38, they will be halted, and you will need to resubmit or recreate in order for them to be processed.
11. Install v38 on your instance.
Copy the v38 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
12. Install v39 on your instance.
Copy the v39 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
Copy the v39 bundle onto the remaining application machines in your instance.
Run bash run.sh (in Docker-based deployments) or sudo bash run.sh (in Podman-based deployments) on the remaining application machines in your instance.
Install the v39 trainer.
Upgrading from v36
1. Update flows to v36.
Upgrade any custom flows to use v36 blocks, if you haven’t already. If you’re using “Document Processing” flows from v35 or earlier, migrate to “Document Processing V36.”
Flows from v36 or earlier will not work in v39.
2. Retrain all of your models.
Retrain any models for flows created in v36 or earlier.
3. Complete submissions from v35.
Using “Document Processing V36” or a custom flow upgraded to v36, complete any submissions created in v35 or earlier.
There is no filter in the application to determine which submissions were created in which versions, but you can look for older submissions by using the submission date and the dates in your upgrade history as a guide. For example, each submission created in v35 or earlier has a Submission Date that predates your upgrade to v36.
Ensure submissions from v35 or earlier have a Completed status before upgrading to v38. If they are not completed when you upgrade to v38, they will be halted, and you will need to resubmit or recreate them in order for them to be processed.
4. Install v37 on your instance.
Copy the v37 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
5. Install v38 on your instance.
Copy the v38 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
6. Update flows on v38.
In v38, upgrade any custom flows to use v38 blocks. If you’re using “Document Processing V36,” migrate to “Document Processing V38.”
7. Retrain all of your models.
8. Complete submissions from v36.
Using “Document Processing V38” or a custom flow upgraded to v38, complete any submissions created in v36 or earlier.
Ensure submissions from v36 or earlier have a Completed status before upgrading to v39. If they are not completed before you upgrade to v39, they will be halted, and you will need to resubmit or recreate in order for them to be processed.
9. Install v39 on your instance.
Copy the v39 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
Copy the v39 bundle onto the remaining application machines in your instance.
Run bash run.sh (in Docker-based deployments) or sudo bash run.sh (in Podman-based deployments) on the remaining application machines in your instance.
Install the v39 trainer.
Upgrading from v37
1. Update flows to v37.
Upgrade any custom flows to use v37 blocks, if you haven’t already. If you’re using “Document Processing” flows from v36 or earlier, migrate to “Document Processing V37.”
Flows from v36 or earlier will not work in v39.
2. Retrain all of your models.
Retrain any models for flows created in v36 or earlier.
3. Complete submissions from v36.
Using “Document Processing V37” or a custom flow upgraded to v37, complete any submissions created in v36 or earlier.
There is no filter in the application to determine which submissions were created in which versions, but you can look for older submissions by using the submission date and the dates in your upgrade history as a guide. For example, each submission created in v36 or earlier has a Submission Date that predates your upgrade to v37.
Ensure submissions from v36 or earlier have a Completed status before upgrading to v39. If they are not completed before you upgrade to v39, they will be halted, and you will need to resubmit or recreate them in order for them to be processed.
4. Install v38 on your instance.
Copy the v38 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
5. Install v39 on your instance.
Copy the v39 bundle onto one of your application machines.
Run bash run.sh init (in Docker-based deployments) or sudo bash run.sh init (in Podman-based deployments).
Copy the v39 bundle onto the remaining application machines in your instance.
Run bash run.sh (in Docker-based deployments) or sudo bash run.sh (in Podman-based deployments) on the remaining application machines in your instance.
Install the v39 trainer.
Upgrading from v38
Complete the upgrade process by deploying v39 on all machines running the application. You also need to install a v39 trainer after upgrading the application.
What to expect after upgrading
After upgrading to v39, you may notice some changes in your Flow Library. There may also be some temporary slowness in processing Structured documents, as described in the Machine Classification section below.
Machine Classification
After upgrading, your first submissions with Structured documents might take up to a few hours to complete. The Machine Classification Block uses pre-computed data to classify Structured documents. After upgrading, this precomputed data is invalidated. The system regenerates this data the first time a submission goes through Machine Classification after upgrading.
If processing submissions with Structured documents takes longer than expected, you should check the logs from the Activity Log section of the Submission Output page. Verify that the Machine Classification task is the one that takes more time than expected.
Flows
When upgrading from a previous version of Hyperscience, the system will automatically move your existing flows to v39 and add new flows included in v39. No changes will be made to your pre-v39 flows as part of this process. Submissions will continue to be processed through your default flow (likely "Document Processing V37" or “Document Processing V38”). This flow will be active and deployed in v39.
Any models, flows, and Custom Code Blocks created in v37 or v38 will continue to work in v39. However, flows created in v30-36, including the pre-built "Document Processing" and "Notifications" flows, will not work in v39, and we do not support the use of these flows. While you can use models created in v37 or v38 in v39, you will not be able to retrain them in v39. If you need to retrain them, you will need to train new v39 models instead.
When migrating your processing to v39’s “Document Processing” flow, we recommend testing the migration in a lower environment (e.g., development, UTA) first. After this testing, you can replicate the migration in your production environment.
To migrate your processing to v39’s “Document Processing” flow:
Go to your lower environment.
Duplicate the newly-created “Document Processing” flow.
a. On the Flows page, find the “Document Processing” flow, and click on the flow's menu (
).b. 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.
Re-train any Identification, Classification, and Transcription models associated with the previous version's flows by clicking the Run training button on the model details page for each model. Doing so ensures that those models are trained on the latest version of the application and are compatible with the new version's flows.
Assign a release to the duplicated “Document Processing” flow by following the steps in Assigning a Release to a Flow.
Deploy the duplicated “Document Processing” flow by following the steps in Managing Flows.
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.
Disable the old “Document Processing” flow by following the steps in Managing Flows.
Repeat steps 2-7 in your production environment, or export the newly created flows and models from your lower environment and import them to your higher environment.
If you are using the “Document Processing Notifications” flow, set up “Submission State Notifications V39” to meet your needs.
System-generated flows
When you upgrade to v39, new document-processing and state-notification flows appear alongside the flows that were in your previous version of Hyperscience. A new on-error flow is also included.
Document Processing
The system-generated flows that appear in your v39 instance depend on which versions you’ve previously used or upgraded to.
Upon upgrading to v39, a new "Document Processing" top-level flow will be added and will be disabled. This flow comes with three new subflows. One of these subflows is named “Document Processing Subflow V39”, which is an updated version of the "Document Processing" flows included in previous versions of Hyperscience and contains features introduced in v39. You can work with your Hyperscience representative to determine if this updated subflow would be beneficial for your business.
If you used v38’s “Document Processing” top-level flow with “Document Processing Subflow V38” in v38, you can replace the subflow with “Document Processing Subflow V39.” If you do so, the input and output connections you configured in v38 can be used as-is.
To replace “Document Processing Subflow V38” with “Document Processing Subflow V39” in v38’s “Document Processing top-level flow:
On the Top-level Flows page (Flows > Top-level Flows), find the Document Processing flow, and click its Open → link.
In the table under the flow diagram, click Document Processing.
On the canvas, click the Start Document Processing Subflow Block.
In the Flow Identifier drop-down list, click Document Processing Subflow V39.
You can complete this step regardless of which option is selected in the Settings Type drop-down list.
Click Save in the upper-right corner of the page.
If you decide to upgrade your “Document Processing” flow to v39, but you did not use the Document Processing flow introduced in v38, you will need to configure the Input Blocks and Output Blocks in the top-level “Document Processing” flow. You must also copy your settings from the “Document Processing” flow from your previous version of the Hyperscience application to “Document Processing Subflow V39.”
Document Processing Notifications
The system will also move your "Document Processing Notifications" and “Submission State Notifications” flows to v39, which contain Notification Blocks that execute mid-flow. Each of these flows remains unchanged during the upgrade. In addition, a new “Submission State Notifications V39” flow is created during the upgrade process. Contact your Hyperscience representative if you need assistance enabling or disabling connections in these flows after upgrading to v39.
In the “Document Processing” top-level flow, you can select a “Submission State Notifications” subflow for each block in the “Document Processing Subflow.” To use “Submission State Notifications V39”:
On the Top-level Flows page (Flows > Top-level Flows), find the Document Processing flow, and click its Open → link.
In the table under the flow diagram, click Document Processing.
On the canvas, click the Start Document Processing Subflow Block.
In the Settings Type drop-down list, click on the name of the type of setting you would like to edit.
The settings of the type you selected are shown. They consist of the flow- and block-level settings found in pre-v39 versions of the “Document Processing” flow. For block-specific settings:
Click Submission Bootstrap to see settings for the Submission Initialization Block.
Click Classification to see settings for the Manual Classification Block.
Click Identification to see settings for the Manual Identification Block.
Click Transcription to see settings for the Manual Transcription Block.
Click Flexible Extraction to see settings for the Flexible Extraction Block.
In the [Block Name] Notification Flow drop-down list, click Submission State Notifications V39.
Repeat steps 4 and 5 as needed to link “Submission State Notifications V39” to other blocks.
Click Save in the upper-right corner of the page.
On Error Flow
An on-error flow sends notifications when a flow exhausts all of its retry attempts, making your organization aware of halted submissions and allowing for timely troubleshooting. An “On-Error with included Submission data V39” flow is included in v39. For more information about on-error flows and how to assign them to top-level flows and subflows, see On-Error Flows.