benchling-inventory

CLI tool to create storage hierarchy for sample inventory management via UI upload or API integration.

Background

Configuration of storage hierarchy is time-consuming and error prone. This solution aims to provide admins and integration specialists a csv output for upload via UI or automated API integration. Functions beginning with "write" will generate a CSV output and functions beginning with "post" are for API requests.

Usage

Authentication

A Benchling App is used to authenticate with the API. App must be configured and have the appropriate project and inventory permissions to write. See Getting Started with Benchling Apps.

boto3 is used to retrieve secret from AWS Secrets Manager. Assumes secret is already configured and role has IAM permissions to retrieve secret at runtime.

Assumptions

1. Supports a parent location schema (i.e. Upright Freezer or Liquid Nitrogen Freezer) with asset number from user input
2. Interior location names and barcodes are appended to the asset number following alphanumeric ordering (i.e. EQ-1234-S1 for EQ-1234 Shelf 1)
3. Assumes box schema remains the same throughout the entire storage unit. Box barcodes are autogenerated by Benchling.

Set Up

1. Update the class attributes returned by settings.py:env_variables per tenant. See below example:

class DevelopmentSettings(BaseModel):
    tenant: Literal["orgdev"]
    freezer_schema: str = "dev_freezer_schema"
    shelf_schema: str = "dev_shelf_schema"
    rack_schema: str = "dev_rack_schema"
    drawer_schema: str = "dev_drawer_schema"
    secret: str = "benchling-inventory"

2. Update the box schemas in settings.py:box_schema_id. Currently only 9x9 and 10x10 box schemas are implemented, however additional schemas can be supported by modifying/adding to settings.py:collect_input.

Implementation

The following prompts will appear at run, even if the API functions are disabled.

Specify the instance (dev, test, prod): dev

Using Racks or Canes? (Racks, Canes): Racks

Using Drawers or Rows? (Drawers, Rows, Neither): Drawers

Enter the asset tag :  EQS-1234

Enter the Location name. This is the refrigerator, freezer or LN2 : Floor A - Blue Freezer

Asset tag: EQS-1234
Location name: Floor A - Blue Freezer

Does this look correct? [y/N]

# N returns you to the prompt to re-enter the asset tag & location name.

How many shelves? : 4

How many [Rack | Cane]s per shelf? 5

# If [Drawer | Row] in `Using Drawers or Rows? `
How many [Drawer | Row]s per [Rack | Cane]? 5

How many boxes per [Drawer | Row]? 3

Select box dimensions:
1. 9x9
2. 10x10 : 1

# of Shelves: 4
# of Racks per shelf: 5
# of Drawers per Rack: 5
# of Boxes per Drawer: 3

Does this look correct? [y/N]:

# N returns you to the prompt to re-enter the # of shelves, racks, drawers, boxes, etc

CSV example outputs

Location	Barcode	Name
EQS-1234	EQS-1234-S1	Shelf 1
EQS-1234	EQS-1234-S2	Shelf 2
EQS-1234	EQS-1234-S3	Shelf 3
EQS-1234	EQS-1234-S4	Shelf 4

Location	Barcode	Name
EQS-1234-S1	EQS-1234-S1-R1	Rack 1
EQS-1234-S1	EQS-1234-S1-R2	Rack 2
EQS-1234-S1	EQS-1234-S1-R3	Rack 3
EQS-1234-S1	EQS-1234-S1-R4	Rack 4
EQS-1234-S1	EQS-1234-S1-R5	Rack 5
EQS-1234-S2	EQS-1234-S2-R1	Rack 1
...	...	...
EQS-1234-S4-R5	EQS-1234-S4-R5-D5	Drawer 5

Location	Name
EQS-1234-S4-R5-D5	Box 1
EQS-1234-S4-R5-D5	Box 2
EQS-1234-S4-R5-D5	Box 3

Requirements

Poetry is the package & dependency manager.

Setup & usage:

# Install dependencies
poetry install

# Activates virtual environment
poetry shell

Dependencies

benchling-sdk = "^1.13.0"
boto3 = "^1.35.3"
click = "^8.1.7"
pydantic = "^2.8.2"
python = "^3.12"

Tests

Pytest is the testing framework for running unit tests

pytest tests

References

Command Line Interface Creation Kit

Benchling SDK

Getting Started with Benchling Apps

Benchling API Reference