In Vivo Sync App Troubleshooting Guide

Introduction

This guide covers troubleshooting procedures for the In Vivo Sync App integration between Benchling In Vivo and Benchling Bioresearch. Read this section before beginning any troubleshooting steps.

How to Use This Guide

Review this Introduction section before navigating to the Glossary of Errors to locate the relevant error message.

Note: Certain triage steps require administrative access. Confirm that a Registry and Tenant Admin is available before proceeding. For an overview of the In Vivo Sync App and its configuration, refer to the "Configure the In Vivo Sync App" help article.

Prerequisites: 

The integration between Benchling In Vivo and Benchling Bioresearch requires a set of configuration prerequisites to be met. These are typically established during initial implementation. Verifying that all prerequisites are satisfied before troubleshooting is recommended, as unmet prerequisites are a common root cause of integration errors.

Bioresearch, In Vivo and App Configuration:

• Ensure the In Vivo Sync App is configured according to the "Configure the In Vivo Sync App" help article.

Data Interaction Guidelines:

• Some resolutions in this guide may require editing data. If you do not have Registry Admin access or Edit access to the In Vivo Schema sets, contact your administrator before proceeding.
• All data must be created in Benchling In Vivo so that it syncs properly.
• Unless a custom solution has been created, no user should be registering entities in Bioresearch under any of the In Vivo classified schemas involved in the In Vivo Sync App.

Glossary of Errors

To view Benchling Sync errors in your In Vivo Tenant, please see the "Use the In Vivo Sync app" help article.

1. Use the table below to find the error you could be experiencing.
   • ‘Ctrl+F’ (for Windows PC) or ‘Cmd+F’ (for Mac) to search the detailed error message. For errors that list an Entity ID, please leave out the Entity ID when searching. (For example, if your error is “Group grp_123 could not be found. If this exists, the error is due to permissions.”, please search “could not be found. If this exists, the error is due to permissions.”)

2. Once you have found an example of your error message or a similar message, identify the error category and the potential root cause. This will give you insight into potentially why the error occurred.

    

3. Of that given error category type, look at the suggested resolution column to identify the troubleshooting section(s) instruction(s) you should follow to resolve the error.

    

4. If your errors persist after trying the suggested resolution, please contact Benchling Support and state the error you're encountering and the troubleshooting steps you have already taken.

Updating Naming Templates

Please see the "Generate registry IDs and entity names from a single naming template for select schemas" section in the "Configure the In Vivo Sync App" help article for our recommended naming templates for schemas to be used with the In Vivo Sync App.

Context: Benchling does not allow multiple entities to share the same name. When the In Vivo Sync App attempts to create an entity whose name already exists in Benchling Bioresearch, a non-unique naming or duplicate entity error will occur.

If the affected entity's name follows the current naming template, the naming template must be updated to ensure each entity receives a unique name upon registration.

Instructions

1. Access Registry settings and navigate to the applicable schema
   1. Navigate to the Benchling Bioresearch tenant
   2. Navigate to your user avatar
   3. Select Feature settings
   4. Select Registry settings
   5. Select the schema of the impacted entity 
2. Update the naming template
   1. Hover over the name template
   2. Select the edit icon (pencil and paper)
   3. Click New Component to add new components as needed
   4. Click the X to the left of each component chip to delete that component. 
   5. Click set when finished

Note: The new naming template is only applied to entities created after the update is made. All existing entities will retain their original names until the corresponding entity is updated in In Vivo. Run a backfill of the object type from within In Vivo to automatically rename all entities according to the new naming template.

3. Retry sync events in the In Vivo Sync app
   1. Navigate to the Benchling In Vivo tenant
   2. Navigate to Manage Teams
   3. Navigate to the Integrations menu and select Benchling Sync 
   4. Click View # Errors in the top right to filter to only failed events.
   5. Select the checkboxes next to each relevant event or click the checkbox in the header row to select all 
   6. Click Bulk Actions and select Retry Sync Events 
   7. Click Retry Events to confirm that you would like to complete this action

After resolving the root cause, rerun the failed events. If a different error appears, restart the troubleshooting process for the new error.

If the same error persists after completing all troubleshooting steps, contact Benchling Support with the following:

• A screenshot of the detailed error message
• A description of the troubleshooting steps taken
• Permission to access your Benchling Bioresearch and In Vivo tenants, if applicable

Step 1: Access Registry Settings.

Go to avatar → ‘Feature Settings’ → ‘Registry Settings’

Step 2: Go to Naming Template 

