Note: Quartzy's Benchling integration is included in Professional, Enterprise, and Non-Profit subscription plans, or as an add-on to the Starter plan.
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!
- 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 email@example.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 firstname.lastname@example.org for assistance
Important: this process (all steps) must be done separately for both the sandbox environment for testing, and the production environment for deployment.
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
- Catalog #
- Lot Number
- CAS Number
- Unit Size
- 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|
|Status Lifecycle||Direct Completion||N/A|
|Default task group folder||Quartzy Orders||N/A|
Entity link to desired schema or any entity, depending upon desired schema configuration
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".
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.
(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.
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 email@example.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.