Products in the LIMS Suite:

• Sample Manager
• LabKey LIMS
• Biologics LIMS
• LIMS Enterprise

• See how Sample Manager can level-up your lab work.
• Getting started with Sample Manager
• LabKey Sample Manager - Guided Tours

LabKey Sample Manager is one of a suite of LabKey products designed to help you track the entire lifecycle of samples in your lab and all associated research data. The topics in this section will help you learn to use the Starter Edition of Sample Manager. All related products use the same general interface, adding additional functionality at each tier.

• Sample Manager Starter Edition
• Sample Manager Professional Edition
• LabKey LIMS
• LabKey Biologics

Sample Manager Starter Edition

The intuitive interface makes it easy to:

• Manage and track your laboratory samples with customizable types and sources.
• Use storage management tools to track locations of samples in freezers and other storage. (Learn more in the documentation.)
• Retain an audit ready log of actions performed on every sample.

Sample Manager Professional Edition

With the Professional Edition of Sample Manager, you will have all of the Starter Edition features, plus be able to:

• Create laboratory workflows and standardize sample processing.
• Upload associated assay and experiment result data and link it to your samples.
• Record your work in electronic lab notebooks integrated directly with your data. (Learn more in the documentation.)
• Partition your data by folder, sharing a storage environment and other resources.

LabKey LIMS

LabKey LIMS includes all features in the Professional Edition of Sample Manager, and adds more, including but not limited to:

• Generate customizable reports with ease.
• Add automation with transformation scripts for assay data.
• Customize the downloadable templates available to users importing data

Biologics LIMS

Biologics adds even more functionality to what is available with LabKey LIMS. Learn more here:

• Biologics LIMS Documentation

Topics

• Get Started with Sample Manager
• Sample Manager Dashboard
• Folder Organization
• User Accounts, Groups, and Roles

More Answers

• Release Notes: Sample Manager: What has changed in each version of Sample Manager.
• Sample Manager - FAQ

How Do I Know the Version of my Application

An administrator can see which version is running by selecting > Application Settings. The version is shown in the upper right of every tab in the Administration section.

Using Sample Manager with Google Translate

Note that if you are using Google Translate and run into an error similar to the following, it may be due to an "expected" piece of text not appearing in the displayed language at the time the application expects it. Try refreshing the browser or temporarily disabling Google Translate to complete the action.

Failed to execute 'removeChild' on 'Node': The node to be removed is not a child of this node.

Learn more about the features and capabilities of Sample Manager on our website.

This topic details the features and enhancements in each release as a guide to help users track changes over time. The reference values like "SM-VAL-##.#-*" are used to map to these changes from Requirements in the Validation Pack provided to our Validated Sample Manager customers.

Release 26.3, March 2026

• LIMS Enterprise Edition is now available.
• Better warnings for unknown fields - when importing cross-sample types, we provide better feedback for unknown fields.
• Improved experience when adding samples to storage - the "Search for Samples" grid now includes the Identifying Fields for a Sample.
• Text Choice options have been increased from 200 items to 500 items.
• Expanded audit coverage - the audit log now captures the creation and editing of grid views.
• Exact text searches now supported using double quotes.

Release 26.2, February 2026

• Column widths now adjust dynamically, allowing more columns to be visible at once with less horizontal scrolling. (docs)
• Configured URL links can now be opened in a new browser tab for easier comparison and multitasking. (docs)
• Entities you don't have access to in lineage views are now shown as restricted rather than being omitted, preserving full context without exposing details. (docs)
• Sample Status is available as a filter for "All Sample Types" in Sample Finder. (docs)

Release 26.1, January 2026

• Support for multiple unit types provides improved inventory and material management. (docs)
• Move workflow jobs to different folders to better reflect changes in projects or organization. (docs)
• Client APIs can query and update samples using the RowId value; using the LSID value is no longer required.
• Sample names (SampleId) can be updated via a file, when RowId is provided. (docs)

Release 25.12, December 2025

• Amount and Units Fields - Improvements have been made to ensure that the Amounts & Units fields function as paired fields. SM-VAL-25.12.A (docs)
• Negative Amount Values Disallowed - Sample Manager now enforces that the Amounts field cannot have a negative value. SM-VAL-25.12.B (docs)
• Identifying Fields - Identifying fields are now shown in more assay import scenarios. SM-VAL-25.12.C (docs)

Release 25.11, November 2025

• Audit log captures additional information on the method or webpage location used to insert, update, and delete records. SM-VAL-25.11.A (docs)
• When an ELN notebook is recalled by an administrator, the author will now receive an email notification, improving visibility and timely follow-up. SM-VAL-25.11.B
• The Customize Grid View and Filter pop-up dialogs now list fields alphabetically, making it faster and more intuitive to find and select fields. SM-VAL-25.11.C
• Two factor authentication is available for configuration by LabKey. Consult your Account Manager for changes. SM-VAL-25.11.D

Release 25.10, October 2025

• Amounts and Units Changes - Amount and Unit fields are now enforced as a pair—both must be completed together or left empty. SM-VAL-25.10.A (docs)
• Required Fields in Workflow Jobs - Required fields in workflow jobs are now enforced during job creation, instead of during job completion. SM-VAL-25.10.B (docs)
• Identifying Fields - Administrators can now set up to 6 identifying fields. SM-VAL-25.10.C (docs)

Release 25.9, September 2025

• Improved Audit Logging Behavior - The LabKey Client APIs will now respect the audit level configured by the system to improve adherence to compliance and ease development. When both the system and API parameters specify an auditing level, the higher, more detailed level is applied. (docs) SM-VAL-25.9.A
• Several improvements were made to overall system reliability and performance.

Release 25.8, August 2025

• Improved ELN Editing: ELN editors now get faster feedback when pasting images into an ELN: files pasted into an ELN now fail immediately if they can't be loaded. SM-VAL-25.7-B (docs)
• The CheckedOut date/time stamp is now an available column in sample grids. SM-VAL-25.7-D
• You can now view all audit events for a transaction in one place. SM-VAL-25.8.A (docs)
• The audit log now records original file names when duplicates are automatically renamed. SM-VAL-25.8-B (docs)

Release 25.7, July 2025

• Improvements were made to address overall system reliability and performance.
• Continued investment in automated testing and internal quality checks to support ongoing feature development.

Release 25.7.8, September 2025

• Selection order is retained when editing in a grid. SM-VAL-25.7-A
• Improved ELN Editing: ELN editors now get faster feedback when pasting images into an ELN: files pasted into an ELN now fail immediately if they can't be loaded. SM-VAL-25.7-B (docs)
• Improved import feedback: When attachment fields are supplied with data in a file import or file update for Sources, users will be provided an error message that Attachment data cannot be provided via a file. SM-VAL-25.7-C
• The CheckedOut date/time stamp is now an available column in sample grids. SM-VAL-25.7-D (docs)
• We have addressed an issue with moving assay runs. Moving assay runs that have multiple file fields now associate correctly. SM-VAL-25.7-E
• We have addressed an issue with cross-sample-type import or cross-folder sample import, where the CheckedOut column was being ignored. SM-VAL-25.7-F
• We have addressed an issue with cross-sample-type import and cross-folder sample import, where Yes/No text fields were being inadvertently converted to Boolean values. SM-VAL-25.7-G
• We have addressed an issue where samples being removed from storage could not be assigned a Locked sample status type. SM-VAL-25.7-H

Release 25.6, June 2025

• Lineage details can be used in aliquot naming patterns. SM-VAL-25.6-A (docs)
• Users can enter a reason when they make changes to a Sample Type, Source Type, or Assay Design. SM-VAL-25.6-B (docs)
• Fields of type "Sample" can be set to validate that values already exist in the system. SM-VAL-25.6-C (docs)
• Several improvements were made to address overall system reliability and performance.

Release 25.5, May 2025

• Several improvements were made to address overall system reliability and performance.
• Continued investment in automated testing and internal quality checks to support ongoing feature development.

Release 25.4, April 2025

• Several improvements were made to address overall system reliability and performance.
• Continued investment in automated testing and internal quality checks to support ongoing feature development.

Release 25.3, March 2025

Maintenance Release 25.3.2, April 2025

• Bulk edit grids now show amounts as entered, regardless of selected units.
• Field names longer than 40 characters are now supported, though not recommended.

Release 25.3.0, March 2025

• You can now use numeric positions for boxes, plates, and tube racks (instead of xy coordinates) when that will better match your lab. SM-VAL-25.3-A (docs)
• Improved support for using special characters in column names and data. SM-VAL-25.3-B (docs)
• Updates to our content security policy (CSP) to enforce strong settings that will block serious cybersecurity threats. Administrators can add allowed external resources if needed. SM-VAL-25.3-C (docs)

Release 25.2, February 2025

• The main dashboard has been simplified. SM-VAL-25.2-A (docs)
• The last storage location is remembered on a per sample type basis, making it easier for users who work with different materials to return to the right locations. SM-VAL-25.2-B (docs)
• Multiple Sample or SourceIDs can now be edited in the editable grid. SM-VAL-25.2-C (docs)
• If desired, you can prevent this by disallowing user-defined names. (docs)

• Adding samples to workflow jobs has been streamlined. SM-VAL-25.2-D (docs)
• Workflow jobs, tasks, and notification subscriptions can be assigned by group as well as by individual user. SM-VAL-25.2-E (docs)

Release 25.1, January 2025

• Creating or deriving samples of multiple types at once can now be done with a streamlined interface. SM-VAL-25.1-A (docs)
• The process of adding lineage details when creating and deriving samples and sources is more consistent. SM-VAL-25.1-B (docs)
• Special characters are not allowed in the names of structures like Sample Types, Source Types, and Assay Designs. SM-VAL-25.1-C (docs)

• When importing new samples and sources from a file, first navigate to the folder where you want to create them. SM-VAL-25.1-D (docs)

Release 24.12, December 2024

• The main dashboard shows "Locations Recently Added To" for easy access to recent storage locations. SM-VAL-24.12-A (docs)
• Improvements in creating and deriving samples and sources let you choose the type and number to create up front. SM-VAL-24.12-B (docs)
• Use identifying fields when editing samples in grids and viewing tooltips during sample creation and derivation. SM-VAL-24.12-C (docs)

• Importing assay data from a workflow job will now only choose relevant sample IDs. SM-VAL-24.12-D (docs)

Release 24.11, November 2024

• Customize which Identifying Fields are shown when users choose samples or sources from dropdowns. SM-VAL-24.11-B (docs)
• Date, time, and datetime fields are now limited to a set of common display patterns, making it easier for users to choose the desired format. SM-VAL-24.11-C (docs)
• A simplified interface for editing lineage and storage information replaces the previous additional tabs on editable grids. SM-VAL-24.11-D (docs)

• Include "Calculation" fields in your sample, source, and assay definitions that can perform calculations on any combination of system and user-defined fields. SM-VAL-24.11-A (docs)
• Folders that are no longer in use can be archived to hide them from view. SM-VAL-24.11-E (docs)
• An administrator may amend any notebook. SM-VAL-24.11-F (docs)

Release 24.10, October 2024

• Lineage relationships can now be marked as required when creating or updating samples or sources. SM-VAL-24.10-A (docs)
• The term "Remove" is now used instead of "Discard" when a sample is taken out of a storage system. SM-VAL-24.10-B (docs)
• The term "Folder" is now used instead of "Project" to describe a subcontainer or partition of data within the application. All data scoping, user access, and configuration options are unchanged. SM-VAL-24.10-C (docs)

Release 24.9, September 2024

• More easily create storage during sample import by adding labels on terminal storage units. SM-VAL-24.9-A (docs)
• Make naming samples easier with the ability to name your samples based on source or sample ancestors regardless of hierarchy. SM-VAL-24.9-B (docs)
• When adding samples to storage, you can use the Sample Creation Order, i.e. the "reverse" of the default grid order. SM-VAL-24.9-C (docs | docs)
• Resolved an issue with editing samples with mixed parent sample or source IDs. In certain scenarios, where projects were in use, samples being edited in the grid with sample or source parents whose sample IDs were a mixture of numeric and non numeric, lineage was unintentionally removed. SM-VAL-24.7.5-J

Release 24.8, August 2024

• More easily get your sample templates to BarTender by exporting the "BarTender Template". SM-VAL-24.8-A (docs)
• Editable grids now validate entered values as you go, rather than waiting for save to check all entries. SM-VAL-24.8-B (docs)
• Resolved an issue with moving boxes and deleting storage hierarchy. In certain scenarios, boxes containing samples were unintentionally deleted when their previous location was simultaneously deleted while they were being moved. SM-VAL-24.7.3-H

Release 24.7, July 2024

Maintenance Release 24.7.5, September 2024

• Resolved an issue with editing samples with mixed parent sample or source IDs. In certain scenarios, where projects were in use, samples being edited in the grid with sample or source parents whose sample IDs were a mixture of numeric and non numeric, lineage was unintentionally removed. SM-VAL-24.7.5-J

Maintenance Release 24.7.3, August 2024

• Resolved an issue with moving boxes and deleting storage hierarchy. In certain scenarios, boxes containing samples were unintentionally deleted when their previous location was simultaneously deleted while they were being moved. SM-VAL-24.7.3-H

Release 24.7.0, July 2024

• The storage dashboard now lists recently used freezers first, and loads the first ten by default, making navigating large storage systems easier for users. SM-VAL-24.7-A (docs)
• New roles, Sample Type Designer and Source (Data Class) Designer, improve the ability to customize the actions available to individual users. SM-VAL-24.7-B (docs)
• Fields with a description, shown in a tooltip, now show an icon to alert users that there is more information available. SM-VAL-24.7-C (docs)
• Lineage across multiple Sample Types can be viewed using the "Ancestor" node on the "All Samples" tab of the grid. SM-VAL-24.7-D (docs)
• Editable grids support the locking of column headers and sample identifier details making it easier to tell which cell is being edited. SM-VAL-24.7-F (docs)
• Exporting data from a grid while data is being edited is no longer supported. SM-VAL-24.7-E (docs)

• Workflow jobs cannot be deleted if they are referenced from a notebook. SM-VAL-24.7-G (docs)

Release 24.6, June 2024

• More easily identify if a file wasn't uploaded with an "Unavailable File" indicator. SM-VAL-24.6-A (docs)
• The process of adding samples to storage has been streamlined to make it clearer that the preview step is only showing current contents. SM-VAL-24.6-B (docs)

• Customize the certification language used during ELN signing to better align with your institution's requirements. SM-VAL-24.6-C (docs)
• Workflow templates can now be copied to make it easier to generate similar templates. SM-VAL-24.6-D (docs)

Release 24.5, May 2024

• Assign custom colors to sample statuses to more easily distinguish them at a glance. SM-VAL-24.5-A (docs)
• Easily download and print a box view of your samples to share or assist in using offline locations like some freezer "farms". SM-VAL-24.5-B (docs)
• Use any user-defined Sample properties in the Sample Finder. SM-VAL-24.5-C (docs)

• More easily understand Notebook review history and changes including recalls, returns for changes, and more in the Review Timeline panel. SM-VAL-24.5-D (docs)
• Administrators can require a reason when a notebook is recalled. SM-VAL-24.5-E (docs)
• Add samples to any project without first having to navigate there. SM-VAL-24.5-F (docs)
• Edit samples across multiple projects, provided you have the appropriate permissions. SM-VAL-24.5-G (docs)

Release 24.4, April 2024

• Maintenance release 24.4.1 addresses an issue with uploading files during bulk editing of Sample data. SM-VAL-24.4.1-K
• Users can better comply with regulations by entering a Reason for Update when editing sample, source or assay data. SM-VAL-24.4-A (docs)
• More quickly find the location you need when adding samples to storage (or moving them) by searching for storage units by name or label. SM-VAL-24.4-B (docs)
• Choose either an automatic (specifying box starting position and Sample ID order) or manual fill when adding samples to storage or moving them. SM-VAL-24.4-C (docs)
• More easily find samples in Sample Finder by searching with user-defined fields in sample parent and source properties. SM-VAL-24.4-D (docs)
• Lineage graphs have been updated to reflect "generations" in horizontal alignment, rather than always showing the "terminal" level aligned at the bottom. SM-VAL-24.4-E (docs)
• Hovering over a column label will show the underlying column name. SM-VAL-24.4-F (docs)
• Up to 20 levels of lineage can be displayed using the grid view customizer. SM-VAL-24.4-G (docs)

• Administrators of the Professional Edition can set the application to require users to provide reasons for updates as well as other actions like deletions. SM-VAL-24.4-H (docs)
• Moving entities between projects is easier now that you can select from multiple projects simultaneously for moves to a new one. SM-VAL-24.4-J (docs)

Sample Manager User Conference - March 28, 2024

Watch the session recordings to hear what's new in Sample Manager, best practices for using key features, and other users sharing how Sample Manager is used in their labs.

• Sample Manager User Conference 2024

Release 24.3, March 2024

Maintenance Release 24.3.5, May 2024

• Resolved an issue with importing across Sample Types in certain time zones. Date, datetime, and time fields were sometimes inconsistently translated.
• Resolved an issue with uploading files during bulk editing of Sample data.

Version 24.3.0, March 2024

• Storing or moving samples to a single box now allows you to choose the order in which to add them as well as the starting position within the box. (docs)
• When discarding a sample, by default the status will change to "Consumed". Users can adjust this as needed. (docs)
• While browsing into and out of storage locations, the last path into the hierarchy will be retained so that the user returns to where they were previously. (docs)
• The storage location string can be copied; pasting outside the application will include the slash separators, making it easier to populate a spreadsheet for import. (docs)
• The icons and are now used for expanding and collapsing sections, replacing and . (docs)
• Assay run fields can now use the datatypes "Date" or "Time". (docs)
• The ":withCounter" naming pattern modifier is now case-insensitive. (docs)

• Workflow templates can be edited before any jobs are created from them, including updating the tasks and attachments associated with them. (docs)

Release 24.2, February 2024

• In Sample Finder, use the "Equals All Of" filter to search for Samples that share up to 10 common Sample Parents or Sources. (docs)
• Include fields of type "Date" or "Time" in Samples, Sources, and Assay Results. (docs)
• Users can now sort and filter on the Storage Location columns in Sample grids. (docs)
• Sample types can be selectively hidden from the Insights panel on the dashboard, helping you focus on the samples that matter most. (docs)
• The Sample details page now clarifies that the "Source" information shown there is only one generation of Source Parents. For full lineage details, see the "Lineage" tab. (docs)
• Up to 10 levels of lineage can be displayed using the grid view customizer. (docs)
• Menu and dashboard language is more consistent about shared team resources vs. your own items. (docs)

• The application can be configured to require reasons (previously called "comments") for actions like deletion and storage changes. Otherwise providing reasons is optional. (docs)
• Developers can generate an API key for accessing client APIs from scripts and other tools. (docs)

Release 24.1, January 2024

• A banner message within the application links you directly to these release notes to help you learn what's new in the latest version. (docs)
• Search for samples by storage location. Box names and labels are now indexed to make it easier to find storage in larger systems. (docs)
• Only an administrator can delete a storage system that contains samples. Non-admin users with permission to delete storage must first remove the samples from that storage in order to be able to delete it. (docs)

• Electronic Lab Notebook enhancements:
• All notebook signing events require authentication using both username and password. Also available in version 23.11.4. (docs | docs)
• From the notebook details panel, see how many times a given item is referenced and easily open its details or find it in the notebook. (docs)
• Workflow jobs can be referenced from Electronic Lab Notebooks. (docs)
• Editing during ELN is fixed after an issue on Chromium-based browsers (eg. Chrome, Edge) caused users to experience jumpiness during notebook authoring. Also available in version 23.11.7 and 24.1.2.

Release 23.12, December 2023

• Samples can be moved to multiple storage locations at once. (docs)
• New storage units can be created when samples are added to storage. (docs)
• The table of contents for a notebook now includes headings and day markers from within document entries. (docs)
• Workflow templates can now have editable assay tasks allowing common workflow procedures to have flexibility of the actual assay data needed. (docs)
• When samples or aliquots are updated via the grid, the units will be correctly maintained at their set values. This addresses an issue in earlier releases and is also fixed in the 23.11.2 maintenance release.

Release 23.11, November 2023

• Moving samples between storage locations now uses the same intuitive interface as adding samples to new locations. (docs)
• Sample grids now include a direct menu option to "Move Samples in Storage". (docs)
• Standard assay designs can be renamed. (docs)
• Users can share saved custom grid views with other users. (docs)
• Authorized users no longer need to navigate to the home project to add, edit, and delete data structures including Sample Types, Registry Source Types, Assay Designs, and Storage. Changes can be made from within a subproject, but still apply to the structures in the home project. (docs)
• The interface has changed so that the 'cancel' and 'save' buttons are always visible to the user in the browser. (docs)

Release 23.10, October 2023

• Adding Samples to Storage is easier with preselection of a previously used location, and the ability to select which direction to add new samples: top to bottom or left to right, the default. (docs)
• When Samples or Sources are created manually, any import aliases that exist will be included as parent fields by default, making it easier to set up expected lineage relationships. (docs)
• Grid settings are now persistent when you leave and return to a grid, including which filters, sorts, and paging settings you were using previously. (docs)
• Header menus have been reconfigured to make it easier to find administration, settings, and help functions throughout the application. (docs)
• Panels of details for Sample Types, Sources, Storage, etc. are now collapsed and available via hover, putting the focus on the data grid itself. (docs)

Release 23.9, September 2023

• View all samples of all types from a new dashboard button. (docs)
• When adding samples to storage, users will see more information about the target storage location including a layout preview for boxes or plates. (docs)
• Longer storage location paths will be 'summarized' for clearer display in some parts of the application. (docs)
• Naming patterns can now incorporate a sampleCount or rootSampleCount element. (docs)

Release 23.8, August 2023

• Sources can have lineage relationships, enabling the representation of more use cases. (docs)
• Two new calculated columns provide the "Available" aliquot count and amount, based on the setting of the sample's status. (docs)
• The amount of a sample can be updated easily during discard from storage. (docs)
• Customize the display of date/time values on an application wide basis. (docs)
• The aliquot naming pattern will be shown in the UI when creating or editing a sample type. (docs)
• The allowable box size for storage units has been increased to accommodate common slide boxes with up to 50 rows. (docs)
• Options for saving a custom grid view are clearer. (docs)

Release 23.7, July 2023

• Define locations for storage systems within the app. (docs)
• Create new freezer hierarchy during sample import. (docs)
• Import & update samples across multiple sample types from a single file. (docs)
• Administrators have the ability to do the actions of the Storage Editor role. (docs)
• Improved options for bulk populating editable grids, including better "drag-fill" behavior and multi-cell cut and paste. (docs | docs)
• Enhanced security by removing access or identifiers to data in different projects in lineage, sample timeline and ELNs. (docs)
• ELN Improvements:
• The mechanism for referencing something from an ELN has changed to be @ instead of /. (docs)
• Autocompletion makes finding objects to reference easier. (docs)
• Move Assay Runs and Notebooks between Projects. (docs | docs)

Release 23.6, June 2023

• See an indicator in the UI when a sample is expired. (docs)
• On Sample grids in Picklists, Workflows & Source Details pages, when only one Sample Type is included in a grid that supports multiple Sample Types, default to that tab instead of to the general "All Samples" tab. (docs)
• Track the edit history of Notebooks. (docs)
• Control which data structures and storage systems are visible in which Projects. (docs)
• Move Sources between Projects. (docs)
• Project menu includes quick links to settings and the dashboard for that Project. (docs)

Release 23.5, May 2023

• Move Samples between Projects. (docs)
• Assay Results grids can be modified to show who created and/or modified individual result rows and when. (docs)
• BarTender templates can only be defined in the home Project. (docs)
• ELN Improvements: Pagination controls are available at the bottom of the ELN dashboard. (docs)
• A new "My Tracked Jobs" option helps users follow workflow tasks of interest, even when they are not assigned tasks. (docs)

Release 23.4, April 2023

• Add the sample amount during sample registration to better align with laboratory processes. (docs | docs)
• StoredAmount, Units, RawAmount, and RawUnits field names are now reserved. (docs)
• Users with a significant number of samples in storage may see slower than usual upgrade times due to migrating these fields. Any users with existing custom fields for providing amount or units during sample registration are encouraged to migrate to the new fields prior to upgrading.
• Use the Sample Finder to find samples by sample properties, as well as by parent and source properties. (docs)
• Built in Sample Finder reports help you track expiring samples and those with low aliquot counts. (docs)
• Text search result pages are more responsive and easier to use. (docs)
• Administrators can specify a default BarTender template. (docs)
• ELN Improvements: View archived notebooks. (docs)
• Sample Status values can only be defined in the home project. Existing unused custom status values in sub-projects will be deleted and if you were using projects and custom status values prior to this upgrade, you may need to contact us for assistance. (docs)

