Migrating assets between Hyperscience instances

Assets such as workflows, releases, models, and system settings are essential components of a Hyperscience deployment. Migrating them between development, testing, and production instances helps maintain consistency while reducing the need to recreate configurations and retrain models.

This article explains how to import and export these assets.

Importance of migration

Asset migration helps organizations move validated configurations and trained assets between instances while maintaining consistency throughout the deployment lifecycle.

Migration supports:

• Consistent configurations– Keep workflows, models, releases, and system settings aligned across instances.
• Faster deployment – Reduce the time and effort required to move validated assets between instances.
• Testing and validation – Validate assets in lower instances before deploying them to production.

Common scenarios for migration

Asset migration is commonly used in the following scenarios:

• Instance upgrades – Moving assets during application upgrades or when transitioning between Hyperscience versions.
• Assets promotion – Promoting validated assets from lower instances, such as development or testing, to higher instances, such as production.
• Workflows expansion– Deploying new workflows, layouts, or models to support additional document types or business processes.
• Model and configuration updates – Migrating updated models, releases, or system settings to improve document processing performance.

Assets available for migration

• Workflows
• Releases
• Classification models
  • To learn more about Classification, see Structured Document Classification and Semi-structured Document Classification.
• Field Identification models and Table Identification models
• Transcription Models
• Vision Language Models (VLM)
• Permission Groups
• Field Dictionary
• Translations
  • Learn more in Providing a Translated User Interface.
• System Settings
  • The core configurations of the platform. Learn more in Application Settings Overview.

Migration process

Preparation

If you are migrating assets as part of an application upgrade, review the following articles before you begin:

• How Upgrades Work in Hypercell
• Planning Your Upgrade
• The Upgrade Process

Migrating assets from the Assets page

Starting with v42.3, you can import and export supported components from Administration > Assets.
The Assets page groups supported asset types into categories and provides dedicated Import and Export actions for each component.

To migrate a component:

1. Go to Administration > Assets.
2. Locate the component type you want to migrate.
3. Select Import or Export.
4. Follow the steps in the respective modal.

Component-specific considerations

The available import/export steps vary depending on the component type.

Classification Models

• Ensure that the Classification model is compatible with the target release version.
• Training data is not included when importing or exporting Classification models. To learn more, see TDM for Classification models.

Field & Table Identification Models

• Field & Table Identification models are associated with layouts.
• When importing or exporting a model, select the relevant layout. Learn more in Identification Models Overview.

System Settings

• You can choose which settings to include when exporting.
• Importing system settings replaces the selected configuration values with those from the imported file. To learn more, see Application Settings Overview.

Releases

• Release packages can contain layouts, custom data types, and related configuration.
• When importing a release, choose how to handle duplicate custom data types. Learn more in Releases.

Field Dictionary

• Field Dictionary entries are imported from and exported to CSV files.
• Download the sample CSV file to review the required format before importing.
• Imported entries must reference existing data types. To learn more, see our Data Types category.

Translations

• Translation files are imported from and exported to CSV files.
• Select the target locale before importing a translation file.
• Use an exported translation file as a template when creating or updating translations. Learn more about translations in Providing a Translated User Interface.

(v42.2 and earlier) Import / Export tool

In v42.2 and earlier, you can import and export supported components from Administration > Import/Export.
The Import/Export tool allows you to migrate supported components between Hyperscience instances.

Using the Import/Export tool

1. Go to Administration > Import/Export.
2. Select the component you wish to import or export.
3. Click Export to download a bundle or Import to upload one.
4. Follow any on-screen prompts to complete the action.

Migrating assets from individual component pages

Assets can also be imported and exported directly from their respective pages. See the drop-downs below for asset-specific migration.

Exporting and importing flows

Exporting flows

Follow the steps below to export a flow:

1. Go to the Flows page and find the one you want to export.
2. Click on the menu for the flow and click Export All Flows.

You can also export your flow from its details page:

1. Go to the Flows page and find the flow you want to export.
2. Open the flow’s details page and scroll down to the Flows table.
3. Click Export on the Top-Level Flow.

The exported file is named Flow-[Flow_name]-[Flow_UUID]-[YYYYMMDD_HHMM].zip, where:

• [Flow_name] is the name of the flow.
• [Flow_UUID] is its unique identifier.
• [YYYYMMDD_HHMM] represents the export date and time in GMT.

The ZIP file includes:

• A flows folder, containing the flow’s JSON file.
• A manifest.json file with metadata about the export.
• If the flow contains Code Blocks, their Python files are included.

Note that client secrets and Python package dependencies are not included in the export.

Importing flows

To import your flow:

1. Go to the Flows page.
2. Click Import Flow.
3. Upload the ZIP file you exported.

Exporting and importing releases

1. Go to Library > Releases, and locate the release you want to export.
2. Click the name of the release to open its details.
3. Click Actions, then select Download Release.
   • The system may take a few minutes to prepare the file. You will receive a notification when it’s ready.
4. When notified, go to Notifications, find the entry for your file, and click Download.

The downloaded ZIP file contains the following assets:

• A JSON file containing metadata about the release, such as creation and last updated timestamps.
• manifest.json, which includes a summary of the release’s contents.
• field_data_types.json, containing a list of data types used in the release.
• Individual JSON files for each layout version in the release.
• Individual JSON files for each layout variation with selected field customizations applied.

Importing releases

To import your release:

1. Go to Library > Releases and click Add Release.
2. Select Upload Existing.
3. Choose one of the following options:
   • Drag and drop the ZIP file into the dialog box.
   • Click Choose File to locate and upload the file from your machine.
