If you are migrating from using another system, you can take advantage of bulk import and update options to move existing storage information for Samples into LabKey Storage Management.

• Define Storage
• Templates for Sample Storage
• Data Format Requirements
• Adjusting Storage Fields to Match Other Systems
• Import of Samples with Storage Location Data
• Work with Stored Samples

Define Storage

You can create all the virtual storage you need in Sample Manager or Biologics LIMS first, or you can define new storage 'on the fly' during import of new samples from a file.

To define storage up front, follow the steps in the following topic, taking care to use the naming and layout that will match the pathways to storage locations that will be present in the data coming from your previous system.

• Create Storage

Naming of storage, structures, and terminal locations like boxes and bags is flexible enough to match the system you were using. If necessary, you can also create custom storage unit definitions as needed. Such storage unit definitions can be specified by name in the "Storage Unit" column when adding new storage in a file.

Templates for Sample Storage

Once you have defined your storage, the next step is to create the Sample Types you will be storing, if they don't already exist in the system. You can use a combination of field inferral from spreadsheets and manual refinement to match the types of samples you have stored.

• Create a Sample Type

Once your Sample Type exists, whether or not it contains Samples, download an import spreadsheet template from the Sample Type dashboard as described here:

• Data Import Guidelines

In addition to the fields defining your Sample data and fields representing any parent or source import alias(es), the template will include fields related to storage including:

• StoredAmount
• Units
• FreezeThawCount
• StorageLocation (A slash-delimited "path" to the terminal storage location - see below)
• StorageRow
• StorageCol
• StorageUnit (Required when defining new storage during import)
• EnteredStorage (Date)
• CheckedOut (Date)
• CheckedOutBy (UserID)
• StorageComment

Data Format Requirements

• StoredAmount
• Must be a number.
• May be negative.
• Units
• Must be one of the supported unit types listed here.
• May be supplied as either the full plural name (e.g., "grams") or the abbreviation (e.g., "g"). Casing matters.
• If the Sample Type has a default unit type provided, the units must be convertible to this unit type. (e.g., "g" and "kg" are convertible, "g" and "mL" are not).
• Note that if a value for "Units" is included in your import spreadsheet, you must also provide a storage location, even if the "StoredAmount" is blank. To import a mixed set of samples, some of which have storage locations and some of which do not, be sure to remove the value from the "Units" column for any samples not in storage.
• FreezeThawCount
• Must be a non-negative integer.
• StorageLocation
• Must contain valid names of locations in a hierarchy separated by slashes (/), for example:
• Freezer #3 / Shelf #1 / Box #1 - Green
• Names of locations may contain slashes, but if so, then they must be quoted.
• Leading and trailing spaces are tolerated and trimmed.
• A leading or trailing slash is tolerated.
• If any storage locations in this path do not exist, they will be created in the background (provided the entire sample import succeeds).
• StorageRow
• Must be either a positive integer or one of a series of letters (A-Z, a-z). Casing does not matter for the letters.
• DOES NOT check if the display format for the box type corresponds to the format provided as input. That is, if you’ve chosen to label your axes as Numeric, you can still provide alphabetic designations for the row value (A for row 1) in the input file.
• Must be in the range of the chosen terminal storage type (cannot be < 0 or larger than the number of rows configured for the terminal storage type).
• StorageCol
• Must be blank if the terminal storage type is a bag or a cane.
• If not blank, must be either a positive integer or one of a series of letters (A-Z, a-z). Casing does not matter for the letters.
• DOES NOT check if the display format for the box type corresponds to the format provided as input.
• Must be in the range of the chosen terminal storage type.
• StorageUnit
• If you are creating any new storage, this field must be populated for the first row of the new storage unit.
• The value must match the name of an existing storage unit type.
• EnteredStorage
• Must be a valid date or date-time value.
• Represents when the sample was stored in the physical storage system.
• If omitted, the time of the data import, i.e. the time of entering the management system is used.
• CheckedOut
• Must be a valid date or date-time value.
• If omitted and a CheckedOutBy user is provided, the current date will be used.
• CheckedOutBy
• Must be a valid email address, username, or userID for a user in the system with sufficient permissions to check out samples. Learn about adding users here: User Accounts, Groups, and Roles.
• Leading spaces and quote marks are not tolerated.
• If omitted and a CheckedOut date is provided, the sample will be checked out by the user importing the data.
• StorageComment
• Always optional.
• Will be ignored if the action for the import is not checking in, checking out, or discarding.

