Premium Feature — Available with the Enterprise Edition of LabKey Biologics LIMS. Learn more or contact LabKey.

Batch Design

Batches represent a specific quantity of a given mixture. The mixture is a virtual entity, i.e. a recipe, used to create a real, physical batch of material. The design of the Batch, meaning the fields, properties, and naming pattern, is set by default to provide commonly used fields and defaults, but can be edited using Manage > Edit Batch Design.

For example, batches include fields for tracking expiration date, amount, and units for that amount, making it possible to track inventories and efficiently use materials.

See details in the instructions for creating a sample type design here: Biologics: Create Samples


To create a new batch, click Add above the batches grid, or select Create > Mixture Batch from any mixture detail page to include that mixture in your batch.

The steps in the batch creation wizard are similar to those in the mixture wizard.


On the Details tab, complete all required fields and any option fields desired. If the Batch Name is not provided, it will be automatically assigned a unique name using the naming pattern for Batches. Hover over the for any field to see more information.

Click Next.


On the Ingredients tab, each ingredient row is disabled until you add a Desired Batch Yield and Unit. Once selected, the rest of the page will become enabled and populate information.

Enter the exact amounts of which raw materials were used to create the mixture recipe. (If ingredients and/or amounts are unknown, see options below.) For each raw material, specify a source lot by its id number. An administrator can enhance the details show to users in this dropdown as described below.

Each ingredient in the recipe may have one or more source lots of raw material This is useful when you exhaust one lot and need to use a second lot to complete the batch. For example, using 40g of Potassium Phosphate empties a lot, if the next lot contains 45, you would need an additional 15g from another lot to reach the target amount of 100g shown in the following. Add additional lots by clicking Add raw material for the specific ingredient.

Note that if one or more raw materials are indicated, the option to set an amount or raw material as unknown is no longer available.

You can also add ingredients (or other mixtures) as you register a batch. Click Add ingredient at the end of the ingredient list.

For each preparation step in the mixture recipe, the user can enter any preparation notes necessary in creating this particular batch. Notes are optional, but can provide helpful guidance if something unusual occurred with the batch.

Once all required fields are filled, the Next button will become clickable.


The confirmation step allows the user to view the information they have entered. If necessary, they can click back to return to previous tabs to make any updates. Preparation notes are collapsed, but can be expanded by clicking the right-arrow icon.

Click Finish to register this batch and see the row as entered in the grid.

If multiple raw materials were used, the batch details panel will display material lot numbers and the amounts used.

If additional ingredients were added to the batch, these modifications from the mixture recipe will be noted in a panel:

Amounts and Units

The amount, and units for that amount, are determined from the Batch Yield details provided on the Preparation tab. Three fields are stored and visible:

  • Recipe Amount (RecipeAmount) : The amount, i.e. "Desired Batch Yield". This value is stored as a property on the run that created the batch. Note that this field is not editable as it is not a property of the batch.
  • Recipe Amount Units (Units and also RawUnits): The units value for the Recipe Amount field.
  • Recipe Actual Amount (StoredAmount and also RawAmount): The "Actual Batch Yield".

Note that if you have existing data prior to the addition of the Amount and Units default fields in version 23.4, the combined amount-with-units field will be parsed into the two fields. If we cannot parse that text field (such as in a case where the units value is not supported) the two fields will be left blank and need to be manually populated.

Registering Batches with Unknowns

When registering batches, the Ingredients step includes the option to mark:

  • all materials as unknown
  • individual raw materials as unknown
  • individual amounts as unknown
This is useful when adding vendor supplied batches to the registry, where you may not know specific details about the vendor's proprietary materials and/or amounts.

If you select Known for Materials/Ingredient Source, you can also select whether Amounts/Raw Materials are all Known, or one or more may include Unknown amounts.

To disable all material and amount inputs, click to set Materials/Ingredient Source to Unknown.

Confirmation warnings are provided if the user provides incomplete values and an 'unknown' box is not ticked.

Once entered into the registry, the unknown factors are reflected in the user interface.

Bulk Registration of Batches That Include Unknowns

In bulk registration of Batches, some fields support the text "unknown" on import. For details, see Bulk Registration of Entities.

Aliquot Batches

Instead of having to register sub-portions of mixture batches in advance, you can create large batches, then later create aliquots from them. You can specify the Aliquot Naming Pattern by editing the Mixture Batch Design. The default name of an aliquot is the name of the parent batch, followed by a dash and a counter for that parent. Learn more here: Biologics: Create Samples

Select one or more Batches from the grid and choose Derive > Aliquot Selected.

In the popup, as for creating sample aliquots, enter the number of Aliquots per parent to create, then click Go to Mixture Batch Creation Grid. Aliquots of mixture batches will be shown in the same grid as the original batch(es). Include the IsAliquot column in your grid view if you want to be able to filter for aliquots.

Add Detail to "Raw Materials Used" Dropdown

The "Name" of a Raw Material is it's generated ID; these are not particularly helpful to users selecting the raw materials for a batch. By customizing raw materials with a lookup view, administrators can provide their users with the necessary details when they select from the dropdown.

  • To customize the "Raw Materials Used" dropdown, first switch to LabKey Server by selecting > LabKey Server > [Name of your Biologics home project].
  • Open the schema browser via: (Admin) > Go To Module > Query.
  • Select the samples schema, RawMaterials table.
  • Click Edit Metadata.
  • Scroll down and click Edit Source.
  • On the XML Metadata tab, add the following:
    <tables xmlns="">
    <table tableName="RawMaterials" tableDbType="NOT_IN_DB">
    <column columnName="Name">
    <column columnName="lotNumber">
    <column columnName="productNumber">
Users in the Biologics LIMS interface will now see additional detail to help them match the raw material they are using.

Use the Recipe API to Update Batches

Batches can be updated after they are created by using the Recipe API. You can make these updates using PUT requests to recipe-batch.api:

  • Mutation of materials and their associated metadata.
  • Mutation of amount, amountUnits, and actualAmount of produces.
  • Comments
Batches cannot be updated in the following ways:
  • Changing which sample is produced.
  • Changing the source recipe (mixture).
  • Changing the batch steps. Use the pre-existing recipe-notes.api endpoint if you're looking to edit these.
Use the dryRun boolean flag for pre-validation of changes without actually updating the recipe. Calling the endpoints with dryRun when experimenting/investigating will go through all the steps of validating the updates and updating the batch but it will not commit these changes. It returns what the updated batch would look like if committed.

The general steps for using the Recipe API for Batches are:

  1. Call recipe-getBatch.api and receive the full mixture batch definition.
  2. Mutate the received object in the way you'd like (change materials, amounts, etc.).
  3. Remove things you do not want to mutate (e.g. "produces", etc.) or similarly copy to a new object only the properties you want to mutate.
  4. Call recipe-batch.api and PUT the mutated object on the payload as the batch.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all