The following example creates results in a demo environment.
In this example, assume we're in a lab running liquid chromatography. Scientists want to run LC, analyze the data with some third-party software, and record those data against samples that are already stored in Benchling. An example of some data is in this csv.
We will start by trying to create results in Benchling, and walk through the other APIs we will need to call along the way.
Note: This example assumes that your tenant has Lab Automation enabled. Without Lab Automation, the result upload steps will work, but associating those results with a run, and inserting that run into the notebook, will not.
You can import configuration using the "Import/Export" option shown below.
Once this has been imported, click on "No Environment -> Manage Environments". This will allow you to set environment variables. We will use two in this example.
base_url should be the URL for your Benchling tenant, followed by
api_key should be the API key for the account you would like to use (see Authentication for more details).
All the imported requests will use Basic HTTP auth with your api key. To access this yourself (or set it for new requests), you can open the second tab of any request.
Once Insomnia is set up, open the first request. This is an empty request to create results.
The body of this request has a list of
assayResult objects, which each have two top-level keys: one for the schema of the result, and one for a dictionary of all the fields associated with it.
Strictly speaking, the schema ID is the only property you need. However, you probably want to fill in at least some of the fields for your results as well (and, depending on your result schema, some of these fields may be required).
To fill in the result schema ID, you will list all result schemas, and pick the one that you want. Result schemas do not have their own endpoint; instead, one endpoint (
GET /assay-schemas) lists schemas for both results and runs. If you run the second request, you'll see all available schemas on the far right. If your environment has different schemas than the ones we're using in this example, you can use this endpoint to see what schemas you have, and what their fields are.
In this case, we're looking for the "Chromatography Result" schema. We'll find that object, copy its
id property, and paste that into the
schemaId property of the Create Results request above.
This request is usually something we'll just need to do once; after that, we can store the values we get as constants that our integration can use.
Runs in Benchling represent runs of an instrument. Typically a run will contain many results, measured against many different samples. While they aren't necessary to upload results, it makes managing them afterwards much easier.
To create a Run, open the Create Runs request. As with results, you will need the ID of the schema you want to use, along with any fields.
In our example, there is only one field to fill in, and it's text. The schema can be found in the
GET /assay-schemas response from earlier. This time, instead of looking for "Chromatography Result", we look for "Chromatography Run". The below image shows this information filled out.
The ID of the run is returned from this request, and should be copied for the next step.
After we fill in the schema ID, we can also fill in most fields.
The first field is a run link. We'll talk more about link fields later, but for now, paste in the run ID returned from the last step.
The next five fields shown all have primitive types (text, float, and date in this case). We can just fill these in with data from the spreadsheet of results, so we'll have something like the below.
The last two fields are link types. To fill in these, we'll need to look up or create the data we want to link to, copy the ID, and use that as the value.
The field definitions of the link fields are shown below (this is what we get from the
GET /assay-schemas endpoint. Notice that the
type property of all three is some kind of link. The name of this indicates what kind of object we need to link to.
The first link field to fill in is
chromatogram_file. This is a blob link, which is useful for uploading things like images.
To create our own blob link, we'll use the
POST /blobs endpoint. The Insomnia template has this endpoint pre-filled with an example graph from a chromatography analysis tool.
This takes a base64-encoded file, along with some metadata, and creates a file in Benchling. A unique ID is returned, which we can paste into the appropriate part of the Create Results endpoint.
Next, we'll want to link to the actual sample that was being measured. The ID in the spreadsheet is one that was generated for a registered entity.
First, we need to find the registry that the sample was registered into. This can be done by listing all registries with the
GET /registries endpoint, and finding the registry you're interested in. Run this, and copy the ID of the registry. If this was part of a larger integration, this ID could be saved as a constant, and referenced throughout.
Second, we need to use the
GET /registered-entities:bulk-get endpoint to look up the specific entity with the appropriate registry ID. This endpoint requires the registry ID to be filled in as a path parameter (the ID you just found), as well as a query parameter for
entityRegistryIDs. A filled-out version is shown in the image below. In the Insomnia template, you will need to replace
<registry_id> in the path with your registry ID.
From here, copy the
id of the returned entity, and paste it into the value for the
sample property of the result (Note:
id is not the registry ID.
id is a system-generated random ID that the API uses.)
After pasting in your run ID, you'll have all the data you need to fill out your Create Results request (as shown below). Click "Send", and you'll be all set.
Results created this way can be inserted into the Benchling Notebook, by inserting a run, and choosing "Insert from Inbox". This will let you see API-uploaded runs. Once you select it, all results uploaded to the run will appear.
After this, you're all set! Once you're comfortable making these calls in a language of your choice, you can try writing a tool to iterate through a CSV and make them for each line in it.
Updated 10 months ago