Configuration Migration 🔍

What is Configuration Migration? 

Configuration Migration is a tool designed to enhance the efficiency and accuracy of transferring configurations between tenants. It is a tool for tenant admins, facilitating the systematic migration of schemas, templates, and dropdowns. It's important to note that other objects like access policies, users or data are not in scope for the GA release. During migration the tenant admin needs to first choose the objects they care to migrate. Benchling then downloads these objects and all their dependencies into a migration file. This file can be used to create or update objects in the destination tenant. Config migration can be used repeatedly between tenants to keep the configurations up-to-date. 

Before and After

Before: Previously, admins had to manually migrate configurations or request customer success assistance, which was time-consuming and prone to errors.

After: With the Configuration Migration tool, admins can export configurations from one tenant and replicate them in another, streamlining and automating the process.

Configuring and using

Configuration

The tool is being rolled out in cohorts. If you do not currently see this capability in Benchling, then your cohort is still in the queue. Please reach out to your CSM to learn more.

Use

At a high level, 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

See below for more detailed instructions on how to complete a migration

Step 1: Open the Configuration Migration Tool

The Configuration Migration tool is located in the Feature settings menu. To navigate to the tool, click your Avatar and select Feature settings. In the left panel of the Feature settings menu scroll down to the Tools section and click on Configuration migration, this will open a screen listing previous imported migrations.

Step 2: Explore previous migrations

Each imported migration has an associated name, description, datetime and user. Click the menu to Download changelog and view the changes applied by a particular migration. Migrations were first recorded in August 2024. Any migrations completed before this date will not appear. 

Step 3: Select the Source Organization

In the menu of the Configuration Migration tool, click the Export Configuration button on the top right side.

Use the Organization dropdown to select which organization has the configurations you intend to migrate. Once selected, tables with the configurations in the selected Organization are displayed. Tables are grouped by object type: Dropdowns, Schemas, Templates, Workflows

Note: Migrations are most commonly between organizations in separate tenants, but migrations between organizations within the same tenant are possible.

Step 4: Select the Configurations to Migrate

Use the list of the Dropdowns, Schemas, Templates, and Workflows to search for what you’d like to include in the export. Click the checkboxes at the left to select an item to include it in the export.

To search for a specific template or schema, use the text box at the top right of each selection table to filter by name.

To export all Organization configurations, select the Migrate entire org option after you select the source Organization.

Note: By selecting a configuration item, all configuration dependencies will be automatically included to prevent import errors. A dependency is anything that is needed to configure an object, which means any object that is linked to the object you are migrating creates a dependency. 

Step 5: Download the Config File

Once you have selected the objects that you would like to export, scroll down and click the Validate and Export button. 

When complete, you will get a notification toast. If your export was successful, you will be able to see a summary of the migration objects and their included dependencies. 

If the export is not successful, you will need to resolve the identified issues before proceeding. 

Click Download export summary below the Migration Summary to save a human readable list of all the items to be migrated.

Step 6: Identify the Organization in the Destination Tenant for Import

Now that you have completed the export of your configuration, you are ready to import it to the destination organization. Like before, navigate to the configuration migration tool via Feature settings. 

Once in the tool, select the Import configuration button, and use the dropdown to select the destination organization. 

Optionally add a migration name and description for this migration.

Step 7: Upload the Config File

Click Choose a file or drag and drop the file to upload it to the destination tenant, then click Continue. 

Optionally, you can download the Compare Configuration file for your upload. Clicking this link will download a CSV which compares the configuration between your source and destination organizations. This file can be useful for understanding how divergent the configurations are between two organizations.

Note: Upon upload, Benchling will begin analyzing the configuration which may take some time. This is displayed by the loading circle that populates in the bottom left-hand corner of the screen. Once the process is complete, you will have the option to click continue. 

Step 8: Validate Schemas, Templates, and Workflows

Your config file will populate a list of schemas, templates, and workflows that are going to be imported. The tool will guide you to inspect each sequentially. 

As you inspect the list, use the directional arrows to inspect the schema fields and use the dropdown at the right to verify if you would like to create, update, or ignore. 

Tip: During export, Benchling auto-included dependencies of selected objects to make import easier. For the smoothest migration experience, avoid ignoring objects unless you included an object by mistake or you are certain nothing depends on it.

Once satisfied with the list of schemas and fields you are importing, click the Validate button. Benchling will validate the configurations, and after this process is complete, click Continue. Repeat this process for both Templates and Workflows, if relevant. Only the pages with configuration updates will be included.    

At the bottom of each page, you are provided an Unchanged Items summary of how Benchling is processing the file based on what already exists in the tenant and what selections you have made. Each section can be expanded to view the items it refers to. See below for an explanation of each section:

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

