Upgrade Best Practices

To make the upgrade process as frictionless as possible, we recommend following the guidelines below.

If you haven’t done so already, read Upgrade Considerations and Known Issues before attempting to upgrade.

Set aside at least four weeks for the upgrade 

To make your transition to a new version as seamless as possible, we recommend allocating at least four weeks for the upgrade process. If possible, install the trainer for the new version alongside your current trainer as soon as you know you want to upgrade. You should install the new trainer in your production environment, along with any other environments where you train new models (e.g., development, staging).

Back up your environment before upgrading

To be able to potentially revert an upgrade and prevent data loss, we recommend you do the following before starting the upgrade process:

  • Create a backup of your database while your application is shut down.

  • Create a backup of your object store while your application is shut down. You can do this while the database is being backed up. 

If you need to restore previously created backups:

  • Restore from the desired database backup while your application is shut down.

  • Restore from the same point-in-time object store while your application is shut down. You can do this while the database is being restored.

Upgrade sequentially

When upgrading, do not skip application versions between your current version and your target version. For example, if you are currently running V35 and would like to upgrade to V37, you should first upgrade from V35 to V36 and then to V37. Doing so ensures compatibility and performance across each version of the application. 

Whenever you upgrade, we strongly recommend following all of the steps outlined in the Upgrade Process Overview—and allowing model training to complete—before upgrading again toward your target version.

Test your upgrade in another environment before upgrading in production

In the world of enterprise software, updates are typically executed in a development environment, followed by the user-acceptance testing (UAT) environment, and finally in the production environment. Throughout this process, you should test all of the elements that you intend to use in the development and UAT phases before proceeding to production. Once you upgrade, you will not be able to revert back to a previous version.

We recommend testing any changes that you intend to use in production. Consider the following checklist of items that you can test:

  • Deploying a release

  • Deploying a model

  • Testing a new layout

  • Testing any new document or layout types

  • Comparing projected accuracy between models in the old and new versions

Avoid upgrading during peak business times

Ideally, you will execute this upgrade during an off-peak business period. If it is feasible within your workload, you should do the following:

  1. Stop sampling for QA (if applicable) and stop uploading new submissions.

  2. Complete all outstanding non-QA Supervision tasks.

  3. Wait until all submissions are completed.

  4. Complete all outstanding QA tasks.

Consider how PII-wiped documents will affect finetuning and automation

Normally, if personally identifiable information (PII) is wiped, or deleted, from a document, the document is still used in finetuning training with all of its remaining information. When you upgrade to a new instance, the machine needs to recalibrate all previous QA records with the new model. 

Note that the number of records available will depend on the “Period of records to use” setting for Transcription Automation Training and, potentially, the number of days specified in the “PII Deletion policy.”

Specifically, the number of records we can use is as follows:

  • For new trainers: all non-PII-wiped records within the training period (“Period of records to use”)

  • For existing trainers: all records within the training period

In v35 and later, you can set different values for the “Period of records to use” setting for Structured and Semi-structured text.

If the records were wiped of PII, recalibrating with them isn’t possible, so you cannot use those records after upgrading. If most of the viable QA records were wiped of PII, there may be a significant loss of records used for that training. This loss of data may result in a reduction in automation after upgrading.

To avoid this loss of automation, attach the updated trainer to your application, and check the result from finetuning with the new trainer. By comparing the trainers’ data, you can check expected automation rates before and after an upgrade, along with the difference in viable QA records between versions. Knowing that information can help you determine if it’s safe to do an upgrade or if you need to process many QA records before or after the upgrade to fill the database with viable records.

You may find it helpful to adjust the “Period of records to use” and “PII Deletion policy” settings. In v34 and earlier, you can find these settings in Administration > Settings. In v35 and later, you can find “Period of records to use” in your flow settings for Structured and Semi-structured text, and the “PII Deletion policy” setting in Administration > Settings. The default “Period of records to use” setting is 30 days, and the default period in the “PII Deletion Policy” is 7 days. To make more records available to your new trainer, increase either or both of these values.