• Navigate to the schema of the affected entity. 
• Hover over the ‘name template’ area. The ‘edit’ (pencil and paper) icon should appear.
• Click the ‘edit’ icon. 

Step 3: Update Naming Template

• In the ‘Set Entity Name Template’ modal, click ‘New Component’ to add new components as needed, and/or click the ‘X’ to the left of each component chip to delete that component. 
• When finished, click ‘Set’.

**Note** Naming template updates are applied only to entities created after the update is made. All existing entities will retain their names after the Naming Template is updated. Please be sure to update existing entities as necessary before re-syncing the In Vivo Sync App in the In Vivo tenant.

Step 4: Re-Sync Data from In Vivo

• In the In Vivo tenant, go to the ‘Benchling Sync’ page. Click ‘View # Errors’ to filter down to only failed Sync tasks. Select the relevant tasks by checking the checkboxes next to each task or by checking the ‘select all’ checkbox to the left of the ‘Status’ column header. Click ‘Bulk Actions’ and select ‘Retry Sync Events’. In the modal that appears, click ‘Retry Events’ to confirm that you would like to complete this action. 
• The selected errors should then clear. In some cases, a different error message may appear for affected Sync tasks. If this occurs, please click the error to access the detailed error message, search this error in the Glossary of Errors, and continue troubleshooting. If the same error persists after performing troubleshooting steps, please contact Benchling Support with a screenshot of the detailed error message, a description of the troubleshooting steps you have taken, and permission to access your BioResearch and In Vivo tenants, if applicable.

Updating Validation Rules

Context: It is not possible for the In Vivo Sync App to create entities that would fail validation, or to make updates to existing entities that would make these entities fail validation. Attempting to do so will result in a invalid field Error.

To resolve invalid field errors, you may either update the data entered in the In Vivo tenant to comply with the Validation rules set in Bioresearch, or update the Validation rules in Bioresearch to accommodate the data in the In Vivo tenant. Below are the instructions for updating the Validation rules. Please use step 2A for updating multi-select and/or required status, or step 2B for updating field definition.

Instructions:

Step 1: Access Feature Settings.

Go to avatar → ‘Feature Settings’ → ‘Registry Settings’

Step 2A: Check/update Multi-Select status or Required status for a field:

• Navigate to the schema of the affected entity.
• Hover over the affected field. Existing Validation Rules are shown in the ‘Validation’ column. A ‘settings’ (gear) icon should appear to the right of the ‘Validation’ column for the field.
• Click the ‘settings’ icon.
• In the ‘Validation rules’ modal, toggle the ‘multi-select’ and/or ‘required’ status to the appropriate value, then click ‘Save’.
• Continue to Step 3.

Step 2B: Check/update a field definition (field data type):

• Navigate to the schema of the affected entity.
• Hover over the affected field. The existing field definition is shown in the ‘Definition’ column. An ‘edit’ (pencil and paper) icon should appear to the right of the ‘Validation’ column for the field.
• Click the ‘edit’ icon.
• In the ‘Definition’ column, click the dropdown to choose the desired field type.
• Click the ‘check’ icon to the right of the ‘Validation’ column when you are done making changes.
• A warning message may appear. Please use the information in the warning message to decide if you would still like to continue with the Field Definition update. If so, click ‘Confirm’ to save the change.
• Continue to Step 3

Step 3: Re-Sync Data from In Vivo

• In the In Vivo tenant, go to the ‘Benchling Sync’ page. Click ‘View # Errors’ to filter down to only failed Sync tasks. Select the relevant tasks by checking the checkboxes next to each task or by checking the ‘select all’ checkbox to the left of the ‘Status’ column header. Click ‘Bulk Actions’ and select ‘Retry Sync Events’. In the modal that appears, click ‘Retry Events’ to confirm that you would like to complete this action. 
• The selected errors should then clear. In some cases, a different error message may appear for affected Sync tasks. If this occurs, please click the error to access the detailed error message, search this error in the Glossary of Errors, and continue troubleshooting. If the same error persists after performing troubleshooting steps, please contact Benchling Support with a screenshot of the detailed error message, a description of the troubleshooting steps you have taken, and permission to access your BioResearch and In Vivo tenants, if applicable.

Update In Vivo Sync App Configuration

Please see best practices guide for our recommended In Vivo Sync App configurations.

Context: Every type of data to be transferred from the In Vivo tenant to the BioResearch tenant must be mapped via the In Vivo Sync App Configuration. If a type of data (Animal, Sample, Measurement, etc.) or a metadata field from In Vivo is not mapped to the correct item, the data will not be transferred into BioResearch successfully, and an App Configuration Error, Parent Not Found Error, or Data Validation Error may occur.
 

