This article guides you through configuring the In Vivo Sync app, a Benchling App crucial for synchronizing data between Benchling In Vivo and Benchling's Registry and Results. You'll learn about its two one-way integrations, understanding how In Vivo data is created and updated in Benchling, and how registered custom entities from Registry become treatments in In Vivo. The guide highlights essential permissions settings, both native and custom metadata configurations, and effective strategies for consistent registry IDs and entity names. Discover how to set up the app, resolve common issues, and navigate limitations. This feature is available for customers with licenses to Benchling In Vivo and Benchling’s Registry.

Introduction

The In Vivo Sync app between In Vivo and Benchling is a Benchling App that utilizes Benchling’s and Benchling In Vivo’s API to sync data between the In Vivo product and the Registry product. Key information from Benchling In Vivo is synced to Benchling’s Registry and Results to connect upstream treatment molecule data with In Vivo studies and subsequently with downstream In Vivo data analysis and sample processing. 

The In Vivo Sync app technically includes two, one-way integrations. 

When a create, update, or delete action occurs in Benchling In Vivo, a corresponding event will occur in Benchling’s Registry for any items in the scope of the integration. These events will generally be processed in Benchling’s Registry within ~5 minutes of the action in In Vivo, but can take up to 24 hours depending upon the workload of all integrations connecting to the Benchling tenant. Events on objects in Benchling In Vivo are mapped to corresponding objects in Benchling’s Registry and Results:

The In Vivo Sync app is not a bidirectional integration and thus data should only be edited where it was originally entered. If data originally created in In Vivo is synced to Benchling’s Registry, and subsequently edited in Benchling’s Registry, those updates will not sync back to In Vivo. It is critical that data be edited only where it was originally created, with no exceptions.

The Benchling In Vivo sync app is hosted on AWS and the code is controlled by Benchling. It is not enabled by default and must be installed by Benchling. In addition, even if the app is installed on the Benchling tenant, certain features of the integration may not be enabled. To request access to the app or specific features of the app, an admin should contact Benchling Support at support@benchling.com.

Configuration guide

Install the In Vivo Sync app

The app must be installed by Benchling. Contact Benchling Support to install the app if you do not have the app in your Benchling tenant.

Set permissions for the In Vivo Sync app

For the In Vivo Sync app to function, it needs permissions to create new entities in a user-designated folder, update existing entities, and archive existing entities.

These permissions are specifically for the In Vivo Sync app. In addition to this, ensure only authorized users can view data in Benchling. Other permission structures can work, however these are the recommended permissions for uninterrupted functionality.

1. Create a new custom access policy called In Vivo Sync App Permissions
   • Use the WRITE policy as your starting point.
   • Adjust the permissions as outlined in Table 1
2. Follow Table 2 to designate the app’s permissions within the tenant

Table 1: In Vivo Sync custom access policy permission requirements

*granted to author is most restrictive, but granted will also work.

Table 2: In Vivo Sync standard permission settings

Configure metadata in the In Vivo Sync app

Set native metadata in the In Vivo Sync app

The In Vivo Sync app comes with built-in metadata, which includes both required and optional fields. These fields can be quickly mapped to your Registry schemas using dropdown menus in the app’s configuration page.

To map native metadata in the In Vivo Sync app:

1. Confirm that each native field you want to use has a corresponding field in the applicable Registry schema
2. In Benchling, click the Connection icon in the left navigation bar
3. Go to the Apps tab and open the In Vivo Sync app
4. Select the Configuration sub-tab
5. Find the native field you want to map
6. Use the dropdown list to select the corresponding schema field
7. Click Submit in the top right to save your configuration

Note: All required fields must be mapped to a schema field in Benchling’s Registry. If even one required field is missing, the configuration cannot be saved.

Set custom metadata in the In Vivo Sync app

In addition to native metadata fields, you can add custom metadata to the In Vivo Sync app. For example, if Coat Color is configured as a custom metadata field on Animal in In Vivo, you can sync that field to Benchling’s Registry alongside all native Animal metadata.

Before you configure custom metadata in the In Vivo Sync app, you must add the metadata field to:

• The relevant object in the In Vivo Glossary

• The corresponding schema in Benchling’s Registry

Field names don’t need to match, but field types must be compatible or the sync will fail. Field type compatibility is as follows:

Note: Custom Entity fields and Entry Link fields cannot be mapped in the In Vivo Sync app

To map custom metadata in the In Vivo Sync app:

1. Gather the API ID of the In Vivo field
2. Gather the slug name of the corresponding Registry field
3. In Benchling, click the Connection icon in the left navigation bar
4. Go to the Apps tab and open the In Vivo Sync app
5. Select the Configuration sub-tab
6. Scroll to the relevant schema section (e.g., Study Schema, Animal Schema)
7. In the Metadata Mapping JSON box, enter the mapping in this format:

{"benchling_registry_field_API_ID": "in_vivo_slug_name"}

8. To map multiple fields, separate each field with a comma. For example:

{"tsf_QwyvJCyy": "coat_color", "tsf_QwovvJCoy": "arrival_date",}

9. Click Submit in the top right to save your changes

To remove custom metadata in the In Vivo Sync app:

1. In Benchling, click the Connection icon in the left navigation bar
2. Go to the Apps tab and open the In Vivo Sync app
3. Select the Configuration sub-tab
4. Scroll to the relevant schema section (e.g., Study Schema, Animal Schema)
5. In the Schema Field<> Metadata Mapping JSON box, remove the Benchling Registry field API ID and the In Vivo slug name for the field you want to delete
   1. You must know the Registry API ID and/or In Vivo slug name to identify the correct mapping
6. Ensure the remaining JSON syntax is valid or has empty closed brackets (e.g., {})
7. Click Submit in the top right to save your changes

To update custom metadata in the In Vivo Sync app:

1. In Benchling, click the Connection icon in the left navigation bar
2. Go to the Apps tab and open the In Vivo Sync app
3. Select the Configuration sub-tab
4. Scroll to the relevant schema section (e.g., Study Schema, Animal Schema) from which the metadata field will be removed.
5. In the associated Metadata Mapping JSON box, update the applicable JSON code for the relevant metadata field being remapped:

{"benchling_registry_field_API_ID": "in_vivo_slug_name"}
ex.) {"tsf_QwyvJCyy": "coat_color", "tsf_QwovvJCoy": "arrival_date",}

8. Press the submit button in the upper right-hand corner of the app. This step is crucial to save your changes.

Note: If you add, update, or remove a metadata field in the app, the corresponding data will not be backfilled, updated, or removed automatically. The data will only be added, updated, or removed if you perform an edit on a corresponding item in In Vivo or if you run a data backfill. To perform a data backfill, see Running a Backfill.

Control the availability of certain custom entity schemas as treatment sources

The In Vivo Sync app lets you limit which custom entity schemas from Benchling’s Registry can be used as treatment molecules in Benchling In Vivo. By default, you can select any custom entity that the integration has READ access to as a treatment molecule in In Vivo. Use the Treatment Schemas section of the app configuration to narrow this to entities of specific schemas and ensure users are selecting only designated custom entities as treatments.

To restrict treatment schemas:

1. In Benchling, click the Connection icon in the left navigation bar
2. Go to the Apps tab and open the In Vivo Sync app
3. Select the Configuration sub-tab
4. Navigate to the Treatment Schemas section
5. Select Add element
6. Use the dropdown to choose the desired entity schemas
7. Repeat steps 5 and 6 for each schema you want available as a treatment molecule
8. Click Submit in the top right to save your configuration (if you don’t see Submit, scroll to the top of the page)

Note: The In Vivo Sync app must have at least READ access to all schemas specified in the elements. If the In Vivo Sync app lacks READ access to even one schema, the treatment sync will fail as a whole. Update schema permissions in Benchling’s Registry as needed.

Generate registry IDs and entity names from a single naming template for select schemas

To reduce the number of identifiers for each object, you can configure one naming template per schema and apply it to both the registry ID and the entity name. You can apply this separately to the Study schema, the Animal schema, and the Sample schema in Benchling’s Registry. It ensures identifiers are consistent within each schema while keeping Registry and In Vivo aligned.

Use the following recommended naming templates to reduce the number of identifiers across tenants:

To generate registry IDs and entity names using a single naming template:

1. Navigate to the desired schema in Benchling’s Registry
2. In Available Registration Naming Options, check Generate Registry IDs and names according to name template
   • If this option is missing, contact Benchling Support to have the naming option Generate Registry IDs and names according to name template enabled
3. Navigate to the Connection icon in the left navigation bar
4. Go to the Apps tab and open the In Vivo Sync app
5. Select the Configuration sub-tab
6. Locate the schema you want to configure (Study, Animal, or Sample)
7. Check Generate Registry IDs and names according to name template
8. Click Submit in the top right to save (if you don’t see Submit, scroll to the top of the page)

Frequently asked questions

Q: Can I edit data in Benchling that was synced from In Vivo?

No. Always make edits in the system of origin to avoid data conflicts.

Q: Can I add custom metadata to Result schemas used in the In Vivo sync?

No. Only Registry schemas can be customized with additional metadata fields. Result schemas cannot be customized.

Q: What happens if I change a field type in the Registry schema?

Changing a field type may break the sync. Contact Benchling Support for help assessing the impact of changing a field type.

Q: Can I backfill only specific studies?

No. Backfills can only be performed using a specified reference date from which all events will be re-run.

Q: What should I do if my backfill fails?

Check the Activtiy tab of the In Vivo Sync app to see what events are failing and contact Benchling Support for help.

Q: Can I create computed fields on the schemas used in the In Vivo Sync app?

Yes. Computed fields can be created on Benchling Registry schemas used by the In Vivo Sync app. See the Computed Field Basics help article for details. Contact Benchling Support to configure computed fields.