Adjusting Storage Fields to Match Other Systems

Examine the export spreadsheet from your previous storage system. It likely includes similar columns, potentially requiring name changes or other adjustments to match the expectation of the template you generated.

This section will also be helpful if you are updating sample data to change storage-related fields from a spreadsheet or using the API. Some fields, such as StorageStatus cannot be user-set. They are determined by the presence or absence of values in other fields.

Modify your exported data as needed, noting the following requirements for recording specific sample actions in the system:

Add a sample to storage

• The StorageLocation and StorageRow columns must be present and valid.
• If adding to a Box, the StorageCol column must be present and valid.
• If adding to a Bag, the StorageCol column must be absent or empty.
• Other fields may be present but are not required.

Add a sample to new storage created in this row of the spreadsheet

• The StorageLocation column must be present and contain the path ending in the new terminal storage for this sample. Any locations along this path, including the freezer itself, will be created if they don't exist.
• The StorageUnit column must be present and the value must match an existing storage unit type.
• The StorageRow columns must be present and valid.
• If adding to a Box, the StorageCol column must be present and valid.
• If adding to a Bag, the StorageCol column must be absent or empty.
• Other fields may be present but are not required.

Discard a sample that is in storage

• SampleId column must be present and not empty.
• At least the StorageLocation column must be present and empty.
• If the StorageRow and StorageCol columns are present they should also be empty.
• No other storage metadata columns should have values.

Update the metadata of an item in storage

• SampleId column must be present and not empty.
• The corresponding metadata columns should be present.
• If the StorageLocation column is present, the StorageRow must be present and, when updating items in a box, the StorageCol column must also be present. All columns must have valid values. If updating items in a bag, the StorageCol column value should be empty if present.

Move a sample to a different location

• SampleId column must be present and not empty.
• The StorageLocation column and the StorageRow column must be present with valid values. If moving to a Box type, the StorageCol column must also be present with a valid value. If moving to a bag, the StorageCol column must be empty if present.

Check out a sample that is currently in storage: Here the behavior is slightly different than for the other actions because there are two columns involved and we allow a user to shortcut supplying one of the columns in order to use the current date or user for all the rows in the file.

• SampleId column must be present and not empty.
• Either the CheckedOut or the CheckedOutBy column must be present and not empty.
• If the CheckedOut column is valid and the CheckedOutBy column is empty/absent, the item will be checked out by the current user.
• If the CheckedOutBy column is valid and the CheckedOut column is empty/absent, the item will be checked out by the user in the CheckedOutBy column using the current date.
• If both the CheckedOut and the CheckedOutBy columns are present, they must both have valid values.
• If both the CheckedOut and the CheckedOutBy columns are empty, the system will not recognize this as a checkout action.

Check in a sample that is currently checked out

• SampleId column must be present and not empty.
• One of the CheckedOut or CheckedOutBy columns must be present and empty.

Storage Comments: The StorageComment will be attached to the operations that are happening for the import if the operation is also one the user can comment on in the UI. That is, for check out, check in, and discard actions, the comment will be attached. Otherwise, the comment will be ignored.

Notes:

• Note that with a file import, it is possible to perform multiple operations at once. For example, you may provide a row that both checks a sample out and moves it to a new location. For samples, there will be two timeline events created for this. There is no guarantee about the order of these events in the timeline.
• Since updating of storage happens only via sample import, there will always be a “Sample update” timeline event, even if nothing in the sample actually changed.
• If you are importing data for a set of samples in which some are in storage and some are not, be sure to only provide values for the storage related columns (including "units") for samples which also include storage locations.

Import of Samples with Storage Location Data

Once your spreadsheet is ready:

• If you are creating all new samples with storage details, use the Add > Import from File, or Add Samples > Import From File from the dashboard.
• If you are adding storage information for existing samples, use Edit > Update from File from the sample grid.
• If your spreadsheet contains a mixture of existing and new samples, use Edit > Update from File and select the option to Create new samples too.

Work with Stored Samples

You can now use all the Storage Management features as if you had stored samples using the user interface:

• Check Out and Check In
• Move Stored Samples
• View Storage Activity
• Create New Storage while Importing Samples from File

Related Topics

• Storage Management