Step 1: Check/Update App Configuration 

• In the BioResearch tenant, navigate to the In Vivo Sync App (Left Sidebar → Connections (folder icon) → Apps Tab → In Vivo Sync App), and, within the app, go to the ‘Configurations’ tab.

• Find the section named in the error - for example, for the error “Measurement results not found. Please review the app configuration.”, find the ‘Measurement Results’ section. First, check that the dropdown directly under the In Vivo Schema indicates the correct schema in BioResearch. If not, click the dropdown and select the corrected dropdown option. If the schema is correct and you’re still encountering an error, review the fields to identify if any fields are not mapping correctly. Click the relevant dropdown and select the corrected dropdown option.

• Scroll up to the top of the Configuration Tab page and Submit your changes.

Step 2: Re-Sync Data from In Vivo

• In the In Vivo tenant, go to the ‘Benchling Sync’ page. Click ‘View # Errors’ to filter down to only failed Sync tasks. Select the relevant tasks by checking the checkboxes next to each task or by checking the ‘select all’ checkbox to the left of the ‘Status’ column header. Click ‘Bulk Actions’ and select ‘Retry Sync Events’. In the modal that appears, click ‘Retry Events’ to confirm that you would like to complete this action. 
• The selected errors should then clear. In some cases, a different error message may appear for affected Sync tasks. If this occurs, please click the error to access the detailed error message, search this error in the Glossary of Errors, and continue troubleshooting. If the same error persists after performing troubleshooting steps, please contact Benchling Support with a screenshot of the detailed error message, a description of the troubleshooting steps you have taken, and permission to access your BioResearch and In Vivo tenants, if applicable.

Updating Dropdown Options

Please see Configure the In Vivo Sync App for how to add custom metadata with the In Vivo Sync App.

Context: 

Metadata fields within In Vivo can be configured as a multi-select custom field with reusable value sets used to standardize data entry. The multi-select options that appear within In Vivo must be configured in the Bioresearch tenant as dropdown options. Please note, dropdown options are case sensitive and all values must exist as a dropdown option in order to sync properly. 

Step 1.  Review Multi-select values in In Vivo Metadata page 

• Go to Glossary —> Metadata —> Animal —> Custom Fields

Step 2.  Confirm Multi-select values match dropdown options in Bioresearch 

• Go to Avatar → Feature Library → Registry Settings → Entity schema 
• Entity field name and metadata field name from In Vivo do not need to match exactly but ensure that all dropdown options do.

Step 3. Add missing values

• Click the ‘+’ icon next to Options.

Step 4. Confirm dropdown entity field is mapped to custom field from In Vivo. 

• Please see the Configure the In Vivo Sync App for more information on how to set custom metadata in the In Vivo Sync app.  

Step 4: Re-Sync Data from In Vivo

• In the In Vivo tenant, go to the ‘Benchling Sync’ page. Click ‘View # Errors’ to filter down to only failed Sync tasks. Select the relevant tasks by checking the checkboxes next to each task or by checking the ‘select all’ checkbox to the left of the ‘Status’ column header. Click ‘Bulk Actions’ and select ‘Retry Sync Events’. In the modal that appears, click ‘Retry Events’ to confirm that you would like to complete this action. 
• The selected errors should then clear. In some cases, a different error message may appear for affected Sync tasks. If this occurs, please click the error to access the detailed error message, search this error in the Glossary of Errors, and continue troubleshooting. If the same error persists after performing troubleshooting steps, please contact Benchling Support with a screenshot of the detailed error message, a description of the troubleshooting steps you have taken, and permission to access your BioResearch and In Vivo tenants, if applicable.

Updating In Vivo Sync App Permissions

Context: For the In Vivo Sync App to be able to create and edit entities in Benchling, it must have the appropriate permissions set. If the appropriate permissions are not set up properly it will result in an “Insufficient” permissions error, which will cause entities to not be synced through the integration. 

To remedy this, you must ensure that the best practice Permissions are deployed for the In Vivo Sync App.

Step 1. Check / Create the “In Vivo Sync App” Policy

• In Benchling Bioresearch, make sure that you have the ability to create custom access policies and have a specific Permission Access Policy for “In Vivo Sync”. If you already have this policy created please proceed to Step 2
• If you do not have the policy created please create the policy by
  • Navigating to Feature Settings --> Access Policies
  •  Following the instructions in the “Set permissions for the In Vivo Sync app” in the Configure the In Vivo Sync app article

