Upgrading to v34

This article explains the v34 upgrade process and lets you know what you can expect after upgrading.

Preparing to upgrade

• Review what’s new — Before upgrading to v34, we recommend reading the release notes for v34 and any versions between your current version and v34. These release notes describe the changes and new features we’ve introduced in each version of the application. For links to these release notes, see the Release Notes section of our site.

• Review our upgrade documentation — For an overview of the upgrade process, review our upgrade documentation:

  • Upgrade Best Practices

  • Upgrade Considerations and Known Issues, particularly the version-specific considerations

  • Upgrade Process Overview

• Make sure your infrastructure meets the requirements for v34 — Over the past few versions, we’ve made the following changes to our infrastructure requirements:

  • Databases:

    • Deprecated support for PostgreSQL 9.5 — Beginning with v30, we’re no longer supporting the use of PostgreSQL 9.5 databases.

    • Deprecated support for Oracle 12.x — Beginning with v34, we’re no longer supporting the use of Oracle 12.x databases.

  • Trainer VM CPU cores: Beginning with v31, we strongly recommend having 16 cores for each CPU in a trainer VM if you are processing Semi-structured documents. If you have only 8 cores for these CPUs, you can expect 60-70% longer training times and an increased risk of crashes during training, particularly on datasets with longer, denser documents.

  • Trainer RAM: Beginning with v31, we strongly recommend that your trainer have 64GB of RAM, which will maximize the performance of the 16-core CPUs described above.

  • Beyond these requirements, your Hyperscience representative can recommend specific infrastructure improvements, based on your anticipated use of Hyperscience v34.

• Increased upgrade times – In v33, we introduced various performance improvements that required the creation of more database indexes and migrating data stored in the application’s database. These changes also impact versions following v33.

  
  On-premise customers may see an increase in the time it takes to upgrade their application services to v34 and should plan up to an extra day in their upgrade window. The impact of these changes is greater for customers with larger databases. 

  
  Our v34 database migrations are executed after running ./run.sh init for the first time within the new bundle, and migrations must be completed before the Hyperscience application can be used. To reduce the size of your database and the time required to upgrade, you can configure a shorter Submission Record Deletion period in Settings.

The upgrade process

The steps involved in upgrading to v34 depend on what version of Hyperscience you're currently using. 

Upgrading from v28 

If you are upgrading from v28, you cannot upgrade directly to v34, as you cannot train a v34 trainer on the v28 application. 

You also need to drain your instance of submissions created in v28 or earlier before upgrading to v32 on your way to upgrading to v34. See Draining submissions for more information.

Follow these steps to upgrade to v34:

1. Train a v31 trainer on your v28 application.
   

2. When all the training tasks have finished, upgrade your application to v31 on all machines running the application. You do not need to upgrade to v30 before upgrading to v31.

   • To learn more about upgrading to v31, see Upgrading from v28 to v31. The key infrastructure and feature considerations explained in the article also apply to v34. Following the outlined steps will establish a foundation for a successful overall upgrade process from v28 to v34.

   • At this point, you should drain your instance of submissions created in v28 or earlier, if you haven’t already.

3. Train a v33 trainer on your v31 application.
   

4. When all the training tasks have finished, upgrade your application to v32 on at least one machine running the application.
   

5. As soon as possible, upgrade your application to v33 on all machines running the application. In order to avoid a possible reduction in model performance, we recommend minimizing the amount of time your instance runs v32.
   

6. Train a v34 trainer on your v33 application.
   

7. When all the training tasks have finished, deploy the v34 application on all machines running the application.

For best results, we recommend upgrading to the latest versions of v30, v31, v32, and v33 before upgrading to v34. 

• When upgrading to v30, your v30 version needs to be v30.0.13 or later.

• When upgrading to v32, your v32 version needs to be v32.0.8 or later.

If you are not using the latest versions of each version in your upgrade path, make sure the versions you upgrade to are compatible with each other:

Draining submissions

Before upgrading, all submissions created in three versions before your target version must be completed. The table below outlines the compatibility between submissions and versions of Hyperscience.

For example, before upgrading to v34, any submissions created in v31 need to be completed in v31, v32, or v33.

There is no filter in the application to determine which submissions were created in which versions, but you can look for older submissions in one of the following ways: 

• Use the submission date and the dates in your upgrade history as a guide — For example, submissions created in v28 or earlier have a Submission Date that predates your upgrade to v30 or v31. 

• Check Administration > Jobs — You can use the Legacy Jobs view of the Jobs table to find submissions created in older versions of Hyperscience. For example, before upgrading to v32, look for jobs with Created dates that predate your upgrade to v30 or v31 and contain submission tasks. These submissions were created in v28 or earlier and need to be completed before upgrading to v32.

Ensure submissions from incompatible versions have a Completed status before upgrading. If they are not completed when you upgrade to your target version, they will likely be halted, and you will need to resubmit or recreate them in order for them to be processed. 

