Configuration migration overview

Configuration Migration is a tool designed for tenant admins to efficiently and accurately transfer configurations between tenants. It facilitates the systematic migration of objects such as schemas, templates, and dropdowns. While it automates the transfer of these configurations, it's important to note that other objects, including access policies, users, or data, are not included in the scope of the tool.

Before this tool, administrators had to manually migrate configurations, a process that was time-consuming and prone to errors. The Configuration Migration tool streamlines and automates this process, allowing you to export configurations from one tenant and replicate them in another. You can use this tool repeatedly between tenants to keep configurations up-to-date.

At a high level, the Configuration Migration process involves selecting the objects you wish to migrate, allowing Benchling to automatically calculate their dependencies, exporting these into a configuration file, and then importing, validating, and applying them to the destination tenant.

Overview of the Configuration Migration tool

Configuration Migration follows this process:

1. Select the objects to migrate
2. Benchling auto-calculates the dependencies for these selected objects
3. Selected objects + dependencies are exported into a configuration file
4. Import the config file into the destination
5. Validate configurations
6. Import configurations

In-scope Configuration Types 

Configuration Migration aims to automate configuration movement between tenants, but its scope is not exhaustive. The tool will migrate the following:

• Registry schemas: Entity schemas, Entry schemas, Plate schemas, Box schemas, Container schemas, Location schemas

• Dropdowns

• Fieldsets

• Result schemas

• Run schemas

• Study schemas

• Workflow task schemas

• Notebook Templates: Templates, Sub-templates, and Workflow execution templates

• Analysis templates

• Computed Fields

• Units

• Recipes and Assays

Out-of-scope Configuration Types 

All other objects are out of scope, including:

• General access policies

• Schema access policies

• Application of access policies (e.g., for projects, template collections)

• Label printing templates

• Users and teams

• Insights dashboards

• Projects and folder.

• Inventory hierarchy

• Data

• Data references in configurations (e.g., @-mentions or pre-filled schema values in Templates)

• Workflow task schema details: Forms, Task prefix updates, Task finder lookups steps updates

• Custom transforms in Run schemas

• Saved searches

• Worklists

• Apps

• Product limits

Access the configuration migration tool by following the steps below: 

1. Click on your avatar in the top-right corner of Benchling
2. Select Feature settings from the dropdown menu
3. In the left-hand panel, scroll down to the Tools section
4. Click on Configuration migration to open the tool

Once you're in the Configuration Migration tool, you can also explore previous migration activities:

• At the bottom of the page, you'll find a History section
• This section lists all prior migrations, including both exports and imports
• You can click into any migration entry to view details, such as selected configurations, dependencies, and migration status
• If available, links to download the export summary, diff file, or changelog will also appear here for reference or audit purposes

The sections below provide steps for exporting configurations and importing them. The process described below for an Entry template and Dropdown is the same for migrating multiple Templates or the configuration of your entire organization.

By default, all objects are set to Create/Update. When you migrate templates that contain references to data, such as pre-filled schema values or @-mentions, the Configuration Migration tool replaces these references with text placeholders. After migration, you will need to manually replace these template placeholders with references to actual data in the destination tenant. Today, only Templates use placeholders. Placeholders for @-mentions are highlighted in yellow in the entry body and include the name and API ID of the mentioned object. 

Placeholders for pre-filled schema field values are capitalized text inserted into the structured table.

Export configurations 

The Export Configuration represents the set of configuration objects in the source tenant that you intend to migrate to a destination tenant. This process packages selected objects and their dependencies for transfer, ensuring consistency across environments.

1. Click the Export Configuration button on the top right side of the Configuration Migration tool menu.
2. Use the Organization dropdown to choose the organization that contains the configurations you want to migrate. Once selected, tables with the configurations from that organization will be displayed, grouped by object type: Dropdowns, Schemas, Templates, and Workflows
   • Note: While migrations are most commonly performed between organizations in separate tenants, you can also migrate configurations between organizations within the same tenant

3. From the displayed lists of Dropdowns, Schemas, Templates, and Workflows, search for the items you wish to include in your export. Click the checkboxes on the left to select item(s). You can use the text box at the top right of each selection table to filter by name if you are looking for a specific template or schema.
   • If you want to export all configurations for the selected organization, choose the Migrate entire org option after selecting your source Organization

4. After selecting all the objects you want to export, scroll down and click the Validate and Export button

