Table of Contents

Purpose 

Introduction

File Format Requirements Specifications 

Applications: 

     1. Picking (new entity creation): 

     2. (Optional) Record Picking Data (results capture): 

Steps within Benchling 

Create Custom Entity Schema for Colony Picks 

Configure Run Schema for Qpix File 

Revision History

Purpose 

To provide details about the necessary steps to implement the Qpix Connector for use with the Benchling Connect platform.

Introduction

Connectors allow Benchling to read a file generated by an instrument and take inventory actions in Benchling or record measurements. Benchling connectors use Allotrope Simple Models (ASM) where possible. This guide provides a non-ASM approach to Connect instruments with Benchling until ASM models or Benchling ASM converters exist.

Connector guides describe the required file format, Benchling configuration steps, and outcomes supported by the connector.  The connector is specific to a single file format and a single type of assay. Your file must meet the requirements described below to be compatible with the instructions that follow. If it does not, it may be possible to adjust your file and the steps to support your instrument’s file format or it may not. Please reach out to your Benchling representative or support@benchling.com for assistance. 

File Format Requirement Specifications: 

• Your export file must be a .CSV or .XLSX formatted file with one tab. 
  • If multiple tabs are present, only the first tab will be processed and others will be ignored. 
• Your Qpix file contains a single data table that either:
  • Starts with column headers in row 1 and data in the following rows.
  • Starts with headers that are a consistent length. I.e. we can always remove the first n rows and after doing so the data table will begin in cell A1.

• Your data table contains columns (exact names can differ) including:
• Required* columns:
  • Source Barcode*
  • Source Well*
  • Destination Barcode*
  • Destination Well*
• Optional columns (examples, but not limited to):
  • Feature position X and/or Y coordinates
  • Area, Perimeter, Diameter, Compactness etc.
• The values in the source and destination barcode columns must be a plate or container in Benchling Inventory. 

Applications:

1. Picking (new entity creation):

• What the connector will do:
  • Create new entities to represent picked colonies (linking to the source entity through an entity link schema field).
  • Transfer the new entities to the destination plate's specified well positions.
• Optional column values will be ignored.
  
  

2. (Optional) Record Picking Data (results capture):

• The file’s additional (optional) columns may be recorded as results data associated with the newly created sample in the destination plate. 
• What the connector will do:
  • Record results data for the selected columns against the sample created in the Picking application.

Steps within Benchling 

From within Benchling, a user must:

1. Enable the Generic FileWatcher adapter on the tenant [internal admin console - for non Benchling employees, please reach out to Benchling Support for assistance]

2. Create a FileWatcher Connection schema

3. Configure a FileWatcher Connection

4. Create (or select an existing) Custom Entity Registry schema to represent the picks into the destination plate. 

5. (Optional) Create a Result schema to structure the data to be recorded

6. Configure a Run schema to accept data from [Instrument Name] and create the new entities (and records Results)

For steps 1 - 3, please reference the Benchling Connect Installation Guide for details related to creating and installing a Gateway and configuring a Connection.

Create Custom Entity Schema for Picked Colonies

The Benchling Connect - Qpix connector uses Benchling’s built-in transform steps to structure the information parsed from the Qpix file export. The data are processed to trigger corresponding Registry and Inventory actions. 

Create a custom entity schema to represent the new entity to be created in the plates into which the Qpix will pick. You do not need to create a new entity schema if one already exists that you would like to use for this purpose. 

Configure Run Schema for Qpix File

• Create a new Run schema. 
• Select the Benchling FileWatcher connection schema.
  
• Click next then next to “Output file configurations” click + 
• Set a custom name and select: 

• “Register and/or update entities” 
• “Transfer samples” 
• “Record results”

• Under “Entity schema” select the schema you plan to use.
• Under “Inventory schema” choose if the destination plates (into which the Qpix will pick) will already exist in Benchling when the run is processed or if Benchling should create them based on the barcodes in the file. 
• (Optional) Under “Result schema” select the results schema you would like to use or “Create new result schema” then “Copy column headers from file” > “From example file”
  • Copy your data table from an example file and paste in. Assign the detected column headers to their Benchling purposes. 
  • Set data columns like “Area” to “New result schema field”
  • Click Create result schema then Name your result schema and click Next. 
  • You may need to adjust the data types or add fields such as “Sample.”
    
  • Select “Create result schema”
    
  • Select “Done”
• If your file does not have headers, skip this step. If your file has headers, click “set transforms:
  • Select Type > Extra headers
  • In the “Row number of column header” box, type the row number where the data table begins. In the above image for example you would choose “9.”
• Under “Configure column mapping” choose to specify either “by column order” or “by column name”
  • “by column order” assigns the columns to their purpose based on position so if column header names change the run will still work. Additional columns not specified will be ignored. 
  • “by column name” assigns the columns to their purpose based on exact match to the column header name. Columns not exactly matched will be ignored. 
  • Then (if you skipped step 6) set the columns to map to your source plate (the plate from which the Qpix will pick) and source well position; and destination plate (plate into which the Qpix will deposit picked colonies) barcode and destination well positions.
    
  • Click “Update” and your run is complete. 
  • Create a connection to the FileWatcher into which files from this instrument will be saved and add the run you created to your Notebook Entries and templates to select and process the file to take the corresponding actions in Benchling. 

Revision History

• 2024/04 Initial Version

Appendix

Full requirements to be attached to SOWs with non-ASM connectors included. 

General Connector Caveats

• The data described above will be recorded as raw data in a new or existing registry or results schema formatted as described.
• Analysis or transformation of any data within the file is not included in the connector itself and will be handled as a separate workstream leveraging Insights, Analyses, or Notebook  features such as tables. 
  • As part of an Implementation Project, effort to manipulate, analyze, validate, verify, or transform data after it is recorded to the raw results schema is separate and additional to connector configuration effort. Any such effort must be accounted for independently or addressed by the Customer independently.
• Benchling Connectors that rely on Benchling’s native file processing features are not specific to an instrument and software version combination. They are specific to a particular file format and use case. 
• Files that are similar to but not expressly supported by the requirements described above may still be able to be supported by native Benchling functionality with adjustments to the above instructions. For such cases, additional scoping is required to confirm feasibility and effort. Additional Implementation Project time will be required to adjust configurations to accept such formats. 

Qpix Caveats

• Customer’s Qpix file must be formatted as described above. 
• Customer may create and transfer new Registry entities alone or may do those steps and record results. Other actions such as creating entities without transferring or transferring without creating new entities are not supported by this connector. 
• Customer’s Qpix file must contain barcodes that are represented by already existing plates in Benchling or, for the destination plate, plates that do not yet exist but can be uniquely created as a unique Benchling plate barcode for each run. i.e. placeholder values cannot be used on multiple runs.