Release 23.3, March 2023

• Samples can have expiration dates, making it possible to track expiring inventories. (docs)
• If your samples already have expiration dates, contact your Account Manager for help migrating to the new fields.
• Administrators can see the which version of Sample Manager they are running. (docs)
• ELN Improvements:
• The panel of details and table of contents for the ELN is now collapsible. (docs)
• Easily copy links to attachments. (docs)

Release 23.2, February 2023

• Clearly capture why any data is deleted with user comments upon deletion. (docs | docs)
• Data update (or merge) via file has moved to the "Edit" menu of a grid. Importing from file on the "Add" menu is only for adding new data rows. (docs | docs | docs)
• Use grid customization after finding samples by ID or barcode, making it easier to use samples of interest. (docs)
• Electronic Lab Notebooks now include a full review and signing event history in the exported PDF, with a consistent footer and entries beginning on the second page of the PDF. (docs)
• Projects in the Professional Edition of Sample Manager are more usable and flexible.
• Data structures like Sample Types, Source Types, Assay Designs, and Storage Systems must always be created in the top level home project. (docs)

Release 23.1, January 2023

• Storage management has been generalized to clearly support non-freezer types of sample storage. (docs)
• Samples will be added to storage in the order they appear in the selection grid. (docs)
• Curate multiple BarTender label templates, so that users can easily select the appropriate format when printing. (docs)
• Electronic Lab Notebook enhancements:
• To submit a notebook for review, or to approve a notebook, the user must provide an email and password during the first signing event to verify their identity. (docs | docs)
• Set the font-size and other editing updates. (docs)
• Sort Notebooks by "Last Modified". (docs)
• Find all ELNs created from a given template. (docs)
• An updated main menu making it easier to access resources across projects. (docs)
• Easily update Assay Run-level fields in bulk instead of one run at a time. (docs)

Release 22.12, December 2022

• The Professional Edition supports multiple Sample Manager Projects. (docs)
• Improved interface for assay design and data import. (docs | docs)
• From assay results, select sample ID to examine derivatives of those samples in Sample Finder. (docs)

Release 22.11, November 2022

• Add samples to multiple freezer storage locations in a single step. (docs)
• Improvements in the Storage Dashboard to show all samples in storage and recent batches added by date. (docs)
• View all assay results for samples in a tabbed grid displaying multiple sample types. (docs)
• ELN improvements to make editing and printing easier with a table of contents highlighting all notebook entries and fixed width entry layout, plus new formatting symbols and undo/redo options. (docs)
• New role available: Workflow Editor, granting the ability to create and edit workflow jobs and picklists. (docs)
• Notebook review can be assigned to a user group, supporting team workload balancing. (docs)

Release 22.10, October 2022

• Use sample ancestors in naming patterns, making it possible to create common name stems based on the history of a sample. (docs)
• Additional entry points to Sample Finder. Select a source or parent and open all related samples in the Sample Finder. (docs | docs)
• Video Tutorial: Sample Finder
• New role available: Editor without Delete. Users with this role can read, insert, and update information but cannot delete it. (docs)
• Group management allowing permissions to be managed at the group level instead of always individually. (docs | docs)
• With the Professional Edition, use assay results as a filter in the sample finder helping you find samples based on characteristics like cell viability. (docs)
• Assay run properties can be edited in bulk. (docs)

Release 22.9, September 2022

• Searchable, filterable, standardized user-defined fields on workflow enable teams to create structured requests for work, define important billing codes for projects and eliminate the need for untracked email communication. (docs)
• Storage grids and sample search results now show multiple tabs for different sample types. With this improvement, you can better understand and work with samples from anywhere in the application. (docs | docs | docs)
• The leftmost column of sample data, typically the Sample ID, is always shown as you examine wide datasets, making it easy to remember what sample's data you were looking at. (docs)
• By prohibiting sample deletion when they are referenced in an ELN, Sample Manager helps you further protect the integrity of your data. (docs)
• Easily capture amendments to signed Notebooks when a discrepancy is detected to ensure the highest quality entries and data capture, tracking the events for integrity. (docs)
• When exploring a Sample of interest, you can easily find and review any associated notebooks. (docs)

Release 22.8, August 2022

• Aliquots can have fields that are not inherited from the parent sample. Administrators can control which parent sample fields are inherited and which can be set independently for the sample and aliquot. (docs)
• Drag within editable grids to quickly populate fields with matching strings or number sequences. (docs)
• When exporting a multi-tabbed grid to Excel, see sample counts and which view will be used for each tab. (docs)

Release 22.7, July 2022

• Our user-friendly ELN (Electronic Lab Notebook) is designed to help scientists efficiently document their experiments and collaborate. This data-connected ELN is seamlessly integrated with other laboratory data in the application, including lab samples, assay data and other registered data. (docs)
• Make manifest creation and reporting easier by exporting sample types across tabs into a multi tabbed spreadsheet. (docs)
• All users can now create their own named custom view of grids for optimal viewing of the data they care about. Administrators can customize the default view for everyone. (docs)
• Create a custom view of your data by rearranging, hiding or showing columns, adding filters or sorting data. (docs)
• With saved custom views, you can view your data in multiple ways depending on what’s useful to you or needed for standardized, exportable reports and downstream analysis. (docs)
• Customized views of the audit log can be added to give additional insight. (docs)
• Export data from an 'edit in grid' panel, particularly useful in assay data imports for partially populating a data 'template'. (docs | docs)
• Newly surfaced Picklists allow individuals and teams to create sharable sample lists for easy shipping manifest creation and capturing a daily work list of samples. (docs)
• Updated main dashboard providing quick access to notebooks in the Professional Edition of Sample Manager. (docs)
• Samples can now be renamed in the case of a mistake; all changes are recorded in the audit log and sample ID uniqueness is still required. (docs)
• The column header row is 'pinned' so that it remains visible as you scroll through your data. (docs)
• Deleting samples from the system entirely when necessary is now available from more places, including the Samples tab for a Source. (docs)

Release 22.6, June 2022

• Save time looking for samples and create standard sample reports by saving your Sample Finder searches to access later. (docs)
• Support for commas in Sample and Source names. (docs)
• Administrators will see a warning when the number of users approaches the limit for your installation. (docs)

Release 22.5, May 2022

• Updated grid menus: Sample grids now help you work smarter (not harder) by highlighting actions you can perform on samples and grouping them to make them easier to discover and use. (docs)
• Revamped grid filtering and enhanced column header options for more intuitive sorting, searching and filtering. (docs)
• Sort and filter based on 'lineage metadata', bringing ancestor information (Source and Parent details) into sample grids (docs)
• Rename Source Types and Sample Types to support flexibility as your needs evolve. Names/SampleIDs of existing samples and sources will not be changed. (docs)
• Descriptions for workflow tasks and jobs can be multi-line when you use Shift-Enter to add a newline. (docs)

Release 22.4, April 2022

• In the Sample Finder, apply multiple filtering expressions to a given column of a parent or source type. (docs)
• Download templates from more places, making it easier to import samples, sources, and assay data from files. (docs)

Release 22.3, March 2022

• Sample Finder: Find samples based on source and parent properties, giving users the flexibility to locate samples based on relationships and lineage details. (docs)
• Redesigned main dashboard featuring storage information and prioritizing what users use most. (docs)
• Updated freezer overview panel and dashboards present storage summary details. (docs)
• Available freezer capacity is shown when navigating freezer hierarchies to store, move, and manage samples. (docs | docs)
• Storage labels and descriptions give users more ways to identify their samples and storage units. (docs)

Release 22.2, February 2022

• New Storage Editor and Storage Designer roles, allowing admins to assign different users the ability to manage freezer storage and manage sample and assay definitions. (docs)
• Note that users with the "Administrator" and "Editor" role no longer have the ability to edit storage information unless they are granted one of these new storage roles.
• Multiple permission roles can be assigned to a new user at once. (docs)
• Sample Type Insights panel summarizes storage, status, etc. for all samples of a type. (docs)
• Sample Status options are shown in a hover legend for easy reference. (docs)
• When a sample is marked as "Consumed", the user will be prompted to also change it's storage status to "Discarded" (and vice versa). (docs | docs)
• User-defined barcodes in integer fields can also be included in sample definitions and search-by-barcode results. (docs)
• Search menu includes quick links to search by barcode or sample ID. (docs)
• See and set the value of the "genId" counter for naming patterns. (docs)

Release 22.1, January 2022

• A new Text Choice data type lets admins define a set of expected text values for a field. (docs)
• Naming patterns will be validated during sample type definition. (docs)
• Editable grids include visual indication when a field offers dropdown choices. (docs)
• Add freezer storage units in bulk. (docs)
• User-defined barcodes can be included in Sample Type definitions as text fields and are scanned when searching samples by barcode. (docs | docs)
• If any of your Sample Types include samples with only strings of digits as names, these could have overlapped with the "rowIDs" of other samples, producing unintended results or lineages. With this release, such ambiguities will be resolved by assuming that a sample name has been provided. (docs)

Release 21.12, December 2021

• The Sample Count by Status graph on the main dashboard now shows samples by type (in bars) and status (using color coding). Click through to a grid of the samples represented by each block. (docs)
• Grids that may display multiple Sample Types, such as picklists, workflow tasks, etc. offer tabs per sample type, plus a consolidated list of all samples. This enables actions such as bulk sample editing from mixed sample-type grids. (picklists | tasks | sources)
• Improved display of color coded sample status values. (docs)
• Include a comment when updating storage amounts or freeze/thaw counts. (docs)
• Workflow tasks involving assays will prepopulate a grid with the samples assigned to the job, simplifying assay data entry. (docs)

Release 21.11, November 2021

• Archive an assay design so that new data is disallowed, but historic data can be viewed. (docs)
• Manage sample status, including but not limited to: available, consumed, locked. (docs)
• An additional reserved field "SampleState" has been added to support this feature. If your existing Sample Types use user defined fields for recording sample status, you will want to migrate to using the new method.
• Incorporate lineage lookups into sample naming patterns (docs)
• Assign a prefix to be included in the names of all Samples and Sources created in a given project. Removed in version 22.12.
• Prevent users from creating their own IDs/Names in order to maintain consistency using defined naming patterns (docs)

Release 21.10, October 2021

• Customize the aliquot naming pattern. (docs)
• Sample names can incorporate field-based counters using :withCounter syntax. (docs)
• Record the physical location of freezers you manage, making it easier to find samples across distributed sites. (docs)
• Contact us to have your Freezer Location hierarchy configured.
• Manage all samples and aliquots created from a source more easily. (docs)
• Comments on workflow job tasks can be formatted in markdown and multithreaded. (docs)
• Redesigned job tasks page. (docs)

Release 21.9, September 2021

• Edit sources and parents of samples in bulk
• View all samples (and aliquots) created from a given Source
• Lineage graphs changed to show up to 5 generations instead of 3
• Redesigned job overview page

Release 21.8, August 2021

• Aliquot views available at the parent sample level. See aggregate volume and count of aliquots and sub-aliquots.
• Find Samples using barcodes or sample IDs
• Import aliases for sample Sources and Parents are shown in the Sample Type details and included in downloaded templates.
• Improved interface for managing workflow jobs and templates.

Release 21.7, July 2021

• Sample actions can be initiated from Freezer views
• Sample actions can be initiated from Source detail views

Release 21.6, June 2021

• Create Aliquots of samples singly or in bulk
• Create and manage Picklists of samples to simplify operations on groups of samples
• Track movement of storage units within a freezer, or to another freezer
• Minor change in freezer editing behavior that the hierarchy is initially collapsed.

Release 21.5, May 2021

• Copy a Freezer definition
• Samples and Sources can include images and other file attachments

Release 21.4, April 2021

• Barcode generation for Samples
• When inferring fields to create Sources, Sample Types, and Assay Designs from a spreadsheet, any "reserved" fields present will not be shown in the inferral, simplifying the creation process
• When importing data, any unrecognized fields will be ignored and a banner will be shown
• On the main menu, "My Assigned Work" has been renamed "My Queue"

Release 21.3, March 2021

• A new Tube Rack type of freezer storage unit has been added
• Derive samples from one or more parent samples
• Pool multiple samples into a set of new samples
• The field editor offers a new "Summary" view

Release 21.2, February 2021

• The field editor now includes checkboxes to enable deletion of multiple fields and export of subsets of fields.
• Background Import:
• Removal of previous size limits on data import
• Progress reporting for asynchronous imports
• In-app Notifications when background imports are complete

Release 21.1, January 2021

• Freezer Management
• Match your digital storage to your physical storage
• Store and locate samples with ease
• Monitor usage and capacity in graphical dashboards
• Track volume, freeze/thaw counts, and comments during check in/out events

Release 20.12, December 2020

• Detailed audit logging now shows only what has changed when data is updated.

Release 20.11, November 2020

• Batching of creating samples and sources, enabling selection of "just created" items.

Release 20.10, October 2020

• Integration with BarTender to print labels. (docs)

Release 20.9, September 2020

• Label colors are shown in the samples section of the main dashboard.
• In anticipation of future support for Freezer Management, underlying functionality like the ability to access storage locations from the main menu have been added.

Release 20.8, August 2020

• Sample Types can have custom Label Color assignments to help users differentiate them. (docs)
• In anticipation of future support for Freezer Management, underlying functionality like the ability to see the storage location of a sample has been added. These facilities are not yet visible in the application interface.

Release 20.7, July 2020

• Improved search experience. Filter and refine search results. (docs)

Release 20.6, June 2020

• Bug fixes and small improvements

Release 20.5, May 2020

• Use Sample Timelines to track all events involving a given sample.
• Detailed audit logging has been improved for samples, under the new heading "Sample Timeline Events."
• Sample Types can be created by inferring fields from a file, or by defining fields manually. Source types offer the same convenience.
• Editing of sample parents is now available.
• The definition of Sample Types can now include "Source Alias" columns, similar to parent aliases already available.

Release 20.4, April 2020

• The creation interface for Sample Types has been merged to a single page showing both properties and fields. This makes it easier to create naming expressions that use fields in your Sample Type.
• Define Sources for your samples. The source of a sample could be an individual or a cell line or a lab. Tracking metadata about the source of samples, both biological and physical, can unlock new insights.

Release 20.3, March 2020

• Samples can be added to a workflow job during job creation. You no longer need to start a job after selecting samples of interest, but can add or update the samples directly within the job editing interface.
• Removing unnecessary fields is easier with an icon shown in the collapsed field view.

February 2020

• LabKey Sample Manager is Launched!

The symbol indicates a feature available in the Professional Edition of Sample Manager or with a Premium Edition of LabKey Server.

• Generate customizable reports with ease.
• Add automation with transformation scripts for assay data.

Each new release of LabKey LIMS includes all the feature updates covered in the Sample Manager Release Notes, plus additional features listed on this page.

• Sample Manager Release Notes

Release 26.2, February 2026

• Column widths now adjust dynamically, allowing more columns to be visible at once with less horizontal scrolling. (docs)
• Configured URL links can now be opened in a new browser tab for easier comparison and multitasking. (docs)
• Entities you don't have access to in lineage views are now shown as restricted rather than being omitted, preserving full context without exposing details. (docs)
• Sample Status is available as a filter for "All Sample Types" in Sample Finder. (docs)

Release 26.1, January 2026

• Support for multiple unit types provides improved inventory and material management. (docs)
• Move workflow jobs to different folders to better reflect changes in projects or organization. (docs)
• Workflow tasks now support sample filters, allowing you to control which samples are included at each step. (docs)
• Improved plot customization with new layout, axis, size, color, and per-series line controls. (docs)
• Client APIs can query and update samples using the RowId value; using the LSID value is no longer required.
• Sample names (SampleId) can be updated via a file, when RowId is provided.

Release 25.12, December 2025

• Amount and Units Fields - Improvements have been made to ensure that the Amounts & Units fields function as paired fields. (docs)
• Negative Amount Values Disallowed - Sample Manager now enforces that the Amounts field cannot have a negative value.(docs)
• Identifying Fields - Identifying fields are now shown in more assay import scenarios. (docs)

Release 25.11, November 2025

• Audit log captures the method used to insert, update, and delete records. (docs)
• When an ELN notebook is recalled by an administrator, the author will now receive an email notification, improving visibility and timely follow-up.
• The Customize Grid View and Filter pop-up dialogs now list fields alphabetically, making it faster and more intuitive to find and select fields.
• Error bars are available on Bar and Line charts. (docs)
• Multiple charts can be displayed above data grids. Select up to 5 charts to display. (docs)

Release 25.10, October 2025

• Amounts and Units Changes - Amount and Unit fields are now enforced as a pair—both must be completed together or left empty. (docs)
• Required Fields in Workflow Jobs - Required fields in workflow jobs are now enforced during job creation, instead of during job completion. (docs)
• Identifying Fields - Administrators can now set up to 6 identifying fields. (docs)

Release 25.9, September 2025

• Improved Audit Logging Behavior - The LabKey Client APIs will now respect the audit level configured by the system to improve adherence to compliance and ease development. When both the system and API parameters specify an auditing level, the higher, more detailed level is applied. (docs)
• Several improvements were made to overall system reliability and performance.

Release 25.8, August 2025

• Improved ELN Editing: ELN editors now get faster feedback when pasting images into an ELN: files pasted into an ELN now fail immediately if they can't be loaded. SM-VAL-25.7-B (docs)
• The CheckedOut date/time stamp is now an available column in sample grids. SM-VAL-25.7-D
• You can now view all audit events for a transaction in one place. SM-VAL-25.8.A (docs)
• The audit log now records original file names when duplicates are automatically renamed. SM-VAL-25.8-B (docs)

Release 25.7, July 2025

• Improvements were made to address overall system reliability and performance.
• Continued investment in automated testing and internal quality checks to support ongoing feature development.

Release 25.7.8, September 2025

• Selection order is retained when editing in a grid. SM-VAL-25.7-A
• Improved ELN Editing: ELN editors now get faster feedback when pasting images into an ELN: files pasted into an ELN now fail immediately if they can't be loaded. SM-VAL-25.7-B (docs)
• Improved import feedback: When attachment fields are supplied with data in a file import or file update for Sources, users will be provided an error message that Attachment data cannot be provided via a file. SM-VAL-25.7-C
• The CheckedOut date/time stamp is now an available column in sample grids. SM-VAL-25.7-D (docs)
• We have addressed an issue with moving assay runs. Moving assay runs that have multiple file fields now associate correctly. SM-VAL-25.7-E
• We have addressed an issue with cross-sample-type import or cross-folder sample import, where the CheckedOut column was being ignored. SM-VAL-25.7-F
• We have addressed an issue with cross-sample-type import and cross-folder sample import, where Yes/No text fields were being inadvertently converted to Boolean values. SM-VAL-25.7-G
• We have addressed an issue where samples being removed from storage could not be assigned a Locked sample status type. SM-VAL-25.7-H

Release 25.6, June 2025

• Lineage details can be used in aliquot naming patterns. SM-VAL-25.6-A (docs)
• Users can enter a reason when they make changes to a Sample Type, Source Type, or Assay Design. SM-VAL-25.6-B (docs)
• Fields of type "Sample" can be set to validate that values already exist in the system. SM-VAL-25.6-C (docs)
• Several improvements were made to address overall system reliability and performance.

Release 25.5, May 2025

• Several improvements were made to address overall system reliability and performance.
• Continued investment in automated testing and internal quality checks to support ongoing feature development.

Release 25.4, April 2025

• Several improvements were made to address overall system reliability and performance.
• Continued investment in automated testing and internal quality checks to support ongoing feature development.

Release 25.3, March 2025

Maintenance Release 25.3.2, April 2025

• Bulk edit grids now show amounts as entered, regardless of selected units.
• Field names longer than 40 characters are now supported, though not recommended.

Release 25.3.0, March 2025

• You can now use numeric positions for boxes, plates, and tube racks (instead of xy coordinates) when that will better match your lab. SM-VAL-25.3-A (docs)
• Improved support for using special characters in column names and data. SM-VAL-25.3-B (docs)
• Updates to our content security policy (CSP) to enforce strong settings that will block serious cybersecurity threats. Administrators can add allowed external resources if needed. SM-VAL-25.3-C (docs)

Release 25.2, February 2025

• Assay transform scripts can be configured to run when data is imported, updated, or both. (docs)
• Use conditional formatting to selectively highlight field values in grids. (docs)

Release 25.1, January 2025

• A trendline option has been added to the chart builder for Line charts. (docs)
• Customize the downloadable template file for Samples, Sources, and Assay Designs. (docs)

Release 24.11, November 2024

• The Chart Builder can be used from within the application to add and edit charts on grids. (docs)

Release 24.10, October 2024

• LabKey LIMS is Launched!

Biologics LIMS offers strong support for antibody discovery operations. Learn more in our webinar:

• Antibody Discovery with LabKey Biologics

Biologics LIMS includes all features available in LabKey LIMS, plus:

• Bioregistry and classification engine
• Media management
• Molecule property calculator
• Plate and plate set support
• Antibody screening and characterization

Each new release of Biologics LIMS includes all the feature updates covered in the Sample Manager and LIMS Release Notes, plus additional features listed on this page.

• Sample Manager Release Notes
• LabKey LIMS Release Notes

Release 26.2, February 2026

• GenBank import improved: nearly all information GenBank files is captured on import, including the original file.
• Improved Molecule creation: Select protein sequences to kick off the molecule creation process.
• Column widths now adjust dynamically, allowing more columns to be visible at once with less horizontal scrolling. (docs)
• Configured URL links can now be opened in a new browser tab for easier comparison and multitasking. (docs)
• Entities you don't have access to in lineage views are now shown as restricted rather than being omitted, preserving full context without exposing details. (docs)
• Sample Status is available as a filter for "All Sample Types" in Sample Finder. (docs)

Release 26.1, January 2026

• Support for multiple unit types provides improved inventory and material management. (docs)
• Move workflow jobs to different folders to better reflect changes in projects or organization. (docs)
• Workflow tasks now support sample filters, allowing you to control which samples are included at each step. (docs)
• Improved plot customization with new layout, axis, size, color, and per-series line controls. (docs)
• Client APIs can query and update samples using the RowId value; using the LSID value is no longer required.
• Sample names (SampleId) can be updated via a file, when RowId is provided.

Release 25.12, December 2025

• Amount and Units Fields - Improvements have been made to ensure that the Amounts & Units fields function as paired fields. (docs)
• Negative Amount Values Disallowed - Sample Manager now enforces that the Amounts field cannot have a negative value.(docs)
• Identifying Fields - Identifying fields are now shown in more assay import scenarios. (docs)

Release 25.11, November 2025

• Audit log captures the method used to insert, update, and delete records. (docs)
• When an ELN notebook is recalled by an administrator, the author will now receive an email notification, improving visibility and timely follow-up.
• The Customize Grid View and Filter pop-up dialogs now list fields alphabetically, making it faster and more intuitive to find and select fields.
• Error bars are available on Bar and Line charts. (docs)
• Multiple charts can be displayed above data grids. Select up to 5 charts to display. (docs)

Release 25.3, March 2025

• Rapidly find the plates and experiments in which samples have been used, and vice versa.
• Automatically generate analytics like regressions and statistics to accelerate your work

Release 25.2, February 2025

• Support for advanced plate layouts using using dilutions.
• Use the "Replicate Group" column to denote a plate well as a replicate instead of setting the well's type to "Replicate".
• Replicate wells have a type of "Sample" and the "Replicate Group" will need to be filled in.
• Add Samples to an existing Plate Set.
• Navigate from a plate set to any notebooks that reference it.
• Edits to outlier exclusions will result in the rerunning of any transform scripts that are configured to run on update.

Release 25.1, January 2025

• Users can now specify hit selection filter criteria on Assay fields. When a run is imported/edited the hit selections for the assay results will be recomputed and automatically applied based on these criteria.
• Navigate from a sample to the plate(s) it has appeared on.
• Perform many types of linear regression analysis and chart them.
• Exclude outlier plate-based assay data points and have that reflected in calculations and charts.