5. Once the export is complete, you will receive a notification. If successful, you will see a summary of the migration objects and their included dependencies. If the export is not successful, you will need to resolve any identified issues before proceeding
6. Click Download export summary below the Migration Summary to save a human-readable list of all the items to be migrated

Note: When you select a configuration item, all its dependencies will be automatically included in the export to prevent import errors. A dependency refers to any object that is linked to the object you are migrating.

Import Configurations 

With your configuration export complete, you are ready to import it into the destination organization. Navigate back to the Configuration Migration tool via Feature settings, just as you did when exporting your configuration. To import configurations, follow the steps below: 

1. Click the Import configuration button. Use the dropdown to select your destination organization. You can optionally add a migration name and description for this migration

2. To upload the configuration file, click Choose a file or drag and drop the file. Then, click Continue

3. You have the option to Download the Compare Configuration file for your upload
   • Clicking this link will download a CSV file that compares the configurations between your source and destination organizations. This file is helpful for understanding how different the configurations are

Validate Imported Configurations

After choosing to import your configurations, Benchling will begin analyzing the configuration which may take some time, indicated by a loading circle in the bottom left corner of the screen. 

Once complete, you will have the option to click Continue to validate the imported configurations and tool will guide you to inspect each sequentially. 

1. As you inspect the list, use the directional arrows to examine schema fields. Use the dropdown on the right to decide whether you want to create, update, or ignore each item

2. Once you are satisfied with the list of schemas and fields you are importing, click the Validate button
3. Benchling will validate the configurations, and after this process, click Continue
4. Repeat this validation process for both Templates and Workflows if they are relevant to your migration. Only pages with configuration updates will be included in this validation step

Note: Benchling automatically includes dependencies during export to simplify the import process. For the smoothest migration, avoid ignoring objects unless you mistakenly included an object or are certain nothing depends on it.

At the bottom of each validation page, you'll find an "Unchanged Items summary". This summary explains how Benchling is processing the file based on what already exists in the tenant and your selections. You can expand each section to view the items it refers to:

• X item(s) from the imported file will be ignored because there are identical item(s) in this organization: This means items in your migration file have exact matches in the destination. No updates will be applied to these items
• Y linked item(s) were not migrated based on selections during export: This indicates that there are items in your destination mapped to items in your source, but these source items were not included in your migration. No updates will be applied to these destination items
• Z item(s) in this organization will remain unchanged: This refers to items that exist only in your destination and not in your source. No updates will be applied to these items

Review the import 

1. After you have validated Schemas, Templates, and Workflows, you will be taken to a Review screen. This page provides a preview of all the changes that will be made during the import process
2. After reviewing the changes, click the Import Configuration button. Benchling will then import the configurations onto your destination organization, which may take a few minutes
3. Upon completion, a "Configuration Imported" message will display, along with a changelog
4. A migration summary file can be Downloaded at the top of the page for record-keeping. This migration summary file is also sent to the email address of the user who performed the migration
5. If you’d like to view the new migration import navigate back to the main configuration migration page where you will see a new entry has been added. You can Re-download the changelog for a previous migration as needed

Note: Recipes and Assays often include references to units and entities. Neither of these objects can be moved using the Configuration Migration tool. Therefore, they must be removed or replaced with placeholders for migration purposes, which may result in warnings indicating where references have changed.

Understanding Configuration Migration Files (Diffs)

The Configuration Migration tool provides two types of diff reports to help you understand changes: a pre-import diff ("Compare configuration") and a post-import diff ("Changelog"). Both are exported in a CSV format.

Pre-import diff (“Compare configuration”) 

This diff report can be downloaded at the beginning of the import process. After uploading your migration file and selecting an organization, you will see the option to Compare configuration. Clicking this downloads a file detailing the differences between the configuration in your import file and the configuration in the selected destination organization.

The CSV format for pre-import diffs includes the following columns:

• Object type: The type of object being migrated (e.g., Dropdown, Entity Schema).
• Object: The name of the object being migrated.
• Object Identifier: A unique identifier for this object during the migration (note: this is migration-specific, not an API identifier). It's provided for support referencing.
• Object difference: A brief description of the type of difference found in the object.
• Path: Populated when differences are found in a specific part of a migrated object (e.g., fields["My Field"].is_multi indicates a difference in the "Multi-select" option of a field called "My Field").
• Source value: Specifies the value of the option found at the "Path" in the configuration from the input file.
• Destination value: Specifies the value of the option found at the "Path" in the configuration in the target organization.

Caveats when interpreting a pre-migration diff:

The diff is calculated between the imported file and the entire selected organization, not just the configurations contained within the import file.

