# 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](https://help.hyperscience.ai/latest/docs/structured-document-classification) and [Semi-structured Document Classification](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/providing-a-translated-user-interface).
- **System Settings**  
  - The core configurations of the platform. Learn more in [Application Settings Overview](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/deployment/docs/how-upgrades-work-in-hypercell)
- [Planning Your Upgrade](https://help.hyperscience.ai/deployment/docs/planning-your-upgrade)
- [The Upgrade Process](https://help.hyperscience.ai/deployment/docs/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](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/providing-a-translated-user-interface?highlight=translations).

## (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](https://help.hyperscience.com/latest/docs/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](https://help.hyperscience.com/latest/docs/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](https://help.hyperscience.ai/latest/docs/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](https://help.hyperscience.ai/latest/docs/flows).

A release is a package of one or more committed layout variation versions. Learn more in [Releases](https://help.hyperscience.ai/latest/docs/releases).

A machine learning model that automatically identifies a document’s type—Structured, Semi-structured, or Additional. Learn more in [Classification models](https://help.hyperscience.ai/latest/docs/classification-models).

A machine learning model that learns where fields are located in Semi-structured documents. Learn more in [Identification models](https://help.hyperscience.ai/latest/docs/identification-models).

A machine learning model that extracts text from scanned document images. Learn more in [Transcription models](https://help.hyperscience.ai/latest/docs/transcription-models).

A group of users who share the same set of permissions. Learn more in [User Management](https://help.hyperscience.ai/latest/docs/user-management).

A centralized place in Hyperscience where you manage field customizations for Structured layouts. Learn more in [Data Types](https://help.hyperscience.ai/latest/docs/data-types).