Release 24.12, December 2024

• Plate sets can be referenced from an Electronic Lab Notebook.

Release 24.11, November 2024

Major antibody discovery and characterization updates including:

• Campaign modeling with plate set hierarchy support.
• Plan plates easier with graphical plate design and templating.
• Automate routine analyses from raw data collected.
• Perform hit selection from multiple, integrated results across plates and data types.
• Generate instructions for liquid handlers and other instruments.
• Automatically integrate multi-plate results including interplate replicate aggregation.
• Dive deeper into plated materials to understand their characteristics and relationships from plates.

Release 24.10, October 2024

• Charts are added to LabKey LIMS, making them an "inherited" feature set from other product tiers. (docs)

Release 24.7, July 2024

• A new menu has been added for exporting a chart from a grid. (docs)

Release 23.12, December 2023

• The Molecule physical property calculator offers additional selection options and improved accuracy and ease of use. (docs)

Release 23.11, November 2023

• Update Mixtures and Batch definitions using the Recipe API. (docs | docs)

Release 23.9, September 2023

• Charts, when available, are now rendered above grids instead of within a popup window. (docs)

Release 23.4, April 2023

• Molecular Physical Property Calculator is available for confirming and updating Molecule variations. (docs)
• Lineage relationships among custom registry sources can be represented. (docs)
• Users of the Enterprise Edition can track amounts and units for raw materials and mixture batches. (docs | docs)

Release 23.3, March 2023

• Potential Backwards Compatibility Issue: In 23.3, we added the materialExpDate field to support expiration dates for all samples. If you happen to have a custom field by that name, you should rename it prior to upgrading to avoid loss of data in that field.
• Note that the built in "expirationDate" field on Raw Materials and Batches will be renamed "MaterialExpDate". This change will be transparent to users as the new fields will still be labelled "Expiration Date".

Release 23.2, February 2023

• Protein Sequences can be reclassified and reannotated in cases where the original classification was incorrect or the system has evolved. (docs)
• Lookup views allow you to customize what users will see when selecting a value for a lookup field. (docs)
• Users of the Enterprise Edition may want to use this feature to enhance details shown to users in the "Raw Materials Used" dropdown for creating media batches. (docs)

Release 23.1, January 2023

• Heatmap and card views of the bioregistry, sample types, and assays have been removed.
• The term "Registry Source Types" is now used for categories of entity in the Bioregistry. (docs)

Release 22.12, December 2022

• Projects were added to the Professional Edition of Sample Manager, making this a common feature shared with other tiers.

Release 22.11, November 2022

• Improvements in the interface for managing Projects. (docs)
• New documentation:
• How to add an AnnotationType, such as for recording Protease Cleavage Site. (docs)
• The process of assigning chain and structure formats. (docs)

Release 22.10, October 2022

• Improved interface for creating and managing Projects in Biologics. (docs)

Release 22.9, September 2022

• When exploring Media of interest, you can easily find and review any associated Notebooks from a panel on the Overview tab. (docs)

Release 22.8, August 2022

• Search for data across projects in Biologics. (docs)

Release 22.7, July 2022

• Biologics subfolders are now called 'Projects'; the ability to categorize notebooks now uses the term 'tags' instead of 'projects'. (docs | docs)

Release 22.6, June 2022

• New Compound Bioregistry type supports Simplified Molecular Input Line Entry System (SMILES) strings, their associated 2D structures, and calculated physical properties. (docs)
• Define and edit Bioregistry entity lineage. (docs)
• Bioregistry entities include a "Common Name" field. (docs)

Release 22.3, March 2022

• Mixture import improvement: choose between replacing or appending ingredients added in bulk. (docs)

Release 21.12, December 2021

• Freezer Management is added to Biologics LIMS

Release 21.11, November 2021

• Apply a container specific prefix to all bioregistry entity and sample naming patterns. (docs)

Release 21.10, October 2021

• Customize the definitions of data classes (both bioregistry and media types) within the application. (docs)

Release 21.9, September 2021

• Customize the names of entities in the bioregistry (docs)

Release 21.7, July 2021

• Removal of the previous "Experiment" mechanism. Use workflow jobs instead.

Release 21.5, May 2021

• Nucleotide and Protein Sequence values can be hidden from users who have access to read other data in the system. (docs)

Release 21.4, April 2021

• Specialty Assays can now be defined and integrated, in addition to Standard Assays (docs)
• Creation of Raw Materials in the application uses a consistent interface with other sample type creation (docs)

Release 21.3, March 2021

• Biologics LIMS begins using the same user interface as Sample Manager.
• Release notes for this and other versions prior to this change can be found in the documentation archives.

Release 17.1, March 2017

• Biologics LIMS is Launched!

Overview

This page will be updated with the most recent version of the release schedule.

25.11.8 Sample Manager/LabKey LIMS Validated Release Schedule

Please refer to this schedule for the 25.11.8 validated release of Sample Manager/LabKey LIMS.

• Week of January 19: Upgrade test environments to early access release of 25.11.8
• Jan 26 : LKSM Validation Pack Released (Originally scheduled for Feb 6)
• Feb 18: Target release date for LIMS Validation Pack (previously scheduled for Feb 13)
• Upgrade of production environments to 25.11.8
• Asia/Oceania - Feb 10 5:30-7:00am AEDT
• Africa/Europe - Feb 09 6:30-8:00pm GMT
• Americas - Feb 09 6:30-8:00pm EST

Last updated: 2026-02-05

Sample Manager & LabKey LIMS Software Validation & Release Schedule - General

This is the generalized release schedule for LabKey Sample Manager & LIMS validation

Phase 1: Validation Planning and Initial Updates

• Week 0: Kickoff: LabKey + CompliancePath meet to discuss approach, timelines, and scope.
• Week 1: LabKey upgrades CompliancePath server (pre-work for validation updates).
• Weeks 1-4: CompliancePath begins updating Validation Pack (URS, Risk Assessment, OQ updates).

Phase 2: Customer PQ Preparation & Staging Environment Updates

• Weeks 2-6: LabKey sends communications to customers:
• Release notes for YY.MM.02–YY.MM.06
• Validation timeline & expectations
• Staging upgrade windows
• Rough plans for production upgrades
• Weeks 2-6: LabKey upgrades customer testing/staging environments.

Phase 3: Validation Pack Release & Production Upgrades

• Week 8: LabKey upgrades CompliancePath and customer testing environments to YY.MM.08.
• Weeks 9-10: CompliancePath executes OQ testing and finalizes the Validation Pack updates.
• Week 10: CompliancePath releases the completed Validation Pack to LabKey and customers.
• Week 11: LabKey upgrades customer production environments to YY.MM.08.

Welcome to LabKey Sample Manager

The resources linked here will help you get started using LabKey Sample Manager for sample tracking. First, complete the steps in the Exploring Sample Manager guide to learn to add sample information, define lineage, and understand the processes you will follow to find and use your data.

Getting Started, Step by Step

• Exploring Sample Manager: Get the most out of your 30-day trial

More Video Overviews and Demos

Each will open in a new tab.

• Upgrade your lab from spreadsheets to Sample Manager
• Spring cleaning with Sample Manager
• See how Sample Manager can level-up your lab work
• Getting started with Sample Manager

Configure Freezers and Other Storage

Matching your physical storage to virtual storage locations in the app can make it easy to know where to find the samples you need.

• Storage Management

Add Sample Inventories

Getting your sample information loaded is the heart of using Sample Manager. Define the structure of the data to describe each "type" of sample in your system. Once the types are defined, the samples can be created within the application or imported from a spreadsheet.

• Create a Sample Type
• Add Samples
• Import Samples from File
• Import Samples with Storage Locations
• Import Samples with Lineage

Associate Sources

If your samples have physical or biological sources that you want to track, you can learn about adding them and associating them with samples in these topics:

• Create Sources
• Associate Samples with Sources

Define Assays (Premium Feature)

The data you obtain from running instrument tests on your samples will be uploaded as an assay to LabKey Sample Manager. These topics will guide you in designing assays and uploading your data.

• Describe Assay Data Structure
• Import Assay Data

Outline Workflow (Premium Feature)

Your laboratory workflow can be managed by creating workflow jobs for the sequences of tasks your team performs. Add your users, set permissions, and organize your jobs and templates following these topics:

• Add Users and Set Permissions
• Create a First Job
• Complete the First Job

Use Electronic Lab Notebooks (Premium Feature)

Collaborate and record your work in data-connected Electronic Lab Notebooks. Use templates to create many similar notebooks, and manage individual notebooks through a review and signing process.

Learn more in this section:

• Electronic Lab Notebooks (ELN)

• Release Announcement Banner
• Dashboard Insights
• Exclude Sample Types from Dashboard Insights
• Sample Finder
• Locations Recently Added To
• Main Menu
• Header Menus
• Notebooks Available in the Professional Edition of Sample Manager.
• Jobs List Available in the Professional Edition of Sample Manager.

Note that on narrower screens, the panels of the dashboard will be stacked vertically instead of being arranged as shown above. Some panels are also only available in the Professional Edition of Sample Manager.

Release Announcement Banner

At the top of the dashboard, you'll see a banner announcing the latest release. Click the text "See what's new" to link to the release notes.

This banner can be dismissed by clicking the on the right. At any time you can also link to the release notes by selecting > Release Notes from the application header.

Dashboard Insights

See the current status of the system, with several display options. By default, you see the total count of samples of each Sample Type, shaded by the label color you assign.

Select from the leftmost dropdown to show:

• Sample Count by Status (Default)
• Sample Count by Sample Type
• Assay Run Count by Assay (Professional Edition Feature)

• Sample Count by Status offers:
• All Statuses
• With a Status
• No Status
• Sample Count by Sample Type -or- Assay run Count by Assay offer the timeframe over which the count of samples or assays is determined. Options:
• All
• In the Last Year
• In the Last Month
• In the Last Week
• Today

Learn more about samples in this section:

• Samples

Exclude Sample Types from Dashboard Insights

If desired, an administrator can selectively exclude selected Sample Types from the Dashboard Insights panel. For example, if you have one "static" set of inventory items in your repository, but these never change, you may be interested in hiding them to make the Insights panel more usable for the types in active use.

Select > Application Settings and scroll down to the Dashboard section. Note that if you are using Folders in Sample Manager, this option is on the Folders tab.

In the Dashboard section, you can uncheck any Sample Types that you wish to have excluded from the Sample Insights dashboard for this folder.

Unchecking boxes in the dashboard section does not delete any data, it simply removes those Sample Types from the graphs displayed, helping users focus on the most important Sample Types for their work.

For example, in the first image, the "Tutorial Samples" type completely overwhelms the actual samples that might be of interest. Once hidden, the details for the other types are clearer.

Sample Finder

Click Go to Sample Finder in the center of the dashboard to search for samples by properties of their parents and sources. Learn more in this topic:

• Sample Finder

Locations Recently Added To

Storage is shown on the dashboard using a Locations Recently Added To widget.

• The "All Recent Locations" tab is the default, showing storage locations that have had samples added to them most recently.
• You can also choose "Your Recent Locations" to see where you last added samples, giving you a quick way to jump back to where you were.

Learn more here. To see the overall Storage List, use the main menu.

Main Menu

Throughout the application, you can access a master menu providing quick links to everything in the system.

• Source Types
• Sample Types
• Storage
• Picklists
• Assays Available in the Professional Edition of Sample Manager.
• Workflow Available in the Professional Edition of Sample Manager.
• Notebooks Available in the Professional Edition of Sample Manager.

Header Menus

In the upper right, menus provide quick access to resources and actions.

• : Search
• : Product Selection Shown when using a Premium Edition of LabKey Server.
• : Notifications
• : Documentation
• Help Opens the documentation home page for the application.
• Release Notes
• : Administration Settings
• Application Settings: Includes Display Settings, Notebook Settings, BarTender Configuration, ID/Name Settings, and Manage Sample Statuses.
• Audit Logs
• Folders If available
• Groups
• Permissions
• Users
• User avatar menu
• Notification Settings
• Profile
• Sign Out (or Sign In)

Notebooks (Professional Edition Feature)

Collaborate and record your work in data-connected Electronic Lab Notebooks. Use templates to create many similar notebooks, and manage individual notebooks through a review and signing process. Available in the Professional Edition of Sample Manager.

Learn more in this section:

• Electronic Lab Notebooks (ELN)

Jobs List (Professional Edition Feature)

At a glance, see the jobs and tasks assigned to you in Your Job Queue. A second tab will show you other Active Jobs. Learn more about jobs and workflow in this section:

• Workflow

Related Topics

• Get Started with Sample Manager

Folders allow users to organize and partition sensitive data within the application, all while maintaining a shared storage environment. Data structures and resources like reagent lists can also be shared lab-wide to support consistency, while individual teams work with their own secured data.

• Video
• Overview
• Home and "Sub" Folders
• Manage Folders
• Create New Folder
• Set Folder Permissions
• Edit Folder
• Archive Folder
• Delete Folder
• Select Types of Data in Folder
• Exclude Sample Types from Dashboard Insights
• Select Folder Storage
• Work within Folders
• Best Practices

Video

In this video, you will see how to configure and use Folders to work with data across different teams using Sample Manager Professional.

Overview

Without the use of Folder organization, Sample Manager does not partition data for different teams. Permissions are granted to all data simultaneously in a single "container".

When you enable Folders in the Professional Edition of Sample Manager, data can be grouped and partitioned by teams.

Home and "Sub" Folders

The home is the top level container and provides shared definitions and storage configurations. Data can be added directly in the home or to the individual "sub" folders as appropriate. Permissions are controlled independently in each folder, making it easy to partition separate team spaces.

• Sample Types, Source Types, etc. are defined in the home folder to support lab-wide consistency. Administrators can create and/or edit these structures from within subfolders, but the changes will be made to the home definition and shared by all subfolders.
• Storage systems like freezers are also defined in the home to match the shared physical space. Individual teams can see the details of stored samples they have permission to read, but only see space allocated to other teams as "occupied".
• Reports and views of all data you have access to can be created in the home, summarizing all the data an individual user has access to.
• Create shared resources like reagents in the home so that they can be shared & viewed by all folders.
• Use folder permissions to partition each study from one another making it easy to operate in compliance with regulations.

Manage Folders

To manage Sample Manager Folders, open the application and select > Folders.

On the Folders administration page, you'll see a listing of any existing folders, with the first selected by default. You can edit existing folder details or create a new one.

Create New Folder

Click Create a Folder to add a new folder. Enter the Folder Name and uncheck the checkbox if you wish to provide a different label.

For the panels below the folder name, uncheck boxes if you want to limit the resources that are shown in your new folder. The default is that everything from the home is visible in all folders. Learn more about each section below.

• Data: Select the types of data that can be viewed in this folder.
• Dashboard: Select the data types to include in the Dashboard Insights graphs.
• Storage: Select the storage that can be used by samples in this folder.

Set Folder Permissions

When first created, only administrators can view a new folder. This can be useful when configuring the folder for a team to ensure the users only access it when ready.

You can configure folder permissions immediately when you create it by clicking Update folder permissions. Later you can also reach this page by clicking the for the folder on the main menu, or from anywhere in the folder by selecting > Permissions.

Note that within a folder, the Application Administrator role is not assignable; it can only be set at the top application level. On a Premium Edition of LabKey Server, you can set the Folder Administrator role to apply to this folder only, but cannot set the application-wide role.

Learn about configuring permissions in this topic:

• Permission Roles

Edit Folder

Click the name of a folder to make any changes to its settings.

• Select Types of Data in Folder
• Select Types for Dashboard Insights
• Select Folder Storage
• BarTender Settings
• ID/Name Settings
• Manage Sample Statuses

Archive Folder

When users no longer need regular access to a given folder, such as when the work it records is completed, the folder can be archived. Archived folders retain all their data and access permission settings, so users with access will still see archive folder data in search results, and in the home (top-level) application. Archived folders can be viewed, but will no longer be offered as options for actions like moving samples or other information. This can simplify the selection interface for users without actually deleting the folder or any data.

To archive a folder:

• Click its name from the > Folders dashboard.
• Click Archive Folder.

• Click Yes, Archive Folder in the popup to confirm.

An archived folder can be restored at any time. It will be listed under Archived Folders and the button will now read Restore Folder.

Delete Folder

To delete a folder:

• Click its name from the > Folders dashboard.
• Click Delete Folder.

Select Data in Folder

An administrator can restrict the Source Types, Sample Types, and Assay Designs that are visible in a given folder. This can be configured during folder creation or later by editing folder settings.

You'll see all the Source Types, Sample Types, and Assay Designs available in the home (top-level) folder. By default, everything available will be visible in the folder, but you can uncheck boxes for types of data that will not be used in the folder. If data is present, you'll see a message about what will no longer be visible.

Note that 'hiding' or deselecting a data structure here does not delete any data that may exist using it. It just simplifies dropdown menus for users. The hidden entities will not be seen, but will still be present (and lineage relationships preserved). Nor does hiding a type of data prevent it from being used in the future if these settings are edited.

The folders in which a given data structure is visible can also be set while creating or editing the data structure itself in the Folders panel. For example, if the "Labs" Source is not in use for "Team B", the Folders panel might look like this:

Exclude Sample Types from Dashboard Insights

When using Folders in Sample Manager, the ability to exclude Sample Types from Dashboard Insights is moved to the Folders tab. There is a Dashboard section for each folder, including for the top level home folder.

Learn more in this topic:

• Sample Manager Dashboard

Select Folder Storage

An administrator can limit the storage systems that are accessible from a given folder by using checkboxes in the Storage panel. For example, if you wanted to create a folder for a team that would only use a single freezer in their local lab, you could hide all other storage systems.

Note that this does not delete any storage or change how samples are stored in the hidden freezers, it just simplifies the dropdown menus for users in the folder.

The folder in which a given storage system is visible can also be set while creating or editing the storage definition using the Folders panel below the hierarchy. For example, if this freezer is not in use in the "Team Beta" folder, that box can be unchecked:

Work within Folders

Once one or more folders have been defined, the main menu will include the name of the current folder and a panel on the left for selecting the home or another folder. Each user will see only the folders to which they have access.

To navigate, click the name of the desired folder, then the page of interest from the main menu. When you hover over a folder name, you'll see quick links to key pages for that folder:

• Dashboard
• Administration

When you are in the home of the application, you can add or manage data and definitions like Sample Types and Assay Designs for all the folders to be able to share.

When in a folder, you will still see data for all folders you can access, but additional data added will only be available in that folder and visible only to users permitted to see that folder's contents.

Note that changes like editing a Sample Type definition in a folder require permission to make those changes at the home level and they will apply to all folders.

Learn about actions across folders in this topic:

• Cross-Folder Actions

Best Practices

• Home: Top-level folder
• All users must have Read access to the top level of the application.
• Recommended: Only assign non-admin users Read access (and Storage Designer/Editor as appropriate) in the top level Home folder. Edit/add permissions will be granted in individual folders.
• The Home is where all Source Types, Sample Types, Assays, Storage Systems and Templates for ELN and Workflow are defined.
• Administrators can create and edit Source Types, Sample Types, Assays, Storage Systems from within folders, but all changes are made in the home definitions and apply to all folders.
• Add to the Home all "shared resources" you want to be able to access in other folders, such as shared reagent lists, etc.
• Folders
• Team/Group/Study-based access to sources, samples, assay data, workflow & ELNs.
• Within a folder, users can edit/update their folder data.
• From the Home level, users can read their folder data (and all data they can access).
• For data to be readable by everyone but that does not need to integrate (or inherit from) other data, create a folder that everyone has access to.

Related Topics

• ID and Name Settings
• Cross-Folder Actions

This topic covers the details about how the Sample Manager and Biologics LIMS products handle actions across Folders.

• Cross-Folder Actions
• Summary of Functionality
• Detailed Cross-Folder Actions
• Restricted Visibility of Inaccessible Data
• Add or Edit Entities Across Folders
• Move Samples, Sources, and Assay Runs Between Folders
• Move Workflow Jobs Between Folders
• Move Notebooks Between Folders
• Storage Shared Across Folders

Cross-Folder Actions

Summary of Functionality

When Folders are in use, the following summarizes the high-level behavior of actions for Samples and Sources (or other Data Classes), collectively referred to as "entities". A given user may have different permissions assigned in different folders, as well as at the application-level, i.e. in the Home folder.

Reading of entities: You can read the current folder's entities as well as the ones in the Home and other folders you have permissions to read.

Connecting entities with lineage relationships: Entities can have ancestor entities in the current folder and the Home, provided you have the necessary permission. Entities defined in the Home cannot have ancestors in a subfolder.

Creating entities: Entities are created by default in the folder the user is viewing at the time the action is initiated. Users with appropriate permissions can choose to create entities in other folders they have access to when using the grid to create them. Importing entities from file will create them in the folder where the import is initiated, unless the file includes a "Container" column (which can also be labelled "Folder").

Updating entities: An entity can be updated from the folders in which it was created. Users with appropriate permissions can also update entities across folders. The folder to which the entity is assigned is shown 'read only' when editing entities from multiple folders in a grid. Moving entities between folders should be done separately.

Deleting entities: An entity can be deleted from the folder in which it was created. Users with appropriate permissions can also delete entities defined in different folders.

Lookups: You can look "UP" but not down the folder hierarchy in lookup fields. In the Home folder you will see only values defined in the Home itself. In a child folder you will see values in both the current and Home folder.

• Lookups from one child folder to another child folder may display as expected when viewed from the Home folder. If a user attempts to edit such a cross-folder lookup value from the Home folder, they may see an error that the target is "no longer a valid value". To support such 'sibling' folder lookups, an experimental "Less Restrictive Lookups" feature can be enabled.

Detailed Cross-Folder Actions

When Folders are in use, these notes apply to how some cross-folder actions are handled:

• Samples:
• Individual sample creation in a grid allows parent types from the current folder and folders above it. You cannot select parents from a "child" folder of the current one.
• Grid edit and sample deletion: Works for entities in the current folder. With appropriate permissions users can also edit and delete entities defined in different folders.
• Sample derivation, pooling, and aliquoting: Works for entities in the current folder. Users with appropriate permissions can also select samples from the Home and up to one folder for these actions. The derivatives or aliquots will be created in the folder where they are derived/aliquoted, or if in the Home with a folder selected, they will be created in the folder.
• File import only allows sample parent type and parent selection from the current folder.
• Editing parent details for an individual sample only works when adding parents from the current folder or the Home.
• Sources (as well as Bioregistry and Media entities in Biologics LIMS):
• Creating entities, either in a grid or via file import, allows parents and related entities to be chosen from the current folder or folders above it in the hierarchy. You cannot select parents from a "child" folder of the current one.
• Editing in a grid or in bulk is allowed for entities in the current folder. Users with permission can also edit entities from any folder they have access to. You do not need to be in the folder the entity belongs to, but you must have edit permission there.
• Deleting is allowed for entities in the current folder and other folders the user has access to.
• Deriving samples from a data class (source, registry source, or some media) allows parent data class objects from only the current folder or a folder above it.
• Assay:
• Imported assay data can reference samples in the current folder or any 'higher' (parent) folder, but cannot reference samples in sibling or 'lower' (child) folder.
• Imported assay data can also reference samples defined in the /Shared project.
• When assay runs and/or results are editable, users with appropriate permissions can select from multiple folders for editing.
• Storage:
• Freezers (or other storage) can only be defined in the Home folder.
• Samples from multiple folders can be selected at once for adding to storage.
• Learn more about shared storage below
• Workflow:
• Creation of workflow jobs using samples from different folders is possible both from any folder.
• The job that is created will belong to the folder in which it was created, regardless of the samples included.
• When the job is opened, the user is navigated to the folder in which it is defined, to ensure that actions performed as part of the tasks are in the correct folder.
• Additional samples from all visible folders can be added to existing jobs.
• Picklists:
• Creation of picklists using samples from different folders is possible from any folder.
• The picklist that is created will belong to the folder in which it is created, regardless of the samples included.
• The picklist will be visible in only the folder in which it was created.
• Additional samples from all visible folders can be added to existing picklists in the current folder.
• Notebooks:
• Notebooks can reference entities from all folders visible in the current context.
• Notebooks created from a parent folder are also visible from any child folder, and vice versa.
• Notebooks created in any folder can be submitted for review, or accessed for review, from any folder.

Restricted Visibility of Inaccessible Data