The first time Configuration Migration is used to import a configuration that was previously migrated manually, the tool may not correctly map the configuration in the file to the existing configuration in the destination organization. This can lead to unexpected diffs, such as 'creating an object / object not in import file'. While this mapping can be set correctly later in the migration process, it cannot be adjusted for this initial comparison.

Pre-import Diff Example: Nested Path 

If an Entity Schema called "My Entity" has a field "My field" that is required in the source but not in the target:

Pre-import Diff Example: Dropdown

 If a Dropdown called "My Dropdown" has options reordered and a new option added from source to target:

Pre-import Diff Example: Unarchive 

If a configuration is archived on the target but not on the source, migrating it will unarchive it on the target. The diff will appear as if the config only exists in the input file because archived configs in the target aren't detected in comparison:

Post-import diff (“Changelog”) 

This changelog is displayed on the final page of Configuration Migration after a successful import, representing the set of changes made to the selected organization. The same information can be downloaded in a CSV format from the changelog page or from the email automatically sent to the user who performed the migration.

The CSV format for post-import diffs includes the following columns:

• Object type: The type of object migrated (e.g., Dropdown, Entity Schema).
• Object: The name of the object that was migrated.
• Object Identifier: A unique identifier for this object during the migration (migration-specific, not an API identifier).
• Object change: A brief description of the type of change made on the object.
• Path: Populated when a change was made to a specific part of a migrated object (e.g., fields["My Field"].is_multi indicates the entity schema was updated on the "Multi-select" option in a field called "My Field").
• Pre-migration value: Specifies the value of the option found at the "Path" in the configuration before the migration.
• Post-migration value: Specifies the value of the option found at the "Path" in the configuration after the migration.

Post-import Diff Example: Nested Path 

Following the previous example, after the migration, the "My field" field in "My Entity" is now required in the target organization:

Post-import Diff Example: Dropdown 

Following the previous example, after the migration, the dropdown "My Dropdown" has reordered options and a new option added:

Post-import Diff Example: Unarchive 

Following the previous example, after the migration, the dropdown "My Dropdown" and its options are unarchived:

Migration Warning Icons 

The Configuration Migration tool uses two primary icons to highlight changes:

• Yellow triangles: These indicate a change that requires your attention but will not prevent the migration from completing. For example, you might see these for placeholders that need to be fixed post-migration.

  

• Red X’s: These indicate an issue that must be resolved before the migration can proceed. For instance, if schema field types need to be aligned manually, you will see a red X.

  

You can also see these messages by clicking the inline icon for a specific item.

Mapping Manually Migrated Objects 

If you have objects that were manually created across two tenants, you can update them using Configuration Migration. The first time you use the tool to align these objects, you will need to manually map them using the Actions dropdown.

If Configuration Migration finds an object with an exact name match, it will suggest that object at the top of the alphabetized list for mapping.

For example, if you are migrating a "Manually Built Schema" for the first time, it will default to Create. However, if you know there is a matching schema on the destination tenant, you should click into the Actions dropdown and search for it. The tool will list exact name matches at the top. You would then select the matching schema and can expand the view to ensure the fields match as expected. Alternatively, you could still choose Create from the Actions dropdown.

Note: Schema fields are the only objects in the tool that default map based on exact name matches.

Important: Once you complete this migration, the objects will be mapped between your source and destination tenants, and the tool will remember this mapping for future migrations. It is crucial to get this mapping correct, as it cannot be undone once the migration is completed.

Permissions

All Tenant Admins will have access to Configuration Migration if the feature flags are enabled. If you need the feature flag enabled, please reach out to Benchling Support. Other permissions are related to what changes you can make with the tool. 

Broadly, Configuration Migration does not allow you to make changes that are not possible directly in the Benchling UI. If you are blocked from making a change in the UI, you will also be blocked by Configuration Migration.

Here’s a summary of changes that can and cannot be made for different schema types via the tool:

*Field attribute cannot be edited if data has been submitted against the schema.

**Field archival will only be performed by the tool if no existing configurations in the destination tenant (e.g., Entity Links, computed fields) depend on the field.

Note: Field definition changes (e.g., text to dropdown) are the one type of change possible via the UI but not via Configuration Migration. This capability was excluded to avoid accidental bulk data loss that could occur if a new definition is more strict than the old one. This change still needs to be applied manually.

Migrations Across Code Versions

Configuration Migration is not supported across different code versions. This is especially important for Validated Cloud customers, meaning:

