Upgrading from v28 to v31

  • Updated on Feb 20, 2026
  • Published on Nov 5, 2024
  • 5 minute(s) read
Prev Next

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

Before proceeding, review How Upgrades Work in Hypercell, Planning Your Upgrade, and The Upgrade Process.

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 sections below.

Single authentication method

Single authentication method

We are enforcing the use of a single authentication method per Hyperscience instance and will invalidate tokens for users created with other methods.

You can determine which authentication method or methods you have enabled by checking your instance’s “.env” file for variables named HS_LOGIN_ENABLE_[NAME_OF_METHOD].

  • If you don’t see a variable with this kind of name, you have local authentication enabled.

  • If you do see one or more of those variables, they indicate which methods are enabled in your account.

If you have multiple methods enabled, you must choose one to be your system’s authentication method.

To prevent users on different authentication methods from being logged out upon upgrade, we recommend running the following script to migrate all users to your single authentication method before upgrading: 

UPDATE user_profile_userprofile SET auth_method = <AUTH_METHOD> ;

In this script, replace <AUTH_METHOD> with the number assigned to your authentication method:

  • Local - 1

  • LDAP - 2

  • SAML - 3

  • OpenID - 4

If you are upgrading to v28.0.11+, v28.2.4+, or v30+, you do not need to run this script, as the system runs it automatically during the upgrade process.

Automatic token invalidation (optional)

Automatic token invalidation (optional)

You can also choose to automatically invalidate API tokens for users created through an external authentication method. If you choose to enable automatic token invalidation, the system will invalidate API tokens for users every 12 hours.

If you enable this feature, you may need to add a list of your API-only users to your instance’s “.env” file to exempt those users from token invalidation. If you have application users who need continuous access to the API without logging in to the application, you should include those users in your list, as well. For more information, see External Authentication Methods and API Users.

As part of your upgrade, you will need to complete the following steps to prevent token invalidation for the users you specify:

  1. Verify authentication methods for all of your accounts — Prior to upgrading, check the authentication methods for your accounts to determine whether you need to add them to your list of exempted users. If they are using local authentication, follow the steps in “Transitioning local users to external authentication” below to prevent interruptions to their access.

  2. Add the TOKEN_REVALIDATION_EXEMPTED_USERS variable to your “.env” file — During the upgrade, add this variable as described in External Authentication Methods and API Users. The value of TOKEN_REVALIDATION_EXEMPTED_USERS serves as your list of exempted users.

  3. Complete a one-time authentication — After upgrading and creating your list of exempted users, you will need to reauthenticate the accounts in the list by logging them into the application via your external authentication method.

Transitioning local users to external authentication

If you're using an external authentication method but also have local users that you want to exempt from token invalidation, you will need to:

  1. Re-create these users with your external authentication method.

  2. Add them to the list of exempted users as part of step 2 above.

  3. Log each of these users into the application via your external authentication method as part of step 3 above.

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 the Automatic token invalidation (optional) section above, 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

© Hyperscience