When a user has access to a subset of folders, there can be situations where this user should be restricted from seeing data from other folders, including identifiers such as Sample IDs that might contain restricted details. In detail pages, listing pages, and grids, entities a user does not have access to will show "unavailable" in the display instead of a name or rowid.

As an example, if a notebook contains references to any data a user cannot access, they will not be able to access that notebook. It will not be included on the "All Notebooks" listing and if they happen to directly access it, such as through a saved URL, they will see only a banner message reading "You cannot view notebook [notebook title] because it contains references to data you don't have permission to view. The references may be in active or archived entries."

As another example, when a storage unit contains samples you cannot view, you'll see the space occupied by a lock icon and a hover message will explain "This location is occupied by a restricted sample."

In timelines, the names of entities the user does not have access to, such as the parent of an entity they can access, will be redacted from the timeline events.

Add or Edit Entities Across Folders

When the user has the appropriate permissions, samples and sources can be added to a folder the user is not currently in by using the Folder dropdown to select the target folder.

With appropriate permissions, a user can edit Samples and Sources that belong to different folders in bulk or in a single grid. When Assay results or runs are editable, the same cross-folder editing behavior applies.

• When editing in bulk, the folder is not shown (and not editable).
• When editing in a grid, the folder to which the sample belongs will be shown read-only. If any selected Samples that belong to folders the user is not authorized to edit, they will not be listed for editing.

Note that users cannot edit the parents or sources for Samples from multiple folders.

Move Samples, Sources, and Assay Runs Between Folders

If a user has access to multiple folders and accidentally adds something to the wrong folder, or later wants to change folder affiliation, they can use Edit > Move to Folder to move Samples, Sources, or Assay Runs between folders. Entities currently belonging to multiple folders can be selected at once to be moved to a new folder.

Sample, Source, and Assay Run moves require that the user must have update permissions in the current container and insert permission in the target container. If selected entities cannot be moved, the user will see a warning, but authorized moves will proceed.

Note that there are some situations in which data cannot be moved:

• Samples with a "Locked" status
• Samples with status values that are not defined in the Home folder. This is an uncommon scenario, and is prevented in the current application.
• Assay Runs with QC states that are not defined in the Home folder.

In the popup, select the folder to Move to from the dropdown. If the application has been configured to require a reason, you must enter a Reason for Moving, otherwise it is optional. Click Move.

The move is audited, tracked in the Timeline for the entity, and parentage and derivation lineage connections are maintained.

Move from Details Page

You can also move a single Sample, Source, or Assay Run from the details page via Manage > Move to Folder.

Move Workflow Jobs Between Folders

To move a workflow job to another folder:

• Go to the Workflow main page.
• In the table of jobs, select one or more jobs.
• Click Move to Folder.

• Select the target folder and click Move.

Move Notebooks Between Folders

Notebooks can be moved from one folder to another provided the user starts in the folder where the notebook is defined and has insert permission in the target folder. One exception is that once a notebook has been approved, it can no longer be moved.

Click the for the current Folder setting in the header section of the notebook.

In the popup, select the folder to Move to from the dropdown, enter a Reason for Moving if required or desired, then click Move.

Storage Shared Across Folders

• Set Up Shared Storage
• Storage Occupied by Inaccessible Samples

Set Up Shared Storage

To share storage, create it in the Home folder, defining the properties and hierarchies as usual. It will then be visible in all subfolders.

Users with the "Storage Editor" role in any folder will then be able to use the freezer to store and manage samples. Access to sample details is always dependent upon permissions in the container where the sample is defined.

In shared storage where a user has permission to see data from all folders using it, the user will see data from all containers as if all the samples were local. When viewing a sample from another folder, you'll see a note "Actions restricted in the current folder" in the hovertext.

Storage Occupied by Inaccessible Samples

In shared storage where a user does not have permission to read data from other folders, storage views will show a spaces as occupied, but instead of revealing any data about the sample, will show a icon. This means the space is occupied by a "restricted sample".

The Legend will give more detail about symbols and colors in the grid.

Related Topics

• Folder Organization

This topic covers management of user access in LabKey Sample Manager. All Sample Manager users are defined by their email address and new users are assigned a unique user ID generated by the system.

Administrators can perform these actions via > Users.

• Add Users
• View User Details
• Manage Users
• User Details
• Deactivate Users
• Delete Users (Not recommended)
• View Inactive Users
• User Limit Alerts

• Biologics Administration
• Permission Roles

Add Users

To add one or more new users, an administrator selects > Users, then clicks Create.

In the popup:

• Enter one or more email addresses, each on its own line for each user you want to create.
• Select the desired Roles for the users you are creating:
• You can assign multiple roles at once. Delete a role by clicking the 'X' for the item.
• Learn more about the available roles here: Permission Roles
• Note that all users added at once are assigned the set of roles you select. You can change these role assignments later.
• Optional Message: You can add an optional additional message to include in the invitation email to your new users.
• Click Create Users.

The new user will receive an email with a link to set a password and log in. Passwords for Sample Manager cloud-hosted customers must meet the criteria for the "Strong" password setting.

If the new user should lose their initial invitation email, an admin can trigger the sending of another by selecting the row for that user and clicking Reset Password in the user details. See below.

View User Details

Within the application, when an administrator (or user with the "See User and Group Details") clicks a username, such as in a sample grid or ELN, they will see a popup showing the full name, email, description, as well as effective roles and groups this user is a member of.

Click Manage in the popup to go to the user management page.

Non-administrators will see only their own username as a link to their profile details. For other users, they will see only a non-linked username.

Manage Users

To manage users, an administrator selects > Users.

You will see a grid of the active users already present in your Sample Manager application. You can use search, sort, and filter options on this user grid.

User Details Panel

To view the details for any user in the grid, check the box for that user. Details including effective roles are shown in a panel to the right.

From this panel, an administrator can click the buttons at the bottom to perform these actions on this individual user.

• Reset Password: Send this user an email with a link to set a new password in order to access the site. Passwords must be strong enough to meet the requirements of the site.
• Deactivate
• Delete

Deactivate Users

Deactivated users may no longer log in, but their display name and group membership information will be retained for display and audit purposes. If the user is reactivated at a later time, this information will be restored. Deactivation is the recommended action for former employees, for example.

To deactivate a user, an administrator has two options:

1. Check the box to select a single user you want to deactivate. Click Deactivate in the User Details panel on the right.
2. You may also select one or more users simultaneously using the checkboxes in the grid, then select Manage > Deactivate Users.

Delete Users (Not recommended)

Deletion of a user is permanent and cannot be undone; it is generally not recommended. A deleted user's display name will no longer be shown with any assignments or actions taken by that user. A deleted user cannot be reactivated to restore any information.

Instead of deleting, deactivation is recommended for any user who has performed any work in the system in the past.

One scenario in which deletion might be appropriate is if you originally create a new user with an incorrect email address or other error.

To delete a user, an administrator has the same two options as for deactivation:

1. Check the box to select a single user you want to delete. Click Delete in the User Details panel on the right.
2. You may also select one or more users simultaneously using the checkboxes in the grid, then select Manage > Delete Users.

View Inactive Users

Notice that the grid reads Active Users by default. To view the grid of deactivated users instead, select Manage > View Inactive Users.

You can check a box to see details for inactivated users, and buttons are offered to Reactivate and Delete a single user.

On the grid of inactive users, the Manage menu actions are also slightly different. You can select one or more rows to reactivate or permanently delete users. You can also switch back to the grid of active users.

Use Manage > View All Users from either view to see the combination of active and inactive users.

User Limit Alerts

When the number of active users approaches the application limit, administrators will see a warning message on the > Users page.

Users of Premium Editions of LabKey Server can learn more in this topic:

• Limit Active Users

Related Topics

• My Account
• Biologics Administration
• Permission Roles
• Audit History
• Workflow

• Sign In and Out
• Session Expiration
• Edit Your Profile
• Upload Avatar
• Change Password
• API Keys (Professional Edition Feature)

Sign In and Out

From within the LabKey Sample Manager application, you can log in and out via the user avatar menu in the upper right.

To sign in, enter your email address and password on the login page, then click Sign In.

When you are logged in, there will be a Sign Out link on the user menu where Sign In was before.

Session Expiration

If your session expires while you are using LabKey Sample Manager, you will see a notification popup with a button to Reload Page. You will be asked to log in again before completing the action.

The default timeout is 30 minutes of idle time in the browser. Session expiration can also occur if the server restarts in the background.

Similarly, if you log out of LabKey Sample Manager in another browser window, you will be notified of the need to log back in to proceed.

Edit Your Profile

Once logged in, you can manage your account information by selecting Profile from the user avatar menu in the upper right.

Edit User Details

On your profile page, you can edit your display name, as well as your first and last name and description. You cannot edit your email address here; contact your administrator if you need to change your email address.

Upload Avatar

Drag and drop an image into the drop area to use a custom avatar on your profile. The avatar image must have a height and width of at least 256 px. If you upload a rectangular image, it will be cropped to fit the square.

Once you have uploaded an avatar, you can reedit your profile and click Delete Current Avatar to revert to the default.

Change Password

To change your password, click Change Password in the upper right. In the popup, enter your old password, and the new password you want to use twice. Passwords must be strong and complex enough to meet the requirements set for the site. For Sample Manager clients, the "Strong" set of password rules applies automatically. Click Submit to save the new password.

API Keys (Professional Edition Feature)

Developers using the Professional Edition of Sample Manager who want to use client APIs to access data in the application can do so using an API key to authenticate interactions from outside the server. A valid API key provides complete access to your data and actions, so it should be kept secret. Learn more in the core LabKey Server documentation here:

• API Keys

• Scroll down to the API Keys section.
• Click Generate API Key to obtain one.
• Provide an optional Description so you can keep track of when each key you create expires.
• Click Generate API Key again.

• The new key will be shown in the popup and you can click the button to copy it to your clipboard for use elsewhere to authenticate as your userID on this server.
• Important: the key itself will not be shown again and is not available for anyone to retrieve, including administrators. If you lose it, you will need to regenerate a new one.
• You'll see the creation and expiration dates for this key in the grid. The expiration timeframe is configured at the site level by an administrator and shown in the text above the grid. A key without an expiration date was configured when keys were set to never expire.
• The last usage date and any description you entered will also appear here.

Later you can return to this page to see when your API keys were created and when they will expire, though the keys themselves are not available. You can select any row to Delete it and thus revoke that key.

Related Topics

Administrators can manage user accounts and permissions as described in this topic:

• User Accounts, Groups, and Roles

LabKey uses a role-based permissions model. This topic covers the permission roles available in Sample Manager and the process for assigning them to the appropriate users and groups.

• Available Roles
• Assign Roles to Users and Groups
• Remove Users and Groups from Roles

Available Roles

Once users and groups have been defined, an administrator can assign them one (or more) of the available permission roles:

• Administrators: Have full control over the application including user management, permission assignments, storage editor and designer tasks, creating and editing sample types, assays, and job templates.
• Application Administrator is the name of this role when Sample Manager is used as a standalone application.
• When Sample Manager is used with a Premium Edition of LabKey Server, there are two levels: Project Administrators and Folder Administrators. Learn more in the core LabKey Server documentation.
• Editors: May add, edit, and delete data related to samples, assays, and jobs, but not storage information. May assign workflow jobs and tasks to other users, but not to project groups.
• Editor without Delete: May add and edit, but not delete, data related to samples, assays, and jobs. May not edit storage information. Learn about limited exceptions here.
• Readers: Have a read-only view of the application.
• Storage Editors: Have read permission for sample data. They may also add, edit, and remove samples from storage. They can move storage units, provided they have the role in the top level folder. They can create, update, and delete their own picklists, and participate in workflow jobs. Learn more here.
• Storage Designers: May read, add, and edit data related to storage locations. They may delete empty locations. Learn more here.
• Workflow Editor: This role includes the ability to read all data, and allows users to be able to add, update, and delete picklists and workflow jobs. Workflow editors can assign jobs and tasks to groups as well as individual users.
• It does not include the ability to add or edit job templates or any sample, source, or assay data.
• Note that this role does allow a user to delete tasks from a workflow job, as part of having the ability to edit the job.

• Sample Type Designer: Create and design new Sample Types or change existing ones.
• Source Type Designer: Create and design new Source Types or change existing ones.
• Assay Designer: Create and edit Assay Designs.

Assign Roles to Users and Groups

Open permissions management by selecting > Permissions.

To add a user or group to any role:

• First click the role section. You'll see the current members of that role.
• Click the Add member or group dropdown and start typing a user's email address or the name of a user group.
• Click the user email or group name to add to the role.
• Selected users and groups will be shown in the panel for the role as you go.
• Each time you select a user, the details for that user will be shown on the right to assist you.
• In the image below, the Editor role is being granted to users named "team lead" and "lab technician"; the Reader role is being granted to the "reviewer".

Click Save.

Remove Users and Groups from Roles

To remove a level of access for a given user or group, reopen the interface for granting that role and click the X for the user or group you want to delete from the role. Removing a user from a role does not deactivate or remove the user account itself.

Related Topics

• User Accounts, Groups, and Roles
• Biologics Administration
• Security Roles Reference: More detail about all the available security roles.
• Freezer Storage Roles
• Sample Manager Permissions with Premium Editions of LabKey Server

• User Groups
• Create Group
• Add Users to Groups
• Grant Permission Roles to Groups
• The "Users" Group
• Delete Group

User Groups

To access the group management page, select > Groups. All existing application groups will be shown.

Create Group

To create a new group, type the name of the group and click Create Group.

You'll now see a new tile for your group. Click Save when ready to save your changes.

Add Users to Groups

Expand the group by clicking anywhere in the tile and use the Add member dropdown to add members. You can add individual users, or other groups, to a group. Each time you add a new member, you'll see User Details on the right.

Click Save to update groups and assignments.

Grant Permission Roles to Groups

User groups can be added to permission roles just as users can. Learn more in this topic:

• Permission Roles

Users with the "Workflow Editor" role can assign workflow jobs and tasks to groups, as well as add groups to the notify list.

The "Users" Group

Note that there is always a "Users" group predefined, sometimes used to represent every user with any access to the application, though this is not automatic. Users or groups must be explicitly added to this group. For example, you might add all the groups you define to the "Users" group in order to assign "Reader" permissions and ensure a minimal level of read access to every group member.

You can also choose to delete this group (when it is empty) if you don't want to use it.

Delete Group

To delete a group, you must first delete the members by clicking the X for each, then click Delete Empty Group.

Related Topics

• User Accounts, Groups, and Roles
• Permission Roles

• In-app Notifications
• Email Notifications

In-app Notifications

Notifications of interest to each user are shown in a menu in the header bar. If any background imports are in progress, the bell will be replaced with a . The number of waiting notices will be shown in orange, superimposed on the bell or spinner icon.

Click for a listing. Each notification has a corresponding status, time of completion, and link to either the successfully imported data, or to more information about an error. Use the View all activity link to see all job details.

Email Notifications

Users of the Professional Edition of Sample Manager can control whether they receive email for either Notebooks or Workflow or both. Email notifications allow users to learn about important events without having to manually check for them.

• Notebook notifications are sent when notebooks the user is a part of are submitted, approved, or have changes requested.
• Workflow notifications are sent about events that occur regarding jobs or tasks assigned to the user or which they are following.
• Users can also find a dashboard of workflow jobs they are on the Notify List for on the Your Tracked Jobs dashboard.

• A task assigned to me is ready to be completed
• A job that includes tasks assigned to me is initiated
• A job that I owned and completed was reactivated by another user
• A comment was added to a task assigned to me

Receive Email Notifications

By default, all users will receive email notifications about Workflow and Notebook events that occur that they are part of, or are following. Users can choose to opt out of all email notifications by disabling these settings.

Select Notification Settings from the user menu, then check the box for the notifications you want. Uncheck the box to disable receiving email notifications for the category.

Related Topics

• My Account

This topic provides answers to some commonly asked questions about LabKey Sample Manager.

• Data Ownership and Audit
• Sample Identification
• Freezer Management
• Data Structures for Assays and Samples
• Jobs, Tasks, and Templates
• Sample Manager and LabKey Server
• Future Plans

Data Ownership and Audit

If I store my data in LabKey Sample Manager do I still own the data? If I choose to end my subscription later, will I be able to get it back?

Absolutely. Whether cloud-based or on premise, you always own your own data. If you stop using Sample Manager, you will receive a full export of all your data.

Will privacy be maintained if I use Sample Manager?

Absolutely, the LabKey security model guarantees privacy and security using our role based access model.

However, if you need to store PHI and/or are interested in HIPAA compliant protection of your data, contact us to discuss whether another LabKey product might better meet your compliance needs.

Do samples have an audit trail for chain of custody tracking?

Yes! Every action is tracked in a set of audit logs on a row by row level. Enhanced chain of custody tracking features are available in a Timeline for samples. Learn more in this topic:

• Sample Timeline

Sample Identification

Is the sample ID assigned by the system unique to just one lab? Can they be shared?

Yes, right now because there is a single Sample Manager application serving each lab, if you ask the application to generate sample IDs for you, they will be unique within that single lab. However, letting the system assign sample IDs is not the only option.

If you wanted to share sample information across multiple labs, you could override the automatic assignment option by providing your own unique sample IDs, such as by using a sample manifest. The distinct Sample Manager applications at many lab sites could accept and use these sample IDs that are drawn from a master assignment list ensuring that they are both unique within a single application and unique across multiple locations.

Does Sample Manager handle replicates?

Yes, sample replicates can be identified using custom naming conventions, i.e. S101-1 and S101-2 are replicates of one original sample.

Does Sample Manager track the subject of study, i.e the source of the sample.

Yes, you can identify and track many types of sample Sources within the application. Learn more in this section:

• Sources

Does Sample Manager support using a barcoding system?

Yes, you can create your own field (either text or integer) to hold your own barcode values. Or, with the addition of a "UniqueID" column, Sample Manager will generate unique barcodes for samples for you. These barcodes are read-only, simple, and easy to use. Learn more in this topic:

• Barcode Fields

• BarTender Integration
• Print Labels with BarTender

Freezer Management

Does Sample Manager provide a freezer management solution?

Yes! LabKey Sample Manager includes a robust and flexible freezer management solution. Design virtual storage to match your physical storage. Easily find samples, or empty space for storing new samples. Track volume and check-in and check-out to support your workflow. Control access with specific storage roles. Learn more in this section:

• Storage Management

Data Structures for Assays and Samples

How do I get my existing sample data into the system?

LabKey Sample Manager is specifically designed to make data import easy. Design the structure of existing data and drag and drop to upload it simply and efficiently. Note that very large uploads may need to be split into batches to upload successfully.

Use custom templates to make it easier to format your data.

How does a user know what columns are expected?

The handy Download Template feature gives the user a blank template for what columns are expected. The user can either add their data to this template or simply confirm that they have the correct columns prior to import.

Can I build in customized data integrity checks?

Absolutely. Every field can have data validation performed, such as ensuring correct formats, valid ranges, and other such measures. You can also use controlled vocabularies for text fields, i.e. presenting uploading users with pulldown menus of options instead of free text entry fields.

Do you have support for tracking study visits, where multiple samples of different types are collected from one subject at once?

We don't have a built-in mechanism for tracking study visits at this time, but by defining additional custom columns for your sample types, you can track the individual and date of collection for matching. For example, using a required column for study visit, you would capture this information.

What export types are supported?

Currently you can export data as CSV, TSV, and Excel. Multi-tabbed sample lists can be exported as multi-tabbed Excel spreadsheets.

Are there predefined templates for data in Sample Manager?

There are no predefined templates. Users have full control of creating data templates for your own needs. During the definition of assays, Professional Edition users have the option to let the application infer fields in the data structure from the columns in a spreadsheet.

Are the Assays customizable? Can I create my own assays? (Professional Edition Feature)

Absolutely, with the Professional Edition of Sample Manager. Our demos and examples include some possible ways to structure typical assays, but when you define your own, you have complete control over the fields and types of data collected. The only requirement is that assay data needs to provide a column linking to the sample.

What happens if you import assay data but it has a column name that doesn't match?

The assay data import process will read only the "expected" columns from your data. If you have additional columns, they will be ignored. If you have a difference in column naming, you may be able to make use of column aliases to import data from a column of a mismatched name.

When importing data, you will see a preview of the first few rows to aid you in correcting issues or adding aliases.

Jobs, Tasks, and Templates (Professional Edition Feature)

Does each workflow job depend on the completion of the previous job? Or can you have multiple jobs underway simultaneously? Can you configure which job is dependent on which other job?

Each workflow job can begin/proceed independently of all other jobs. You can have as many jobs underway simultaneously as you like. If you want to have actions that proceed in a sequence, consider whether these should be defined as tasks within a single larger job, rather than separate jobs.

In the future, we hope to add an administrative option to make a job dependent upon completion of another job, but at present this is not supported. In the meantime, you could also consider having a 'check for previous job completion' task at the start of the job you want to happen 'next'.

Sample Manager and LabKey Server

Can assay results loaded via Sample Manager be linked to LabKey Studies?

Yes, if you are using the Professional Edition of Sample Manager as part of a Premium Edition of LabKey Server, your application will be running on the same server as your other LabKey projects. After loading assay data into Sample Manager, you can access it via traditional LabKey Server folder management tools and link that data into your study on the same server.

Can Sample Manager make use of assays already defined in my LabKey Server?

Yes, if you have defined Standard Assays in the scope available to your integrated Professional Edition of Sample Manager, you will see them in the list of assay designs. You may need to map one of the columns to your sample information before you can use them.

Future Plans

We are very interested in hearing your feedback about what is important to you. Future development of new features for LabKey Sample Manager is already underway.

Do you need other software to do data analysis and generate reports?

Yes, at this time, users of Sample Manager export their sample data for analysis and reporting. In the future, analysis and reporting will be added within the application.

Note that LabKey Server itself is a candidate for such analysis and reporting, and in fact, users of Premium Editions of LabKey Server can access data from Sample Manager directly from the traditional LabKey user interface.

Does Sample Manager track reagents, vendor batch number, etc.?

Not explicitly at this time. You can use custom columns to track this information yourself. One option is to use a controlled vocabulary text field to track information and let users select from lists instead of free entering values.

Related Topics

• Data Import Guidelines

More Questions?

Have more questions or need additional information? Please get in touch with us:

• Contact Us

New to Sample Manager?

• Request a Demo

Already a Subscriber?

• Request Support

Return to Documentation

• Sample Manager

• LabKey Sample Manager

• Take a self-guided tour of the application
• Sign up for a personalized demo to ask your questions
• Get started with your own trial version of the application where you can experience working with your own data

This section covers the creation and management of sample types and samples.

Topics

• Create a Sample Type
• Add Samples:
• Create Samples from Grid
• Import Samples from File
• Sample ID Naming
• ID and Name Settings
• Sample Lineage / Parentage
• LIMS: Samples
• Sample Expiration
• Sample Timeline
• Manage Samples
• Manage Sample Status
• Edit Selected Samples
• Sample Finder
• Built-in Sample Reports
• Sample Search
• Print Labels with BarTender
• BarTender Integration
• Barcode Fields
• Sample Picklists

Related Topics

• Sources: Sources can be physical, biological, or a combination of both.
• Storage Management

This topic covers the details of creating and configuring sample types.

• Video Overview
• Create a New Sample Type
• Define Sample Type Properties
• Naming Pattern
• Aliquot Naming Pattern
• Lineage Settings
• Storage Settings
• Define Sample Type Fields
• Default System Fields
• Add Custom Fields
• Barcodes
• Configure Sample/Aliquot Field Inheritance
• Finish Creating Sample Type
• Edit Sample Type Design
• Resource: Sample Naming Pattern Examples

Video Overview

In this video you will learn how to create a new Sample Type.

Create a New Sample Type

Create a new Sample Type by clicking Sample Types on the main header menu, then selecting Create > Sample Type.

Note for users of Folders: you can only create Sample Types in the home (top-level) folder. If the creation button is missing, navigate first to this top level.

Define Sample Type Properties

• The Name of the Sample Type is required and must be unique.
• The Name must start with a letter or number character, and avoid special characters and some reserved substrings listed here.
• You can edit the Name later if needed, unless an admin has disabled this option.
• Entering a Description is optional. A description can help others understand the usage.
• Naming Pattern: Every sample must have a unique name or identifier, known as a "Sample Id". Unless you will always provide these sample IDs yourself you should provide a pattern to generate them for you.
• Hover over the to see an example name using the current pattern.
• Details about customizing naming patterns are below.
• Aliquot Naming Pattern: For aliquots created from samples of this type, you can leave this blank to accept the default naming pattern, or customize it if desired.

