Benchling Integration: Migrating to Inventory Instances

Who this is for: labs that already use the Quartzy-Benchling integration. If you're setting up the integration for the first time, start with the Benchling Integration Setup Guide, then follow Steps 2 and 3 below.

The Quartzy-Benchling integration now supports inventory instances. Each instance of an item in Quartzy (with its own lot #, expiration date, location and quantity) now syncs to Benchling as its own registry entity, linked to its parent item.

To start syncing instances, a Benchling admin needs to make three changes:

  • Upgrade the Quartzy App in Benchling
  • Create a new instance entity schema
  • Map the Quartzy App to your new schema

Important: your integration keeps working while you make these changes. Until your lab is migrated, lot #, expiration date, location and quantity will temporarily stop syncing to Benchling. All other item data syncs as usual.

 

Migration Guide

Step 1. Upgrade the Quartzy App in Benchling

Version 1.1.0 of the Quartzy App adds a setting for your new instance schema. The upgrade happens in place, so you don't need to reinstall the app or re-grant its permissions.

  1. Find your Benchling tenant name in the URL when you're logged in (see bolded): https://TenantName.benchling.com/
  2. Insert your tenant name into the following URL, then copy/paste it into your browser: https://TenantName.benchling.com/app-catalog/apps/appdef_aUL4IYt2ga/install
  3. Click the Upgrade button
  4. Click View app in workspace (or go to Connections > Apps > Quartzy)
  5. Confirm the app shows version 1.1.0. If you see an Activate button, click it

Step 2. Create the instance entity schema

You'll create a second schema for instances by duplicating your existing Quartzy schema. Your original schema stays in place and continues to hold item-level entities. Each instance links back to its item.

Duplicate your schema

  1. Navigate to User Icon > Feature Settings > Registry Settings > Entity Schemas
    Navigating to Registry Settings.png
    Entity Schemas.png
  2. Open your existing Quartzy schema (e.g., Quartzy Items) and click Duplicate
    Duplicating Schema.png
  3. Configure the Prefix, Name and Entity Type as follows:
    1. Prefix: user's choice, e.g., qtz_inst
    2. Name: Quartzy Item Instances
    3. Entity Type: Custom Entity

Set up the entity fields

Your new schema already includes your item fields (Item Name, Vendor, Catalog #, etc.). Make sure it also has the fields below, and add any that are missing.
Registry Settings for Instances.png

Field Name Field Type Validation
Quartzy Instance ID Text Required
Quartzy Inventory ID Text Required
Parent Inventory Item Entity link to your original Quartzy schema (e.g., Quartzy Items) None
Lot # Text None
Expiration Date Text None
Location Path Text None
Quantity Text None

Note on locations: Quartzy now supports nested locations, so a single Location Path field (the item's full location path) replaces the old Quartzy Location and Quartzy Sub Location fields. Add Location Path to your new schema. You can archive the old location fields on the new schema.

Set the unique constraint and naming

  1. Under Unique Constraint, change the unique field from Quartzy Inventory ID to Quartzy Instance ID. Multiple instances share one inventory ID, so keeping the old constraint will prevent instances from syncing
  2. Edit the Name template to include Quartzy Instance ID, so each instance gets a unique name. Example templates:
    • inst - Quartzy Instance ID
    • [Item name] Vendor Name: Catalog # - Quartzy Instance ID
  3. Under Available Registration Naming Options, select "Generate new registry IDs, set names from name template"
    Registration Naming Options.png
  4. Save the schema

Step 3. Map the Quartzy App to your new schema

  1. In Benchling, go to Connections > Apps > Quartzy and click the Configuration tab
    Configuration Step.png
  2. Under Registry Mappings, in your existing mapping, select your new schema (e.g., Quartzy Item Instances) as the inventory instance schema
    Select Schema.png
  3. Select the matching schema field for each app field, including:
    • Quartzy Instance ID
    • Quartzy Inventory ID
    • Parent Inventory Item
    • Lot #, Expiration Date, Location Path and Quantity
    • Any other fields your team uses for naming or reporting
      Instance Schema Field Mapping.png
  4. Leave your existing Custom Entity Schema mapping (e.g., Quartzy Items) as is
  5. Save the configuration. If you see an Activate button at the top of the page, click it

What Happens Next

  • Until your lab is migrated: items keep syncing to your original schema. Lot #, expiration date, location and quantity pause until migration
  • After migration: the next time an instance is created or updated in Quartzy, it syncs as its own entity in your instance schema, linked to its parent item. Instances that don't change won't appear in Benchling until they're next updated
  • Your existing entries stay as they are: item entities already in your original schema are not changed or removed

Related: Benchling Integration Setup Guide

 

More questions? Contact us

Chris Tappe -
Have more questions? Submit a request

Comments