Upgrading from v28 to v31

This article highlights the key points of upgrading from v28 and v31. It does not replace our existing upgrade documentation.

Before proceeding, review Upgrade Best Practices, Upgrade Considerations and Known Issues, and Upgrade Process Overview.

1. Understand the key user-experience differences between v28 and v31. 

We introduced Layout Management in v28.2.0 and Flows in v30.0.0, both of which included significant changes to the Hyperscience user experience.

For more information on these features, see the V28 Release Notes and V30 Release Notes. You may also want to review these features with your Hyperscience representative to learn more about their implications for your organization.

Latency in v30 and later

To support flows and other customizable features in v30 and later, we needed to make changes to the application architecture used in earlier versions. As a result of these changes, you may notice increased latency in submission processing after upgrading to v30 or later. However, while each individual submission may take longer to process, the throughput, or total number of submissions that can be processed within a given time period, is greater in v30 and later than in earlier versions.

To control how quickly the system processes submissions, you can include the SDM_BLOCKS_TASK_POLL_INTERVAL variable in your ".env" file.

2. Make sure you are using v28.0.10+, v28.2.3+, or v28.3.x.

Depending on your current version of Hyperscience, you may need to upgrade to v28.0.11,  v28.2.4, or v28.3.x before upgrading from v28. Doing so will prevent a loss of automation in v31, and it will eliminate the need for you to run a script to migrate your users to a single authentication method.

If you're using…

…upgrade to:

v28.0.0-28.0.9

v28.0.11

v28.0.10 or v28.0.11

(no upgrade needed)

v28.1.0-28.1.2

v28.2.4

v28.2.0-28.2.2

v28.2.4

v28.2.3 or v28.2.4

(no upgrade needed)

v28.3.0 or v28.3.1

(no upgrade needed)

For more information about the security measures introduced in these later versions of v28, see the "Upgrading to v27.0.8+, v28.0.10+, v28.2.3+, or v30+" section of Upgrade Considerations and Known Issues.

3. Ensure you have the required infrastructure for v31.

Before upgrading, you should be aware that v28 and v31 have different infrastructure requirements. Specifically:

  • Databases: PostgreSQL 9.5 is not supported for v31. If you are using PostgreSQL 9.5, upgrade your database to a supported version listed in Infrastructure Requirements.

  • Trainer VM CPU cores: 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: We strongly recommend that your trainer have 64GB of RAM, which will maximize the performance of the 16-core CPUs described above.

  • Other components: Your Hyperscience representative can provide more specific recommendations for your system infrastructure based on your use of Hyperscience.

4. Upgrade the application directly from v28 to v31.

Note that the v28-to-v31 upgrade path differs from our normal upgrade path.

  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.

5. If you enabled automatic token invalidation, reauthenticate exempted users.

If you chose to enable the automatic token invalidation feature described in Upgrade Considerations and Known Issues, you will need to reauthenticate the exempted users by logging them in to the application via your external authentication method.

What to expect after upgrading

After upgrading to v31, you may notice slowness in processing Structured documents. To learn more, see the following section.

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.

mceclip0.png