• Provide any Lineage Settings needed.
• Set Storage Settings.
• Define a Barcodes field if desired.
• Before you click Finish Creating Sample Type, determine whether you need to add Fields.

Naming Pattern

Every sample must have a unique name or identifier, known as a "Sample Id". For each Sample Type, determine whether you will provide these sample IDs or whether you want the system to generate them for you. This decision determines what, if anything, you will enter in the Naming Pattern field. Learn more in this topic: Sample ID Naming.

• If you will provide the sample IDs, and they are in your data in a column named "SampleID", you can delete the default naming pattern (and ignore the grayed out placeholder text).
• If you will provide the sample IDs, but they are in a column named something other than "SampleID", you provide a naming pattern like this pattern ${COLUMN_NAME}. See below.
• If you want sample identifiers generated for you by the system, provide a naming pattern using the guidance in this topic: Sample ID Naming. A few examples are at the bottom of this page.
• The default naming pattern is "S-${genId}", meaning the letter S followed by a dash and an incrementing counter.

Aliquot Naming Pattern

By default, the name of the aliquot will use the name of its parent followed by a dash and a counter for that parent's aliquots.

${${AliquotedFrom}-:withCounter}

For example, if the original sample is S1, aliquots of that sample will be named S1-1, S1-2, etc.

If instead you wanted to use a dot between the sample name and aliquot number (S1.1, S1.2, etc.) you'd use the pattern:

${${AliquotedFrom}.:withCounter}

Learn about more options for aliquot naming patterns in the core LabKey Server documentation. Aliquot naming patterns will be validated during sample type creation.

Lineage Settings

• To declare a field that will identify a parent sample, click Add a Parent. Select the Sample Type of the parent and enter the File Import Column Name.
• If there are Sources defined in the system, you will have a similar option to Add a Source here.

Storage Settings

• Label Color: You can assign a color to this type of sample to help make quick visual identification easier in various application views.

• Amount Type
• Any: Amounts can be entered in any Mass, Volume, or Other unit listed below. Amounts entered won't be converted for storage or display.
• Mass: Samples may be registered with these units: ng, ug, g, mg, or kg. Amounts entered will be converted for storage and display. For storage in the database, user-entered amounts are converted to the base mass unit mg. For display, the amounts will be converted to the display unit configured by the administrator.
• Volume: Samples may be registered in these units: uL, mL, or L. Amounts entered will be converted for storage and display. For storage in the database, user-entered amounts are converted to the base volume unit mL. For display, the amounts will be converted to the display unit configured by the administrator.
• Other: Samples may be registered in these units: unit, pieces, packs, blocks, slides, cells, boxes, kits, tests, bottles. Amounts entered won't be converted for storage or display.
• Amount Display Units: Amounts will be converted to this unit for display.

Label Color

To assign a Label Color when you are creating or editing your sample type, click the selection area to open a color picker:

• Click a block of color to select it.
• Type a hex code next to the # sign or individual RGB values into the panel for more color control.

Define Sample Type Fields

Click the Fields section to open it.

Default System Fields

Every Sample Type is created with several default fields (columns) built in. For example, like any data structure, "Created/CreatedBy/Modified/ModifiedBy" record the userID and time of creation/modification respectively. In addition, you will see the Sample Type Default System Fields at the top of the Fields panel.

• SampleID: The name of the sample.
• Status (SampleState): Tracks the status of the sample.
• Description: This is a description field for an individual sample, not the description of the Sample Type as a whole that is shown in the properties section.
• Expiration Date (MaterialExpDate): Tracks the date this sample expires on.
• Amount (StoredAmount): The amount of this sample.
• Units: The units associated with the Amount value for this sample. This may be different from the "Amount Display Units" set for the Sample Type.
• Aliquots Created Count (AliquotCount)
• Freeze/Thaw Count (FreezeThawCount)
• Storage Location, Row, and Column

Find a full list of reserved and internal field names in this topic: Data Import Guidelines

Collapse the display of default system fields by clicking the for the section. You can expand it any time by clicking the

Add Custom Sample Type Fields

Add any additional fields that you want in your Sample Type definition as follows:

There are options for adding Custom Fields:

• Import or Infer Fields from File
• Manually Define Fields

Import or Infer Custom Fields from File

After importing or inferring fields from a file, you can adjust them or add additional fields using the manual field editor described below.

Manually Define Fields

Instead of using a file, click Manually Define Fields and continue.

• For each additional field in your sample data, click Add Field:
• Enter the Name. Names should not contain spaces or special characters; instead you can use such characters in the label for the field. Learn more in this topic.
• Select the Data Type. Learn more about types and their properties in this topic.
• Check the box if the field is required.
• Click the (expansion) icon to define more properties of your new field as needed.
• You can reorder the fields by dragging and dropping with the six-block handle.

• Add all the fields you need. If you add an extra and need to delete it, click the on the right.

Barcodes

If a field of type Unique ID is included in your Sample Type, the system will generate barcode values for you.

When you are defining a new sample type, you will see in the initial setting of the Barcodes property that no Unique ID field exists. You will be prompted to include one after inferring or manually creating other fields.

Clicking Yes, Add Unique ID Field will add a new field named "Barcode". Every new sample of this type will have a new barcode generated for it.

You'll be able to search for samples by these generated barcodes, as well as by any fields you specifically designate as containing barcode values.

Learn more about creating and using barcodes in this topic:

• Barcode Fields

Configure Sample/Aliquot Field Inheritance

For each field included in the Sample Type, whether inferred or manually created, you can configure whether the field is settable (and editable) for samples, aliquots, or both.

• Click the to expand each field's details.
• Under Sample/Aliquot Options, select one:
• Editable for samples only (default): Aliquots will inherit the value of the field from the sample.
• Editable for aliquots only: Samples will not display this field, but it will be included for aliquots.
• Separately editable for samples and aliquots: Both samples and aliquots can set a different value for this property.

Finish Creating Sample Type

• Click Finish Creating Sample Type when finished.

Learn more about defining fields and their properties in this topic:

• Field Editor

Edit Sample Type Design

If necessary, you can return to edit properties or fields/columns later via Manage > Edit Sample Type Design.

Use caution if you change the naming pattern(s) to ensure that all SampleIDs will remain unique. You can also edit the Name of the Sample Type itself. Note that changes to the Sample Type definition and naming pattern do not 'propagate' to existing samples, which will all retain their original names.

Only limited changes are allowed for the display units setting once data is included. The system can, for example, convert from L to mL, but cannot change from 'unit' to any of the 'scaled' unit types. To change from 'unit' to another type, you must export your data, create a new sample type with the intended units, and reimport.

Whether fields can be set for samples, aliquots, or both can be edited later; note that if you change an existing field from "Editable for samples only" to this "Separately editable for samples and aliquots" option, any stored values for aliquots will be dropped.

After completing edits, users can provide a Reason for Update if desired or required before clicking Finish Updating... in the lower right.

Resource: Sample Naming Pattern Examples

A few examples of how you might choose to name your samples and how to design a naming expression. You can use values from your data, dates, and counters to ensure that every sample name is unique. Separators like '-' and '_' are commonly used but optional.

Learn more about building naming patterns in this topic:

• Sample ID Naming

Related Topics

• Barcode Fields
• Get Started with Sample Manager
• Sample ID Naming
• Attach Images and Other Files
• Add Samples
• Samples
• Field Editor

Once you have created the Sample Type, you can add the samples themselves in several ways. Import an existing inventory spreadsheet, add the samples individually, or enter information in bulk (and then refine it). The Sample Type acts like a table and each individual sample of that type will be a row in the table.

• Create New Samples
• Create Samples from Grid
• Import Samples from File
• Assign Amount and Units
• Work with New Samples
• Create Derivatives, Pooled Samples, and Aliquots

Create New Samples

To add new samples, you either navigate to the type of sample you are adding and use the Add menu above the grid, or go to the home page or the Sample Types dashboard and click Add Samples. In both places you choose either:

• Add Manually
• Import from File

Create Samples From Grid

Using the Add Manually option gives you several options for entering sample information into the application directly, as opposed to uploading a file of data. You can manually enter values for the fields in a grid format, or use bulk insert and bulk update to streamline entry of similar values.

Learn more in this topic: Create Samples from Grid

Import Samples From File

The other method for entering samples, particularly useful for a large group or when sample information is available in a spreadsheet already, is to import directly from a file.

Learn more in this topic: Import Samples from File

Assign Amount and Units

During Sample import, you can provide Amount and Units values for each sample.

The Amount and Units fields are enforced as a pair — both must be provided together or both left blank. This rule applies in all contexts, including file import, grid editing, bulk updates, and manual entry. In the field designer, when you select or deselect one of these fields, the other field will be selected or deselected accordingly. In pop-up editing boxes, these fields appear on the same line, emphasizing that they are paired fields.

Negative values cannot be entered in the Amount field. Users cannot manually specify a negative amount value when inserting or updating. Also, amounts cannot be decremented to a negative value.

When the Amount Type is configured as Mass or Volume, user-entered amounts are converted to the "base unit" for storage in the database: milligrams (mg) for Mass, milliliters (mL) for Volume. User-entered amounts are also converted for display. For example, if the display unit is mL, and the user enters amount 1 and unit L, then 1000mL will be displayed. Learn more about display values for amounts and units here.

Original user-entered amounts are retained and can be viewed in the sample Timeline and Audit Log.

Whether a Sample is or is not in freezer storage within the application, you'll be able to see the amount displayed in an Inventory/Storage Details panel of the sample details.

Sample amount values can be used to generate "low volume" reports in the Sample Finder.

Also see: Create a Sample Type

Work with New Samples

After creating samples, the banner message indicates how many were created. In that message, click select them in the grid to select this recently created batch for actions like adding them to a picklist or workflow job. You can also click Add them to storage to immediately add the new samples to freezer storage locations.

If your creation did not already set the status of these samples, you could select them all in the grid, then use Edit > Edit in Bulk to set it. Learn more about sample status here:

• Manage Sample Status

• Sample Grid Menus

Create Derivatives, Pooled Samples and Aliquots

Once you have created the Samples you want to use as parents, you can also create new samples as derivatives, pooled samples, and aliquots. Learn more in these topics:

• Sample Lineage / Parentage
• LIMS: Samples

Related Topics

• Create a Sample Type
• Create Samples from Grid
• Import Samples from File
• Manage Sample Status
• Attach Images and Other Files
• Sample Lineage / Parentage
• Associate Samples with Sources: Create new samples from Sources of those samples.
• LIMS: Samples
• Data Import Guidelines
• Store Samples
• Migrate Storage Data into LabKey

• Add Manually
• Select Type and Number
• Add Samples of Multiple Types
• Add Parent
• Add Source
• Add Sample Data in Grid
• Bulk Add
• Bulk Add with Parent(s)
• Edit in Bulk

Add Manually

Open the grid method for creating new Samples from the desired Sample Type by selecting Add > Add Manually. You can also choose Add Samples > Add Manually from the main dashboard.

Select Sample Type and Number

In the popup, select the Sample Type and provide the Number of Samples.

If you want to add samples of multiple types, click Add Another Sample Type, and enter the other type and number of samples.

Click Go to Sample Creation Grid.

The entry grid will contain the number of rows you requested, with a column for each built-in and custom property in the Sample Type, as well as a prepopulated parent or source column for any Lineage Settings (parent or source aliases) the type includes.

Add Samples of Multiple Types

You can simultaneously add samples of multiple types by using Add Another Sample Type, providing a second type and number of samples.

You will enter data for the two types on grids on different tabs.

Add Parent

If the Sample Type has one or more Parent samples, you will see a prepopulated parent field. In cases where the parent field is marked as Required you will need to provide a value, otherwise it is optional. To add more, click Add Parent and select the Sample Type of the parent(s). If you will have parents of different types, add one for each type of parent.

Learn more about including parentage information in this topic: Sample Lineage / Parentage

If you add but then want to remove a parent linkage, you can delete it by clicking the column header's menu and selecting Remove Column.

Add Source

If the Sample Type has one or more Sources, you will see a prepopulated source field. In cases where the source field is marked as Required you will need to provide a value, otherwise it is optional. Click Add Source and select the type of Source you want to associate with samples of this type.

Learn more about including source information in this topic: Sample Lineage / Parentage

If you add but then want to remove a source linkage, you can delete it by clicking the column header's menu and selecting Remove Column.

Add Sample Data in Grid

The data entry grid will have the number of samples you requested in the modal. To add more rows, you can enter the number and click Add Samples. Remove excess rows by selecting them and clicking Delete.

Each row in the grid will have a Status column plus a column for each field included in your Sample Type (not including any "File" fields).

• Sample ID:
• If you provided a Naming Pattern with the Sample Type, the Sample ID can be generated, and this will be noted in the grid. Hover over the to see an example of a generated name.
• You could override this value by manually typing in the box, but remember that all sample IDs must be unique.
• Parent and Source Fields:
• If the Sample Type includes any parent or source lineage settings, there will be columns for the Sample or Source Types of these fields included by default.
• Enter values for remaining fields using the guidance in this topic
• Choose a value from fields with a .
• Enter data directly into the grid. Copy and paste of cells is supported, as is dragging to propagate text or number series values.
• When ready, click Finish Creating ## Samples.

Bulk Add

Instead of directly populating a grid, you can click Bulk Add to create many samples at once. This is particularly convenient when samples share the same settings for some or all columns.

• Specify the number of New Samples.
• Note that if you have included a parent field, you will have additional options here.
• Enter values for any or all of the properties listed that you want to be applied to all the new samples.
• Click Add Samples To Grid.

You will see a banner message offering a link to select these newly created samples for further work if desired.

Bulk Insert with Parent(s)

If you added one or more parent fields before clicking Bulk Add, you will have an additional selection to make in the bulk creation popup. Choose whether you want to use the parent sample(s) to create:

• Derivatives, specifying the number of derivatives per parent.
• Pooled Samples, specifying the number of new samples to create for the pooled parent(s).

• Provide values for properties that will be shared by the newly created samples. Including 'parents' as applicable.
• Hover over the for the Status field to see a legend of available statuses.
• Click Add Samples to Grid and continue to complete the grid with any properties not shared by all the new samples.
• Click Finish Creating ## Samples when done.

Edit in Bulk

While creating new samples in the grid, you can use the Edit in Bulk option to assign a common value to a selected set of rows. As for bulk update of assay data rows, you control which fields are Enabled for update to a new common value you provide. The disabled fields will retain their original values.

Related Topics

• Add Samples
• Import Samples from File
• Data Grid Basics
• Work with New Samples

When creating new Samples, the Add > Import from File option (or Add Samples > Import from File from the dashboard) lets you upload a spreadsheet of sample data, streamlining the process over entering data into a grid. You can also update data for existing samples via Edit > Update from File from a grid of samples.

• Obtain File Import Template
• Import Samples from File
• Import Across Sample Types
• Import Samples and Create New Storage
• Update Existing Samples
• Merge by Allowing New Samples

Obtain File Import Template

An import template shows all the expected columns for your data structure, making it easier to ensure your imported data will conform to system expectations. Templates are available for Sample Types, Source Types, and Assays from the main dashboard for the type of structure.

From the main menu, select the target Sample Type. Click the Template button to download the template for this type of sample.

• Use this template as a guide for ensuring your data matches the expected columns.
• Note that any "File" fields will be omitted from the downloaded template.
• When populating the template, you may not need to include all columns. For example, if you have defined lineage import columns (aliases) for sources or parents, all possible columns will be included in the template, but you only need to include the ones you want to use.

Import Samples From File

You can start from the home page of the application or the Sample Types dashboard and select Add Samples > Import from File or from the overview page for a specific Sample Type, select Add > Import from File.

• Set the Sample Type for the Samples you will import.
• If you started from a specific sample type grid, the type will be prepopulated and you will not see the dropdown.
• If you want to import samples of multiple types, select Import multiple sample types. Learn more below.
• If you are including storage information for the samples you're importing, select the appropriate radio button:
• Add samples to existing storage only: all storage locations must exist already.
• Add samples to existing or new storage (created during import): a combination of existing and new storage units are allowed.
• Use the Template button if you didn't already download a template file for your data.
• Drag and Drop the file into the target area to upload it.
• You will see the sample information obtained from the file in the panel.
• Only fields included in the definition of the Sample Type will be imported. In this example, the Sample ID will be generated for you, so is not included in the imported file or shown here. If any fields are unrecognized, they will be ignored and a banner will be shown.
• Note that you cannot edit the values here. If you see an error, you can use the X to delete the loaded file, make changes offline, and reselect the revised file.

• Click Import to create the samples from the data in the file.

Additional examples and details are available here:

• Import Samples with storage locations
• Import Samples with lineage

Import Samples Across Multiple Sample Types

To import samples across multiple Sample Types, select the Sample Type option Multiple sample types.

Ensure the file contains a "Sample Type" column that contains the name of the Sample Type (e.g. Blood) for every row, in order to map the samples being added to the correct sample type.

It is good practice to check after a file import that the number of samples imported matches your expected total for each type. Confirm by comparing the number of samples in the notification of the completion of the background task with the number shown in the new sample grid.

Import Samples and Create New Storage

The default Storage Option when you import samples from file is to Add samples to existing storage only, provided the location details are included in the file. Learn more about the details that you need to provide here.

To create any new storage locations while importing samples from file, i.e. to assign new samples to either new or existing storage locations within the same file, a user with the "Storage Designer" role can select the option Add samples to existing or new storage (created during import).

Ensure the file contains a "Storage Unit" column that corresponds to the name of the Storage Unit (eg. "9x9 Box" to use one of the default box types) to create the appropriate type of storage unit for at least the first row placing a sample into that unit. This is in addition to the "Storage Location, Storage Row, and Storage Col" values required (in every row) for adding samples to storage.

The creation of new storage during import is determined by parsing the value provided in the "StorageLocation" field for each row.

• If any locations in that path do not exist, they will be created.
• The "StorageLocation" field value should be slash-separated and must end with a terminal storage unit.
• If any levels in this field value do not exist, they will be created.
• You can also create an entirely new storage system (freezer) with this process, using a value like "MyNewFreezer/Shelf1/Box1" where "MyNewFreezer" does not already exist.
• You can also precede new storage with a / to make it clear that a new top level system is to be created, i.e. "/MyNewFreezer/Shelf1/Box1".
• If the terminal storage unit (final element in the field value) does not already exist, it will be created as the type of unit specified in the "Storage Unit" field.
• This means that only the first row for a new storage unit needs to provide the correct type of unit to create.
• If all units in the full "StorageLocation" field already exist, the "Storage Unit" value is not read for that row.

Update Existing Samples

To update existing samples, or merge a combined spreadsheet of new and existing samples, select Edit > Update from File. The update page is very similar to the Import from File page, with additional Update Options. The default is Only update existing samples.

• Any data you provide for the rows representing samples that already exist will replace the previous values.
• When updating, you only need to provide the columns you wish to update. Existing data for other columns will be left as is. If you wish to update the SampleId values, then you must include the RowId column in your file.
• Important: All columns you upload will be updated in the system. If you include an empty column, all data for that data will be deleted.
• Note that you cannot update an existing sample to make it an aliquot of another sample.
• Before clicking Import, provide a Reason for Update if desired or required.

A common scenario for using "update" for samples is to add storage information for a group of samples that are already registered in the system. Learn more in this topic: Migrate Storage Data into LabKey

Merge by Allowing New Samples

The Create new samples too update option controls whether you will be able to merge the incoming file or simply update existing rows.

• When this option is not selected, the default, the update will fail if rows are included that do not match existing samples already in the system.
• When selected, any rows for samples that do not yet exist will add them as new samples.
• As for updates without merge, before clicking Import, provide a Reason for Update if desired or required.

Related Topics

• Import Samples with Storage Locations
• Import Samples with Lineage
• Add Samples
• Work with New Samples
• Create Samples from Grid
• Data Import Guidelines

• Unique Sample Names are Provided: Unique sample names are provided to the system
• Column Name is "SampleID" or "Name"
• Column Name is Something Else
• Generate Names with Naming Patterns: Generate unique names within the system
• Default Naming Pattern
• See and Set genId
• Date Based Naming
• Incorporate Column Values
• Incorporate Lineage Lookups
• Include Ancestor Names/Properties Using "~"
• Include Grandparent Names/Properties Using ".."
• Naming Pattern Elements/Tokens
• Formatting Values
• :defaultValue Modifier
• :minValue Modifier
• Names Containing Commas
• Incrementing Sample Counters
• sampleCount Token
• rootSampleCount Token
• Date Based Incrementing Counters
• :withCounter Modifier
• Naming Pattern Validation
• Caution: Escaping Special Characters
• Caution: Using Numbers-Only as Sample IDs
• Examples

Unique Sample Names are Provided

If your data already includes the unique sample names to use, identify the column name that contains them.

Naming Column is "SampleID" or "Name"

If the name of this column is "SampleID" or "Name", these default column names are automatically recognized as containing sample names. To confirm that they are used, be sure to Delete the default naming pattern that is provided in the user interface (and ignore the grayed out placeholder text that remains).

Naming Column is Something Else

If the column containing unique sample names is named something else, you provide that column name using a simple naming pattern expression that specifies the name of the column to use, rather than an expression to generate one.

For example, if the sample names are in a column named "Identifier", you would enter the naming pattern:

${Identifier}

Note that while this is entered as a naming pattern, it does not generate any portion to make the sample names unique, so you are responsible for ensuring uniqueness.

Generate Names with Naming Patterns

If your data does not already contain unique names, the system can generate them upon import using a naming pattern that contains tokens, including counters to ensure names are unique. The system can build a unique name from syntax elements, such as:

• String constants
• Incrementing numbers
• Dates and partial dates
• Values from columns in the imported data, such as tissue types, lab names, subject ids, etc.
• Separators such as '_' underscores and '-' hyphens
• Note that if you use a hyphen '-', you will want to use double quotes when you later search for your samples. An unquoted search for Sample-11 would interpret the hyphen as a minus sign and seek pages with "Sample" without "11".

Default Naming Pattern

The default naming pattern in Sample Manager generates names from two elements: the prefix "S-" plus an incrementing integer.

S-${genId}

The first few samples would be:

S-1
S-2
S-3
and so on...

See and Set genId

The token genId is an incrementing value which starts from 1 by default, and is maintained internally for each sample type (or source type) in a container. Note that while this value will increment, it is not guaranteed to be continuous. For example, any creations by file import will 'bump' the value of genId by 100, as the system is "holding" a batch of values to use.

When you include ${genId} in a naming pattern, you will see a blue banner indicating the current value of genId.

If desired, click Edit genId to set it to a higher value than it currently is. This action will reset the counter and cannot be undone.

You can also reset the counter by including the :minValue modifier in your naming pattern.

Date Based Naming

Another possible naming pattern for samples is to incorporate the date of creation. For example:

S-${now:date}-${dailySampleCount}

This three-part pattern will generate an incrementing series of samples for each day.

1. The S- prefix is simply a string constant with a separator dash. Using separators like "-" and "_" is optional but will help users parse sample names.
2. The now:date token will be replaced by the date of sample creation.
3. The dailySampleCount token will be replaced by an incrementing counter that resets daily.

Incorporate Column Values

If you want to use a column from your data as part of the name, but it does not contain unique values for all samples, you can incorporate it in the pattern by using the column name in token brackets and also including an additional uniqueness element like a counter. For example, if you want to name many samples for each participant, and the participant identifier is in a "ParticipantID" column, you could use the pattern:

${ParticipantID}-${genId}

Multiple column names and other substitutions can be included in a naming pattern, for example:

${ParticipantID}-${CollectionDate}-${LabName}-${now:date}-${genId}

Incorporate Lineage Lookups

More general syntax to include properties of sample sources or parents in sample names is also available by using lookups into the lineage of the sample.

• Specific data type inputs: MaterialInputs/SampleType1/propertyA, DataInputs/DataClass2/propertyA, etc.
• Import alias references: parentSampleA/propertyA, parentSourceA/propertyA, etc.
• In some scenarios, you may be able to use a shortened syntax referring to an unambiguous parent property: Inputs/propertyA, MaterialInputs/propertyA, DataInputs/propertyA
• This option is not recommended and can only be used when 'propertyA' only exists for a single type of parent. Using a property common to many parents, such as 'Name' will produce unexpected results.