Upgrading from v30

When upgrading from v30, you need to upgrade to v31, v32, and v33 before upgrading to v34. 

Before upgrading to v34, follow the steps in Draining submissions to make sure that all submissions in your system that were created in v28 or v30 are completed before upgrading to v32 or v33, respectively. 

1. Train a v32 trainer on your v30 application.
   

2. When all the training tasks have finished, upgrade your application to v31 on at least one machine running the application.
   

3. As soon as possible, upgrade your application to v32 on all machines running the application. In order to avoid a possible reduction in model performance, we recommend minimizing the amount of time your instance runs v31.
   

4. Train a v34 trainer on your v32 application.
   

5. When all the training tasks have finished, upgrade your application to v33 on at least one machine running the application.
   

6. As soon as possible, upgrade your application to v34 on all machines running the application. In order to avoid a possible reduction in model performance, we recommend minimizing the amount of time your instance runs v33.

For best results, we recommend upgrading to the latest versions of v31, v32, and v33 before upgrading to v34. 

• When upgrading to v32, your v32 version needs to be v32.0.8 or later.

If you are not using the latest versions of each version in your upgrade path, make sure the versions you upgrade to are compatible with each other:

Upgrading from v31

When upgrading from v31, you need to upgrade to v32 and v33 before upgrading to v34.

Before upgrading to v34, follow the steps in Draining submissions to make sure that all submissions in your system that were created in v28, v30, or v31 are completed before upgrading to v32, v33, or v34, respectively. 

Follow these steps to upgrade from v31 to v34:

1. Train a v33 trainer on your v31 application.
   

2. When all the training tasks have finished, upgrade your application to v32 on at least one machine running the application.
   

3. As soon as possible, upgrade your application to v33 on all machines running the application. In order to avoid a possible reduction in model performance, we recommend minimizing the amount of time your instance runs v32.
   

4. Train a v34 trainer on your v33 application.
   

5. When all the training tasks have finished, deploy the v34 application on all machines running the application.

For best results, we recommend upgrading to the latest version of v32 and v33 before upgrading to v34. If you are not using the latest versions of each version in your upgrade path, make sure the versions you upgrade to are compatible with each other:

Upgrading from v32

Before upgrading to v34, follow the steps in Draining submissions to make sure that all submissions in your system that were created in v30 or v31 are completed before upgrading to v33 or v34, respectively. 

Follow these steps to upgrade from v32 to v34:

1. Train a v34 trainer on your v32 application.
   

2. When all the training tasks have finished, upgrade your application to v33 on at least one machine running the application.
   

3. As soon as possible, upgrade your application to v34 on all machines running the application. In order to avoid a possible reduction in model performance, we recommend minimizing the amount of time your instance runs v33.

For best results, we recommend upgrading to the latest version of v33 during the upgrade process.

Upgrading from v33

Before upgrading to v34, follow the steps in Draining submissions to make sure that all submissions in your system that were created in v31 are completed. 

To upgrade from v33 to v34, you can follow our standard process for direct upgrades, which we've outlined in Upgrade Process Overview.

What to expect after upgrading

After upgrading to v34, you may notice some changes in your Flow Library and slowness in processing Structured documents. You may also need to complete some additional steps to restore full functionality to your instance, as described in the sections 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 precomputed 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 v30,  v31, v32, or v33, the system will automatically move your flows to v34 and add new ones for v34. No changes will be made to your pre-v34 flows as part of this process. Submissions will continue to be processed through your default flow (likely "Document Processing," "Document Processing (V31)," “Document Processing (V32),” or “Document Processing (V33)”by default). This flow will be active and deployed in v33.

Any flows and Custom Code Blocks created in v32 or v33 will continue to work in v34. However, we cannot guarantee that flows created in v30 or v31, including the “Document Processing” and “Document Processing Notifications” flows, will work in v34, and we do not officially support the use of these flows. 

When migrating your processing to “Document Processing (V34),” 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 “Document Processing (V34)”:

1. Go to your lower environment.
   

2. Duplicate the newly-created “Document Processing” flow.
   

3. Configure the duplicated flow with the configuration settings and notifications of the “Document Processing” flow you are using to process submissions in your production environment.
   

4. 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.
   

5. Assign a release to the duplicated “Document Processing” flow.
   

6. Deploy the duplicated “Document Processing” flow.
   

7. To test the duplicated “Document Processing” flow, manually upload and process a few submissions through this flow.
   

8. 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.
   

9. Disable the old “Document Processing” flow.
   

10. 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, work with Hyperscience to set up “Submission State Notifications for Document Processing (V34)” to meet your needs.

If you are actively using custom flows created in v30 or v31, work with your Hyperscience representative to recreate these flows in v34. 

System-generated flows

