Benchling Integration Setup Guide

The Quartzy-Benchling Integration allows users to quickly and easily sync data between Benchling and Quartzy. With the integration, users can:

• Create new order requests in Quartzy without leaving Benchling 
• Automatically sync new inventory items from Quartzy to Benchling  
• Automatically sync changes/edits to inventory items from Quartzy to Benchling 
• and more! 

Read below to find out how to integrate your lab's Benchling account with Quartzy! 

Prerequisites

• The user that sets up the integration should be a Lab Admin in the Quartzy Lab that's being integrated and have Benchling Registry and Organization Admin permissions in their Benchling tenant. This user should have the same login email address for both Quartzy and Benchling. 
• Contact support@benchling.com or your Benchling account team to request they turn on the Quartzy integration feature flag for your organization's account 
• [Optional] Benchling Inventory Licenses
  • Necessary for tracking granular inventory within Benchling
• [Optional] Benchling Workflows Licenses 
  • Necessary for creating a request in Quartzy from Benchling
• Ensure the following features are enabled in your Benchling tenant:  
  • Access to the Developer Platform via User Icon > Feature Settings > Developer Console
  • Access to the Connections & Apps feature via the left navigation bar (folder with small circle icon; last option in the navigation bar)
  • Access to the Registry via the left navigation bar
  • [Workflows only] Access to Workflows via the left navigation bar
  • If you do not have access to the necessary features in Benchling, reach out to Benchling customer support at support@benchling.com for assistance

Benchling Configuration 

 

1. Create the following in your Benchling account:

A. Project: Quartzy Integration

• Folder: Quartzy Entities within the Quartzy Integration Project

• • This folder will contain all entities of items synced from Quartzy to Benchling 
• [Optional] Folder: Quartzy Orders within the Quartzy Integration Project 
  • Optional: this step is only required for users that would like to submit Quartzy requests from Benchling 
  • This folder will contain all Quartzy Order workflow tasks created in Benchling 

B. Registry Entity Schema: Quartzy Items. This will be the main schema for all items brought over from Quartzy. 

• Prefix = user's choice 
  • One option is "QTZ" as shorthand for Quartzy
• Name = Quartzy Items 
• Entity Type = Custom Entity 
• Containable Type = Entity 
• Add the following Entity fields: 
  • Item Name
  • Vendor
  • Catalog #
  • Lot Number
  • CAS Number
  • Type
  • Unit Size 
  • Quantity
  • Price (USD)
  • Quartzy Location
  • Quartzy Sub Location
  • Quartzy Product ID
  • Quartzy Lab Name
  • Quartzy Lab ID
  • Quartzy Inventory ID = REQUIRED
  • Quartzy URL
  • Lot number
  • Expiration Date
  • Technical Details 
• Constraint = Quartzy Inventory ID  
• Once you've created the schema, open it, and click Set Name Template. This will ensure consistent, informative names are created for the Quartzy inventory items in Benchling. Here are some example naming templates: 
  • • Item name : Vendor Name : Catalog number
    • [Lab Name] Item name : Vendor Name : Catalog number
    • [Item name] Vendor Name : Catalog # - Quartzy Inventory ID 
    • Once the Name Template is set, select "Generate new registry IDs, and replace name according to name template" from Available Registration Naming Options 

C. Workflows Task Schema: Add Request in Quartzy.

[Optional] This step is only required for users that would like to submit Quartzy requests from Benchling. This will be the Task Schema used to sync order requests from Benchling to Quartzy.  

• • From the bottom of the page, click Remove Output Schema  
  • The table below highlights the configuration of the Workflow. Field names/values must match exactly as written in the table. 

Component	Field Name / Value	Field Type
Task Group Prefix	QZOrd	N/A
Name	Quartzy Order	N/A
ID Prefix	QZ	N/A
Execution Type	Direct	N/A
Status Lifecycle	Direct Completion	N/A
Default task group folder	Quartzy Orders	N/A
Responsible Team	None	N/A
Assignee	Checked	N/A
Flowchart only	Unchecked	N/A
Task field	Quartzy Item*	Entity link to desired schema or any entity, depending upon desired schema configuration
Task field	Date Required*	Date
Task field	Quantity*	Decimal
Output fields	None	N/A

The asterisk (*) denotes required fields 

2. Upload the Quartzy App Manifest to Benchling