4. Under How To Handle Duplicate Custom Data Types? select an option:
   • Skip if duplicate custom data type exists - Retains the existing custom data type’s list of values without overwriting.
   • Update with data from the JSON - Overwrites the existing custom data type’s list of values with those from the imported file.
5. Click Upload.

• The system may take a few minutes to process the release. You will receive a notification when the process is complete.

6. After the import is finished, click View Release in the Notification Center to view the release’s details.

Exporting and importing Classification models

Exporting Classification models

You can export Classification models through Training Data Management in v40.1 and later. Learn more in TDM for Classification.

1. Go to Library > Models.
2. Click on Classification Models in the drop-down list at the top of the page.
3. Click on the name of the model you want to export.
4. Click the menu in the upper-right corner of the page, and click Download Classification Model.
   • The system may take a few minutes to prepare the file. You will receive a notification when it’s ready.
5. When notified, go to Notifications, find the entry for your file, and click Download.

or

1. On the model’s details page, scroll down to the Model Activity table.
2. Click the Download model button next to the last-trained version of your Classification model.

The ZIP file contains the following items:

• Metadata for the model.
• The model itself.

Note that the model’s training data is not included in the ZIP file.

Importing Classification models

Classification models can be uploaded only in v40.1 and later and only for live releases. Learn more in TDM for Classification.

1. Go to Library > Models.
2. Click Classification Models in the drop-down list at the top of the page.
3. Click Import Model.

Exporting and importing Identification models

Exporting Identification models

Follow the steps below to export your Identification models:

1. Go to Library > Models.
2. Find your Identification model and click its name.
3. On the model’s details page, scroll down to the Model History table.
4. Click the download button in the Actions column to export the model.

The ZIP file contains:

• Model metadata.
• The model itself.

Note that the training data is not included in the ZIP file.

Importing Identification models

Follow the steps below to import your Identification model:

1. Go to Library > Models.
2. Click the name of your model to access the model management page.
3. From the Actions drop-down click Upload Model.
4. Once the model is uploaded, click Submit.

Exporting Transcription / Finetuning models

You can export all finetuning models in a Transcription model, or you can download individual finetuning models.

Export all finetuning models in a Transcription model

1. Go to Library > Models, and click on Transcription Models in the drop-down list at the top of the page.
2. In the Transcription Models table, click on the name of the transcription model whose fine-tuning models you want to download.
3. Click Download all models.

The models are downloaded as a ZIP file with the name confidence_thresholding_model_export.zip.

Export an individual finetuning model

1. Go to Library > Models, and then select Transcription Models in the drop-down list at the top of the page.
2. In the Transcription Models table, click on the name of the transcription model that contains the finetuning model you want to download.
3. Click on the tab that matches the type of fine-tuning model you want to download.
4. In the Available Models table, find the version of the model you want to download, and click Download Model.

The model is downloaded as a ZIP file with the name confidence_thresholding_model_export.zip.

Importing Transcription models

1. Go to Library > Models, and then click Transcription Models in the drop-down list at the top of the page.
2. In the Transcription Models table, find the transcription model you want to import a finetuning model for and click on its name.
3. Click Upload model.

Exporting and importing system settings

To move system settings between multiple instances that are on the same major version, follow the steps outlined in this section.

Exporting system settings

To export system settings:

1. Go to Administration > System Settings
2. Click Export at the top of the page.
3. Deselect the system settings that you do not want to export.
4. Click Download Settings.

The system settings are exported in a JSON file. You can then use this JSON file to import these system settings into another instance that uses the same major version of the application.

Importing system settings

To import system settings:

1. Go to Administration > System Settings.
2. Click Import at the top of the page
3. Drag and drop your settings file and click the Import button. You can also click Browse to find the settings file on your machine and open it.
4. Deselect the settings you do not want to import. All settings that you choose not to import will keep their current value.
5. Click Apply Changes now.

Exporting and importing permission groups

To export permission groups:

1. Go to Users > Permission Groups, and select the checkboxes for the groups you want to export.
2. Click Actions, and then click Export.

The system creates a JSON file for each exported permission group, which is then downloaded to your machine. If you’ve exported multiple groups, the system creates a ZIP file containing a JSON file for each permission group.

Importing permission groups

To import a permission group:

1. Go to Users > Permission Groups.
2. Click Add Permission Group in the upper-right corner.
3. In the Add Permission Group dialog box, click the Upload Existing tab.
4. Do one of the following:
   • Drag and drop the permission group’s JSON file to the dialog box.
   • Click Choose File, and find and open the permission group’s JSON file on your machine.
5. Click Upload.

Best practices for assets migration

• Migrate dependent components in the correct order:
  • Flows → Releases → Classification Models → Identification Models → Training Data
• Disable Continuous Model Improvement.
  • Learn more in Identification Settings.
• Maintain high-quality training data.
  • Use validated training datasets when retraining models after migration.
  • Poor-quality annotations or QA data can negatively affect model performance.
• Validate imported artifacts.
  • Verify that flows are associated with the correct releases.
• Retain older instances until validation is complete.
  • Keep historical data accessible until the migration has been successfully validated.
  • Validate model performance and automation rates before deprecating older instances.

A Workflow or Flow is a customizable workflow in Hyperscience that automates the processing of documents. Learn more in Flows.

A release is a package of one or more committed layout variation versions. Learn more in Releases.

A machine learning model that automatically identifies a document’s type—Structured, Semi-structured, or Additional. Learn more in Classification models.

A machine learning model that learns where fields are located in Semi-structured documents. Learn more in Identification models.

A machine learning model that extracts text from scanned document images. Learn more in Transcription models.

A group of users who share the same set of permissions. Learn more in User Management.

A centralized place in Hyperscience where you manage field customizations for Structured layouts. Learn more in Data Types.