Blood-${DataInputs/Mouse/Strain}-${genId}

You can use the qualifier :first to select the first of a given set of inputs when there might be several.

If there might be multiple parent samples of a given type (like "Blood"), you could choose the first one in a naming pattern like this:

Blood-${parentBlood/SampleID:first}-${genId}

Include Ancestor Names/Properties Using "~"

To reference an ancestor name (or other property), regardless of the depth of the ancestry, you can use syntax that includes a tilde and will 'walk the lineage tree' to the named Source or Sample Type regardless of depth of a lineage tree (up to a maximum depth of 20). Note that this type of syntax may be more resource intensive, so if you know that the ancestor will always be the direct parent or at another specific/consistent level, you should use another lineage lookup for efficiency.

For example, consider a "Participant" Source Type and also a Sample Type like "Blood" that could be either a direct 'child' of the source, or a grandchild (of an intermediate sample like "Tissue"), or any further descendent. You can include properties of the Participant source of a "Blood" sample with a naming pattern like this:

${~DataInputs/Participant/Name}
${~DataInputs/Participant/OtherProperty}

Similarly, for ancestor Sample Types at any depth, use syntax like this:

${~MaterialInputs/SampleTypeName/Name}
${~MaterialInputs/SampleTypeName/OtherProperty}

This syntax can be combined with other naming pattern elements, including counters as shown in this example. This will maintain a counter per Participant, regardless of the depth of tree where the sample is created:

${${~DataInputs/Participant/Name}-:withCounter}

Note that if the ancestor type appears multiple times in the lineage for a given sample, the "furthest" ancestor will be used.

Include Grandparent Names/Properties Using ".."

If you know that the ancestor of interest is a fixed number of generations above the direct parent, i.e. the grandparent or great-grandparent generation, you can use ".." syntax to walk the tree to that specific level. Here are a few examples of syntax for retrieving names from the ancestry of a sample. For simplicity, each of these examples is shown followed by a basic ${genId} counter, but you can incorporate this syntax with other elements. Note that the shortened syntax available for first generation "parent" lineage lookup is not supported here. You must specify both the sample type and the "/name" field to use.

To use the name from a specific grandparent sample type, use two levels:

${MaterialInputs/CurrentParent/..[MaterialInputs/GrandParentSampleType]/name}-${genId}

To use another propertyColumn from a specific grandparent sample type:

${MaterialInputs/CurrentParent/..[MaterialInputs/GrandParentSampleType]/propertyColumn}-${genId}

You can use a parent alias for the immediate parent level, but not for any grandparent sample types or fields:

${parentAlias/..[MaterialInputs/GrandParentSampleType]/name}-${genId}

Compound this syntax to further "walk" the lineage tree to use a great grand parent sample type and field:

${MaterialInputs/CurrentParent/..[MaterialInputs/GrandParentSampleType]/..[MaterialInputs/GreatGrandSampleType]/greatGrandFieldName}-${genId}

To define a naming pattern that uses the name of the grandparent of any type, you can omit the grandparent sample type name entirely. For example, if you had Plasma samples that might have any number of grandparent types, you could use the grandparent name using syntax like any of the following:

${plasmaParent/..[MaterialInputs]/name}-${genId}
${MaterialInputs/Plasma/..[MaterialInputs]/name}-${genId}
${MaterialInputs/..[MaterialInputs]/name}-${genId}

Naming Pattern Elements/Tokens

The following elements, or "tokens" are available for building naming patterns.

Formatting Values

You can use formatting syntax to control how the tokens are added. For example, "${genId}" generates an incrementing counter 1, 2, 3. If you use a format like the following, the incrementing counter will have three digits: 001, 002, 003.

${genId:number('000')}

Learn more about formatting numbers and date/time values in this topic: Date, Time, and Number Formats

Additional string modifiers are available. Find a list in this topic: String Expression Format Functions

:defaultValue Modifier

When you are using a data column in your string expression, you can specify a default to use if no value is provided. Use the defaultValue modifier with the following syntax. The 'value' argument provided must be a String in ' single quotes.

${ColumnName:defaultValue('value')}

:minValue Modifier

Tokens including genId, sampleCount, and rootSampleCount can be reset to a new higher 'base' value by including the :minValue modifier. For example, to reset sampleCount to start counting at a base of 100, use a naming pattern with the following syntax:

S-${sampleCount:minValue(100)}

If you wanted to also format the count value, you could combine the minValue modifier with a number formatter like this, to make the count start from 100 and be four digits:

S-${sampleCount:minValue(100):number('0000')}

Note that once you've used this modifer to set a higher 'base' value for genId, sampleCount, or rootSampleCount, that value will be 'sticky' in that the internally stored counter will be set at that new base. If you later remove the minValue modifier from the naming pattern, the count will not 'revert' to any lower value. This behavior does not apply to using the :minValue modifier on other naming pattern tokens, where the other token will not retain or apply the previous higher value if it is removed from the naming pattern.

Names Containing Commas

It is possible to include commas in Sample and Source names, though not a best practice to do so. Commas are used as sample name separators for lists of parent fields, import aliases, etc., so names containing commas have the potential to create ambiguities.

If you do use commas in your names, whether user-provided or LabKey-generated via a naming pattern, consider the following:

• To add or update lineage via a file import, you will need to surround the name in quotes (for example, "WC-1,3").
• To add two parents, one with a comma, you would only quote the comma-containing name, thus the string would be: "WC-1,3",WC-4.
• If you have commas in names, you cannot use a CSV or TSV file to update values. CSV files interpret the commas as separators and TSV files strip the quotes 'protecting' commas in names as well. Use an Excel file (.xlsx or .xls) when updating data for sample names that may include commas.

Incrementing Sample Counters

The genId token is a basic incrementing value, but you can incorporate other ways of including counts in naming patterns. Some auto-incrementing counters calculate the next value based on all samples and sources across the entire application, while others calculate based on only the current Sample Type in the current container. See the Scope column for the specific incrementing behavior. When the scope is application-based, within a given container values will be sequential but not necessarily contiguous.

sampleCount Token

When you include ${sampleCount} as a token in your naming pattern, it will be incremented for every sample created in the application (the home and any folders it contains), including aliquots. This counter value is stored internally and continuously increments, regardless of whether it is used in naming patterns for the created samples.

For example, consider a system of naming patterns where the Sample Type (Blood, DNA, etc) is followed by the sampleCount token for all samples, and the default aliquot naming pattern is used. For "Blood" this would be:

Blood-${sampleCount}
${${AliquotedFrom}-:withCounter}

A series of new samples and aliquots using such a scheme might be named as follows:

If desired, you could also use the sampleCount in the name of aliquots directly rather than incorporating the "AliquotedFrom" sample name in the aliquot name. For Blood, for example, the two naming patterns could be the same:

Blood-${sampleCount}  <- for samples
Blood-${sampleCount}  <- for aliquots

In this case, the same series of new samples and aliquots using this naming pattern convention would be named as follows:

The count(s) stored in the sampleCount and rootSampleCount tokens are not guaranteed to be continuous or represent the total count of samples, much less the count for a given Sample Type, for a number of reasons including:

• Addition of samples (and/or aliquots) of any type anywhere in the application will increment the token(s).
• Any failed sample import would increment the token(s).
• Import using merge would increment the token(s) by more than by the new number of samples. Since we cannot tell if an incoming row is a new or existing sample for merge, the counter is incremented for all rows.

rootSampleCount Token

When you include ${rootSampleCount} as a token in your naming pattern, it will be incremented for every non-aliquot (i.e. root) sample created in the application (the home and any folders it contains). Creation of aliquots will not increment this counter, but creation of any Sample of any Sample Type will increment it.

For example, if you use the convention of using the Sample Type (Blood, DNA, etc) followed by the rootSampleCount token for all samples, and the default aliquot naming pattern, for "Blood" this would be:

Blood-${rootSampleCount}
${${AliquotedFrom}-:withCounter}

A series of new samples and aliquots using this convention for all types might be named as follows:

The count stored in the rootSampleCount token is not guaranteed to be continuous or represent the total count of root samples for the same reasons as enumerated above for the sampleCount token.

Administrators can see the current value of the rootSampleCount token on the Administration > Settings tab. A higher value can also be assigned to the token if desired. You could also use the :minValue modifier in a naming pattern to reset the count to a higher value.

Date Based Sample Counters

Date-based sample counters are available that will be incremented based on the date when the sample is inserted. These counters are incrementing, but since they apply to all sample types, within a given Sample Type, values will be sequential but not necessarily contiguous.

• dailySampleCount
• weeklySampleCount
• monthlySampleCount
• yearlySampleCount

• As standalone elements of a name expression, i.e. ${dailySampleCount}, in which case they will provide a counter across all sample types and source types based on the date of creation.
• As modifiers of another date column using a colon, i.e. ${SampleDate:dailySampleCount}, in which case the counter applies to the value in the named column ("SampleDate") and not the date of creation.

:withCounter Modifier

Another alternative for adding a counter to a field is to use :withCounter, a nested substitution syntax allowing you to add a counter specific to another column value or combination of values. Using :withCounter will always guarantee unique values, meaning that if a name with the counter would match an existing sample (perhaps named in another way), that counter will be skipped until a unique name can be generated.

The nested substitution syntax for using :withCounter is to attach it to an expression (such as a column name) that will be evaluated/substituted first, then surround the outer modified expression in ${ } brackets so that it too will be evaluated at creation time. The counter is applied to the case-insensitive version of the inner expression, such that if there is a case-only mismatch in a column (Blood/blood), the counter will not 'restart' for the differently cased variation.

This modifier is particularly useful when naming aliquots which incorporate the name of the parent sample, and the desire is to provide a counter for only the aliquots of that particular sample. The default naming pattern for creating aliquots combines the value in the AliquotedFrom column (the originating Sample ID), a dash, and a counter specific to that Sample ID:

${${AliquotedFrom}-:withCounter}

You could also use this modifier with another column name as well as strings in the inner expression. For example, if a set of Blood samples includes a Lot letter in their name, and you want to add a counter by lot to name these samples, names like Blood-A-1, Blood-A-2, Blood-B-1, Blood-B-2, etc. would be generated with this expression. The string "Blood" is followed by the value in the Lot column. This combined expression is evaluated, and then a counter is added:

${Blood-${Lot}-:withCounter}

Use caution to apply the nested ${ } syntax correctly. The expression within the brackets that include the :withCounter modifier is all that it will be applied to. If you had a naming pattern like the following, it looks similar to the above, but would only 'count' the number of times the string "Blood" was in the naming pattern, ignoring the Lot letter, i.e. "A-Blood-1, A-Blood-2, B-Blood-3, B-Blood-4:

${Lot}-${Blood-:withCounter}