Step 2. Deploy Custom Access Policy for In Vivo Sync App

• Deploy Permission Policy for Select Projects:
  • Navigate to the Project in which you would like to have In Vivo Entities synced to
  • Right-click the project and select “Settings”
  • Click Manage Access and add the “In Vivo Sync App” in the search bar
  • Change the permission setting dropdown to “In Vivo Sync”
  • Click “Save”

• Deploy Permission Policy for the General Registry
  • Navigate to your Avatar and select “Registry Settings” under the feature settings dropdown
  • Select the “General” section in the Registry search for the “In Vivo Sync App” in the users
  • Change the permission setting dropdown to “In Vivo Sync”
  • Click “Save”

• Deploy Standard permissions for each Entity and Result schema
  • Navigate to your Avatar and select “Registry Settings” under the feature settings dropdown
  • Select the “Entity Schemas” section and search for any of the In Vivo Entity Schemas
  • Click into the “Access Policies” sub-section and search for the “In Vivo Sync App” in the search bar
  • Change the permission settings to “Create” and select Add
  • Ensure that “Members of the Organization has a “READ” access policy and “Admins of the Organization” has an “ADMIN” access policy
  • Repeat for each In Vivo Entity Schema and Result Schema

Step 3: Re-Sync Data from In Vivo

• In the In Vivo tenant, go to the ‘Benchling Sync’ page. Click ‘View # Errors’ to filter down to only failed Sync tasks. Select the relevant tasks by checking the checkboxes next to each task or by checking the ‘select all’ checkbox to the left of the ‘Status’ column header. Click ‘Bulk Actions’ and select ‘Retry Sync Events’. In the modal that appears, click ‘Retry Events’ to confirm that you would like to complete this action. 
• The selected errors should then clear. In some cases, a different error message may appear for affected Sync tasks. If this occurs, please click the error to access the detailed error message, search this error in the Glossary of Errors, and continue troubleshooting. If the same error persists after performing troubleshooting steps, please contact Benchling Support with a screenshot of the detailed error message, a description of the troubleshooting steps you have taken, and permission to access your BioResearch and In Vivo tenants, if applicable.

Updating Data in Bioresearch

Context: There are sometimes a variety of errors that can occur if users are updating In Vivo entities and data manually in Bioresearch. Usually these occur when users are archiving and/or unregistering entities in Bioresearch and then trying to make updates to the corresponding objects in In Vivo. It is important that all updating of entities occurs in Benchling In Vivo only unless a custom solution is deployed. This will ensure that there is a limit of errors the integration will produce. 

Step 1: Unarchiving / Unregistering entity in Bioresearch

• Navigate to Benchling In Vivo and identify the error. Go to the Study in which the error was associated with and select the “Benchling Sync” section on the study
• For whatever did not sync over to Bioresearch, check and see if the error message falls under one of the following categories:
  • “Item not found” 
  • “Parent not found” 
  • “Duplicate Entity” 
  • “Unhandled Error: Registration Status”
  • “Entity Already Archived” 
• Once you have identified the error and the corresponding entity in In Vivo you will then need to navigate into Benchling Bioresearch and locate that entity 
  • Navigate to the project folder in which all of the In Vivo Entities are syncing to
  • Filter on the object type under “Type”
  • Set the filters for “Archived” → “All Archived” and/or “Registration status” → “Unregistered”

*Note* for the “Parent not found” error type you may need to locate the parent object i.e. if an Animal Sample has this error you will need to locate the error of the “Animal” which is the parent object of the Animal Sample!

• Unarchive and re-register the entity where applicable
• For “Duplicate Entity” error, rename existing duplicate entity then re-archive item

Step 3: Re-Sync Data from In Vivo

• In the In Vivo tenant, go to the ‘Benchling Sync’ page. Click ‘View # Errors’ to filter down to only failed Sync tasks. Select the relevant tasks by checking the checkboxes next to each task or by checking the ‘select all’ checkbox to the left of the ‘Status’ column header. Click ‘Bulk Actions’ and select ‘Retry Sync Events’. In the modal that appears, click ‘Retry Events’ to confirm that you would like to complete this action. 
• The selected errors should then clear. In some cases, a different error message may appear for affected Sync tasks. If this occurs, please click the error to access the detailed error message, search this error in the Glossary of Errors, and continue troubleshooting. If the same error persists after performing troubleshooting steps, please contact Benchling Support with a screenshot of the detailed error message, a description of the troubleshooting steps you have taken, and permission to access your BioResearch and In Vivo tenants, if applicable.