In this step, you will follow the steps mentioned in the sub-section "In Quartzy" and then navigate to Benchling where you will follow the steps mentioned in the sub-section "In Benchling".

 

In Quartzy

You have two options here:

(A) If you want to sync ALL Inventory Types in your lab from Quartzy to Benchling, then save this file linked below. 

• • • https://info.quartzy.com/hubfs/Quartzy-Benchling%20integration/quartzy.yaml 

(B) If you want to sync only certain specific Inventory Types in your lab from Quartzy to Benchling, then follow the steps mentioned below

• Back in your Quartzy account, navigate to Manage Labs > Developers 

• In the Quartzy-Benchling Integration section of the Developers page, select the individual Inventory Types from your lab in Quartzy that you would like to automatically sync to your Benchling Registry. 
• Once you have selected your desired Inventory Types, click the Download App Manifest button to save the file to your computer. 

In Benchling: 

• Select User Icon > Feature Settings > Developer Console

• Navigate to Apps, select Create > From Manifest 

• Upload the Quartzy App Manifest (the .yaml file) you just generated 

• Select Create 
  • The app will be created with the name Quartzy Sync 

3. Configure the Event source:

[Optional] This step is only required for users that would like to submit Quartzy requests from Benchling. 

• Select User Icon > Feature Settings > Developer Console
• Navigate to Events, select "+" 
• Specify the following information: 
  • AWS Region: us-west-2
  • AWS Account ID: 183060441923
  • Event Bus Name: quartzy-sync
  • Event Type: v2.workflowTask.created

4. Establish permissions

A. Project Permissions 

• Navigate to the Quartzy Integration Project created in Step 1 

• Right click > Settings
• Add Quartzy Sync with WRITE permissions
• Select Save 

B. Registry Permissions 

• Navigate to User Icon > Feature Settings > Registry Settings

• Select General

• Add the Quartzy Sync app to the collaborator list and grant WRITE permissions 

• Select Update Collaborators 

C. Tenant and Organization Permissions 

• Navigate to User Icon > Organization

• Select Apps

• Add the Quartzy Sync app as a member of the organization

D. Schema Permissions

[Optional] Prevent registration of items outside of the integration.

• Navigate to the Quartzy Items registry schema

• Select Access Policies

• Add the Quartzy Sync app to the collaborator list and grant CREATE permissions 

• Set all other collaborators in the list to READ permissions, keeping the ADMIN unchanged 

5. Map the integration to the appropriate Benchling Schemas

• Navigate to the Connections page using the left navigation bar 

• Select Apps > Quartzy Sync

• Under the Folder section, specify to which Project or Folder you would like the entities to belong. Note that these entities will belong to the Registry, but will also be associated with the Project or Folder which you specify here.

• Under Custom Entity Schema, specify the Quartzy Items schema

• Map the metadata fields: 

  • Under the Fields section, on the left, Quartzy item metadata is listed as stagnant text. On the right, the available Benchling metadata on the specified schema is listed in dropdown menus.

  • Per row, specify which Benchling entity field should be used to hold the corresponding Quartzy item information.

  • Each Benchling entity field can be selected no more than once. If the Quartzy item information is not desired, select No Field from the dropdown menu.

• Specify the desired Completed Task Status. This will determine what the Task status in Benchling is updated to when the order is created in Quartzy. 

  • We recommend selecting Completed 

6. Install the Integration

• Navigate to the Connections page using the left navigation bar

• Select Apps > Quartzy Sync > Activate 

• Email support@quartzy.com with the subject “Benchling integration details” and include your Quartzy lab's name, and the URLs for your Benchling Staging/Testing and Production instances (ex: quartzytest.benchling.com and quartzy.benchling.com). The Quartzy team will get back to you after confirming that your setup is complete. 

  • Workflows only: also include in the email your Event Source Name and a list of users who would need access to creating Quartzy requests in Benchling 

Once confirmation is received from the Quartzy team, the integration should be running between Benchling and Quartzy!

• Follow this user guide to start using this integration.
• Be sure to test the behavior by monitoring the receipt of items in Quartzy and the creation of corresponding entities in Benchling.
• If using workflows, test to be sure orders are being pushed from Benchling to Quartzy. 

 

Next Up: Learn how to utilize the Quartzy-Benchling integration

 

More questions? Contact us