This modifier can be applied to a combination of column names. For example, if you wanted a counter of the samples taken from a specific Lot on a specific Date (using only the date portion of a "Date" value, you could obtain names like 20230522-A-1, 20230522-A-2, 20230523-A-1, etc. with a pattern like:

${${Date:date}-${Lot}-:withCounter}

You can also use a starting value and number format with this modifier. For example, to have a three digit counter starting at 42, (i.e. S-1-042, S-1-043, etc.) use:

${${AliquotedFrom}-:withCounter(42,'000')}

Learn more about using :withCounter in naming patterns for aliquots in the LabKey documentation here:

• Aliquot Naming Patterns

Naming Pattern Validation

During creation of a Sample Type, both sample and aliquot naming patterns will be validated. While developing your naming pattern, the admin can hover over the for a tooltip containing either an example name or an indication of a problem.

When you click Finish Creating/Updating Sample Type, you will see a banner about any syntax errors and have the opportunity to correct them.

Errors reported include:

• Invalid substitution tokens (i.e. columns that do not exist or misspellings in syntax like ":withCounter").
• Keywords like genId, dailySampleCount, now, etc. included without being enclosed in braces.
• Mismatched or missing quotes, curly braces, and/or parentheses in patterns and formatting.
• Use of curly quotes, when straight quotes are required. This can happen when patterns are pasted from some other applications.

Caution: Escaping Special Characters

When field names or data type names contain special characters, including but not limited to {,}, and \, these characters must be escaped with a backslash \.

Caution: Using Numbers-Only as Sample IDs

Note that while you could create or use sample names that are just strings of digits, you may run into issues if those "number-names" overlap with row numbers of other samples. In such a situation, when there is ambiguity between sample name and row ID, the system will presume that the user intends to use the value as the name.

Examples

Example String Modifiers

The following naming patterns show usage of string modifiers.

Related Topics

• Create a Sample Type
• Date, Time, and Number Formats
• String Expression Format Functions

Aliquots can be generated from samples using LabKey Biologics and Sample Manager. As for all samples, each aliquot must have a unique sample ID (name). A custom Aliquot Naming Pattern can be included in the definition of a Sample Type. If none is provided, the default is the name of the sample it was aliquoted from, followed by a dash and counter.

• Aliquot Naming Patterns
• Naming Pattern Validation
• withCounter Syntax
• Dash Count / Default Pattern
• Dot Count
• Start Counter at Value
• Set Number of Digits
• Include Lineage Elements
• Examples

Aliquot Naming Patterns

To set a naming pattern, open your Sample Type design within LabKey Biologics or Sample Manager. This option cannot be seen or set from the LabKey Server interface.

As with Sample Naming Patterns, your Aliquot Naming Pattern can incorporate strings, values from other columns, different separators, etc. provided that your aliquots always will have unique names. It is best practice to include the AliquotedFrom column, i.e. the name of the parent sample, but this is not strictly required by the system.

Aliquot Pattern Validation

During pattern creation, aliquot naming patterns will be validated, giving the admin an opportunity to catch any syntax errors. Users will be able to see the pattern and an example name during aliquot creation and when viewing sample type details. Learn more in this topic:

• Sample ID Naming

withCounter Syntax

Using nested substitution syntax, you can include a counter specific to the value in the AliquotedFrom column (the originating Sample ID). These counters will guarantee unique values, i.e. will skip a count if a sample already exists using that name, giving you a reliable way to create unique and clear aliquot names.

Prefix the :withCounter portion with the expression that should be evaluated first, then surround the entire expression with ${ } brackets. Like sample naming patterns, the base pattern may incorporate strings, and other tokens to generate the desired final aliquot name.

The following are some examples of typical aliquot naming patterns using withCounter. Learn more in this topic: Sample ID Naming

Dash Count / Default Pattern

By default, the name of the aliquot will use the name of its parent sample followed by a dash and a counter for that parent’s aliquots.

${${AliquotedFrom}-:withCounter}

For example, if the original sample is S1, aliquots of that sample will be named S1-1, S1-2, etc. For sample S2 in the same container, aliquots will be named S2-1, S2-2, etc.

Dot Count

To generate aliquot names with "dot count", such as S1.0, S1.1, an admin can set the Sample Type's aliquot naming pattern to:

${${AliquotedFrom}.:withCounter}

Start Counter at Value

To have the aliquot counter start at a specific number other than the default 0, such as S1.1001, S1.1002., set the aliquot naming pattern to:

${${AliquotedFrom}.:withCounter(1001)}

Set Number of Digits

To use a fixed number of digits, use number pattern formatting. For example, to generate S1-001, S1-002, use:

${${AliquotedFrom}-:withCounter(1, '000')}

Include Lineage Elements

As for Sample IDs, Aliquot Naming Patterns can include elements like names and properties from the AliquotedFrom sample's lineage. Learn more about this syntax here:

• Incorporate lineage elements from parent samples or sources.
• Include ancestor elements from any lineage depth using "~".

Examples

Related Topics

• Sample ID Naming
• Sample Manager Documentation for Aliquots

• User-defined IDs/Names: Force the use of naming patterns for consistency
• Naming Pattern Elements/Tokens: See and update Sample count tokens

User-defined IDs/Names

To maintain consistent naming, you may want to force usage of naming patterns for samples and sources rather than allow users to enter their own names, risking inconsistencies. This requires that all types have a naming pattern that can be used to generate unique names for them.

When users are not permitted to create their own IDs/Names, the ID/Name field will be hidden during creation and update of rows, and when accessing the design of a new or existing Sample Type or Source Type.

Additionally:

• Attempting to import new data will fail if an ID/Name is encountered.
• Attempting to update existing rows during file import will also fail if an unrecognized or new ID/Name is encountered.

To disallow User-defined IDs/Names:

• Select > Application Settings.
• Scroll down to ID/Name Settings.
• Uncheck the box Allow users to create/import their own IDs/Names.
• Note that to complete this change, all entities in the system must have a valid naming pattern. You will see a warning if any need to be added.

Naming Pattern Elements/Tokens

The sampleCount and rootSampleCount tokens are used in Naming Patterns across the application. In this section, you'll see the existing value (based on how many samples and/or aliquots have already been created). To modify one of these counters, enter a value higher than the value shown and click the corresponding Apply New... button.

Related Topics

• Sample ID Naming

• Add a Parent
• Add a Source
• Define Lineage When Creating Samples
• Require Lineage Relationships (Optional)
• Create Aliquots, Derivatives, and Pooled Samples
• Create from Samples Grid
• Create from Sources Grid
• Import from File
• Include Ancestor Metadata in Sample Grids
• Explore Sample Lineage Graph
• Explore Sample Lineage Grid

Add a Parent

Within the definition of a Sample Type, you can indicate one or more columns that will generate a parentage relationship with the samples being created. The parent(s) can exist in the same or different Sample Type than the one you are creating. Adding a parent and providing a File Import Column Name (aka a "Parent Alias") in the definition of a Sample Type creates the linkage to parent samples during import. You can opt to make this relationship Required if desired. Note that the column alias/import column name is not actually added to the Sample Type, instead the system pulls data from it to determine parentage relationships.

For example, if you have a group of "Vial" samples like the following, where v1 has two 'children', v1.1 and v1.2:

...you could indicate the parent column name "MyParent" as part of the definition of this Sample Type, so that these relationships would be represented in lineage immediately upon import.

• You can add the parent relationship:
• During initial Sample Type creation.
• After creation by reopening the type for editing via Manage > Edit Sample Type Details.
• Click Add a Parent.

• Parent Type: Select the sample type of the parent. This may be in the "(Current Sample Type)" or another one that has been defined.
• File Import Column Name: Enter the parent column name for import. The column name is case sensitive.
• Check the Required box if you want every sample of this type to require a parent of this type.

• You can add additional parentage columns if applicable by clicking Add a Parent and repeating the process.
• Click Save.

You will see the Parent Import Alias(es) listed on the overview tab for the Sample Type.

Add a Source

Within the definition of a Sample Type, you can indicate one or more columns that will indicate a Source of the samples being created. Adding a source of a given type in the definition of a Sample Type creates the linkage to sources during import, rather than requiring sources be added later.

As for sample parents, you'll select the type, give a File Import Column Name (a "Source Alias"), and can optionally check the Required box if you want every sample to have a source of this type. You can include multiple source aliases as needed. When you use an import template or add samples manually in a grid, columns for all source aliases will be included.

You will see the Source Import Aliases listed on the overview tab for the Sample Type.

Learn more about sources in this section:

• Sources

Define Lineage When Creating Samples

When creating samples, you can include parent/source information based on the Lineage Settings in the sample type, i.e. for any parents or sources included. When you use a template to import from file columns for all parent/source lineage relationships will be included. As shown below, the "MyParent" column contains the parent identifier.

If you add samples manually in a grid, a parent of the selected type will included by default, though the "File Import Column Name" you gave will not be shown in the UI. Instead it will be named for the selected sample type plus the word "Parents", i.e. "Vial Parents".

The system will capture and generate lineage for the parent(s) of the samples you have created. Learn more about using the Lineage tab in sample details below.

Require Lineage Relationships (Optional)

If you want to require that all samples of a given type have a given type of parent or source entity, use the checkbox in the Sample Type definition:

When you add new samples, this column will be required. Note that if you are using a grid method, you won't see the "MyParent" column name, you'll see the type of the parent that must be provided.

Create Aliquots, Derivatives, and Pooled Samples

Once you have created the parent samples in the system and want to create new samples with specific parents (i.e. aliquot, pool, or derive new samples), you can do so from the Samples grid or by importing from a file referencing the parent sample IDs.

Create from Samples Grid

Within the application, you can create new samples from any grid of parent samples. Note that if you select more than 1000 rows, the option to create samples with those parents is disabled.

• Select the Sample Type of interest from the main menu.
• Select the parent sample(s) using the checkbox(es).
• Select the desired option from the Derive menu. On narrower browsers, this will be a section of the More menu:
• Aliquot Selected: Create aliquot copies from each selected sample.
• Derive from Selected: Create multiple output samples per selected parent sample. Select the type to derive.
• Pool Selected: Created one or more pooled outputs from the selected samples.
• Add the desired number of new samples and click Go to Sample Creation Grid.

Learn more about providing the required information to Finish Creating the selected type of child sample in this topic:

• LIMS: Samples

Create from Selected Sources

If you have already created the Sources in the system and want to create new samples from specific sources, you can do so from the Sources grid.

• Select the Source Type of interest from the main menu.
• Select the desired source(s) using the checkbox(es).
• Select Derive > Samples.
• Choose the Sample Type and enter the desired number of samples in the popup.

• Click Go To Sample Creation Grid.
• You will see the selected Sources prepopulated in the column for that type of source in the grid.
• Enter remaining sample information before clicking to Finish Creating the samples.

Import from File

After creating the parent samples, you can create new derivatives, pooled samples, and aliquots by importing from a file, referencing the parent samples you already created. Obtain the expected import format template, then populate it to indicate the relationships.

You can also update existing samples with parent and source relationships, or merge both existing and new samples using the Edit > Update from File option.

Learn more about the specific fields to populate in this topic: LIMS: Samples

Include Ancestor Metadata in Sample Grids

You can include fields from ancestor samples and sources in customized grid views. Any user can make their own named custom views, selectively sharing them with the rest of the team, and administrators can customize the default view everyone sees.

For example, if you had a "PBMC" sample type and wanted to include in the grid both the "Draw Date" field from the parent "Blood" sample type AND the "Strain" field from a "Mouse" source, you would add the following:

The selection of the Mouse Strain field would look like this, with Ancestor and Mice nodes expanded:

Save the updated grid view, and you can then filter, sort, and search based on that parent metadata. Shown below, we're showing only samples that come from "BALB/c" mice.

Up to 20 levels of ancestor can be traversed and displayed in a grid.

Lineage across multiple sample types in one tabbed grid can be viewed using the Ancestor node on the All Samples tab. Note that when viewing some grids, such as picklists, the Ancestor node will be under the Sample ID instead of at the top level in the customizer.

Explore Sample Lineage Graph

Viewing any sample detail page, you will see a tab for Lineage in the header bar. For example:

The lineage graph lets you explore a visual representation of the parentage of samples.

• Click anywhere in the graph and drag to reposition it in the panel.
• Click any node to see details in the panel to the right.
• Double-click any node to shift focus to that node, which will also adjust to show up to 5 generations from that node.
• This allows you to view the "siblings" of a sample of interest by first double-clicking the common "parent", and then single clicking each sibling node for details.
• Zoom out and in with the and buttons in the lower left.
• Step up/down/left and right within the graph using the arrow buttons.
• Refresh the image using the button. There are two options:
• Reset view and select seed
• Reset view

• On the right of the graph, a side panel lists the children as links.
• Click any sample to reset the graph focus in the left hand panel.
• Hover over a link to reveal direct links to the overview page or lineage view for that child. A tooltip will also show the Sample Type name.

Note that only five generations will display on the lineage graph. To see additional generations, walk the tree up or down to see more levels in either direction.

You can switch to the grid view of the lineage by clicking the green Go To Lineage Grid button.

Lineage Generations in Graph

When lineage is complex, different "generations" are shown horizontally aligned.

Lineage Grid

The lineage grid can be especially helpful when viewing lengthy lineages or derivation histories. By default, the children of the currently selected sample, aka the "seed", are shown.

If this sample has parents, the Show Parents button will be enabled and you can click it to see them. If the sample has children that are not shown, the Show Children button will be enabled and you can click it to see them.

Entries in the Names column are clickable and connect to the overview page for the sample.

The Distance column specifies the number of generations between each row and the selected seed sample.

Use the arrow buttons in the Change Seed column to change the focus of the grid, expanding and collapsing lineage hierarchies to focus on a different seed.

Troubleshooting

In situations where sample names are only strings of digits, you may see unexpected lineage results if those "number-names" overlap with row numbers of other samples. In such a situation, when there is ambiguity between sample name and row ID, the system will presume that the user intends to use the value as the name.

Related Topics

• Create a Sample Type
• Custom Grid Views
• Samples
• Sources
• LIMS: Samples

• Aliquots: Split a sample into identical aliquots which retain the properties of the parent sample and may have additional properties.
• You may also split an aliquot into a next generation of "subaliquots" by the same process.
• Derivatives: Derive new samples from one or more existing samples, possibly with new properties or treatments.
• Samples may also be derived from Sources in the system.
• Pooled Samples: Group together existing samples to make a combined pool sample for actions on the aggregate.

• Create New Samples from Selected Parents
• Derive from Selected Samples
• Pool Selected Samples
• Aliquot Selected Samples
• Aliquot Naming
• Aliquot Information in Grids
• Import Aliquots, Derivatives, and Pooled Samples from File
• Work with Aliquots
• View Aliquots of a Sample
• Find Original Sample Details for an Aliquot
• Aliquots in Lineage

Create Samples from Selected Parents

If you have already created the parent samples in the system and want to create new samples from these specific parents (whether by aliquoting, deriving, or pooling), you can do so from the Samples grid. (Note that if you select more than 1000 rows, the option to create samples with those parents is disabled.)

• Select the Sample Type of interest from the main menu.
• Select the parent sample(s) using the checkbox(es).
• Select Derive > , then the type of derivation. Note that on narrower browsers, the "Derive" section will be under the More > menu.
• Aliquot Selected
• Derive from Selected
• Pool Selected: Put multiple samples into pooled outputs.

Derive from Selected Samples

When you select Derive from Selected, you'll see the popup with the Derivatives option chosen.

• Select the Derivative Type.
• Provide the desired number of Derivatives per parent.

• Click Go to Sample Creation Grid.
• You will see the Samples you had selected prepopulated as parents in the grid, with as many rows per parent as you specified.

• Enter remaining sample information before clicking to Finish Creating the samples.

Pool Selected Samples

To pool a set of samples into pooled outputs, such as for testing on an aggregate of many samples, follow these steps:

• Select the Sample Type of interest from the main menu.
• Select the 'parent' samples using the checkboxes.
• If you only select one parent sample, the pooling option will not be shown.
• Select Derive > Pool Selected.
• In the popup, choose the Sample Type for the new pooled samples, enter the desired number of New samples from Pool, and click Go to Sample Creation Grid.

• You will see the Samples you had selected prepopulated as parents in every row of the grid.

• Enter remaining sample information before clicking to Finish Creating the samples.

Aliquot Selected Samples

To create aliquot portions of samples, follow the same initial process. The aliquots will share (inherit) some properties from the parent sample and may have additional aliquot-specific and/or aliquot-editable properties. If you select several samples first, each one will be aliquoted individually, i.e. you will see the desired number of rows per 'parent' with each only having the single parent.

• Select the Sample Type of interest from the main menu.
• Select the 'parent' sample(s) using the checkbox(es).
• Select Derive > Aliquot Selected.
• Add the desired number of Aliquots per parent by entering the number and clicking Go to Sample Creation Grid.

• You will see the Samples you had selected prepopulated as Aliquoted From parents in every row of the grid.
• You will also see any field properties that are editable for aliquots ("Provider" and "Color" as shown here).

• You cannot change parent or source types when creating aliquots.
• Each aliquot row will have the AliquotedFrom field set to the selected 'parent' (which may itself have additional parent and source information in the system).
• Enter values in the rest of the columns as needed before clicking to Finish Creating the aliquots.

When the aliquot creation is complete, as with any other you will have a banner message telling you how many were created. They are not selected by default (the original 'parent' samples remain selected) but the banner offers you quick links to add them to storage or select them in the grid. Learn more here.

Aliquot Naming

Like any other sample, aliquots must each have a unique name within the sample type. It is best practice for aliquots to include the name of the 'parent' sample, i.e. the value from the ${AliquotedFrom} column. You can accept the default naming pattern for aliquots or include a custom pattern in the sample type definition.

The default aliquot naming pattern is the parent sample name followed by a dash and incrementing counter:

${${AliquotedFrom}-:withCounter}

Using this default as an example, if you create 5 aliquots of the sample "Tutorial-30", then "Tutorial-30-5" is the 5th aliquot. If you create a new set of aliquots later, the incrementing numbers will continue to help you clearly track the total number of aliquots of your sample. When you are creating aliquots, you can see an example of the name that will be generated in a tooltip.

If instead you wanted to use a dot between the sample name and aliquot number ("Tutorial-30.5") you'd use the pattern:

${${AliquotedFrom}.:withCounter}

Learn about more options for aliquot naming patterns in the core LabKey Server documentation.

Aliquot Information in Grids

When viewing a grid of samples, you can expose various calculated columns related to aliquots. These columns are populated only for the original samples; they are set to null for aliquots themselves.

• Aliquot Total Amount: Aggregates the total available amount of all aliquots and subaliquots of this sample.
• Available Aliquot Amount: Aggregates the volume of all aliquots with a status of type "Available".
• Aliquots Created Count: The total number of aliquots and subaliquots of this sample.
• This column is populated only for samples, and set to zero for samples with no aliquots.
• Available Aliquot Count: The total number of aliquots (and subaliquots) that have a status of type "Available".

Import Aliquots, Derivatives, and Pooled Samples from File

After creating the parent samples, you can create new derivatives, pooled samples, and aliquots by importing from a file, referencing the parent samples you already created. Obtain the expected import format template, then populate it to indicate the relationships.

Aliquots

Populate the AliquotedFrom column with the Sample ID of the parent Sample. Leave the SampleID column blank to have a name created using the aliquot naming pattern. For example, to create 3 aliquots of sample "S-001":

When importing a mixed set of new samples, where some are aliquots and others are not, whether there is a value in this column will determine whether "isAliquot" is set to true, and whether the aliquot suffix pattern is used (i.e. S-001-1, S-001-2, S-001-3 in the above).

Derivatives

Pooled Samples

Work with Aliquots

View Aliquots of a Sample

When viewing sample details (click the name of the sample on the grid) you will see a panel showing Aliquots, if any aliquots of this sample exist.

• Total Aliquots Created: includes any subaliquots.
• Available Aliquot Count: Availability means that an aliquot is marked with a sample status of the "Available" type. This may include custom statuses created of that type represented by a green tag.
• Available Aliquot Amount: based on the combined amounts for all 'Available' aliquots.
• Jobs with Aliquots: Count will link to a grid filtered to show the set of jobs.
• Assay Data with Aliquots: Count will link to a grid filtered to show the set of runs.

On the Aliquots tab for the originating sample, you'll see a grid showing all the aliquots of that sample, making it easy to track and perform storage operations on the group.

Find Original Sample Details for an Aliquot

When you are viewing sample details for an aliquot it will look like any sample, with Aliquot Data on the Overview panel, as well as Original Sample Data for the sample it was aliquoted from. A link to the details page for that originating sample is included.

The Aliquots panel and tab in this case would show any subaliquots of this aliquot (if any).

Aliquots in Lineage

The Lineage tab for a sample that has aliquots will show them as 'children' in the graph. Use the Filter menu to select whether to include Derivatives, Sample Parents, and Aliquots in the display.

Note that only 5 generations will display on the lineage graph. To see additional generations, walk the tree up or down to see more levels in either direction.

Related Topics

• Sample Lineage / Parentage
• Manage Samples: Edit lineage for a single sample.
• Edit Selected Samples: Edit parents and sources for multiple selected samples.
• Manage Sample Status

• Enable Expiration Date Field
• Disable Expiration Date for a Sample Type
• Assign Expiration Dates to Samples
• Find Expired Samples or Samples About to Expire

Enable Expiration Date Field

When you define or edit a Sample Type, you will see the MaterialExpDate (Expiration Date) column listed with the Default System Fields.

Enable it by checking the box (it is enabled by default).

You can also check the box in the Required column to require that every Sample of this type have an expiration date. Note that if you have existing Samples without expiration dates, they must be populated before the field can be required.

Disable Expiration Date for a Sample Type

If you uncheck the box for this field, you and your users will not see, be able to set, or use Expiration Dates for this Sample Type. Note that if you use this field at first and it contains data, disabling it will not delete the data. If you later re-enable it, the previous data will be returned to view.

Assign Expiration Dates to Samples

When Samples are added or updated, either manually using a grid or via import from file, the Expiration Date can be supplied. In a file import, the column name should be MaterialExpDate.

Find Expired Samples or Samples About to Expire

Samples that have already expired are marked with an indicator in the UI. Look for a red triangle in the corner of the grid value or the storage cell location. You'll also see these indicators in the detail panel for a sample.

You can save ways to view expiring or expired samples by filtering or sorting grids by the Expiration Date column. You can save as a named grid to access later.

In addition, you can use the built in Sample Finder report to find Samples of all types with an Expiration Date value in the next week.

• Samples Expiring in the Next 7 Days

Related Topics

• Samples
• Sample Finder
• Built-in Sample Reports

The sample timeline can play an important role in tracking chain of custody for samples and complying with good laboratory practices. A sample timeline can help you answer questions like:

• Where is my sample located right now?
• Who has it now and when did they take possession of it?
• What has been done to my sample before I received it?

• View Sample Timeline
• Current Status
• Event Details
• Listing Order
• Filter Timeline
• Export Timeline

View Sample Timeline

To see the sample timeline, click the name of the sample in any grid where it is listed. You can find it on the grid for the Sample Type, access it from any assay data uploaded for it, or find it listed for a workflow job.

Click the Timeline tab along the top row. You will see all events for that specific sample.

Shown here, a sample was created (registered), it was added to a job, assay data was loaded for it, and then it was updated. The update Event Details show that there were changes to two Sources for the sample.

Current Status

The Current Status section in the upper right includes summary details like where the sample is now, who was the last to handle it (and when) and active status values.

Sample status, storage status, and job status of samples are highlighted with color coded indicators:

• Available (green)/Consumed (yellow)/Locked (red)
• Not in storage/in storage
• No job assigned/Assigned to job

Event Details

Click any event on the timeline to see the Event Details in a panel on the lower right. For example, when the event is "Sample was updated," the details section will say when and by whom.

Listing Order

By default, the timeline will Show Oldest first. Use the dropdown at the top to switch to Recent first instead.

Filter Timeline

When the list of timeline events is long, it can be helpful to filter for events of interest. Click Show filters above the listing to open the filters panel (the link will now read "Hide filters").

Use checkboxes to filter events to show any combination of:

• Sample Events
• Assay Events
• Job Events
• Storage Events

Export Timeline

Click the (Export) button to download the timeline as an Excel file. The exported file will include:

• Date
• Type of event
• Event name
• User
• Old Event Details
• New Event Details

Related Topics

• Audit Log: View all events for all samples.
• Storage Events Timeline for a Sample
• Manage Sample Status

• View All Sample Types
• View Samples of One Type
• Sample Type Details
• Sample Insights Panel
• Manage Menu
• View Individual Sample Details
• Panels on the Overview Tab
• Edit Sample Details
• Edit Sample Lineage
• More Sample Editing
• Delete Samples
• Deletion Prevention
• Delete One Sample
• Delete More Samples
• Partial Deletion
• Move Samples (Premium Feature)

View All Sample Types

To view all the Sample Types defined in LabKey Sample Manager, click Sample Types on the main menu.

The Sample Types dashboard lets you:

• Add Samples
• Create Sample Type
• View All Samples of all types in a tabbed grid.
• Manage > Sample Statuses

Click the name to open the set of individual samples of that type.

View Samples of One Type

You can open the grid of all samples of a specific type in several ways:

• Click the type name in the Sample Types grid.
• Click the graph bar for that Sample Type on the main dashboard.
• Click the sample name directly from the top level menu from anywhere in the application.

Sample Type insights are available in a horizontal panel and the Manage menu offers various actions.

Hover over the Details link to see the Description, Naming Pattern, Metric Unit, Parent Import Alias(es), and Source Import Alias(es) for this Sample Type.

Below the insights panel, the grid of Samples offers menus, custom views, filtering, sorting and searching. Learn more in this topic:

• Sample Grid Menus

Sample Type Insights

The panel above the grid gives a quick visual summary of Storage Status, Sample Status, and Aliquots. Color coded bars show the relative prevalence of each state. Hover for details about any colored segment. Click any bar segment to filter the samples grid to show only those samples.

When several Sample Status values have the same base type, such as "Received" and "Available" both being "Available" (green shaded) samples, you can hover over portions of the bar for details of that specific sample status. Click any bar segment to filter the samples grid to show only those samples.

Manage Menu

The Manage menu in the upper right offers these options:

• Edit Sample Type Design: Reopen the existing details and fields; edit using the same interface as you used to create the Sample Type.
• Edit Identifying Fields: Add or edit additional fields to be shown to users selecting these samples.
• Manage Templates (LIMS Feature): Users of LabKey LIMS and Biologics LIMS can customize the import templates offered to users.
• Delete Sample Type: Note this will delete all sample data and dependencies as well. Deletion cannot be undone. The administrator deleting a Sample Type can provide a Reason for Deleting if required or desired, and must confirm the action.
• View Audit History: Administrators can view the audit history for this Sample Type from this link.

• Sample Grid Menus

View Individual Sample Details

Click the Sample ID for any sample to view the details about it in the system in a series of panels. Tabs along the top offer more details about the sample. From the Manage menu you can create new samples of any type, delete this sample, add it to a picklist, or upload assay data for this sample. Storage editors can add to storage, check it out, or remove it from storage. You can also view the audit history for this specific sample.

The tabs along the top of the details page let you see the following for this specific sample:

• Lineage: View a lineage graph or grid.
• Aliquots: See aliquots and subaliquots of this sample.
• Assays: All assay data available for this sample (and any aliquots).
• Jobs: Find all jobs involving this sample (and any aliquots).
• Timeline: See a detailed timeline of all events involving this sample.

Panels on the Overview Tab

Panels on the Overview tab include:

• Storage: This panel shows the amount of the sample (if provided). If the Sample is already in storage, it also shows the current location and checkout status, if any. Otherwise, you'll see a link to add the sample to storage
• Aliquots: Details about any aliquots created of this sample. Note that to be "available" in this panel, an aliquot must have a Stored Amount > 0.
• Notebooks: Links to any notebooks that reference this sample will be shown here. Click the name to open the notebook
• Details: Details about this sample.
• For an aliquot, you will see both Aliquot Details and Original Sample Details in separate panels.
• Source Details: Information about sources of this sample. Note that only one generation is shown; see the lineage tab for more.
• Parent Details: Information about parents of this sample. Note that only one generation is shown; see the lineage tab for more.

Edit Sample Details

To edit the details for this sample, click the (Edit) icon for that section. Make changes using dropdowns and selectors similar to when you originally assigned the values.

Note that you can edit the SampleID (Name) here, keeping in mind that all Sample IDs must remain unique. This is useful in a situation where the original name may have included a typo or other error. You cannot, however, edit SampleIDs using any bulk method, including 'Edit in Grid' and import from a file.

You can provide a Reason for Update if desired or required before clicking Save.

Edit Sample Lineage

You can edit the immediate source and parent information (i.e. the first generation of lineage) directly from the sample details page. Use the (Edit) icon for the Source Details or Parent Details section as needed. Make changes using dropdowns and selectors similar to when you originally assigned the values.

You can provide a Reason for Update if desired or required before clicking Save.

More Sample Editing

Learn more about editing samples in this topic:

• Edit Selected Samples

Delete Samples

Deletion of samples may be necessary for a variety of reasons, and once completed, deletion cannot be undone.

Deletion Prevention

For samples with data dependencies or references, deletion is disallowed. This ensures integrity of your data in that the origins of the data will be retained for future reference. Samples cannot be deleted if they:

• Are 'parents' of other derived samples or aliquots
• Have assay runs associated with them
• Are included in workflow jobs
• Have a status that prevents deletion
• Are referenced by Electronic Lab Notebooks

The Delete Sample option will be grayed out when deletion is disallowed.

Delete One Sample

For samples which can be deleted, you can delete a single sample while viewing it's details page.

• From the detail page for the sample to delete, select Manage > Delete Sample.

• In the popup, you can enter the Reason for Deleting if required or desired.
• Confirm the deletion by clicking Yes, Delete.

Delete More Samples

You can also delete one or more samples from the grid view for the Sample Type. Note that you can only delete up to 10,000 samples at one time, so if you need to delete more than that, perform the deletion in batches.

• From the grid view for the type of sample to delete, select one or more checkboxes for the sample(s) you wish to delete. To select all samples, use the checkbox at the top of the column.
• Select Edit > Delete.

• In the popup, you can enter Reason for Deleting if required or desired.
• Confirm the deletion by clicking Yes, Delete.

Partial Deletion

If deletion is disallowed for any of the samples you attempt to delete, the popup will give you more details and ask you to confirm or cancel the partial deletion of any samples without dependencies.

When you delete samples, they will be automatically removed from any picklists to which they had been added.

Move Samples (Premium Feature)

When using the Professional Edition of Sample Manager (or any edition of LabKey Biologics LIMS), users with the appropriate permissions will be able to move eligible samples between Folders.

Learn more in this topic:

• Move Samples Between Folders

Related Topics

• Add Samples
• Samples
• LIMS: Samples
• Edit Selected Samples
• Manage Sample Status
• Sample Grid Menus
• Store Samples

Sample Manager supplies basic built in status types, Available, Consumed, and Locked, as well as assignable statuses by these names. An administrator can add additional statuses of any of these types to match their workflows. For example, custom status values could be used to track which samples have been shipped, received, are in use, are offsite, etc.

• Sample Status Types
• Manage Sample Statuses
• View or Edit Status Details
• Add New Status
• Choose Status Color
• Assign Sample Status
• Change Status to Consumed
• Sample Status Legend
• View Sample Status
• Status of Samples in Storage
• Sample Count by Status Dashboard

Sample Status Types

The Sample Manager application has 3 built-in status types, also represented by assignable statuses. Additional named statuses can be created of any of these types.

• Available: Allows any action. This status type is also used to determine calculations of available amounts.
• Consumed: Used up, and no longer can be aliquoted or checked out, but remains in the system for analysis and tracking. Storage updates are prevented.
• Locked: While locked, all actions are prevented except adding the sample to a picklist. A sample cannot be edited, have its storage updated, be moved between folders, or be added to workflows. The status can later be changed to another type of status.

Manage Sample Statuses

From the main menu, click Sample Types then select Manage > Sample Statuses. You can also reach this option using > Application Settings.

Scroll down to find the current set of defined statuses. You'll see the lozenge for each showing the color assigned to it. A lock icon indicates that there are currently samples "using" that status value so that it may not be deleted and its type cannot be changed. Additional status values can be defined of any of the three basic types. For example, "Received" might be an interim internal status on they way to full availability. The sample is neither consumed, nor locked, but might still need a step like assignment to a storage location before it will be switched to full "Available" status.

Samples in certain statuses will be prevented from certain actions, both in the UI and enforced by the server. For example, a Locked sample can't be deleted or checked out of storage, a consumed sample can't be aliquoted, etc. An administrator may, however, update the status of a sample if a mistake was made or conditions have changed.

View or Edit Status Details

Click the name of a status to see details on the right. Here you may edit the Label, Color, Description, and for statuses not currently in use, you can change the Status Type.

Add New Status

The three main statuses correspond to the three main "status types" with different actions allowed for each type. Adding additional custom status settings can support your lab's procedures and user expectations. Click Add New Status and populate the fields on the right.

For example, you might add a new status named "Received" which is another form of the "Available" type of status, representing newly arrived samples which may need an additional step performed before they are officially "Available" to your users.

Choose Status Color

For both built in and custom statuses, you can customize the color by selecting from the color picker. You may choose to assign the same color to all status of a given type, such as green for all "Available" statuses, or can choose something else to make specific statuses stand out in the system.

Assign Sample Status

Users can assign statuses to their samples throughout the system:

• At sample creation
• During file import of new or updated samples
• When updating a single sample's details
• In a bulk sample update

The status of a sample can later be changed by editing in a grid or in bulk for a set of samples at once.

Change Status to Consumed

When you change the Sample Status to "Consumed" (i.e. to any named status of the "Consumed" type), this typically means that there is no more of the sample to be used. If the sample is in storage, the user will also be asked whether they also want to remove it from storage.

When editing a single sample's details, use the checkbox to also Remove sample from storage?, adding a reason for the update if desired or required:

When editing in a grid or in bulk, saving will open a popup where you can check Yes, remove the sample(s) and enter a reason if desired or required::

Sample Status Legend

To see the set of available status values, hover over the for the Status column or field to see a legend listing all the available status values and their color coding.

View a Sample's Status

Sample status information will be displayed in sample grids and on the sample overview and storage sample details pages. Color-coded blocks and the legend make it easy to see status at a glance. The name of the specific status will be shown, using the color-coding you have assigned.

Sample Status and Storage Status

Sample Status can be viewed for a sample in storage, and is not the same as the Storage Status (In Storage, Checked Out, etc.), described further in this section: Storage Management

Sample status values are available in storage views as part of the sample details. Hovering will show the description of the status value, as shown below for a locked sample.

Sample Count by Status Dashboard

On the main dashboard, you can see an overall picture of the status of your samples using the Sample Count by Status chart. A bar for each Sample Type is color coded to show how many samples of that type in each status.

Hover over any bar segment for more details and click for the filtered set of samples of that type in that status; shown above, you'd see 260 "Available" Plasma samples.

Use the refinement menu, select All Statuses, With a Status, or No Status to control which sample statuses are displayed. For instance, using the No Status option, you can easily see and click through to the subset of samples that still need to have a status assigned, in this case in two sample types.

Related Topics

• Samples

To edit selected samples, select them on a grid or picklist using the checkboxes. If you are viewing a grid that contains samples of several types, you will first need to switch to the tab for the specific sample type before you can edit properties. Once you've selected the samples to edit, use the Edit menu to select one of the options:

• Edit in Grid
• Edit in Bulk
• Edit Lineage
• Edit Sample Name

Edit in Grid

Learn more about options for editing data in grids in this topic:

• Editable Grids

• You cannot edit the sample ID or fields like generated Barcode values in the grid.
• If you have selected a mixed set of samples and aliquots, you will also see fields grayed out when they are not editable for both categories. For example, a field that is inherited by aliquots from the originating sample (i.e. only editable for samples) will not be editable here.

Edit in Bulk

Sample details, including amount and units, can be edited in bulk. If any Aliquots are selected when you edit samples in bulk, only the aliquot-editable fields will be shown in the modal and available for bulk editing. To bulk edit sample fields that are not aliquot-editable, be sure to only select non-aliquot samples before selecting this option.

In the update panel, click the slider to enable the fields that you want to assign the same value for all the selected samples. Hovering over the will give you more detail about any field, such as for the Status field, you'll see a legend of available statuses. Shown below, the "Status" will be changed but the other fields will be left unchanged.

Click Edit with Grid to make further adjustments to details in the grid editor. Provide a Reason for Update if desired or required.

Click Update Samples when finished editing.

Edit Lineage

Edit the sources and parent samples for the selected samples. Lineage for aliquots cannot be edited.

The grid will show the current source and parent settings for the selected samples.

• To edit or add a selection to an existing column, click the or start typing, you will see a dropdown of matching options to choose from.

• To add a new parent or source association for these samples, click Add Parent or Add Source, select the desired type for the new association, then select values for the rows in the new column that will be added to the grid.

Edit Sample Name

Note that you cannot edit the SampleID using any grid, bulk or file import method. To change the SampleID, you can edit the individual sample's Details. Keep in mind that sample names must remain unique.

Related Topics

• Update Samples via File Import
• Manage Samples
• LIMS: Samples
• Permission Roles
• Data Grid Basics

The criteria you define will persist for the next time you visit the Sample Finder making it easy to focus on what you need regularly. You can also save your search criteria by name to keep track of common searches.

• Video Tutorial
• Open the Sample Finder
• Find Derivatives in Sample Finder
• Sample Finder
• Filtering Criteria
• Choose Values
• Filter With Expressions
• Find Samples with Multiple Common Ancestors
• Edit Criteria
• Search Results
• Saved Searches
• Save Search Button
• Manage Saved Searches

Video Tutorial

In this video, you will see how to create persistent, reusable reports using the Sample Finder.

Note that updates since the making of this video mean that you select Reports > Find Derivatives in Sample Finder to open this report (instead of clicking "Find Derivatives"). Also, criteria can now include both common and user-defined properties of samples, parents, and sources.

Open the Sample Finder

To open the Sample Finder, select it from the search menu anywhere in the application. You can also click Go to Sample Finder from the main dashboard.

Find Derivatives in Sample Finder

You can prepopulate the Sample Finder with a starting search filter by selecting a set of samples or sources and selecting Reports > Find Derivatives in Sample Finder. On some grids, this option will be under the More menu. For example, to find all the samples created from any "Mouse" source, select all rows on the Source page for Mice. When you select Find Derivatives in Sample Finder, you'll jump to the sample finder with all sample "children" from your selections where you can add more search criteria.

Sample Finder

When you open the Sample Finder without preselecting samples, you'll see the tile dashboard:

Click a tile to find samples using one of the categories of filtering criteria, detailed below.

In the popup, choose the specific type and field on which you want to filter. You can filter some fields by values and any field using filtering expressions.

Click Find Samples to add your filter.

Filtering Criteria

• Sample Properties: Find Samples based on properties defined in the Sample Type, whether built-in (common to all Sample Types) or user-defined. You can either narrow to a specific type or search across common properties of all Sample Types.
• Ex: Find all Samples with an expiration date in the next 7 days.
• Parent Properties: Find Samples based on the properties of their parent Samples.
• Both built-in and user-defined properties of the parent Sample Type are available for searching here.
• Ex: Find all child Samples derived from any Blood Sample parent with a Draw Date during a certain timeframe.
• Source Properties: Find Samples based on properties of a Source parent:
• Both built-in and user-defined properties of the Source Type are available for searching here.
• Ex: Find Samples taken from male, BALB/c mice.
• Assay Properties (Professional Edition Feature): Find Samples based on Assay Result data.
• Ex: Find Samples with a Platelet count on a CBC assay in specific range of values.
• You an also use a checkbox to find Samples without any results for a selected assay.

Choose Values

For some fields with a limited set of value options, you can use a checkbox interface to select one or more values to include. For example, to choose only samples with a Blood parent where the ParticipantID is either "PT-101" or "PT-102".

Filter with Expressions

You can also use the Filter tab to specify a filtering expression and enter a value. If desired, you can add a second filter to this column to indicate a range or other combination of expressions that will be AND-ed together.

If your first filtering expression fully constrains the result (such as an "Equals" filter) you will not have the option to add a second expression.

Find Samples with Multiple Common Ancestors

Use the specialty Equals All Of filter operator to find samples that share all of a provided set of multiple ancestors of a given type in common. This option is only available on the Parent Properties and Source Properties cards and can only be used for ID fields, including Sample ID and Source ID. For example, if you wanted to find samples who had both Mouse-1 and Mouse-2 as ancestors, you could use this filter operator. Up to 10 IDs can be provided separated by either new lines or semicolons.

All samples which have all of the provided IDs as ancestors will be returned.

Edit Criteria

Once you've defined any sample finding criteria, you can use the buttons in the upper right to add more filters on other columns of any other available type.

Each type that you filter on will have a tile, listing the active filters on columns in that type.

You can use the for any tile to edit the criteria it will use to find samples. For example, you could add additional filters on other fields of a parent or source filter you already created.

To add search criteria for another type of source or parent, start from the Source/Parent Properties button.

• Each type will have a separate "tile" showing filters applied. When a filter includes "does not equal", you will see the values with strikethrough styling.
• To set a filter to simply require that the sample have any parent of a given type, use "SampleID is not blank" for that filter.

To delete all criteria associated with a given source or parent, click the for that tile.

Search Results

As you build your set of criteria, you will see the results grid below the tiles. There is a tab for All Samples as well as individual tabs for all defined sample types. Each shows the count of samples of that type that were found using your criteria.

The data grid will show the parent and source columns included in your criteria, as well as common properties of the samples themselves, such as status and creation date. You can use these results to refine the sample finder criteria tiles. When ready, you can save your current search criteria so that you can apply them later. If you want to save a given result set of samples, use a picklist.

Learn about options for actions, filtering, searching, and sorting sample grids in this topic:

• Sample Grid Menus

• Creating new derivatives or aliquots (only available on the tab for a specific sample type)
• Importing assay data
• Adding to picklists or workflow jobs
• Storage Editors can manage storage status, including checking out the found samples

Saved Searches

To save a Sample Finder search, click the Save Search button (only shown when you have generated a set of search criteria).

Give your search a name, then click Save in the popup. This name will be used to retrieve this set of criteria later, and perform a new search using them, possibly finding a different set of samples depending on how your data has changed over time.

You'll now see the name of your custom search as the name of the Saved Search menu. Options:

• Most Recent Search:
• The date and time of your most recent search is shown; click to open it.
• Saved Searches:
• You'll see a list of any named saved searches you've created here.
• Note that saved searches are not shared with other users.
• Other Reports
• Built in sample reports are listed here. Learn more in this topic: Built-in Sample Reports
• Manage saved searches
• Save as custom search

Save Search Button

Switching to a previous search result (such as "Searched 2022-06-21 10:27" in the above) will add a Save Search button to the header.

If you make changes to an existing saved search, you'll be able to use the Save Search button as usual, or select the dropdown and Save as... a new named search.

Manage Saved Searches

When you click Manage Saved Searches you can edit the name of other searches, or delete them. You cannot edit (or delete) the currently active search; it is shown with a lock icon.

Related Topics

• Sample Search
• Search
• Built-in Sample Reports

In all cases, these built in reports can be a starting place for further refining results and saving new named sample searches to create your own custom reports.

• All Samples Created by Me
• All Samples Created by Other Users
• All Samples Created in the Last 7 Days
• Samples Expiring in the Next 7 Days
• Samples with Fewer than 5 Aliquots Available

All Samples Created by Me

This report is the equivalent of filtering Sample Properties for All Sample Types where Created By is the current user.

All Samples Created by Other Users

This report is the equivalent of filtering Sample Properties for All Sample Types where Created By is NOT the current user.

All Samples Created in the Last 7 Days

This report filters All Sample Types where the Created date is greater than or equal to 7 days ago. Notice the use of the syntax "-7d" to mean 7 days ago in this report.

Samples Expiring in the Next 7 Days

This report selects Samples where both conditions are true:

• They are not already expired, i.e. their Expiration Date has not passed.
• They have an Expiration Date in the next seven days.

When maintaining a stock of Sample materials, using this report can help you rotate and efficiently prioritize using the Samples before they expire.

Learn more about expiration dates in this topic:

• Sample Expiration

Samples with Fewer than 5 Aliquots Available

This report filters the Available Aliquot Count to find those with fewer than 5. In order to be included in this report, the aliquot(s) must have a sample status of the "Available" type.

Related Topics

• Sample Finder
• Save Your Own Sample Reports (Named Searches)

• Sample ID
• Barcode: Barcodes include both:
• Unique Storage ID fields and
• Other data fields specifically designated as containing barcodes

If you want to search for samples by properties of their source, parent, or assay data, you can use the Sample Finder.

If you are only looking for a single sample, you can use the site-wide search box with a single Sample ID or Barcode.

Topics:

• Find Samples in Bulk
• Find Samples by Barcode
• Find Samples by ID
• Add More Samples
• Clear Search Results
• Work with Found Samples

Find Samples in Bulk

Click the right edge of the search bar or the icon on narrower browsers and select:

• Find Samples by Barcode
• Find Samples by ID

Depending on which selection you made, one of the following will be selected in the popup. (You can change to the other method if desired.)

• Barcodes: Search for values in all fields designated as "Barcode Fields" across all Sample Types. This includes:
• All fields of type Unique ID.
• Any text fields designated as Barcode Fields; i.e. those which have the box "Search this field when scanning samples" checked.
• Sample IDs: Search all fields of type Sample.

List up to 1000 Barcodes or Sample IDs, each on its own line, then click Find samples.

All the samples located will be listed in a grid, where you can immediately work with them or add more to the list.

If any samples you requested were not found, you will see a notification message. Click Show all to see the IDs that were not found. In the case of a typo or incorrect type of search, you can use Add More Samples to find additional samples to add to the list.

Click Reset to start a new search from scratch.

Add More Samples

Once you have found some Samples, you can click Add More Samples to add to the list. As in the original search, you can input either Barcodes or Sample IDs. This allows you to create a set of results that blend the two search methods.

Click Find Samples to search for these new IDs and add them Samples to your list if found.

Clear Search Results

To clear the set of search results in the grid, click Reset. This may be a useful option in the case of entering a large number of incorrect samples or other issues.

Work with Found Samples

Once you've built your list of Samples in the grid on the search page, you can use the menus for many actions on the All Samples tab. All search result Samples are selected by default.

You can also switch to any Sample Type-specific tab to use the other actions available on sample grids, including the ability to customize the grid view.

Related Topics

• Sample Finder
• Search
• Barcode Fields

This topic describes how to use LabKey applications, including Sample Manager and Biologics LIMS, with BarTender for printing labels for your samples. Note that an administrator must first complete the one-time steps to configure BarTender Automation. Once configured any user may send labels to the web service for printing.

• Print BarTender Labels for Samples
• Print Labels for a Single Sample
• Print Labels for Multiple Samples
• Download BarTender Template
• Troubleshooting

• BarTender Integration

Print BarTender Labels for Samples

Before you can print labels, an administrator must have completed the one-time setup steps in this topic, and configured LabKey to print labels. The admin can also specify a folder-specific default label file. When printing, the user can specify a different variant to use.

After configuring BarTender, all users will see the options to print labels in the user interface.

Print Single Sample Label

Open the Sample Type from the main menu, then open details for a sample by clicking the SampleID.

Select Print Labels from the Manage menu.

In the popup, specify (or accept the defaults):

• Number of copies: Default is 1.
• Label template: Select the template to use among those configured by an admin. If the admin has set a default template, it will be preselected here, but you can use the menu or type ahead to search for another.

• Click Yes, Print to send the print request to BarTender.

Print Multiple Sample Labels

From the Sample Type listing, use checkboxes to select the desired samples, then select Print Label from the (Export) menu.

In the popup, you have the following options:

• Number of copies: Specify the number of labels you want for each sample. Default is 1.
• Selected samples to print: Review the samples you selected; you can use the Xs to delete one or more of your selections or open the dropdown menu to add more samples to your selection here.
• Label template: Select the template to use among those configured by an admin. You can type ahead to search. The default label template file can be configured by an admin.

• Click Yes, Print to send the print request to BarTender.

Download BarTender Template

To obtain a BarTender template in CSV format, select > Download Template.

Troubleshooting

If you have trouble printing to BarTender from Chrome (or other Chromium-based browser), try again using Firefox.

If you are not seeing values populate in your labels, confirm that you have configured BarTender to have the necessary data source connection.

Error Reporting

If there is a problem with your configuration or template, you will see a message in the popup interface. You can try again using a different browser, such as Firefox, or contact an administrator to resolve the configuration of BarTender printing.

Related Topics

• BarTender Integration
• Samples

This topic describes how an administrator can configure LabKey applications, including Sample Manager and Biologics LIMS, to use BarTender for printing sample labels. Once configuration is complete, any user can send sample labels to the web service for printing.

• Video Tutorial
• Configure BarTender Integration
• Include Print Portal
• Create and Bind Self-Signed Certificate
• Example BarTender Configuration File(s)
• Configure LabKey to Print BarTender Labels
• Manage Label Templates
• Set Up Data Source Connection in BarTender
• Error Reporting

Video Tutorial

Configure BarTender Integration

BarTender integration is supported when used with a BarTender Automation license. We have tested versions 2019, 2021, and 2022.

In the BarTender application, you will identify the web service URL and create the label file(s) for printing. The label file has the extension .btw. LabKey applications accept a default label file, but also allow the user to specify a different variant at the time of printing.

• BarTender by Seagull Scientific

Include Print Portal

When you install BarTender, be sure to select Specify advanced installation options, then select the BarTender with Print Portal option. To add Print Portal to an existing installation of BarTender, re-open the original installer file, select Modify, and select BarTender with Print Portal.

Also check the box to Add Microsoft SQL Server Express if you have not already installed it on your system.

Create and Bind Self-Signed Certificate

The following script will:

• Create the certificate with the appropriate flags, including KeyUsageProperty.
• Export the certificate.
• Import the certificate to the local CA so it is trusted by browsers.

# Create Cert
$pwd = 'password'
$cert = New-SelfSignedCertificate -FriendlyName "BarTenderCert" -DnsName $env:COMPUTERNAME -CertStoreLocation "cert:\LocalMachine\My" -KeyUsage DigitalSignature,KeyEncipherment,DataEncipherment -KeyAlgorithm RSA -HashAlgorithm SHA256 -KeyLength 2048 -KeyUsageProperty All -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider" -NotAfter (Get-Date).AddYears(5)
$SSpwd = ConvertTo-SecureString -String $pwd -Force -AsPlainText
Export-PfxCertificate -Cert "Cert:\LocalMachine\My\$($cert.Thumbprint)" -FilePath bartender_cert.pfx -Password $SSpwd
Import-PfxCertificate -FilePath bartender_cert.pfx -CertStoreLocation "cert:\LocalMachine\Root"  -Password $SSpwd
echo $cert.Thumbprint

Example BarTender Configuration File

Download this example to help you get started with BarTender 2021 or 2022:

• labkeyBT-2021.btin

• labkeyBT.btin

https://localhost/Integration/LabKeyBarTenderService/Execute

For versions prior to Bartender2021, use this URL:

https://localhost/BarTender/API/Integration/LabKeyBarTenderService/Execute

Configure LabKey to Print BarTender Labels

Return to the LabKey application (Sample Manager or Biologics LIMS) and select > Application Settings.

In the BarTender Web Service Configuration panel, enter:

• BarTender Web Service URL: This is the URL of the web service to use when printing BarTender labels.
• Click Save to save it.

• Once you've saved the URL, you can use Test Connection to test your configuration.

Manage Label Templates

Click Add New Label Template for each template you want your users to be able to use. If you are using multiple Folders, templates can only be defined in the top-level home.

• Name: Give the template an identifying display name your users will recognize.
• Description: The description can provide more detail.
• File Path: Provide the path to the label template file to use. The path should be relative to the default folder configured for the BarTender web service specified above.
• Set as Default: Click the selector if you want this template to be the default.
• You are not required to set a default, but if you do, it will be preselected when users print labels.
• For users of multiple Folders, there can be a different default template in each folder.

Once templates are defined, you can return to the > Application Settings page to manage them.

• Click a template name to see or update details, including whether the template is the default.
• Select and then click Delete to delete a template.

Set Up Data Source Connection in BarTender

For each template and Sample Type, you will need to set up the data source connection in BarTender as follows.

Error Reporting

If there is a problem with your configuration or template, you will see a message in the popup interface allowing you a chance to verify or change the label template you've selected. If a change needs to be made to the underlying URL configuration, contact an administrator to retry the configuration process.

Related Topics

• Print Labels with BarTender

Once a sample has either type of Barcode Field, you'll be able to search for it using these values.

• Add UniqueID Field for LabKey-Managed Barcodes
• Generate UniqueID Barcodes
• Use Existing Barcode Values
• Search by Barcode

Add UniqueID Field for LabKey-Managed Barcodes

To support barcodes generated and managed by Sample Manager, you will need a field of type "UniqueID" in your Sample Type. When you create a new Sample Type, you will be prompted to include such a barcode field.

To add a "Unique ID" field to an existing sample type, open it for editing. In the Sample Type Properties section, you will see under Barcodes, a blue banner inviting you to create the field necessary. Click Yes, Add Unique ID Field.

By default, it will be named Barcode. If you wish, you can click the Fields section to open it and edit the field name.

Click Finish Updating Sample Type. Barcodes will be automatically generated for any existing samples of this type, as described in the next section.

Generate UniqueID Barcodes

When you add a UniqueID field to a Sample Type that already contains samples, as you finish updating the sample type, you will be prompted to confirm that adding this field will generate barcodes for existing samples.

Click Finish Updating Sample Type to confirm, then view the grid of samples to see the generated barcode values.

In addition, when any new samples are added to this Sample Type, barcodes will be generated for them. You cannot provide values for a UniqueID field, or edit them.

UniqueID generated barcodes are 9+ digit text strings with leading zeros ending in an incrementing integer value. Ex: 000000001, 000000002, etc. Generated barcodes are unique across the Sample Manager application, i.e. if you use UniqueID barcodes for several different Sample Types, every sample in the system will have a unique barcode. When more than a billion samples are defined, the barcode will continue to increment to 10 digits without leading zeros.

Once generated by the system, barcodes in a UniqueID field cannot be edited and if data is imported into one of these fields, it will be ignored and an automatic barcode will be generated. If you need to provide your own barcode values or require the ability to edit them, do not use a UniqueID field.

Use Existing Barcode Values

If you have barcodes in your Sample data already, and do not want them generated or managed by LabKey, you can include a field of type "Text" or "Integer" in your Sample Type, and check the Barcode Field box for "Search this field when scanning samples".

This field may be named "Barcode" if you like, but will not be managed by LabKey, or shown as the Barcode property of the Sample Type. It will have the "scannable" field property set to true.

Users can locate samples using the barcode values in this column, but must manage uniqueness and generate new barcode values for new samples outside of the application.

Search by Barcode

Once your samples have a barcode column of either type, you can search for the value(s) to locate the sample(s). To find by a single barcode, you can search, sort, and filter the samples grid, or use the global Search option in the header throughout the application to find a single barcode value.

To more easily find samples by barcode value, you can use the Find Samples option.

Enter values by typing or using a scanner, then click Find Samples to search for them.

Learn more in this topic:

• Sample Search

Related Topics

• Create a Sample Type
• Sample Search

Administrators and users with the Workflow Editor role can create and edit picklists.

A user can build a picklist privately, adding and removing samples until the correct set are defined. Samples of different types can be included on the same picklist. The completed list may be kept private or shared with other team members for use when performing other tasks.

• Create a New Picklist from Samples
• Create Empty Picklist
• Add Samples to Picklist
• Manage Picklists
• View a Picklist
• Refine and Use a Picklist
• Export Picklist
• Shared Picklists and Permissions

Create a New Picklist from Samples

Select the desired samples on a grid and select Picklists > Create a New Picklist. On narrower browsers, this option will be under the More > menu:

Give the picklist a name, optional description, check the box if you want to share it with team members, then click Create Picklist. The selected samples will be added to the new picklist.

You will return to the sample grid, with a banner available offering a quick link to View picklist.

Create Empty Picklist

You can also create an empty picklist and add samples later. Click Picklists on the main menu, then click Create Picklist. Give it a name, optional description, and check the box if you wish to share it.

Add Samples to Picklist

When you select samples in a grid and choose Picklists > Add to Picklist (or More > Add to Picklist), you will see all the Picklists available. If no picklists exist yet, you will be able to click create a new one here.

When the number of picklists is long, you can narrow the list by typing in the "Find a picklist" box. Shared picklists are shown on a separate tab, with shared picklists you created yourself shown on the "Your Picklists" tab with a icon.

Click to select the desired picklist. You'll see the existing number of samples already on the list.

Click Add to Picklist to add your selected samples to it.

Manage Picklists

Click Picklists on the main menu.

• Click Create Picklist to create a new empty one.
• The primary Your Picklists tab shows the picklists you have created. The Sharing column indicates whether you've shared them ("Yes" or "No").
• Click Shared Picklists to see shared ones created by you or other team members.
• Click the Name of a picklist to open it for review or editing. Learn more about using picklists below.

Note that if a sample is deleted from the system, it will be also be removed from any picklists.

View a Picklist

From the Picklists dashboard, click the name of a picklist to open it in grid form. You will see the samples on the list, available on a series of tabs.

Learn more about multi-tabbed sample grids here.

Refine and Use a Picklist

Actions available for picklists include:

• Manage
• Edit Picklist: Change the name, description, and whether the list is shared with your team.
• Delete Picklist: This removes the picklist, but does not delete any sample data.

• Remove from Picklist
• Use options on the Assay/Jobs/Storage/Reports menus

• Sample Grid Menus

Export Picklists

To export a picklist, such as to use as a guide for physically removing samples from the freezer, click the icon above the list of samples in the picklist. If any sample rows are selected, only selected rows will be exported. If no rows (or all rows) are selected, the entire picklist will be exported.

Export formats include:

• CSV
• Excel: For multi-tabbed picklists, you can select which tabs to include in your Excel export.
• TSV

Shared Picklists and Permissions

When the Share this picklist box is checked for a picklist, it will appear for all team members on the Shared Picklists tab of the Picklist dashboard.

• Only the creator of a picklist may edit the name, description, and whether the list is shared with the team.
• All users with the Reader role in Sample Manager can read a team picklist and export the data for completing tasks.
• Any user with Editor or Admin permissions may also add or remove samples from team picklists and add picklists to jobs.
• Storage Editors can use picklists for adding and managing freezer storage of samples.

Related Topics

• LIMS: Workflow
• Store Samples

• Physical Sources like labs, vendors, locations, studies, etc.
• Biological Sources like patients, mice, trees, cell lines, etc.

For instance, multiple types of sample might be taken from a single source subject, i.e. blood and urine from the same mouse. Relating data from different assays performed on the different types of sample might turn up trends or correlations not available from a single sample.

Similarly, each sample might have multiple sources, such as a blood sample from a certain patient who visited a certain lab location during participation in a specific study. If that patient were part of other studies, or changed which lab they visited to submit samples, tracking sources would provide additional context to your data.

Topics

• Create Sources
• Associate Samples with Sources
• Manage Sources
• Sample and Source Lineage

• Create Source Type
• Source Naming Patterns
• Add a Parent Source
• Add Sources
• Update or Merge Sources from File

Create Source Type

Describe the type of source. Within the system, you might have several different types of source from which samples are taken, such as biological sources like animals or cell lines and physical sources like labs or vendors.

From the main menu, select Source Types and click Create Source Type. When you create your first Source Type, there is a shortcut to Create a source type on the main menu. Note that you can only create Source Types in the home (top-level) folder. If the creation button is missing, navigate first to the home.

• Enter a Name (Required) for this Source Type, shown here 'Creature'.
• The Name must start with a letter or number character, and avoid special characters and some reserved substrings listed here.
• You can edit the Source Type to change this name later.
• Enter an optional Description.
• Like with samples, all individual sources must have a unique name. You can either:
• Provide these with your data in a column named "SourceId" or
• Ask the system to generate them using a Naming Pattern.
• The default pattern is the word 'Source' followed by an incrementing number:

  Source-${genId}

• Either accept this default, specify another pattern, or delete it (and ignore the placeholder text) if you plan to supply source names.
• You can change the pattern later, but existing names of sources will not change.
• If you want to include lineage relationships (parent sources) for this type of source, click Add a Parent Source

• As for sample types, click the Fields section to open it.
• Every Source Type includes Default System Fields "SourceId" (Name) and "Description". You can use the checkbox to disable the description, but the name/sourceID is always required. In addition, fields like "Created/CreatedBy", and "Modified/ModifiedBy" are always included but not shown here. Find a list of reserved and internal field names in this topic: Data Import Guidelines
• For defining Custom Fields, you can Import or infer fields from file or manually define fields yourself. Details are found in the topic for creating fields in sample types.
• If you infer from a file that contains the built-in fields, they will not be shown as they will always be created for you.

• Note that you can create fields of the same data types as you can for sample types and assays, with the exception that you do not include fields of type "Sample". Associations of samples with sources are made from the sample definition to it's source, not the other way around.

• Click Finish Creating Source Type when finished.

Source Naming Patterns

When you create a Source Type, you decide how unique names for all the sources will be generated. You can provide them yourself or have them automatically generated with a naming pattern, similar to how samples are named.

The default pattern is the word 'Source' followed by an incrementing number:

Source-${genId}

Add a Parent Source

Sources may have parent sources of the same or other types. For example, you might have source types for both "Studies" and "Subjects", in which all "Subjects" have a parent "Study". Just as how parent aliases can be defined for Sample Types, you can include a Parent Source for your Source Type, giving you a column name to include when uploading parents of the selected source type.

Select the Parent Source Type and provide a File Import Column Name that will be used to identify this field in incoming spreadsheet imports. Use the Required checkbox if you want to require every source have a parent of that type.