• It will not work between quarterly upgrades when Preview/Sandbox tenants and Production tenants are on different versions.
• It will never work between Research tenants and Validated Cloud tenants.

Configuration File Expiration 

Configuration files do not last indefinitely. The best practice is to export a file and immediately use it for import. If the file includes entry templates with attachments, it may expire in as little as 6 hours.

Product Limits 

To ensure the best experience, product limits have been enforced for Registry schemas and entry templates within Configuration Migration. When these limits are reached, Configuration Migration will fail quickly to prevent long waiting times on operations that will not succeed.

For Registry schemas:

•  Updating one dropdown option to another will fail if attempted on more than 10,000 entities.
• Updating the field link type (including changing the dropdown) will fail if attempted on more than 100,000 entities.
• Archiving a field will fail if attempted on more than 100,000 entities.
• Unarchiving a field will fail if attempted on more than 100,000 entities.
• Updating a unique constraint will fail if attempted on more than 100,000 entities.

For entry templates:

• Import of more than 300 templates or sub-templates will fail.

For analysis templates:

• Analysis templates can only be created, not updated, via Configuration Migration. If you select “Update” for an analysis template during import, the migration will fail validation.
• Templates containing one or more variable input tables created from “Experiment run data” are not supported. If migration is attempted, the template will fail validation in the import stage.
• Templates containing files are partially supported; everything except the template’s files will be migrated if attempted.

Frequently Asked Questions 

Q: What is Configuration Migration? 

A: Configuration Migration is a tool for tenant administrators that streamlines and automates the transfer of specific configurations, such as schemas, templates, and dropdowns, between tenants. It replaces manual, error-prone processes with an efficient, systematic method.

Q: What types of configurations can I migrate? 

A: You can migrate Registry schemas (Entity, Entry, Plate, Box, Container, Location), Dropdowns, Fieldsets, Result schemas, Run schemas, Study schemas, Workflow task schemas, Notebook Templates (Templates, Sub-templates, Workflow execution templates), Analysis templates, and Computed Fields.

Q: What objects are not included in a migration? 

A: Objects not included are access policies (general, schema, and their application), label printing templates, users and teams, Insights dashboards, projects and folders, inventory hierarchy, data, data references in configurations (@-mentions, pre-filled values), Workflow task schema details (Forms, Task prefix updates, Task finder lookups), custom transforms in Run schemas, saved searches, worklists, apps, units, and product limits. Recipes and Assays are also not directly movable and require special handling.

Q: Can I migrate between organizations in the same tenant? 

A: Yes, while migrations are most commonly between organizations in separate tenants, migrations between organizations within the same tenant are possible.

Q: How does the tool handle dependencies? 

A: When you select a configuration item for export, all its dependencies are automatically included to prevent import errors. During import validation, Benchling also accounts for these dependencies to make the process smoother.

Q: What are "placeholders" and what should I do about them? 

A: Placeholders are text substitutions that Configuration Migration inserts when it encounters data references (like @-mentions or pre-filled schema values) within templates. These placeholders need to be manually replaced with references to actual data in your destination tenant after the migration is complete.

Q: What do the warning icons mean? 

A: Yellow triangles indicate issues that require your attention but will not block the migration. Red X’s signify critical issues that must be resolved before the migration can proceed.

Q: Can I update manually created objects with the tool? 

A: Yes, you can update objects that were created manually between two tenants. The first time you do this, you will need to manually map the objects using the Actions dropdown during the import process. Once mapped, the tool will remember this mapping for all future migrations.

Q: Are there any limitations on changes I can make? 

A: Yes, Configuration Migration cannot make any changes that are not possible directly in the Benchling UI. For example, field definition changes (like changing a text field to an entity link) are not supported by the tool to prevent accidental data loss.

Q: Why might my migration fail? 

A: Migrations can fail due to product limits (e.g., migrating too many templates at once, or attempting changes on too many entities in schemas) or unresolvable issues indicated by red X's during the validation steps.

Q: How long do config files last? 

A: Configuration files do not last forever. It is best practice to export a file and immediately use it for import. Files containing entry templates with attachments may last for as little as 6 hours.

Q: Who can use the tool? 

A: All Tenant Admins have access to Configuration Migration if the feature flags are enabled for their tenant.

Q: What is the difference between "Compare configuration" and "Changelog"? 

A: "Compare configuration" is a pre-import diff report that you can download before you finalize an import. It shows the differences between the configurations in your import file and what currently exists in your destination organization. The "Changelog" is a post-import diff report that shows the changes that were actually made to your destination organization after a migration is completed.