(Mostly application upgrades needed, but prevents any new submissions from being processed during the upgrade)
This article explains how to upgrade to v41 when you need to complete all outstanding Supervision tasks (i.e., move all submissions to the Completed status) and temporarily stop the flow of new submissions to your production environment during the upgrade procedures.
In this case, the upgrade process is faster and has fewer steps than “Upgrading to v41 (with submissions being created during the upgrade process,” as you don't need to update flows or retrain models for every two major versions (in accordance with the “N-2 compatibility” rule).
However, if you cannot stop new submissions from coming into your production environment, don’t have the capacity to finish all Supervision tasks, or don't have a separate development environment, some submissions may halt during the upgrade. In that case, we recommend following the process described in Upgrading to v41 (with submissions being created during the upgrade process).
What’s changed in v41
Docker 25.0.3 and earlier not supported — Hyperscience v41 supports Docker 25.0.4 and later. It will not run on earlier versions of Docker. To learn more about supported container environments, see Infrastructure Requirements.
Ubuntu 19 and earlier and RHEL 8.9 and earlier not supported — Beginning in v41, we no longer support the use of Ubuntu 19 or earlier or RHEL 8.9 or earlier with Hyperscience. If you are using either of these operating systems, you will need to upgrade to a supported version of Ubuntu or RHEL. For a list of supported operating systems, see Infrastructure Requirements.
Supported versions of PostgreSQL and Microsoft SQL Sever (MSSQL)
We’ve added support for PostgreSQL 15 and 16 in v41. The use of PostgreSQL 13 is no longer supported.
Hyperscience v41 supports MSSQL 2022, but MSSQL 2016 is no longer supported.
For a list of supported database versions, see Infrastructure Requirements.
Support for Python 3.12 — Hyperscience v41 supports Python 3.9, 3.11, and 3.12. Because Python 3.9 will reach end-of-life in October 2025, we recommend updating your flows and code blocks to use Python 3.12. To learn more, see Developing Flows.
For a complete list of updates included in v41, see the V41 Release Notes.
Upgrade process
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.
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 v40, you must install v36, v37, v38, v39, v40, and then v41.
As described above, this upgrade scenario does not allow the creation of any new submissions while all of the above versions are installed, which needs to be taken into consideration before starting. Any submissions still in flight for past versions will need to be moved to the Completed status.
2. Update flows on v41.
In v41, upgrade your flows to use v41 blocks. To do so in the “Document Processing” flow, go to the flow settings for the "Document Processing" top-level flow, and click on Document Processing Subflow V41 in the Flow Identifier drop-down list under "Block Details."
For more information, see the System-generated flows section below.
3. Retrain all of your models.
This retraining includes Transcription, Classification, and Identification models.
4. Update Python packages to 3.12.
If you've installed external Python packages, update them to versions that use Python 3.12. While your packages can also use Python 3.9 or 3.11 in v41, we recommend updating them to use Python 3.12, the latest Python version supported in Hyperscience.
To learn how to update packages, see Developing Flows.
What to expect after upgrading
After upgrading to v41, 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 v41 and add new flows included in v41. No changes will be made to your pre-v41 flows as part of this process. Submissions will continue to be processed through your default flow (likely "Document Processing V37," or “Document Processing” for v38 and later).
Any models, flows, and Code Blocks created in v39 or v40 will continue to work in v41. You can retrain models created in v39 or v40 in v41 without upgrading their flows, as long as those flows were created in v39, v40, or v41. To learn more, see Compatibility Across Application, Flow, and Model Versions. However, flows created in v30-38, including the pre-built "Document Processing" and "Notifications" flows, will not work in v41, and we do not support the use of these flows.
When migrating your processing to v41’s “Document Processing” flow, we recommend testing the migration in a lower environment (e.g., development, UAT) first. After this testing, you can replicate the migration in your production environment.
To migrate your processing to v41’s “Document Processing” flow:
Go to your lower environment.
Duplicate the newly-created “Document Processing” 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 a “Document Processing Notifications” flow or a “Submission State Notification” flow from a previous version, set up v41’s “Submission State Notifications” flow to meet your needs.
System-generated flows
When you upgrade to v41, a new document-processing flow appears alongside the flows that were in your previous version of Hyperscience. New state-notification flow and on-error flows are also included, but, unlike these flows from v39 and earlier, they are not versioned in v41.
Document Processing
The system-generated flows that appear in your v41 instance depend on which versions you’ve previously used or upgraded to.
Upon upgrading to v41, 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 V41”, which is an updated version of the "Document Processing" flows included in previous versions of Hyperscience and contains features introduced in v41. You can work with your Hyperscience representative to determine if this updated subflow would be beneficial for your business.
If you used the “Document Processing” top-level flow from v38, v39, or v40 with “Document Processing Subflow V38,” “Document Processing Subflow V39,” or “Document Processing Subflow V40,” you can replace the subflow with “Document Processing Subflow V41.” If you do so, the input and output connections you configured in v38, v39, or v40 can be used as-is.
To replace “Document Processing Subflow V38,” “Document Processing Subflow V39,” or “Document Processing Subflow V40” with “Document Processing Subflow V41” in the “Document Processing” top-level flow from v38, v39, or v40:
On the Flows page (Flows > Flows), find the “Document Processing” top-level flow, and click on its name.
Click Edit Flows.
On the canvas, click Start Document Processing Subflow.
In the Flow Identifier drop-down list in the right-hand panel, click Document Processing Subflow V41.
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 use the latest flow blows and features, but you did not use the top-level “Document Processing” flow in v38, v39, or v40, you will need to configure the Input Blocks and Output Blocks in that 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 V41.”
Document Processing Notifications
The system will also move your "Document Processing Notifications" and “Submission State Notifications” flows to v41, which contain Notification Blocks that execute mid-flow. Each of these flows remains unchanged during the upgrade. In addition, a new “Submission State Notifications” 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 v41.
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 v41’s “Submission State Notifications” flow:
On the Flows page (Flows > Flows), find the “Document Processing“ flow, and click on its name.
Click Edit Flows.
On the canvas, click Start Document Processing Subflow.
In the Settings Type drop-down list in the right-hand panel, 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-v38 versions of the “Document Processing” flow, along with new settings introduced in later versions.
In the [Block Name] Notification Flow drop-down list, click Submission State Notifications.
Repeat steps 4 and 5 as needed to link “Submission State Notifications” 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” flow is included in v41. For more information about on-error flows and how to assign them to top-level flows and subflows, see On-Error Flows.