The system-generated flows that appear in your v34 instance depend on which version you're upgrading from.

Document Processing (V34)

A new, uncustomized "Document Processing (V34)" flow will be added and will be disabled. This flow is a modified version of the default "Document Processing" and “Document Processing (V3x)” flows and contains features introduced in v34. You can work with your Hyperscience representative to determine if this updated flow would be beneficial for your business. 

If you decide to use the new flow, you will need to add Input Blocks and Output Blocks to it, as they are not included by default.  

Document Processing Notifications

The system will also move your "Document Processing Notifications" flows to v34, which contain Notification Blocks that execute mid-flow. Each of these flows remain unchanged during the upgrade. In addition, a new “Submission State Notifications for Document Processing (V34)” flow is created during the upgrade process. This flow is similar to the “Document Processing Notifications” flows from previous versions, but with a new name. Contact your Hyperscience representative if you need to enable or disable connections in these flows after upgrading to v34.

Importing flows

Starting in v33, flows are exported as ZIP files. These ZIP files contain the flow’s JSON file and the Python files for any Custom Code Blocks in the flow. 

In the unlikely event that you need to import a v33 or v34 flow to an instance using a previous version of Hyperscience, you need to manually upload your flow’s Python files after importing your flow.

Submission Initialization Block

In v32 and v33, we added settings that allow you to configure your submission retrieval store in the Flow Studio.

S3 Submission Retrieval Store 

If:

• you are using an S3 bucket as your submission retrieval store,

• you are not authenticating through IAM roles, and

• you are planning to use the "Document Processing (V32)," “Document Processing (V33),” or “Document Processing (V34)”  flow after upgrading, 

you can use the S3 Submission Retrieval Store field of the Submission Initialization Block to enter the values for AWS access key ID and secret access key. You do not need to edit your “.env” file.

If you are not using an S3 bucket for your submission retrieval store, or if you are authenticating to S3 through IAM roles, this field should contain an empty object (i.e., {}).

S3 Submission Retrieval Endpoint URL

If:

• you use a submission retrieval store that is not in the public cloud (i.e., its URL does not point to s3.amazonaws.com — for example, a government cloud or an S3-compatible internal setup), and 

• you are planning to use the "Document Processing (V32)," “Document Processing (V33),” or “Document Processing (V34)”  flow, 

make sure you can see your S3 submission retrieval endpoint URL in the Submission Initialization Block. It should appear in the S3 Submission Retrieval Endpoint URL field.

If this value is missing or incorrect, you can edit it directly in the Submission Initialization Block. You do not need to edit your “.env” file.

If the bucket you’re using as your submission retrieval store is in a public cloud (as opposed to a government cloud or an S3-compatible internal setup), this field should be blank. 

OCS Configuration

If:

• you use an OCS instance as your submission retrieval store, and

• you are planning to use the “Document Processing (V33)” or “Document Processing (V34)” flow, 

you can use the OCS Configuration field of the Submission Initialization Block to enter the host URL, username, password, and SSL certification information for your OCS instance. You do not need to edit your “.env” file.

Generic Web Storage (HTTP/HTTPS) Configuration

If:

• you use a generic web storage solution as your submission retrieval store, and

• you are planning to use the “Document Processing (V33)” or “Document Processing (V34)” flow, 

you can use the Generic Web Storage Configuration field of the Submission Initialization Block to enter the username, password, and SSL certification information for your storage service. You do not need to edit your “.env” file.

Additional considerations when upgrading from v28, v30, or v31

If you’re not currently using v32, you should be aware of the following changes that we made in v32, as they can affect your use of v34.

Flow-specific transcription models

If you are processing Structured documents, you have the option of training flow-specific transcription, or finetuning, models in v32. By default, flows created in previous versions use the system-level transcription model.

If you do not run recalibration on a v32 trainer on a v31 application during the upgrade process, you may experience delays in processing submissions. Recalibration runs on any flows that are live when the upgrade occurs. We recommend completing this recalibration as a best practice for upgrades, even if you are not planning to use flow-specific transcription models.

Message Queue Listener connections

Starting in v32, the Hyperscience application includes an updated version of the Message Queue Listener connector. This version fixes several performance and reliability issues found in previous versions. It also changes the behavior of the connector when processing malformed or erroneous input, delegating the job of surfacing errors to the message broker. To ensure the message broker is ready to handle these errors, a Dead Letter Queue (DLQ) should be set and configured so messages that can’t be processed by the input connector are removed from the queue and moved to a different queue for automatic or manual supervision.

Details on how to set up a DLQ and create a policy for it can be found in these articles:

• SQS — Amazon's Amazon SQS dead-letter queues

• IBM MQ — IBM's Dead-letter queues

• ActiveMQ — ActiveMQ's Message Redelivery and DLQ Handling

• RabbitMQ — RabbitMQ's Dead Letter Exchanges