Step 9: Import Configuration 

Once you have validated Schemas, Templates, and Workflows, you will be brought to a Review screen. This page is a preview of all the changes that have been made during the import process. 

After reviewing the changes, click the Import Configuration button so Benchling can import the configurations onto your destination organization, this may take a few minutes. 

Upon completion of the process, a Configuration Imported message will display, and a changelog will be displayed. 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 of the user who conducted the migration. 

The steps above shows how to use the configuration migration tool on an Entry template and Dropdown, but the process for migrating multiple Templates or the configuration of your entire organization is the same. 

Step 10: View new migration import on main page 

After each import, a new entry will be added to the main Configuration migration page. Re-download the changelog for a previous migration as needed.

Other Considerations for Use

Default Settings

• Schemas are default set to Create/Update
• Templates are default set to Ignore 

This is important to keep in mind when you migrate Templates with references to data, like pre-filled schema values or @-mentions. On the destination tenant, you will need to replace the Template placeholders with references to actual data in the destination tenant. The default settings for Templates are configured as such to avoid accidental overwriting of data with placeholders during subsequent migrations of the same Template. 

Migration Warning Icons

The configuration migration tool uses two main icons to draw attention to changes to be made. These icons appear both in the Errors section at the bottom of each page and inline for each item they refer to.

• Yellow triangles indicate a change that requires attention, but will not block the migration. In the example below, admins should make sure to fix the placeholders post-migration, but they can complete the migration without issue.

• Red X’s indicate an issue that will need to be resolved before the migration can complete. In the example below, the field types of the schema will need to be aligned manually to unblock the migration.

These same messages can also be seen by clicking the inline icon for a specific item, like below:

Mapping Manually Migrated Objects

Objects that were created manually between two tenants can be updated via Configuration Migration. The first time that Configuration Migration is used to align these two objects, you will just need to manually map them in the Actions dropdown. If Configuration Migration finds an object with an exact name match, it will offer that object at the top of the alphabetized list of objects available for mapping.

In the example below, if you are migrating Manually Built Schema for the first time, it will default to Create. But if you know that there is a matching schema on the destination tenant, you will need to click into the Actions dropdown and search for the matching schema from the available objects. In this case, you can see that Config Migration found an exact name match and the Manually Built Schema on my destination is listed at the top of the list.  

You would then select the matching schema, after which you could expand the view to ensure that the fields match as expected. Schema fields are the only objects in the tool that default map based on exact name matches. Alternatively, you could select the Actions dropdown and choose Create instead.

Once you complete this migration, Manually Built Schema will be mapped between your source and destination tenants. For every migration thereafter, the tool will remember this mapping.

Note: It is very important to get this mapping done correctly, as it cannot be undone once the migration is completed.

Caveats and limitations

In-scope Configuration Types

Config migration aims to automate the movement of config between tenants, but the tool is not currently exhaustive in scope. Config migration 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
• Templates, Sub-templates, and Workflow execution templates
• Computed Fields

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, etc)
• Label printing templates
• Users and teams
• Insights dashboards
• Projects and folders
• 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

To ensure the best experience, product limits have been enforced for Registry schemas and entry templates within Configuration migration. When these limits are hit, Configuration migration will fail fast to avoid long wait times on operations that will not succeed.

For Registry schemas:

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

For entry templates:

• Import of >300 templates or sub-templates will fail.

Warnings and Limitations

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

Given the in-scope objects above, the table below further summarizes the changes that can and cannot be made by the configuration migration tool for different schema types. 

*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 (i.e. Entity Links, computed fields) depend on the field.

Note: The one change in the table above that is possible via the UI and not possible via Configuration migration are field definition changes. Field definition changes can cause data loss if the new definition is more strict than the old definition (e.g. text to dropdown). This updating capability was excluded for now to avoid accidentally causing bulk data loss. This change will continue to need to be applied manually.

Placeholders

When configurations with references to data are migrated, Configuration Migration replaces these references with text placeholders. Placeholders need to be manually fixed after a migration. Only Templates use placeholders today.

• Placeholders for @-mention are highlighted in yellow in the body of the entry and include the name and API ID of the object that was mentioned.

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

Migrations across code versions

Config migration is not supported across code versions. This is particularly important for Validated Cloud customers because it means:

• It will not work in between quarterly upgrades while 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 forever. The best practice is to export a file and immediately use it for import. If the contents include entry templates with attachments, they may last for as little as 6 hours.

Permissions and entitlement

All Tenant Admins will have access to config migration if the flags are enabled.

We will continue to update this article to provide a more detailed guide. Always ensure to check the latest version of Benchling's documentation or reach out to our support team for any unresolved issues or complex scenarios.