Table of Contents

guest
2024-10-10
Sample Manager Overview
   Get Started with Sample Manager
   Tutorial: Learn Sample Manager
     Tutorial: Add Samples
     Tutorial: Define Assays
     Tutorial: Add Users and Assign Roles
     Tutorial: Outline Workflow
     Tutorial: Track Sample Sources
   Release Notes: Sample Manager
   Sample Manager Dashboard
   Folder Organization
     Cross-Folder Actions
   User Accounts, Groups, and Roles
     My Account
     Permission Roles
     Manage Groups
     Manage Notifications
   Sample Manager - FAQ
Samples
   Create a Sample Type
   Add Samples
     Create Samples from Grid
     Import Samples from File
   Sample ID Naming
     ID and Name Settings
   Sample Lineage / Parentage
   Aliquots, Derivatives, and Sample Pooling
   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
Sources
   Create Sources
   Associate Samples with Sources
   Manage Sources
Experiment / Assay Data
   Describe Assay Data Structure
   Import Assay Data
   Manage Assay Designs
   Manage Assay Data
Electronic Lab Notebook (ELN)
Storage Management
   Create Storage
   Store Samples
   Manage Storage
   Manage Storage Unit Types
   View Storage Details
   Edit Storage Definition
   Manage Storage Locations
   Move Stored Samples
   Manage Stored Samples
   Check Out and Check In
   View Storage Activity
   Migrate Storage Data into LabKey
Workflow
   Start a New Job
   Manage Job Queue
   Complete Tasks
   Edit Jobs and Tasks
   Create a Job Template
   Manage Jobs and Templates
Data Resources
   Data Grid Basics
   Data Import Guidelines
   Custom Grid Views
   Audit History
   Search
   Field Editor
   Field Properties Reference
   Attach Images and Other Files
   URL Field Property
   Date, Time, and Number Formats
   String Expression Format Functions
Explore Sample Manager
   Ontology Concept Annotations
   Help Links
   Click to Explore

Sample Manager Overview


LabKey Sample Manager is an easy-to-use sample management system for any size lab. Video overviews and demos will help you get started. Each will open in a new tab:

The intuitive interface makes it easy to track the entire lifecycle of samples in your lab and all associated research data.

With the Professional Edition of Sample Manager, you will also be able to:


You can take a guided tour, learn directly from other users describing how they are using the application, and sign up for a personalized demo on our web site:

Topics

To return to this documentation from within the application, click the in the header bar.

More Answers

How Do I Know the Version of Sample Manager

An administrator can see which version of Sample Manager 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.



Get Started with Sample Manager


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

More Video Overviews and Demos

Each will open in a new tab.


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.

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.

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:

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.

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:

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:




Tutorial: Learn Sample Manager


This tutorial will help an administrator get started with a new, empty Sample Manager project. Users of the system may also find it helpful to read along to understand how the underlying structures are created.

Administrator Tutorial

Learn the tasks of an administrator by adding a few "Tutorial" samples, defining an assay, and creating simple workflow jobs. Define sources for the samples and see how lineage and timeline features will help users manage their data.

These topics will give you a quick introduction to the tools and process before you load your real data.

Topics

After completing the tutorial topics, you will have an understanding of how to use Sample Manager for your own data and workflows.

User Tutorial Sections

Users of the Sample Manager application without administrative permissions but with the "Editor" role will perform the following tasks. Portions of the tutorial that are common user tasks are:

Users with the "Reader" role (or higher) will be able to:



Tutorial: Add Samples


Sample Types help you organize samples in your lab and allow you to add fields that help you describe attributes of those samples for easy tracking of data. Each individual Sample has a unique ID and is a member of one Sample Type. This topic assumes you are starting from an "empty" application and walks you through creating a "Tutorial Samples" type and populating it with a set of samples to use in the next steps.

Create a New Sample Type

Create the first Sample Type in the system by clicking the linked word here in the empty Dashboard Insights panel or by selecting Create a sample type from the main menu under Sample Types.

Once one or more Sample Types have been created on your server, you will click the Sample Types heading from the main menu, then click Create Sample Type.

Define Sample Type Properties

  • Enter the Name: "Tutorial Samples"
  • Replace the default contents of the Naming Pattern box with the following, so that samples of this type will be clearly identified as part of this tutorial:
    Tutorial-${genId:number('000')}
    • You can now hover over the tooltip for the Naming Pattern field to confirm that the pattern has been validated and see an example name that might be generated.
    • Similarly you will see the default Aliquot Naming Pattern and can hover to see an example name. Do not change this default for the tutorial.
  • Click Add Parent Alias to tell the system the name of the column where we will include information about parent samples with our data.
    • Enter "ParentSample" as one word to match our spreadsheet.
    • Select "(Current Sample Type)"
  • If you also see a button for Add Source Alias you can ignore it for now.
  • Click the Label Color selector to choose a color to associate with samples of this type. Our images show orange, but you can select any color you like by clicking, entering a hex value, or individual RGB values.
  • Amount Display Units: Select "mL (milliliters)". Notice that a variety of built-in solid and liquid unit measurements are available, as well as "unit" for cases where each sample is tracked independent of amount.
  • Barcodes: Ignore this setting for this tutorial. Learn more about barcodes in this topic: Barcode Fields

Define Sample Fields

  • Click the Fields section to open it.
  • You'll see Default System Fields that are automatically included in every Sample Type.
  • Click the to collapse this section for the tutorial.

The Custom Fields section lets you either import or infer fields from file.

  • For this tutorial, click Manually Define Fields.
  • In the field editor:
    • For this tutorial, disregard the blue banner about adding a Unique ID field for barcodes.
    • Enter the name "Provider" and leave the default type "Text" selected.
    • Click Add Field to add another row, enter then name "Concentration" and select "Decimal (floating point)" as the data type.
  • Click Finish Creating Sample Type.

You will now see the details page for this new Sample Type and are ready to create your first samples in the system.

Import Samples from File

Once you have defined the Sample Type for your samples, you can import them by typing directly into a grid, bulk entering values, or by importing a spreadsheet of sample information, as used in this tutorial.

  • Download this spreadsheet to use:
  • The "Tutorial Samples" Sample Type is now available on the main menu. Click to open it.
  • Click Add, then choose Import from File.
  • You'll see the Sample Type selection of Tutorial Samples sample only. Disregard for now the Storage Options, as we have not created any storage and do not include any storage details in our file.
  • Drag and drop the "TutorialSamples.xlsx" file into the target area.
  • You will see a preview of the data file as it will populate rows in the type. A unique "Sample ID" will be generated for each line based on the naming pattern provided.
  • Click Import.
  • When complete, you will see the samples listed.
    • The generated Sample IDs for each row may vary if other samples have already been created on your system.
    • There are a number of additional built-in columns created for you, including but not shown below, the creation date and user.

Learn more about importing samples from a file in this topic: Import Samples from File

Other Ways to Import and Create Samples

You can also add samples manually, in a grid or using bulk insert methods. Learn more in this topic:

View Sample Details

You can view details about your samples by clicking the Sample ID. For example, scroll down and click Tutorial-018.

On the details page, you have several tabs with information:

  • Overview: basic details including the values of all sample properties and fields as well as the storage location (if any)
  • Lineage: parentage and source information (Tutorial-018 has both parent and child sample linkages provided in our example file)
  • Aliquots: any aliquots created from this sample
  • Assays: all data about this sample
  • Jobs: all jobs that involve this sample
  • Timeline: a history of events for this sample (so far only registration has occurred)
Browse the information on these tabs before continuing to the next tutorial step.

Related Topics

Start Over | Next Step (2 of 5)




Tutorial: Define Assays


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

Assay Designs describe the structure of assay data you will gather for your samples. Similar to sample types, you define the properties and fields of your experiment data. Assay data will also be mapped to the sample that it is about. In this topic, we define a "Tutorial Assay" and import an example run of data for the "Tutorial Samples" we created in the previous step.

Create Assay Design

  • From the main menu, select Assays > Create an assay design.
    • If any assay designs have already been created, you will not see this link. In that case, click Assays and then Create Assay Design.

Define Assay Properties

Assay properties are elements that apply to all runs that use this assay design, i.e. one value is set for all runs.

  • Enter:
    • Name: Tutorial Assay
    • Description: Complete blood count
    • Active: Leave this box checked; unchecking it will archive the assay design.
    • Check both boxes for Editable Runs and Editable Results to give you the most options to explore with this tutorial assay design.

Add Run Fields

Assay run fields are set once for each run that uses this assay design, i.e. one value is set for each run.

  • Click the Run Fields section to open it.
  • Click Manually Define Fields.
  • Click Add Field to add each of the fields shown below and select the Data Type shown:
    • "Date" of type "Date Time"
    • "Instrument" of type "Text"

Add Results Fields

You could also manually add results fields, which will be different for each row of data within a given run, but in this tutorial, we will infer them from an example spreadsheet.

In the assay designer:
  • Click the Results Fields section to open it.
  • Drag and drop the "TutorialAssay_Run1.xlsx" into the target area.
  • The results fields will be inferred from your upload and shown in the panel. You could make adjustments if needed, but for this tutorial just accept all defaults.
    • Notice that the SampleID field from the example spreadsheet has been inferred to be of type "Sample" automatically. All assay results must map to samples, so if the system could not infer which field contained that mapping, you would have had to assign it yourself.
    • By default samples of any sample type (i.e. "All Samples") could be uploaded for this assay. If needed you could constrain the lookup to a specific sample type for this specific assay design.
    • For this tutorial accept the defaults.
  • Click Finish Creating Assay Design.

Now that your assay design has been created, you can use it to import the data from the same example spreadsheet.

Import Assay Data

The "TutorialAssay_Run1.xlsx" spreadsheet you already downloaded contains some "Tutorial Assay" data for some of the samples we created in the previous tutorial step.

You can confirm that the expected set of samples already exists by selecting Menu > Tutorial Samples and seeing that "Tutorial-003 through Tutorial-012" already exist. (Hint: Sort by Sample ID or use the to see the second page of samples.)

  • If you navigated away to check samples, reopen your Assay Design page by selecting Tutorial Assay from the main menu.
  • Click Import Data.
  • Enter Run Details:
    • Assay Id: Enter "Run1". If you leave this blank, a run name will be generated for you based on the assay design name and current day and time.
    • Comments are optional.
    • Workflow Task would let you link this run to a specific workflow task. Leave this blank for the tutorial.
    • Date: Enter "2019-10-01" or click the field to use the day/time date picker.
    • Instrument: Enter "INS-01"

Upload Results from File

  • In the Results panel, the Import Data from File tab will be preselected.
  • Drag and drop the "TutorialAssay_Run1.xlsx" file into the target area.
  • You will see the first three rows of the data file in the preview section.
  • Click Import.

You will see the grid of results. As for other grids, you can filter, search, and sort the result data.

Other Ways to Enter Results

The other tabs in the Import Data interface allow you to copy and paste data from a spreadsheet or enter values directly in a grid, individually or in bulk. Learn more in this topic:

Related Topics

Previous Step | Next Step (3 of 5)




Tutorial: Add Users and Assign Roles


Now that we have created some Samples and learned how to describe and import assay data, it's time to add some other users so we can understand how the workflow management tools work in Sample Manager. To do this, we will add a few fake users and assign them different roles. You must have administrator permissions yourself to complete the tasks in this step.

Add Users

  • To add one or more new users, select > Users.
  • On the User Management page, click Create.

In the popup:
  • Enter one or more email addresses, each on it's own line for each user you want to create.
    • For this tutorial, create users for
      team_lead@local.test
      lab_technician@local.test
      reviewer@local.test
  • Select the desired Role(s) for the users you are creating. For the tutorial, you can use only the default Reader, or add Storage Editor if you want to experiment with freezer storage actions.
  • Click Create Users.
You will see the new users added to the grid. In the green banner message, you can click the link to filter the grid to only the newly added users.

Assign Roles

Once users have been defined, an administrator can assign them one of the available permission levels, including but not limited to:

  • Readers: Have a read-only view of the application.
  • Editors: Have the Readers' access, and can also add new information and edit or delete data related to samples, assays, and jobs.
  • Administrators: Have full control over the application. This includes user management, permission assignments, storage actions, and creating and editing sample types, assays, and job templates.
  • Open > Permissions.
  • All of our fake users are currently in the Reader role.
  • Click the Editor role panel to open it.
  • Click the Add member... dropdown and select "team_lead".
    • Selected users will be shown in the panel for the role as you go.
  • Click Add member... again and select "lab_technician".
    • Each time you select a user, the details for that user will be shown on the right.
    • In the image below, the Editor role is being granted to the team lead and lab technician; all three fake users we added are still also members of the Reader role.
  • Click Save.

View Audit History

This is a good time to mention that all actions in Sample Manager are logged for later use and reference. The audit logs can be viewed from the > Audit Logs page, or by clicking View Audit History on other pages in the Administration section. This option is sometimes under the Manage menu. The log opens to the section most relevant to where you were when you opened it.

Learn more in this topic: Audit History

Related Topics

Previous Step | Next Step (4 of 5)




Tutorial: Outline Workflow


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

In this step of the tutorial, you will create a simple job and template, helping you understand how to use jobs, tasks, and templates to represent an efficient sample management workflow. Jobs can include a set of samples, direct links to the necessary assays, and notification mechanisms to ensure the right people know about actions that impact their work.

Create a Job with Selected Samples

  • Select "Tutorial Samples" from the Sample Types section of the main menu.
  • Click the button to open a filter panel.
    • Select SampleID (if it is not selected by default).
    • Select "Tutorial-018", "Tutorial-019" and "Tutorial-020". (A spreadsheet with some assay data for these specific samples is included below.) First clicking one label, then clicking the other two checkboxes is one quick way to accomplish this.
    • Click Apply.
  • Click the checkbox at the top of the column to select all three.
  • Select Start a New Job from the Jobs menu above the grid. On narrower browsers, this will be a section of the More menu.

Job Details and Priority

On the Details tab of the job creation wizard, enter general properties, assignments, priority, and upload any attachments needed:

  • Job Name: "Tutorial Workflow Job"
  • Description: "This is an example job with three tasks"
  • Job owner: Select "team lead" for this tutorial. This is the user who "owns" the overall job completion, not necessarily owns the tasks. Note that if you did not create the fake "team lead" user and assign them the role of "Editor" in the previous step, you won't be able to select them here and can just select yourself.
  • Notify these users: Add users who should get notifications as this job progresses. Select yourself here.
  • Job start and due dates: Use the date picker to select any begin and end dates you like for the job as a whole. Each task can have an individual due date as well.
  • Priority level: Select "Medium".
  • Attachments: For this tutorial, you can ignore this field. In practice, you could upload a protocol document, detailed instructions, label image file, or any other file attachment required for the job.

Define Job Tasks

Click the Tasks tab to define the tasks for this job.

Any job can be composed of several tasks to complete in sequence. You'll see an empty task when you first open the wizard. Click Add Task to add additional tasks.

For each task in your job, enter the necessary details:

  • Name
  • Description
  • Assign to: Select a user from the dropdown
  • Assays to perform: Select one or more assay here
  • Due date: For this specific task
For this tutorial create the following tasks, using Add Task to add the second two tasks, leaving other fields blank.
Task NameAssign toAssays to Perform (if any)
Prepare SamplesYourself 
Run Tutorial Assaylab technicianTutorial Assay
Review Resultsteam lead 

Assign Samples

Click the Input Samples tab to open it. You will see the samples you selected listed on the Included Samples tab.

Finish Creating Job

Click Finish Creating Job.

You will see the job overview. Note the tabs along the top edge for viewing Tasks, Samples, Assays, and Files in addition to the Overview.

Complete Job Tasks

Click the Sample Manager logo to return to the home page of the application. You will now see that the Jobs section has begun to grow. Your Job Queue includes the job you just created (because the first task is assigned to you).

Click the name of the job to open it. On the Overview page, you'll see summary information, including the list of tasks. The current task is assigned to you.

  • Click Complete Current Task to mark it as complete.
In the Status column, you'll now see that the second task, "Run Tutorial Assay" is now "In Progress".

The assay task is assigned to the "lab technician" but as an administrator you have the ability to complete any task in the system. Let's use that power here to illustrate assay data import from within the workflow system.

  • Click the Tasks tab to see more detail about the task. In this view, you have an Import Run link since the task involves importing data to the "Tutorial Assay".
  • Click Import Run.
  • Enter:
    • Assay Id: "Run2"
    • Notice that the Workflow Task field shows the currently selected job and task.
    • Date: Today's date (click the entry field to use the date picker)
    • Instrument: INS-01
  • Click Import Data from File.
  • Download this example data sheet: TutorialAssay_Run2.xlsx, then drop it into the upload window.
  • You'll see the data preview.
  • Click Import.
  • When complete, you'll see the imported data.

  • To return to the job details page, you can click the bolded word "here" in the green "Successfully created assay run" banner. For this tutorial, navigate as follows to see how task assignment changes your task queue.
    • Click the Sample Manager logo to return to the home page.
    • In the Jobs List, notice that the job is no longer shown in Your Job Queue because the current task is not assigned to you. To find the job, click Active Jobs.
    • Click the name Tutorial Workflow Job.
  • Click the Assays tab to see the data you just uploaded.
  • Click the Tasks tab to return to task details.
  • You can now click Complete Task to mark the lab technician's task complete.
  • Notice that the button changes to read Reactivate Task making it easy to correct accidentally marking a task as complete.

View Timeline

Each sample has a record of all activities that happen for it within the system. To see a timeline, select Sample Types > Tutorial Samples from the main menu and locate "Tutorial-020". Click the name to open details about that sample.

Click the Timeline tab to see the event timeline for this sample.

  • You'll see when it was created (registered), when it was added to the job, and when assay data was uploaded for it.
  • You're also shown the current status of the sample on the right, including who last handled it.
  • If you click an event, such as "Assay Data Loaded" you'll see an additional panel on the right which includes details including, in this case, a link to the run of data you uploaded.

Related Topics

Previous Step | Next Step (5 of 5)




Tutorial: Track Sample Sources


Sources help you track where your samples came from and trace common attributes across sets of samples from the same source. Sources can be:
  • Physical like labs, vendors, locations, studies, etc.
  • Biological like patients, mice, trees, cell lines, etc.
In this tutorial step, we create and populate two kinds of sources, "TutorialLabs" and "Creatures", then associate the tutorial samples we created earlier with some of each. After doing that, we will examine the kinds of detailed information that are available for samples including timeline and lineage.

Create a Source Type

Creating source types is very similar to the creation of sample types covered in the first step of this tutorial.

  • From the main menu, look under Source Types and click Create a source type.
    • Once source types have been created, click Source Types, then click Create Source Type.
  • Enter:
    • Name: Tutorial Labs
    • Delete the default Naming Pattern that is provided (and ignore the placeholder text). We will provide unique source names when we create them.
  • Click the Fields section to open it.
  • You'll see the Default System Fields for Sources (Name and Description). Click the to collapse this section.
  • Download this spreadsheet: TutorialLabSources.xlsx
  • Drop it in the upload area under Custom Fields.
  • You will see the inferred fields.
  • Notice the blue banner informing you that your file contained fields with reserved names which are not shown. This refers to the "SourceId" field that is present in the data file and cannot be "defined" again, though you will be able to populate it in the next step..
  • Click Finish Creating Source Type.

You can now select your new source from the Source Types section of the main menu.

Create Sources (Populate a Source Type)

  • Select your Tutorial Labs Source Type from the main menu, if you navigated away.
  • Select Add > Import from File.
  • Drag and drop the same "TutorialLabSources.xlsx" spreadsheet into the target area.
  • You'll see a preview of the first three lines.
  • Click Import to import the file and create these sources.

Create and Populate a Second Source Type

Follow the two sections above to create another source type to use for our tutorial samples, in this case a biological one.

  • From the page for the "Tutorial Labs" you just imported, click < Sources, then click Create Source Type.
  • Name this type "Creatures".
  • Delete the Naming Pattern.
  • Download and use this file for inferring the Fields: TutorialCreatures.xlsx
  • Click Finish Creating Source Type.
  • Select Add > Import from File.
  • Drag and drop the same "TutorialCreatures.xlsx" spreadsheet into the target area.
  • Click Import.

Now you have two Source Types and we can mark the Samples as having come from one or both types of source.

Associate Samples with Sources

When we originally created the "Tutorial Samples" type, we had not defined these sources, and did not include a way to reference them in the Sample Type definition.

We can now use these new Sources when using the Create Samples from Grid entry method for new samples, or by editing existing Samples either individually or in bulk. Learn more in this topic: Associate Samples with Sources.

For this tutorial, we want to add Source information to our existing Samples. To do so, we must modify the Sample Type design to identify the columns where we will import source information, i.e. the source aliases.

  • From the main menu, select the Tutorial Samples Sample Type.
  • Select Manage > Edit Sample Type Design.
  • Click Add Source Alias.
  • Enter the Source Alias "Lab", and select the Tutorial Labs Source Type.
  • Click Add Source Alias again.
  • Enter the Source Alias "Creature" and select the Creatures Source Type.
  • Click Finish Updating Tutorial Samples.

We now will update the samples we created earlier.

  • If any samples are currently selected, click Clear All.
  • Select Edit > Update from File.
  • Download this file: TutorialSamplesWithSources.xlsx then drop it into the target area.
  • You'll see a preview:
  • Note that if our spreadsheet included both existing samples to update and new samples to create, you'd need to select Create new samples too but for this tutorial, leave only the default selections.
  • You can enter a Reason for Update if desired or required.
  • Click Import.

The existing samples have now been updated with source information.

View Lineage

As an example, click the Tutorial-020 sample. Click the Lineage tab. You'll see a graphical representation of the creature and lab sources for this sample, as well as child samples 'derived' from it. Click the icon for either source to see more details about it in the panel to the right.

View Timeline

In the previous step, we saw how assay data import is included in the timeline for a sample, open the Timeline tab for the "Tutorial-020" sample to see that the update we just completed was also recorded for this sample. Clicking the timeline event populates the Event Details panel.

Learn more about the timeline here: Sample Timeline

Congratulations!

Now that you have learned to use Sample Manager with our tutorial content, you are ready to start loading your own data into the system. Learn more in the documentation for each area:

Previous Step




Release Notes: Sample Manager


LabKey Sample Manager makes it easy to manage samples, storage, data collection, and workflows in growing labs across all disciplines.

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 Customers.

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
  • 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, this is merely a terminology change. SM-VAL-24.10-C (docs)
  • When configuring BarTender, you must first save the URL prior to being able to test the connection. SM-VAL-24.10-D (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)
XXProfessional Edition Features:
  • 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)
XXProfessional Edition Features:
  • 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)
XXProfessional Edition Features:
  • 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 (resolved issue)
  • 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)
XXProfessional Edition Features:
  • 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.


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 issue)
  • Resolved an issue with uploading files during bulk editing of Sample data. (resolved issue)

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)
XXProfessional Edition Features:
  • 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

Note: Beginning with the February (24.2) release, Sample Manager will require stronger passwords. Users may be prompted to set a more complex password to align with security requirements when they log in.
  • 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)
XXProfessional Edition Features:
  • 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)
XXProfessional Edition Features:
  • 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. (learn more)

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)

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 on any Sample Type, you should rename it prior to upgrading to avoid loss of data in that field.

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)
  • 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)
  • 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

Release 21.8, August 2021

Release 21.7, July 2021

Release 21.6, June 2021

Release 21.5, May 2021

Release 21.4, April 2021

Release 21.3, March 2021

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

Release 20.10, October 2020

Release 20.9, September 2020

  • A new tutorial is available to help you get started with a new/empty instance of sample manager. Try it here: Tutorial: Learn Sample Manager
  • 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.




Sample Manager Dashboard


The home page of the Sample Manager application offers a summary dashboard for getting a quick overview of everything in the system. Return to this dashboard at any time by clicking the LabKey Sample Manager logo in the upper left corner of the page.

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)
The next menu lets you control subcategories for the insights you are viewing.

  • 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
Use the < and > buttons to step back and forth through these submenu options.

Learn more about samples in this section:

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:

Storage List

The Storage List presents a quick summary of your freezers and other storage units, showing details, available capacity, and a color-coded bar indicating the types of samples in each freezer.

  • Hover over the Legend to see which colors are associated with which sample types.
  • Hover over any bar segment for details about what it represents, and click to jump to the storage view of those samples in that storage.
Learn more about options available from the Storage List in this topic:

Main Menu

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

Header Menus

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

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:

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:

Related Topics




Folder Organization


This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.

Premium Feature — Available in the Professional Edition of Sample Manager and all Premium Editions of Biologics LIMS. Also available when Sample Manager is used with a Premium Edition of LabKey Server. Learn more or contact LabKey.

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

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

Note that there have been many improvements to the interface and user experience for working in Folders since the making of the video, including but not limited to the change from using "Project" to using "Folder" for data partitioning containers.

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.

Click Create 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:

Edit Folder

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

Delete Folder

To delete a folder, either:

  • Click it's name from the > Folders dashboard.
  • Click Delete Folder.

When a folder is deleted, all data contained in it will also be deleted. The administrator will see a warning detailing the folder's contents and need to confirm to proceed.

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:

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:

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




Cross-Folder Actions


This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.

Premium Feature — Available in the Professional Edition of Sample Manager and all Premium Editions of Biologics LIMS. Learn more or contact LabKey.

This topic covers the details about how the Sample Manager and Biologics LIMS products handle actions 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.

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.

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.
    • 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). Lookup and file fields are not editable when samples from multiple folders are selected.
  • 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.
From the grid, select the desired (eligible) rows, then select Edit > Move to 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 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

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 null Legend will give more detail about symbols and colors in the grid.

Related Topics




User Accounts, Groups, and Roles


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.

Related Topics:

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.
You will see the new user(s) added to the grid.

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.

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.
For either option, you will be asked to confirm that this is the action you want to take by clicking Yes, Deactivate in a popup.

Note that if you are using Sample Manager with a Premium Edition of LabKey Server, you may want to remove this user's access to the Sample Manager application by revoking all permission roles, instead of deactivating them completely from the system.

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.
You will be warned that deletion is permanent and need to click Yes, Permanently Delete to proceed.

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:

Related Topics




My Account


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.

If you are using an evaluation/trial version of Sample Manager, CAS authentication provides single sign on and will automatically log you back in. Choosing Sign Out will sign you out of the application and you can click Return to Application to log back in.

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:

Generate an API key from your Profile page.
  • Scroll down to the API Keys section.
  • Click Generate API Key to obtain one.
  • The new key will be shown in the window 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.

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. An administrator also has the ability to revoke API keys for other users if necessary.

Manage API Keys (Administrators)

In the API Keys section, administrators will see an additional blue banner with links to configure site settings, including whether API keys are enabled or disabled and when they expire. Admins can also click to manage keys for other users, including bulk deleting (revoking) API keys, such as when personnel leave the organization or permissions are changed.

Learn more here:

Related Topics

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




Permission 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

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.
  • 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, edit, and delete data related to storage 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.
    • 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.
Additional Permissions: The following roles do not include general "Reader" access, so should be assigned in conjunction with one of the above roles. Note that users with these roles cannot delete a Sample Type, Source Type, or Assay Design if there is data present for it.
  • 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.

A note about role-based permissions: Users can be assigned multiple roles in the system, either independently or via groups, and each is independent. If a user is both Editor and Reader, removing them from the Reader role will not in fact remove that user's ability to read information in the system, because they will still have that access via the Editor role.

Related Topics




Manage Groups


Managing user accounts by groups can make it more efficient to assign permissions, workflow tasks, and review of notebooks. In many organizations, the specific person assigned to complete a task is not known in advance, but work can be picked up by anyone on a given team.

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:

When using the Professional Edition, if you want to be able to assign notebook review to a group, that group must be granted the "Editor" role (or higher).

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




Manage 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.
For example, some events that trigger Workflow email notifications are:
  • 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




Sample Manager - FAQ


You can read a detailed overview of Sample Manager, LabKey's sample management software on our website. Other documentation here will help you better understand specific features and options.

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

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 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:

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:

Sample Manager also supports integration with BarTender for groups to use for printing labels with sample details. Learn more in these topics:

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:

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

More Questions?

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




Samples


For each different kind of sample you manage, you will create a Sample Type, which functions as a framework for representing the data describing that kind of sample. All Samples of that type can then be entered into the system for tracking and data analysis.

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

Topics

Tutorial

Get started with samples in the Sample Manager tutorial step: Tutorial: Add Samples.

Related Topics




Create a Sample Type


Sample Types help you organize samples in your lab and allow you to add fields that help you describe attributes of those samples for easy tracking of data. For example, "Blood" samples might have some different properties than "Serum" samples, so could be defined as two different types with different sets of fields.

This topic covers the details of creating and configuring sample types. For a tutorial to help you learn this process, see Tutorial: Add Samples.

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.

Before any Sample Types have been created, you can also use two quicker pathways: clicking the linked word here in the empty Dashboard Insights panel, or selecting Create a sample type from the main menu under Sample Types.

Note that you can only create Sample Types in the home (top-level) folder. If the creation button is missing, navigate first to the home folder.

Define Sample Type Properties

  • The Name of the Sample Type is required and must be unique.
    • 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.
  • To declare a field that will identify a parent sample, click Add Parent Alias. Enter the field name and select the Sample Type where the parent information will be found. It can be the current type or a different one.
  • If there are Sources defined in the system, you will have a similar option to Add Source Alias here.
  • 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.
Naming patterns will be validated before you can save your sample type. You will see a message if there are any syntax errors so that you can correct them. Learn more in this topic: Sample ID Naming

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.

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.
  • Display stored amount in (Required): Select the units in which you want stored amounts of this sample to be displayed. Options:
    • g (grams)
    • mg (milligrams)
    • kg (kilograms)
    • mL (milliliters)
    • uL (microliters)
    • l (liters)
    • unit (for cases where none of the other options are appropriate and each sample is a unit)

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 units set for the Sample Type in general.
  • Aliquots Created Count (AliquotCount)
  • Freeze/Thaw Count (FreezeThawCount)
  • Storage Location, Row, and Column
While you do not add and cannot remove or change these columns, you can choose which are enabled for this Sample Type using the checkboxes on the left, with the exception of Name and SampleState. For example, if you don't need to see and record expiration dates for a given Sample Type, you can uncheck that 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:

  • Click the Fields section to reopen it if needed.
  • You can collapse the Default System Fields section to hide it.

There are options for adding Custom Fields:

Import or Infer Custom Fields from File

The default is Import or infer fields from file:

You can select or drag a spreadsheet containing your data into the upload panel.

  • This will populate the fields section based on inferrals from the data.
  • Note: If your spreadsheet contains columns for built-in fields, such as "SampleID" and "Description", they will not be shown here.
  • You can also import field definitions from a prepared JSON file if you have one.

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.

Learn about attaching images and other files using a File field in this topic:

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:

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:

After creating a new Sample Type, you will see it listed on the main header menu and be able to begin creating samples of this type.

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.

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, click Finish Updating Sample Type 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.

DescriptionExample SampleIDsNaming Pattern
The character 'S' followed by a counter (Default)
(always unique within this type of sample)
S-1
S-2
S-3
S-${genId}
The word 'Blood' followed by a 2 digit counterBlood-01
Blood-02
Blood-03
Blood-${genId:number('00')}
The value of the "Lab" column + '_' + a counterLabA_1
LabB_2
LabC_3
${Lab}_${genId}
Use a default value if the "Lab" column is empty (+ '_' + a counter)LabA_1
LabB_2
LabUnknown_3
${Lab:defaultValue('LabUnknown')}_${genId}
'S' plus current date followed by a counter that resets daily
(always unique; tracks date of entry into system)
S-20200204-1
S-20200204-2
S-20200205-1
S-${now:date}-${dailySampleCount}
'S' plus values from two columns in my data: the Study and ParticipantID
(only unique if one sample per participant)
S-Study101-pt231
S-Study101-pt232
S-Study101-pt233
S-${Study}-${ParticipantId}
Values of "ParticipantID" and "Draw Date" columns, then a counter
(always unique and tracks draw date, not date of entry into system)
pt231-20191203-1
pt231-20191214-2
pt231-20191214-3
${ParticipantID}-${DrawDate}-${genId}
The values already present in the "SampleID" column in my dataunique
values
provided
No naming pattern required
The values already present in the "Identifier" column in my dataunique
values
provided
${Identifier}

Learn more about building naming patterns in this topic:

Related Topics




Add Samples


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.

For a tutorial walkthrough of adding samples to the system, see this topic: Tutorial: Add Samples

Note: Once you have added some samples, you can select one or more before clicking More and then selecting one of the Derive options:
  • Aliquot the Selected Sample(s)
  • Derive from Selected
  • Pool Selected
Learn about these options in the topic: Aliquots, Derivatives, and Sample Pooling.

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:

Note that fields of type File are not included in either import method. Values for these fields must be individually added as described in this topic: Attach Images and Other Files.

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 creation, you can assign the Amount of that Sample, with Units. Previously these values were provided and tracked when the Samples were in storage.

The column providing the amount can be named either "Amount" or "Stored Amount". If the units value provided is different from the units value set for the Sample Type, the amount will be converted to those units for display. For example, if your Sample Type is set to display values in mL, and you enter an amount of 1 L, you'll see 1000mL displayed. Learn more about display values for amounts and units here.

Whether a Sample is or is not in 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.

Work with New Samples

After creating samples, the banner message indicating 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:

Learn more about options for working with samples here:

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:

Related Topics




Create Samples from Grid


When creating new Samples, the Add Manually option gives you several options for entering sample information in 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.

Note that fields of type File are not included in grid import methods. Values must be individually added as described in this topic: Attach Images and Other Files.

Create Samples From Grid

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 on the home page or the Sample Types dashboard, choose the desired Sample Type from the dropdown.

The entry grid will contain a column for each built-in and custom property in the Sample Type, as well as a prepopulated parent or source column for any import aliases the type includes. The alias name will not be used, but there will be a column for including the parents of the same type.

Add Parent (Optional)

If the Sample Type has one or more Parent samples, you will see a prepopulated parent field. To add more, click Add Parent. 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 X next to "Remove Parent #" on the right.

Add Source (Optional)

If the Sample Type has one or more Sources, you will see a prepopulated source field. Click Add Source to add additional columns for each Source Type you will associate with samples of this type. Select the Source Type from the dropdown.

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 X next to "Remove Source #" on the right.

Add Samples Individually

To directly create samples in a grid, start by adding a blank row for each samples you want to create. Enter the number of samples and click Add Samples.

A grid with the requested number of rows will be created, with 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 aliases, there will be columns for the Sample or Source Types of these aliases included by default.
  • Enter values for remaining fields using the guidance in this topic
  • When ready, click Finish Creating # Samples. The number you are creating will appear on the button.
You will see the sample grid for that type, with a banner message indicating how many were created and offering actions for working with them.

Reopen to add more samples by selecting Add > Add manually.

Bulk Insert

Instead of directly populating a grid, you can click Bulk Insert 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.
  • Enter values for any or all of the properties listed.
  • Click Add Samples To Grid.
You will see the samples in the same grid as if you had created them individually, with the shared values. If necessary, you can further edit the property settings in the grid (directly or using bulk update, before clicking Finish Creating # Samples.

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 Insert, 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.

Bulk Update

While creating new samples in the grid, you can use the Bulk Update 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




Import Samples from File


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.

Note that fields of type File are not included in file import methods. Values must be individually added as described in this topic: Attach Images and Other Files.

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 import 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:
  • 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.
You will see the sample grid for that type, with a banner message indicating how many were created and offering actions for working with them.

Additional examples and details are available here:

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.
New storage locations are created in the background during the import, and the user will see a notification when the import completes. If the import and creation of samples fails for any reason, the new storage locations will not be created.

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.
    • 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.
Just as for importing new samples from file, you can make use of import templates to know which fields you want to update. You might start from an existing grid of samples, make adjustments offline and/or add new samples to it, and then Edit > Update from File by first downloading the update template, merging your data to fit, then importing. Be sure to remove all columns you don't plan to update.

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




Sample ID Naming


Each Sample and Source in the system must have a unique name/id within its type. The unique names can be provided by the user, or can be generated by the system. When you ask the system to generate names, you specify a Naming Pattern to use. For each type, you will choose one of these two options. If you already use a unique naming structure outside the system, you will want to ensure those names are carried in to LabKey Sample Manager.

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.
In this example, samples added on November 25, 2019 would be "S-20191125-1, S-20191125-2, etc.". Samples added on November 30 would be "S-20191130-1, S-20191130-2, etc."

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.
For example, to include source metadata (e.g. my blood sample was derived from this mouse, I would like to put the mouse strain in my sample name), the derived sample's naming expression might look like:
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 Grandparent Names/Properties Using ".."

The above lineage lookup syntax applies to parent or source details, i.e. the immediate "parent" generation. In order to incorporate lookups into the "Grandparent" of a sample, use the ".." syntax to indicate "walking up" the lineage tree. Here are a few examples of syntax for retrieving names from deeper 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 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}

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.

Naming Pattern Elements/Tokens

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

Name ElementDescriptionScope0000000000000000000000000
genIdAn incrementing number starting from 1. This counter is specific to the individual Sample Type in a given container. Not guaranteed to be continuous.Current Sample Type
sampleCountA counter incrementing for all samples of all Sample Types, including aliquots. Not guaranteed to be continuous. Learn more below.All Sample Types in the application (home plus any folders)
rootSampleCountA counter incrementing for non-aliquot samples of all Sample Types. Not guaranteed to be continuous. Learn more below.All Sample Types in the application (home plus any folders)
dailySampleCountAn incrementing counter, starting with the integer '1', that resets each day. Can be used standalone or as a modifier.All Sample Types and Source Types on the site
weeklySampleCountAn incrementing counter, starting with the integer '1', that resets each week. Can be used standalone or as a modifier.All Sample Types and Source Types on the site
monthlySampleCountAn incrementing counter, starting with the integer '1', that resets each month. Can be used standalone or as a modifier.All Sample Types and Source Types on the site
yearlySampleCountAn incrementing counter, starting with the integer '1', that resets each year. Can be used standalone or as a modifier.All Sample Types and Source Types on the site
randomIdA four digit random number for each sample row. Note that these random numbers are not guaranteed to be unique.Current Sample Type
batchRandomIdA four digit random number applied to the entire set of incoming sample records. On each import event, this random batch number will be regenerated.Current Sample Type
nowThe current date, which you can format using string formatters.Current Sample Type
InputsA collection of all DataInputs and MaterialInputs for the current sample. You can concatenate using one or more values from the collection.Current Sample Type
DataInputsA collection of all DataInputs for the current sample. You can concatenate using one or more values from the collection.Current Sample Type
MaterialInputsA collection of all MaterialInputs for the current sample. You can concatenate using one or more values from the collection.Current Sample Type
<SomeDataColumn>Loads data from some field in the data being imported. For example, if the data being imported has a column named "ParticipantID", use the element/token "${ParticipantID}"Current Sample Type

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:

Sample/AliquotNamevalue of the sampleCount token
sampleBlood-10001000
aliquotBlood-1000-11001
aliquotBlood-1000-21002
sampleDNA-10031003
aliquotDNA-1003-11004
sampleBlood-10051005

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:

Sample/AliquotName
sampleBlood-1000
aliquotBlood-1001
aliquotBlood-1002
sampleDNA-1003
aliquotDNA-1004
sampleBlood-1005

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.
Administrators can see the current value of the sampleCount 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.

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:

Sample/AliquotNamevalue of rootSampleCountvalue of sampleCount
sampleBlood-100100100
aliquotBlood-100-1100101
aliquotBlood-100-2100102
sampleDNA-101101103
aliquotDNA-101-1101104
sampleBlood-102102105

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
All of these counters can be used in either of the following ways:
  • 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.
Do not use both "styles" of date based counter in a single naming expression. While doing so may pass the name validation step, such patterns will not successfully generate sample names.

: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:

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.
Once a valid naming pattern is defined, users creating new samples or aliquots will be able to see an Example name in a tooltip both when viewing the sample type details page (as shown above) and when creating new samples in a grid within the Sample Manager and Biologics applications.

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

Naming PatternExample OutputDescription
S-${genId}S-101
S-102
S-103
S-104
S- + a simple sequence
${Lab:defaultValue('Unknown')}_${genId}Hanson_1
Hanson_2
Krouse_3
Unknown_4
The originating Lab + a simple sequence. If the Lab value is null, then use the string 'Unknown'.
S-${now:date}-${dailySampleCount}S-20170202-1
S-20170202-2
S-20170202-3
S-20170202-4
S- + the current date + "-" + daily resetting incrementing integer
S-${Column1}-${Column2}S-Plasma-P1
S-Plasma-P2
Create an id from the letter 'S' and two values from the current row of data, separated by dashes.

Example String Modifiers

The following naming patterns show usage of string modifiers.

Naming Pattern00000000000000000000000000000000000000000000000Example Output000000000000000000Description
S-${Column1}-${now:date}-${batchRandomId}S-Blood-20170103-9001 
S-${Column1:suffix('-')}${Column2:suffix('-')}${batchRandomId}S-Blood-PT101-5862 
${Column1:defaultValue('S')}-${now:date('yy-MM-dd')}-${randomId}Blood-17-01-03-2370
S-17-01-03-1166
${Column1:defaultValue('S')} means 'Use the value of Column1, but if that is null, then use the default: the letter S'
${DataInputs:first:defaultValue('S')}-${Column1}Nucleotide1-5
S-6
${DataInputs:first:defaultValue('S')} means 'Use the first DataInput value, but if that is null, use the default: the letter S'
${DataInputs:join('_'):defaultValue('S')}-${Column1}Nucleotide1_Nucleotide2-1${DataInputs:join('_'):defaultValue('S')} means 'Join together all of the DataInputs separated by undescores, but if that is null, then use the default: the letter S'

Related Topics




ID and Name Settings


Administrators can configure some elements of how IDs/Names are generated from the > Application Settings menu.

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 Lineage / Parentage


This topic describes how to define and explore sample lineage and parentage among samples.

Add Parent Alias

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. Setting a parent alias in the definition of a Sample Type creates the linkage to parent samples during import, but note that the column aliased 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 samples like the following, where v1 has two 'children', v1.1 and v1.2:

SampleIDMyParent
v1 
v1.1v1
v1.2v1

...you could indicate the parent column alias "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 alias:
    • During initial Sample Type creation.
    • After creation by reopening the type for editing via Manage > Edit Sample Type Details.
  • Click Add Parent Alias.
  • Enter an alias for import: Name the column containing parentage information that will be in the file. The column name is case sensitive.
  • Select a sample type...: Select the Sample Type where the parent resides. This may be in the "(Current Sample Type)" or another one that has been defined.
  • You can add additional parentage columns if applicable by clicking Add Parent Alias and repeating the process.
  • Click Save.

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

Define Lineage When Creating Samples

When creating samples of this type, include parent information in one of the aliased columns. When you use a template to import from file columns for all parent aliases 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 column name from your alias will not be shown in the UI. Instead it will be named for the selected sample type plus the word "Parents", i.e. "Blood 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.

Add Source Alias

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

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

Give the name of the source alias column and select the source type from the dropdown, as for parent samples. 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.

Learn more about sources in this section:

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:

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 Create Samples > [Name of Sample Type].
  • Add the desired number of samples by entering the number and clicking 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.

  • Select the Sample Type of interest from the main menu.
  • Select Add > Import from File.
  • Click Template to download the template of fields.
  • Populate the spreadsheet as needed to indicate the intended relationships, then import it to create the new samples.

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: Aliquots, Derivatives, and Sample Pooling

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:

Sample Type: PBMC
Parent TypeParent FieldLabelPosition
Blood (a Sample Type)Draw DateBlood Draw Dateright of Processing Operator
Mice (a Source Type)StrainMouse Strainright of Blood Draw Date

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




Aliquots, Derivatives, and Sample Pooling


New samples can be created from existing samples in three distinct ways:
  • 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.
This topic describes the mechanisms and options for creating these new samples from existing samples:

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.

Derive from Selected Samples

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

  • Add the desired number of "Derivatives per parent" by entering the number and clicking 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, add the desired number of New samples per parent group by entering the number and clicking 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 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 will see the following calculated columns related to aliquots. Both of 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. Includes any aliquot 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.
Like other columns, you can use a custom grid view to show, hide, or relocate them in the grid as desired.

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.

  • Select the Sample Type of interest from the main menu.
  • Select Add > Import from File.
  • Click Template to download the template of fields.
  • Populate the spreadsheet as needed to indicate the intended relationships. Key details follow.
  • Drop the completed spreadsheet into the upload window, then click Import.

Aliquots

Populate the AliquotedFrom column with the Sample ID of the parent Sample. To create 3 aliquots of sample "S-001" for example:

SampleID...Other columns...AliquotedFrom
[generated ID]...Other values...S-001
[generated ID]...Other values...S-001
[generated ID]...Other values...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

Populate the columns defined as parent aliases with the Sample IDs of the parent(s). For example, to create two derivatives of two parent samples, where IDs will be generated and the parent alias column is named "ParentSample":
SampleID...Other columns...ParentSample
[generated ID]...Other values...S-001
[generated ID]...Other values...S-001
[generated ID]...Other values...S-002
[generated ID]...Other values...S-002

Pooled Samples

Similar to the above, populate the columns defined as parent aliases with the Sample IDs of the parents. For example, to create two pooled samples from two parent samples:
SampleID...Other columns...ParentSample
[generated ID]...Other values...S-001, S-002
[generated ID]...Other values...S-001, S-002

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 Expiration


All Sample Types have a built in system field for recording Expiration Dates. This information can be used to assist lab managers in managing materials in their lab by finding samples due to expire soon. In addition, tracking samples with low aliquot counts can help determine when additional supplies may need to be ordered.

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.

Edit this report if you want to change the time interval, such as to find samples expiring in the next month. You can save a revised report with a new name.

Related Topics




Sample Timeline


Events that happen to individual samples are available on the Sample Timeline. You can view them in a graphical format which records the full history for an individual sample in your system.

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?
While the main audit log tracks all events occuring in the system, the sample timeline is useful for isolating events of different types happening to a single sample.

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:

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
Use the dropdown to filter by user, and date selectors to show a portion of the timeline for a range of dates of interest. Click Apply to apply filters and Clear to clear existing ones.

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




Manage Samples


This topic covers the management of samples and types of samples within the Sample Manager application.

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:

The grid of all Sample Types below lists the name, description, and other details about each type of sample in the system. You can also download a template for easier import of data from files.

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 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.
  • 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.
Learn more about sample grid menus and buttons in this topic:

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:

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:

Note that some Sample Statuses, including "Locked", prevent samples from being moved.

Related Topics




Manage Sample Status


This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.

Samples often get categorized as scientists are tracking them. By defining and using Sample Status values, your users can easily tell whether samples are available, consumed, or locked (unavailable). Aliquots have status values separate from their parent sample.

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.

Manage Sample Statuses

The Sample Manager application has 3 built-in status types, also represented by assignable statuses:

  • Available: Can be used. 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.
  • Locked: While locked, 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.
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
Aliquots have status values separate from their parent sample.

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




Edit Selected Samples


This topic describes how to edit the details and lineage for multiple samples either in a grid or with bulk setting of chosen fields.

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:

You can also bulk edit samples using the Edit > Update from File option.

Edit in Grid

When using the grid editor, there are three tabs available with grids of details. Learn more about options for editing data in grids in this topic:

Sample Data: Enter new values for the selected samples.
  • 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.

Storage Details: Storage Editors can edit the freeze/thaw count for any selected samples that are currently in storage.

Lineage Details: Edit the sources and parent samples 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.
  • Note that lineage for aliquots cannot be changed after they are created. Rows for any selected aliquots will be grayed out here.
  • 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 grid.
When finished editing, provide a Reason for Update if desired or required. Click Finish Updating # Samples

Edit in Bulk

Sample details 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 or storage information in the grid editor. Provide a Reason for Update if desired or required.

Click Update Samples when finished editing.

Edit Sources

When you Edit Sources for selected samples, any values provided will replace the existing sources of the chosen type(s) for the selected samples. Do not provide values for any source type that you want to remain unchanged for the selected samples.

In this action you will not see the current source values for the selected samples; use the grid editor to see those details as you edit.

  • Select the Source Type 1 that you want to replace for the selected samples.
  • Select the Source ID to assign to the selected samples.
    • Note that if you leave this selection blank, it will remove any current values for that type of source.

To provide a new value for another type of source, click Add Source and repeat the selection process for Source Type 2.

Provide a Reason for Update if desired or required and click Update Sources when finished.

Note that lineage for Aliquots cannot be changed. If any aliquots are selected for a bulk edit of Sources, they will be ignored.

Edit Parents

When you Edit Parents for selected samples, any values provided will replace the existing parents of the chosen type(s) for the selected samples. Do not provide values for any parent type that you want to remain unchanged for the selected samples.

In this action you will not see the current parent values for the selected samples; use the grid editor to see those details as you edit.

  • Select the Parent Type 1 that you want to replace for the selected samples.
  • Select the Parent ID to assign to the selected samples.
    • Note that if you leave this selection blank, it will remove any current values for that type of parent.
    • To choose multiple parents of the same type, select one, then click elsewhere in the entry box to reopen the selection menu.

To provide a new value for another Parent Type, click Add Parent and repeat the selection process for Parent Type 2

Click Update Parents when finished.

Note that lineage for Aliquots cannot be changed. If any aliquots are selected for a bulk edit of Parents, they will be ignored.

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




Sample Finder


This topic describes how to find samples in bulk using sample properties, attributes of their parents or sources, or in the Professional Edition, based on related assay results. The Sample Finder helps you build a set of criteria to find samples of interest across all the Sample Types in your system. For example, you might want to find all samples of different types from a specific source or lab, or see if you have enough samples in the system from male, BALB/c mice to perform a given experiment.

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.

If instead you want to search for samples in bulk by barcode or sample ID, follow the instructions in this topic: Sample Search.

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.
As the set of criteria tiles grows, you can scroll to see them all above the results. You can save your current search criteria at any time for later reuse.

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:

Actions available on the Sample Finder results vary based on user permissions, but include actions available on other kinds of sample grids for the same user, such as:
  • 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
  • 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




Built-in Sample Reports


Built in reports make it easy to use the Sample Finder to keep track of expiration dates, for prioritizing the soon-expiring sample stock, and for monitoring samples with low aliquot counts, which could indicate the need to reorder materials.

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

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:

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 Search


This topic describes how to search for Samples in bulk using either: You can enter a list via cut and paste, or via integration with a barcode scanner. Once found, you can act on the set of search results as a group.

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

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




Print Labels with BarTender


Premium Feature — Available with LabKey Sample Manager and Biologics LIMS. Learn more or contact LabKey.

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.

Configuration steps and management of label templates:

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.
The labels will be sent to the web service.

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.

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


This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.

Premium Feature — Available with LabKey Sample Manager and Biologics LIMS. Learn more or contact LabKey.

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.

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.

Include Print Portal

When you install BarTender, be sure to select Specify advanced installation options, then select the BarTender with Print Portal option. (It is included by default in version 2019.) To add Print Portal to an existing installation of BarTender, re-open the original installer file, select Modify, and select BarTender with Print Portal.

Enable HTTPS Endpoint for BarTender

Current versions of BarTender do not natively support the HTTPS secure endpoint. Until BarTender is able to provide this support, you must use a self-signed certificate and complete these additional steps in your BarTender installation:

  • Install and set up the BarTender Print Portal web application from the exe/msi installer.
  • Set up the BarTender Print Portal with HTTPS in IIS 7. This guide provides step-by-step instructions, including obtaining the certificate and configuring the SSL port:
  • (Optional) Enable HTTPS in Print Portal under the administrative setup->security->enable authentication over HTTPS
    • This just verifies that SSL is set up, but is otherwise optional since we aren't doing any authentication.
  • Set up your web service integration in Integration Builder and deploy it as usual.
    • Key step: Deploy the Integration service on port 80, instead of a custom port.
    • This is a stock file that just needs deployment via the BarTender tooling
  • Set up the Label template folder location(s) in the Administration console.
  • The BarTender portal service URL is then:
    https://<your host>/Integration/<integration service name>/Execute
    • For versions prior to BarTender 2021, use this URL:
      https://<your host>/BarTender/API/Integration/<integration service name>/execute
Additionally, in BarTender 2021 and 2022, https requests to the BarTender API are disabled by default. This creates an issue with LabKey Server, since it requires an https connection. A workaround is available by following the instructions below, specifically enabling the "Passthrough" functionality of the BarTender Print Portal:

1. First following these steps: Turning on Integration Passthrough

2. Use this BarTender URL in LabKey:

https://<BarTender host>/BarTender/API/IntegrationServicePassthrough?targetURL=<service URL>

Example BarTender Configuration File

Download this example to help you get started with BarTender 2021 or 2022:

For versions prior to BarTender 2021, use this example: Once deployed using the BarTender deployment wizard, the LabKey application would access at the following location (unless you edit the service name):

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.

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




Barcode Fields


This topic covers options for using barcode values with your samples. Existing barcode values in your data can be represented in a text or integer field, or you can have Sample Manager generate unique barcode identifiers by using a UniqueID field. LabKey-generated barcodes are read-only and unique across your Sample Manager application.

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

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:

Related Topics




Sample Picklists


Samples may be added to user-defined Picklists that facilitate operations on groups of samples such as adding or removing from a freezer, adding to a workflow job, or performing bulk operations. You can add samples to picklists from many places in the application, and create new ones as needed on the fly. Shared Picklists can be shared with others on your team.

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.

Note that picklists are intended as a temporary grouping to support actions like including in a more persistent workflow job or freezer storage. Addition to picklists is not tracked as a timeline action for a sample.

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.
To delete a picklist, select it here and click Delete.

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.
Select one or more samples to: On the tabs for individual Sample Types, you'll see the type-specific fields, and have more options for editing and deriving new samples. Learn more in this topic:

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
Note that if you are using Sample Manager within a Premium Edition of LabKey Server, you can export most Sample Manager resources as part of a folder export, but picklists are not included in these folder archive exports.

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




Sources


A sample can be mapped to one or more Sources, for example:
  • Physical Sources like labs, vendors, locations, studies, etc.
  • Biological Sources like patients, mice, trees, cell lines, etc.
Tracking the sources of a sample can help lab managers understand the broader picture of the data in the system.

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

Tutorial

Get started with sources in the Sample Manager tutorial step: Tutorial: Track Sample Sources.




Create Sources


This topic covers the creation of Source Types that describe the kinds of entities from which your samples are derived or other logical "sources" of samples. It also covers import of data to these types, i.e. creation of the individual Sources. Creating and populating Source Types is very similar to the process used for sample types and samples, with the exception that sources do not have the option to include parent sources. If you would like a tutorial walkthrough of this process, complete the last step of the Tutorial.

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'. You can edit the Source Type to change this name later; the SourceIDs/Names of existing sources will not change.
  • 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.
  • If you want to include lineage relationships (parent sources) for this type of source, and want to be able to import them from spreadsheets, click Add Parent Source Alias
  • 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}
You can change the string in this default pattern to disambiguate the sources and make their types more clear to users; for example, a 'Creatures' source could use the pattern "Creature-${genId}" and have names like "Creature-1, Creature-2, etc."

Add Parent Source Alias

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 Alias for your Source Type, giving you a column name to include when uploading parents of the selected source type.

Shown above, if your "Subjects" spreadsheet includes a column named "ParentStudy", you can use it to provide the source ID for the study source of each subject.

Add Sources

Once you have created the Source Type, populate it with the individual sources. This process is very similar to the process of creating samples.

Note that fields of type Attachment are not included in any grid or file import methods. Values must be individually added for each Source as described in this topic: Attach Images and Other Files.

Start from the desired Source Type by clicking it's name on the main menu or Source Types page. You may want to obtain the Template to assist you in formatting your data. Use the Add menu, or you can also use the Add Sources menu on the Source Types page to open either import option, in which case you will first select the desired Source Type. Select either:

Shown here we add 3 source 'creatures' directly in a grid. Notice that you could add a column for providing a source parent by using the Add Source Parent button. If there are any source aliases, source parent columns will be provided by default.

Click Finish Creating # Sources when ready (the number will appear on the button).

You will see a banner message with the number of new sources created and the option to click to select them in the grid.

These sources are now available for associating with samples.

Update or Merge Sources from File

Using the Add > Import from File option will only create new sources. If there is data for any existing Source IDs, the import will fail.

To update existing sources, or import a spreadsheet merging existing sources and adding new ones, use Edit > Update from File.

The Update Options selection can be either:

  • Only update existing sources: (Default) Update only. Any new sources will cause the import to fail.
  • Create new sources too: Merge. Both existing and new sources can be included.
Only the fields that are changing in the existing Source IDs should be included in the upload. If you provide any column in the file with empty values, it will cause any existing data in those fields to be removed.

Users can provide a Reason for Update if desired or required before clicking Import.

Related Topics




Associate Samples with Sources


Once source types and sources have been created, individual samples can be associated with them. This topic describes how to make those associations. For a hands-on walkthrough of this process, complete the Tutorial: Learn Sample Manager.

Associate Samples with Sources During Sample Creation

When you create new samples, you will see an Add Source button in the creation wizard if any source types have been created in the system. If the Sample Type you are adding has any source aliases, source columns for them will be added by default.

Note that if no source types have been created yet, you will not see this button in the user interface.

To add a source for the samples you are creating, click Add Source. Select the source type from which the source will be selected.

When you add a source, a new column is added for the new "parents" (i.e. Sources) of the samples you are creating.

If more than one type of source is defined in the system, the Add Source button will remain enabled so that you can add as many types of source as needed. For example, you might have both a biological source organism, and a physical source lab.

Populate the grid as when creating samples, making use of the bulk insert and update options if appropriate. When you start typing into the source parent field (labelled "Creature Parents" in the above), it will filter a listing of all sources of that type from which you can select one or more.

When ready, click Finish Creating Samples as before.

Create Samples from Sources

You can also create, or derive, new samples from selected sources starting from the source grid. This process is very similar to creating new samples from other "parent" samples, and the same terminology is used in the popup panel.

Open the grid listing the Sources, then select one or more to use as "parent(s)" of the new samples. Select Create Samples > [Sample Type Name]. (Note that if you select more than 1000 rows, the option to create samples is disabled.)

You can also go to the overview page for the specific source "parent" you want to use and select > Create Samples > [Sample Type Name].

In the popup, enter the number of New samples per parent to create, then click Go to Sample Creation Grid. You'll see the grid prepopulated with rows showing the associated source(s). For each source you selected, you'll have the specified number of rows. Continue to edit sample details in the grid before finishing creation.

View Source Association

Click the name of one of the newly created samples to open the overview page for that sample.

Scroll down and notice that the Source Details section has been populated with details about the source(s) you linked when you created it.

View Source Lineage

Click the Lineage tab to see that the source is also represented in the lineage grid. Click the node for the source to see if there are other samples derived from that specific source.

Associate Existing Samples with Sources

If you create new sources after creating samples, you can add the association from the sample details page. In the next section, see how to edit existing source associations.

Open a sample type using the main menu, then an individual sample by clicking the Sample ID. You will see the Source Details (if any). Click the icon to edit the source associations for this sample.

This will open an editor panel similar to that in the sample creation wizard. Select the Source Type you want to associate.

This will add an entry box for Source IDs. Click to select from the menu; type ahead to narrow the choices. You can select more than one source ID for this field.

Note that if more than one source type is defined in the system, the Add Source button would remain activated allowing you to add sources of different types for the sample.

Click Save when finished.

You can now view the details and lineage for this sample and it's source(s) as described above.

Edit/Remove Source Associations

Open a sample type using the main menu, then an individual sample by clicking the Sample ID. Use the same icon to edit existing source associations in the Source Details section.

  • Use dropdowns for Source IDs to add new sources of the types that are already associated.
  • Click 'X' to delete individual sources or remove all sources of a given type
  • Click Add Source to add new sources of another type.

Related Topics




Manage Sources


This topic covers the administration and management of Sources you have defined.

View all Source Types

The top level menu lists the name of source types that are defined in the system. Click Source Types to see the full listing:

You'll see the name and description of each source type, as well as the number of sources that have been created. Click to download a Template for any source type to make importing data from a file easier.

Manage a Source Type

Click the name of a Source Type to manage that particular type. You can use the grid view or the top menu to switch which source page you are viewing. Use the Manage menu to select:

  • Edit Source Type Design: Reopen the source type creation wizard to change details or fields. Note that you changes to the design of the source type will not be 'propagated' to change the name of any existing sources.
  • Delete Source Type: Delete this type of source completely. This will delete the type, all sources of this type, and all dependencies. Deletion cannot be undone. You can enter the Reason for Deleting if required or desired.
  • View Audit History: See the history of actions on this source type.

The grid of Sources of this type is shown below. Filter sort and use the available menus to:

  • Add new sources of this type.
  • Edit or delete one or more sources, or update from file.
  • Create Samples using any selected source row(s) as parent(s).
  • Reports: Select one or more sources, then choose Find Derivatives in Sample Finder to open the Sample Finder showing all the samples created from any selected source(s). Any filters on the grid are also included in the Sample Finder.

Source Type Details

Hover over the Details link to see the naming pattern and any aliases defined for this source type.

Manage a Single Source

Click the Source ID to see details for a particular source.

  • In the top panel you will see all the Samples generated from this specific source.
  • Below, a panel lists all the details and offers authorized users an edit link.
  • If this Source is referenced in any Notebooks, you'll see links to them here.
  • In the Source Parent Details you'll see, and can edit, any lineage this source has, i.e. parent sources of the same or other type(s).
  • Tabs along the top row let you click for all the Lineage, Samples, Assays, and Jobs that involve this source.

You can also create new samples associated with this source directly from the overview tab by selecting Manage > Create Samples. To associate existing samples with this source, see this topic: Associate Samples with Sources.

View Lineage, Samples, Assays, and Jobs

Use the Overview, Lineage, Samples, Assays, and Jobs tabs for a source to see the other information associated with this particular source.

Lineage: See the lineage of both parent sources (if any) and derived/child samples associated with this source. Learn more about browsing lineage graphs and grids here.

Samples: This tab lists the direct children, grandchildren, and further descendants from this source, including any aliquots. Learn more below.

Assays: On the Assay tab, the data you see is what has been uploaded for any samples associated with this source.

Jobs: See workflow jobs associated with samples from this source.

Samples Created from this Source

On the Samples tab for a given source, you will see all samples (up to a maximum of 5 generations) associated with this source, including any aliquots of those samples. The All Samples tab shows samples of every type, with properties common to any sample, like storage information and status. Samples of each individual type can also be viewed on a separate tab, with the properties specific to that type.

When viewing the tab containing samples of all types, many sample grid menus and actions are available. When viewing samples on a sample-type specific tab, additional menus for editing and deriving new samples are available.

Edit Sources

Edit Single Source

You can edit the details of a single source by clicking the Source ID and clicking the edit icon.

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

Edit Multiple Sources

You can bulk edit several sources at once by selecting them in the source type view and selecting either:

Users can provide a Reason for Update if desired or required before clicking Finish Updating ## Sources.

Update from File

Use Edit > Update from file to update source information in bulk. You can select to either:
  • Only update existing sources (update)
  • Create new sources too (merge)

Users can provide a Reason for Update if desired or required before clicking Import.

Edit Source Parents

You can edit the parents of sources on the Lineage Details of the Edit in Grid interface.

From the listing of Sources, you can also choose Edit > Edit Source Parents to bulk edit a selected group of Sources. Choose the Source Parent Type, then select specific sources of that type that will be replace any existing parent sources of that type.

Delete Sources

A Source cannot be deleted if it has descendants, i.e. any samples associated with it (or derived from it). You also cannot delete a source that is referenced from an Electronic Lab Notebook. Deleting a source cannot be undone.

Delete a Single Source

You can delete a single source from it's details page by selecting Manage > Delete Source.

  • In the popup, enter the Reason for Deleting if required or desired.
  • Confirm the deletion by clicking Yes, Delete.
If the source has descendants or is referenced from a notebook, this menu option will not be activated, as shown below.

Delete Multiple Sources

Multiple sources that do not have descendants can be deleted directly from the source type page by selecting the desired sources and selecting Edit > Delete. Enter the Reason for Deleting if required or desired, then click Yes, Delete to confirm.

If the group of selected sources includes any that cannot be deleted, you will see a popup message indicating possible reason(s). If some sources can be deleted, you have the option to complete the partial deletion.

Deletion of sources cannot be undone.

Move Sources (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 Sources (including Registry Sources) between Folders.

Learn more in this topic:

Related Topics




Experiment / Assay Data


Premium Feature — Available in the Professional Edition of Sample Manager and with the Starter Edition when used with a Premium Edition of LabKey Server. Learn more or contact LabKey.

The data you obtain from running your samples through various instruments and experimental procedures can be uploaded into LabKey Sample Manager. To describe how each kind of data should be interpreted, stored, and associated with the samples themselves, you create a framework called an Assay Design. Using this framework, many runs of data can be uploaded and stored in a way that makes it easy to interpret and analyze.

You can create as many different assay designs as you will need to describe the different types of data you will upload. In this section, learn about describing, importing, and updating assay data.

Topics

Tutorial

Get started with assay designs in the Sample Manager tutorial step: Tutorial: Define Assays.




Describe Assay Data Structure


Premium Feature — Available in the Professional Edition of Sample Manager and with the Starter Edition when used with a Premium Edition of LabKey Server. Learn more or contact LabKey.

The results of experiments and instrument runs can be uploaded and associated with samples that are registered in the system.

This topic covers how to create a "template" describing each different type of experiment data you will upload. LabKey Sample Manager calls these data descriptions Assay Designs. All assay data must be associated with a sample, via a field of type "Sample".

Create Assay Design

From the main menu, select Assays and then click Create Assay Design. Before any assays have been created, you will see a direct link to "Create an assay design" on the menu. Note that you can only create Assay Designs in the home (top-level) folder. If the creation button is missing, navigate home first.

  • Give the assay design a Name (Required). The name must be unique.
  • Enter a Description to give more information (Optional).
  • Active: Check the box for assay designs in active use. When this box is unchecked, the design is archived and hidden in certain views.
  • Choose Editing Settings using the checkboxes. Either runs, results, or both can be editable.
  • Add the necessary fields and sample mapping described below before clicking Finish Creating Assay Design.

Add Run Fields

Run fields represent information that will be set once per run of data, such as a spreadsheet of individual result rows uploaded together. All result rows in a run will have the same value for any run fields you define.

  • Click the Run Fields section to open it.
  • If you have a specially prepared JSON file of field definitions, you can drop it into the Import fields from file panel.
  • Otherwise, click Manually Define Fields.
  • Use Add Field to add each run field you need (one is created for you).
    • Enter a Name (without spaces)
    • Select the Data Type.
    • To set more properties of the field, click the to expand it.

If you add any extraneous fields, delete them by clicking the .

In addition to any fields you define, each assay design in Sample Manager includes a Workflow Task run field, which can be used to link assay runs with specific workflow tasks. If your assay design includes making runs editable, you can also associate runs with workflow tasks after import.

Add Results Fields

Results Fields represent the data information in the spreadsheet. You can define results fields in several ways:

  1. Upload a sample spreadsheet to infer all the necessary fields. Either drag and drop a file into the upload area, or click within the same area to select a file directly.
  2. Import a specially designed JSON file containing field definitions by dropping or selecting it in the same panel.
  3. Click Manually Define Fields below the panel to define fields in the editor.
In the Sample Manager tutorial, you can try this procedure with our sample data in the step: Tutorial: Define Assays.

Results fields will be inferred from your upload.

  • Note that the data itself will not be imported at this time.
  • Once fields have been inferred, you can make changes as needed.
    • For example, if your results spreadsheet also includes columns for the run fields you defined, you may need to delete the duplicate fields. Click the to delete a field.
    • If your result spreadsheet contains any reserved fields, they will not be shown on the inferral list, but they will always be created. You will see a blue banner indicating this reason for not seeing specific fields from your file.
There must be a field mapping assay data to the sample it represents. If your fields include one named "SampleID", it will be automatically mapped. Otherwise, you will see a blue notice and need to follow the steps in the next section before clicking Finish Creating Assay Design for your assay design.

Map to Samples

In order to associate all assay data with the sample it represents, every assay design must included a field which maps to samples in the system. The data type Sample is used to represent that mapping as a lookup into the Sample Type containing the samples.

After you infer fields, if one of them is named "SampleID" (such as when you use a naming pattern), it will be mapped automatically. If not, you will see a blue message section asking you to map one of the fields to be the Sample Lookup. The pulldown menu will be populated with the results fields that were inferred. If you need to add a new field to provide the sample linkage, use Add new field. In this example, the SampleID field will be our lookup.

As soon as you select it from the dropdown, the chosen field changes to be of type Sample and opens the properties panel. Select the desired Sample Type from the dropdown.

Click Finish Creating Assay Design in the lower right when finished.

The assay design describing the structure of assay data has now been created. Note that the actual data contained in the spreadsheet you used to infer fields was not imported.

Now you can add experiment data that matches this structure and map it to samples and other associated data.

Related Topics




Import Assay Data


Premium Feature — Available in the Professional Edition of Sample Manager and with the Starter Edition when used with a Premium Edition of LabKey Server. Learn more or contact LabKey.

This topic describes how to import assay data about your samples. You should already have defined the assay structure of your data and how it will map to your samples.

You can follow this topic to upload our example data to the "Tutorial Assay" once you have created it.
Note that our assay data assumes you have followed the previous tutorial steps and already created enough samples in the "Tutorial Samples" Sample Type to have the Sample IDs "Tutorial-003" through "Tutorial-012" available to associate with our data. You can confirm this by selecting Tutorial Samples from the main menu and add more if necessary.

Import Data

Select the assay design you want from the main menu.

To start the import, click Import Data.

Enter Run Details

Enter the Run Details requested.

  • Any fields that are required will be marked with an asterisk (the getting started tutorial does not include any required fields).
  • The Assay Id field will be the name for this run of data. If you don't enter a name here, an Assay ID will be generated for you. If you upload a data file, the filename will be used. Otherwise, it will be a concatenation of the assay design name and the date and time.
  • The Workflow Task field can be used to associate this assay run with a specific workflow task if appropriate.

For the getting started tutorial, enter:

  • Assay Id: "Run1"
  • Date: "2019-10-01" (the time "00:00" will autopopulate if you don't select a time)
  • Instrument: "INS-01"

Enter Data (Results)

You can enter the result data in one of two ways:

Import Data from File

You may want to first download a template file of the expected format by clicking Template, then populate it.

Drag and drop the file(s) containing your result data into the target area or click the region to select a file.

The first three rows of data will be shown for a quick verification before you upload. If any fields are unrecognized, they will be ignored and a banner will be shown.

If everything looks as expected, click Import to import the data. For large files (over 100kb), you may see a notice that your import will be done in the background, freeing you to continue using the app for other use. Learn more about background imports in this topic.

Enter Data into Grid

If neither method described above is appropriate, you can use the Enter Data Into Grid tab to type directly into the entry window. Start by adding the number of rows you want to add and clicking Add row(s).

Enter values directly into the grid. Any columns that are required, including the sample mapping field (SampleID), will be marked with an asterisk (*). Before you can import the data, these columns will need a valid value in every row.

Fields which show a indicator let you choose from the dropdown menu, or start typing to narrow the options. You can enter a text or number sequence, then drag to populate the rest of the column.

At any point you can click to download the contents of the editable grid in CSV, TSV, or Excel format. This can make it easier to complete your import using Excel or similar methods, then reimport it from a saved file.

Learn more about using editable grids in this topic: Data Grid Basics

Bulk Insert

You can also use the Bulk Insert button to prefill the grid with many rows of data with some or all values in common. Enter the number of rows to add and provide values that those rows should share. You do not need to enter a value for every column.

After bulk inserting rows, you can hand edit as needed in the grid view.

Bulk Update

Once data has been entered into the grid, either directly or using bulk insert, you can select one or more rows and click Bulk Update to assign new values to all the selected rows for one or more columns. In the popup, use the slider to enable the updating of a row and enter the new value. Values in columns which are disabled in the update will remain unchanged. Any values shared by all the selected rows (such as "Hb" here) will be shown.

Delete Rows

If you enter extra rows by mistake, you can select them using the checkboxes and click Delete Rows.

Complete Import and Review Data

Click Import when ready to import. If there are any missing or invalid values, you will need to fix them before the import will complete.

When your data has been imported, you will see the results for the specific run you just entered. Run details are at the top, results in a grid below.

The results grid can be searched, sorted, and filtered. Learn more in the topic: Data Grid Basics

Related Topics




Manage Assay Designs


Premium Feature — Available in the Professional Edition of Sample Manager and with the Starter Edition when used with a Premium Edition of LabKey Server. Learn more or contact LabKey.

This topic describes how to edit and manage existing assay designs. To create new designs, see this topic: Describe Assay Data Structure

View All Assay Designs

The assays defined are all listed on the main menu under Assays. To see the list of assays as a grid, click the heading Assays.

You will see the Grid listing the name and description of each defined assay. The Active tab is shown by default; click the All tab to also see archived assay designs.

Manage Assay Design

Click the name of any assay from the main menu or grid to open the runs page for that assay. You will see the assay description, as well as a grid of runs.

To see details about the assay design, hover over the Details link.

Click Runs for the grid of runs and Results for the grid of result data.

From any page within the assay interface, you can click Import Data to import a new run.

Edit Assay Design

Click the name of any assay from the main menu or assay grid to open the runs page.

  • To edit the design select Manage > Edit Assay Design.
  • The panels for editing properties and fields in your assay will open.
    • You can edit the Name if necessary, ensuring that it is unique. It is best to time such renaming for when there are unlikely to be other users importing data or viewing results, as they may encounter errors and need to refresh their browser to pick up the name change.
  • Use the field editor to adjust as needed. Remember that if you delete any fields, all their data will be deleted as well.
  • When finished making changes, click Save.

Copy Assay Design

To copy the design select Manage > Copy Assay Design. This can be a convenient way to make many similar assay designs or add a new variation without losing the previous design.

Export Assay Design

This option is only available when Sample Manager is used with a Premium Edition of LabKey Server.

To export the assay design as a XAR file, select Manage > Export Assay Design.

Learn more about exported assay designs in the LabKey Server documentation

Delete Assay Design

Click the name of any assay from the main menu or assay grid to open the runs page.

  • To delete the design select Manage > Delete Assay Design.
  • Note that when you delete a design, all runs of data associated with it will also be deleted. Deletion cannot be undone.
  • Enter the Reason for Deleting if required or desired. It will be included in the audit log.
  • Confirm in the popup to complete the deletion.

Archive Assay Design

Assay Designs can be hidden from certain views by unchecking the Active checkbox in the Assay Properties panel. Archived, or inactive, designs are not shown on the main menu or available for new data entry through Sample Manager, but existing data is retained for reference.

Using the archive option can be helpful when a design evolves over time. Making the older versions "inactive" will ensure that users only use the latest versions. An assay design may be reactivated at any time by returning to edit the design and checking the Active box again.

When viewing all assay data for a sample, both the active and archived assays will be shown if there is any data for that sample.

On the main Assays dashboard, you will be able to find inactive assays by switching to the All tab.

Related Topics




Manage Assay Data


Premium Feature — Available in the Professional Edition of Sample Manager and with the Starter Edition when used with a Premium Edition of LabKey Server. Learn more or contact LabKey.

This topic describes how to work with assay data runs and results within the Sample Manager application.

Manage Runs

First open the assay design of interest, by using the main menu or assay dashboard then then clicking the assay design name. You'll land on the Runs tab by default.

Click the name of an individual run to manage it. From this run details page, users with "Editor" or "Admin" access can reimport a run, and see and manage results for that run.

Edit Run Properties

If your assay has editable runs and you have sufficient permissions, you can edit run details.

To edit run properties for a single run, click the name of the run, then use the (Edit) icon in the Run Details panel to open them for editing. You will see an entry panel you can use to make changes.

Users can provide a Reason for Update if desired or required before clicking Save Run Details when finished.

Bulk Edit Run Properties

Provided your assay has editable runs and you have sufficient permissions, you can also edit run properties in bulk.

Learn about these interfaces in the section below about editing Result data.

Re-Import Run

If you have a change of data or metadata after importing a run, and have editable runs and/or results, you may be able to make the change directly. However, if your runs/results are not editable, you can import a revised version of the run as follows. LabKey Sample Manager will track run re-imports and maintain data integrity.

Opening the run details (shown above) and select Manage > Re-Import Run.

You will see the interface from when you originally imported the run, including the values and datafile previously entered. Make changes as needed, provide a Reason for Update if desired or required before clicking Re-Import.

A note about event logging: When you re-import an assay run, two new assay events are created:
  • Assay Data Re-imported: This event is attached to the "old run" that is being replaced.
  • Assay Data Loaded: This event is for the "new run" you import.

Delete Run

To delete a run, either:

  • Start from the run details page and use Manage > Delete Run
  • Start from the Runs tab, select one or more runs and choose Edit > Delete.
  • In the popup, enter the Reason for Deleting if required or desired. It will be included in the audit log.
  • Confirm the deletion by clicking Yes, Delete.

Note that a run cannot be deleted if it is referenced in an Electronic Lab Notebook. You will see a message indicating why the option is unavailable.

Manage Results

The result data for your assay is available on the Results tab. Results are individual rows within runs. You cannot add results rows within the user interface. To do so, either import a new run containing the results, or add them to an existing run by reimporting the run after adding the additional rows to the run data file.

You may want to include one or more of the Created/CreatedBy/Modified/ModifiedBy fields in the assay result grid view for tracking when and by whom results are edited.

Edit Selected Results in Grid

If your assay has editable results, and you have sufficient permissions, you can select one or more rows using checkboxes and select Edit > Edit in Grid.

A grid will be shown, with a row for each row you selected, allowing you to edit the necessary values. Users can provide a Reason for Update if desired or required before clicking Finish Updating # Results to save changes.

Learn more about using editable grids in this topic:

Edit Selected Results in Bulk

If you are editing a number of rows to insert shared values, select the desired rows with checkboxes and select Edit > Edit in Bulk.

An editing popup will let you select which field or fields you want to batch update. By default, all fields are disabled; enabling a field using the toggle will let you enter a value to assign for that field in all rows. Shown here, the MCV field will be updated with a shared value, but all other fields left unchanged.

After entering updated values, you can Users can provide a Reason for Update if desired or required before leaving the bulk popup using either:

  • Edit with Grid to switch to updating in a grid format (with the bulk changes you just made already applied). Use this option if you want to make individual as well as bulk row changes.
    • Be sure to click Finish Updating # Results when finished with the grid update to save both the bulk changes AND individual changes you made.
  • Update Results if no further editing is needed. The bulk updates will be saved.

Delete Results

To delete one or more rows of results within any run, either open the run from the Runs tab or find the desired rows on the Results tab. Use sorting and filtering to help you isolate rows of interest.

Check the box(es) for the row(s) you want to delete and select Edit > Delete. In the popup, enter the Reason for Deleting if required or desired. It will be included in the audit log. Confirm the deletion by clicking Yes, Delete.

Note that you can only delete 10,000 assay results in one operation. To delete more than that, perform the deletion in batches.

Work with Samples from Assay Results

From the page of assay results, you can select a desired set of rows and then use the Samples menu to work with the set of samples mapped to those results.

View Assay Data for a Sample

On the details page for any Sample, click the Assays tab to see data about that specific sample. There is an Assay Run Summary tab showing the number of runs per assay type. In addition, a tab for each assay type lets you browse the collected profile of results.

From any assay-specific tab, you can also Import Data for any assay that can be linked to samples of this type, regardless of whether there are runs of that type yet.

View Assay Results for Selected Samples

From a grid of samples, including tabbed grids showing multiple sample types like picklists, you can select desired samples, then choose Reports > View Assay Results for Selected.

The report includes an Assay Run Summary tab, showing the count of runs of each assay type for each sample. This can provide a handy dashboard for confirming that data analysis is on track for a mixed set of samples.

On assay-specific tabs, you can see all the assay results for your selected group of samples.

Exporting any tab from this report to Excel offers the option to include any or all of the tabs. Multiple tabs will be exported as a multi-sheet Excel file.

Related Topics




Electronic Lab Notebook (ELN)


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

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.

Access the ELN by clicking Notebooks Home from the home page of the application or select Notebooks from the main menu. Your own notebook work is highlighted and linked from both the home page and notebook dashboard, making it easy to find and complete assigned tasks.

Learn more about creating, using, and reviewing notebooks in this section (the link will open in a new tab):




Storage Management


Managing the contents of your freezers and other storage systems is an essential component of sample management. There are endless ways to organize your sample materials, in a wide variety of systems on the market, both freezers and non-temperature-controlled options. With LabKey Storage Management, create an exact virtual match of your physical storage system, and then track where each sample can be found.
  • Match your digital storage to your physical storage.
  • Represent your exact physical system, with shelves, racks, boxes, canes, bags, etc.
  • For freezers and other temperature controlled units, you can track storage temperatures and freeze/thaw counts for samples.
  • Track overall available storage capacity helping you decide where to store new samples.
  • Answer questions about overall volume of samples by type and source; i.e. is there enough blood from patient X to complete the series of assays I want to run.
  • Find specific samples and know if they are available.
  • Assign samples to storage locations in groups of any size you need, including across multiple locations.
  • Move samples as needed and track each location change, creating a full timeline of any sample.
  • Control access to physical samples using storage-specific roles.

Topics




Create Storage


Create as many digital storage systems in the application as you have physical storage locations. You can have both room temperature and temperature-controlled storage systems such as freezers or incubators. Customize the storage layout, aka hierarchy, within each digital storage system to match the physical options available to your users.

This topic describes how to define a new storage system from scratch. Once you have created one, you may copy it to create additional similar storage. Users must have either the Storage Designer or Administrator role to create and edit storage systems and layouts.

Note that you can only create storage systems in the home (top-level) folder. If the creation button is missing, navigate first to the home folder.

Create Storage

To create a new storage system, click Create Storage on the main dashboard, or from the Storage option on the main menu.

To create additional storage, you can start from scratch again or you may copy existing storage.

Storage Properties

Under Storage Properties define the following:

  • Storage Type: Use the selector for either:
    • Temperature Controlled (Default) or
    • Room Temperature
  • Name: Any string name that will clearly identify the physical storage; it must be unique in the system. You'll be able to search by this name later.
  • Label: Optional text description that will be shown with the name. You'll be able to search by this label later.
  • Manufacturer (For temperature-controlled storage only): Optional string for the company name or maker of this unit.
  • Freezer Model (For temperature-controlled storage only): Optional string for the manufacturer-assigned model number or name. Note that while the name of this field is "Freezer" model, it could also be an incubator holding samples at a non-frozen temperature.
  • Temperature (For temperature-controlled storage only): Optionally include the set-point or consistent operating temperature of this storage system when in use. When giving a temperature, specify Celsius or Fahrenheit.
  • Physical Location: If any physical locations have been configured, you can specify here where to find this storage system.

Continue to define additional properties if needed and describe the structure of this storage in the Storage Hierarchy section before clicking Finish Creating Storage. You can also return to edit after saving if you need to make changes to the properties later.

Advanced Storage Settings (For temperature-controlled storage only)

Click Advanced Settings to set the following properties for temperature-controlled storage. Click Apply to save any changes.

  • Serial Number: Unique identifier for this unit that can be useful for troubleshooting with the manufacturer.
  • Sensor Name: If this system is using an alarm or monitor, you can provide the name here.
  • Loss Rate: Indicates the time needed or rate at which the unit will return to an ambient temperature from its set-point.
  • Status: Used to indicate if the unit is storing samples, available as a backup, or defrosting/cooling/reheating as part of a maintenance routine. Options:
    • Active
    • Backup
    • Defrosting

Storage Hierarchy

Click the Storage Hierarchy section to open it. Add the specific Storage Units available to the panel on the right, either by:

  • Individually dragging them to the proper location in the hierarchy.
  • Using Bulk Add to add many storage units at once.
There are two categories of storage unit available:
  • Non-Terminal Storage Units : These units can be contained within each other in any combination, but cannot directly contain samples. For example, a shelf can have a rack which has 2 shelves, but there must be a bag, box, or plate on those inner shelves to contain the samples themselves.
    • Shelf
    • Rack
    • Canister
  • Terminal Storage Units: These units can directly contain samples and cannot contain other units. Note that these units will only appear in the hierarchy interface when one or more types or sizes have been defined.
    • Bag
    • Box
    • Cane
    • Plate
    • Tube Rack

The system includes several built-in types (sizes/layouts), of each kind of terminal storage unit. You can customize the available terminal storage unit selections or add new ones by clicking Manage storage unit types. Note that your work in progress creating this storage will be lost if you click away now. Consider saving your work and returning to edit the definition when you have refined the options available.

Add each storage unit, customizing the default short name if you like, and optionally adding a more descriptive label.

Start with the "large" containment in your storage, then drop structure within that container directly on top in the panel to place it "within" the container. Drag to rearrange them to match the physical storage system. For example, in this image there are three shelves, and to describe several racks on one shelf, we drop the first rack directly "on" the shelf. If we put it "next to" the shelf, it would be added as a separate rack at the same level as that shelf instead of "within" it.

Click the icon to collapse the display of any nested units - it will become a you can use to expand the display again. To speed creation of repetitive hierarchies, you can use either:

Continue to add the structures and terminal storage units that will contain your samples. For each terminal storage unit, you also specify the type (size/layout) of the unit.

  • Bag: Select bag type from the dropdown.
  • Box: Select box type from the dropdown.
  • Cane: Select cane type from the dropdown.
  • Plate: Select plate type from the dropdown.
  • Tube Rack: Select the type of tube rack from the dropdown.

Storage Unit Names

By default, all the storage units you add will be named in a sequential numbering scheme, including the type of storage unit in this name. You can edit these names in any way will help your users find the correct locations, such as position/color/identifying labels you have applied or calling racks "partitions" if that is how your users refer to them. Unit names must be unique at any given level in the hierarchy. It is good practice to use unique names throughout the storage system to avoid confusion, particularly where there are many similar structures.

The name is indexed making it possible to later search for units by name.

Storage Description Labels

You can include a more verbose descriptive Label for every level of your storage hierarchy. When present, labels will be shown in many places to help users better identify the specific storage unit. Both as additional text in hierarchy listings, and as hover text when viewing storage location 'pathways' throughout the application.

You can add new labels to existing units, or edit labels to update them, either by returning to edit the definition via this interface, or directly edit them in the storage view for the unit using the icon.

The label is indexed making it possible to later search for units by label.

Clone Units

If you click , you can clone a unit that contains other nested units. The entire structure will be cloned at the same level as the parent. This can speed the process of describing a repetitive storage hierarchy.

Finish Describing Hierarchy

Continue to add elements and rearrange them to describe your storage. Here, there are three shelves. One of the shelves has 2 bags, another shelf has two racks, each with 2 boxes of different sizes.

  • Once you have completed your storage hierarchy, click Finish Creating Storage.
    • Note that you can return to edit your storage hierarchy later, such as after defining new storage units.
    • If any storage names are duplicates within a given hierarchy, an error will be raised highlighting both of the matching names so that you can edit one or both to be unique. No error is raised for duplicate names in different parts of the hierarchy.
After saving, you will see the Overview page for your storage. Learn more in the topic: View Storage Details

As long as you have included some terminal storage units such as bags or boxes, you will see how many samples you can now store in it. If not, you will see the message "This location has no terminal storage units configured", with a quick link to add some.

Bulk Add Storage Units

Instead of adding all your storage units individually, you can click Bulk Add to add many at once, streamlining the above drag and drop/copy process. For example, in this example we're adding a shelf that contains 6 racks, each containing 12 plates.

Click Apply to complete the addition. By default, bulk units are named [unit type] #[number]. No labels are applied. You'll be able to expand and customize the new units just as if they had been added individually.

Create New Storage Units When Storing Samples

When you are adding samples to storage, you can easily add a new box, bag, cane, plate or tube rack (i.e. any terminal storage unit) from within the Add Samples interface.

Expand the existing storage hierarchy to find where you want to place the new unit. Click the , then type the name, select the Unit Type, and optionally include a label.

Click Save to add the new storage unit. The samples you are storing will be placed in it as if it had existed already. Continue to Select Positions within the new box.

Learn more about storing samples in this topic:

Next Steps

Once you have added at least one storage system that includes some terminal storage locations, you can proceed to store samples.

Related Topics




Store Samples


Once you have configured at least one storage system with some terminal storage units, you can assign samples to the virtual location corresponding to their physical location. Any protocol about where to place samples of different types can be accommodated in this system.

To add samples to storage, the user must have been granted the Storage Editor role or be an administrator. This topic assumes the user has this role.

Start from the Storage System

Start from a List or Grid of Samples


Start from the Storage System

Find Available Space

If you know the name or label of the storage unit you want to use, you can search for it directly. Click it in the search results, then skip to adding your samples to it.

Otherwise, start from the Storage List on the application home page, or the Storage dashboard. You'll see a summary of storage and how many spaces are available for samples in each to guide you.

Click the name of the storage to open the details page.

  • Here you'll see the top level of the storage hierarchy you defined. A note of the number of free spaces in each section is provided to assist you.
  • Click the to expand the nested hierarchy.
  • Each level will summarize space available and in the case of terminal storage, will show the specific storage unit name (i.e. bag size or box dimension).
  • As you browse, the system will remember where you were in the hierarchy if you need to go back to a different branch.
  • Click any level to see more details in the panel on the right.

Continue to use the to expand until you find enough capacity in terminal storage units where your samples can be stored. Note that if you cannot find sufficient space, you can also add new storage when you are adding samples to storage from a grid.

Click any location in the left panel to show it's summary information on the right. You can only store samples in "terminal" storage locations: bags, boxes, canes, plates, and tube racks.

  • Click Go to Storage View to open it.
  • You can also click the location name in the 'breadcrumb' trail along the top of the panel.

You are now on the Storage View tab for this storage, open to the location you selected.

Select Space to Fill

There are two categories of terminal storage units to which you can add samples.

  • 1. Bags and Canes use a simple numbering scheme for positions.
    • For bags and canes, you don't need to do anything except click Add Samples to activate the sample panel on the right.
  • 2. Boxes, Plates, and Tube Racks have a 2D layout of row and column positions (aka cells, spaces, wells, etc.) within the unit. You have two choices here:
    • Click cells or drag within the layout to select a range of positions, as shown below, then click Add Samples. The selected positions will be eligible for placing samples, provided they are not already occupied.
    • OR, click Add Samples without making any selection. All available positions will be eligible for placing samples.

A popup modal will help you add the samples.

For a box, plate, or tube rack, the left side of the panel previews the storage layout, with any selection you made. The right side of the popup offers both a grid entry option and a way to search for samples. You can also specify the fill order, direction, and (if no cell selection was made) the starting location for the samples you are adding.

For a bag or cane, there is no layout preview, but a single panel for the grid entry option or searching for samples.

Position Already Occupied

If you select a range of cells and one (or more) are already occupied by samples, when you click Add Samples, you will see only the unoccupied positions in the grid.

Identify Samples to Store

Edit Location Properties

On the Edit Location Properties tab, you can paste into the grid from a spreadsheet or by typing directly into the grid:

Values added to the Sample ID column must already exist in the system. If you start typing you will see a narrowing list of available samples. Note that this means if you received a new set of samples, you must first add them to a Sample Type before you can assign them to locations using this interface.

Search for Samples

Click the Search for Samples tab to get more assistance with finding specific samples.

First, select the desired Sample Type from the dropdown.

Once a Sample Type has been selected, you can:

See below for how to Assign Positions once you've identified the samples you want to store.

More Filters

Click More Filters on the Search for Samples tab to select on or more of the filter options:

  • Created By: Find samples added by a specific user.
  • From/To: Find samples created in a specified date range.
  • Click Show Results to see the samples that match your filters.
    • Use checkboxes to select the samples of interest, then click Assign Positions, or return for More Filters.
    • Once some filters are applied, you'll be able to click Clear all filters to clear them.
  • Use Back to Grid to return to the previous set of selected samples.

Assign Positions

Once you've filtered to find the samples you want, use checkboxes to select the ones you will be adding to this storage unit.

  • Note: If you select more samples than there are spaces available, you will see an error message telling you to reduce the number of selected samples before proceeding.
Click Assign Positions.

The selected samples are shown in a numbered position-assignment table on the right. You can directly edit the grid to provide:

  • Position:
    • In the case of a bag, the numbered position is not meaningful.
    • For a cane, it could be numbered from top to bottom (or bottom to top) as your convention dictates.
    • For boxes, plates, and tube racks, the "Position" column shows row/column position numbers corresponding to the layout on the left. Learn about assigning specific positions below.
  • Sample ID: the selected samples are listed, but you can add more rows directly. Sample IDs must already exist in the system.
  • Amount: Volume
  • Units: Units for that volume (mL, mg, etc.)
  • Freeze/Thaw Count: The default is zero. If you know the sample has been thawed and frozen before, you can edit this value.
Bag or cane:

Box, plate, or tube rack:

Choose Fill Order, Starting Location, and Fill Direction

When you start from the storage and search for samples to add to a structured storage unit like a box, after clicking Assign Positions, you'll be able to select the order, starting point, and fill direction.

  • Fill Order:
    • Manual (Default)
    • Sample Creation Order
    • Sample ID Ascending
    • Sample ID Descending
  • Starting Location:
    • If you preselected cells, the first available spot in your selection is used and this dropdown is not offered.
    • If not, then the first available spot in a storage unit is selected by default. You can specify another starting location if desired using the dropdown.
  • Fill Direction:
    • Left to Right
    • Top to Bottom

You can further adjust these assignments by using copy/paste to move the rows in the assignment grid to other available positions in the layout.

Add to Storage

Click Add to [Storage Type] to complete the position assignments.

After assignment is complete, you will see the Storage View for the location.

  • The newly added samples will be selected in the grid.
  • In the case of a box, plate, or tube rack, the cells containing the newly placed samples will also be highlighted.


Start from a List or Grid of Samples

Instead of starting from the Storage, as described above, you can add Samples to storage starting from the sample grid, either while viewing the Sample Type as a whole, or starting from a curated picklist or Sample Finder search results.

Select Samples to Store

Open the grid of Samples of interest. Either select the Sample Type from the main menu, or choose Picklists from the user menu and click the name of the picklist you want. On the grid, identify the Samples you want to store. Only Samples with a Storage Status of "Not in storage" can be added, so applying this as a filter can be helpful.

Use checkboxes to select the Samples, then select Storage > Add to storage above the grid. On narrower browsers, this option will be on the More > menu.

If you are viewing details for an individual sample, you can also click Add to Storage from the Storage Location panel.

Note that there are some situations where samples cannot be added to storage, such as a status that prevents the action or the user's permission in the folder where the sample is defined. You will see a banner warning describing any issues with the selected samples.

Find Storage Location(s) for Samples

In the Assign Samples to Storage popup, you will see storage systems with available storage space. The number of spaces available at each level will help you see easily where there is room for your new samples. To quickly find particular storage you want, use the search box at the top of the panel to find storage units by name or label.

Use the icons to expand the hierarchy of the storage of your choice, seeing available spaces at each level. You'll see unit names, as well as the type/size of terminal storage units to assist you.

When you find the desired terminal storage unit, click Select. If necessary, you can also add new terminal storage units by clicking the for the level where you want them.

For boxes and plates, you'll see a preview of the current contents of the storage on the right.

The Select link will switch to Clear, in case you change your mind at this point and want to select another location.

Automatic or Manual Location Assignment

Once you have selected a storage location with enough space for all selected samples, click Select Positions. Starting from a list or grid of samples gives you somewhat different options than if you had started from the storage system to store them. By default, the samples will be placed in the first available layout positions, using left to right, then top to bottom sequencing. Select either:

  • Automatically Fill: Customize the fill order, starting point and fill direction.
  • Manually Fill: Place them manually, with the option to change the fill direction to adjust how the rows are listed in the grid.
For either option, you will still:
  • Populate the grid with storage properties.
  • Assign positions, make any position adjustments needed.
  • Click Add to [Storage Type] to complete the position assignments.

Automatic Fill Options: Fill Order, Starting Location, Fill Direction

  • Fill Order:
    • Samples Grid Order (Default): This option reads "Manual" if you did not start from a sample grid.
    • Sample Creation Order
    • Sample ID Ascending
    • Sample ID Descending
  • Starting Location:
    • By default, the first available spot in a storage unit is selected. You can specify another starting location if desired using the dropdown.

Manual Fill Options: Fill Direction

When you choose the manual fill option, you can select the fill direction which will reorder the rows in the grid for manual filling.

Store Samples in Multiple Locations Simultaneously

When you're storing more samples than can fit in one terminal storage unit, you'll be able to select multiple storage locations in the "Add Samples to Storage" modal. For example, if you have a rack of many 10x10 boxes and want to continue filling them in sequence with arbitrary numbers of samples to store in each batch, you might have a situation where there are 6 spaces left in a box. Rather than having to first pick 6 samples for that box, then the remaining samples for another box, you can select all your samples and choose multiple locations. You can even choose storage locations across different storage systems if desired.

Samples are added to storage in the order they appear in the grid.

As you find storage locations for your selected samples, clicking Select, you'll see a tally of the number of samples you still need to find spaces for before you can click Select Positions. Each time you choose a storage unit by clicking Select for it, that link will change to Clear in case you change your mind. In this example, we have 9, and chose a box with 6 spaces, so need 3 more from another box, but you could have hundreds and fill as many boxes as needed.

On the next panel, you can edit the Stored Amount, Units, and Freeze/Thaw Count for the samples you are storing. You start on the Edit in Bulk tab; only enable the fields where you want the same value assigned to every sample and provide that value.

You can also switch to Edit Individually where you can edit these values in a grid.

When finished, click Add to Storage. The samples will be added directly to storage in the locations you selected. You will not see the same location assignment interface as when using a single destination storage unit and cannot further adjust positions at this point. After the action, you'll see a banner with the number added and a clickable link letting you View their storage locations here.

Related Topics




Manage Storage


Once one or more storage systems have been configured in your system, you will see them in the Storage List on the main dashboard. View the overall Storage Management dashboard from the Storage option on the main menu. Note that some storage management and sample actions require the user to have the Storage Editor and/or Storage Designer roles. This topic assumes the user has both.

From this Storage Dashboard, you can see an overview and manage your sample storage.

Sample Activity

The Sample Activity panel shows summary information about all samples in storage. Clickable links give you access to :

  • View ### total samples in storage: open a filterable grid of all stored samples. Learn more here: View Storage Activity
  • Click a Date to open the grid of samples added to storage by any user on that date.
You can also click to see Your recent sample activity. Learn more here: View Storage Activity.

Storage Overview

The Storage Overview panel includes a graphical, color-coded representation of the current storage of samples in storage. The color you assign to each Sample Type is used to represent those samples in a variety of charts.

Use the dropdown to select one:

  • Samples Stored By Sample Type: A bar chart with the total count of each sample in all storage shown.
  • Samples Checked Out By Sample Type: A bar chart representing the types of samples currently checked out to all users.
  • Samples Checked Out By User: A bar chart showing the total samples checked out to each user, regardless of Sample Type. Color coding is not used on this chart to represent Sample Type, but if you click the bar for a user, you will see a grid of the samples that user has checked out.
Within any chart, if you hover over a colored segment, you will see a tooltip with the count and type of sample it represents. Click any bar segment to see a grid of data for the samples it represents.

Storage List

The top of the Storage List shows Recent Storage, the most recently accessed storage systems for each individual user. Below that, All Other Storage is listed. Note that only 10 freezers are shown in this list initially; click Show More to see the rest, also 10 at a time.

There are two action buttons for administrators:

  • Manage Storage Units: Define the "terminal" storage units in which samples are stored. Boxes, bags, canes, plates, and tube racks can be of different sizes, storage layouts, and labelling conventions.
  • Create Storage: Add another storage system.
All users can hover over the Legend for a guide to the colors for each sample type.

In the section for each storage you have defined, the panel includes:

  • On the left:
    • Name: Click the name to open the details for this storage.
    • Above the name, you'll see this storage system's location, if any has been defined.
    • If set, the Status will be displayed in a colored block.
    • Below the name, the label (description) may also give more identifying information to users.
    • Configured set-point temperature (for temperature-controlled storage).
  • On the right:
    • Color coded bars represent the number of samples currently stored in that storage, scaled to give a visual indication of overall capacity free.
    • The capacity of the storage system is below the bars. You'll see the number of samples stored, the total number of spaces, and the percent of spaces available.
  • Click anywhere in the tile to go to that storage overview page.

Related Topics




Manage Storage Unit Types


Your physical storage can be duplicated within the Storage Management tools by customizing the storage units that can hold samples directly, known as terminal storage units. Non-terminal storage units like shelves and racks cannot hold samples themselves, but must have terminal storage units 'within' them. They can be of different sizes, and in the case of structured storage units (boxes, plates, and tube racks), you can also configure the labeling pattern to match existing conventions, making it easy for your users to find the correct positions within these structured layouts.

An administrator can define the storage unit sizes, layouts, and labelling systems that will be available when creating storage in the system. The Name you give a particular size/dimension of a terminal storage unit, also known as the storage unit type, will be displayed to users selecting where to store samples. It must be unique and can also be used when adding new storage during sample import.

Click Manage Storage Units in the Storage List panel on the home page or storage dashboard. Note that you do not need to have created any storage systems yet to manage the storage units that they will be able to contain.

After editing storage units, click Finish Editing Units to save your changes.

Bags

Bags are a flexible way to store samples. Default bag sizes created in the system can hold 10, 100, 200, or 500 samples.

If you want to add an additional size bag, select the Bags tab and click Add a New Bag. There is no internal limit to the number of samples a bag can hold.

Enter the Name and Capacity for the new bag. While it is good practice to use the capacity in the name of the bag, the system does not require it.

To delete a bag type, click the . You may delete the built-in types if desired.

To expand the details for a bag type, click the icon to expand it. You can add a Storage unit description to assist your users.

Boxes

Boxes can be of different sizes and layouts, accommodating many types of sample storage. Click the Boxes tab to manage box types. Some common sizes are built in to the system:

  • 10x10
  • 10x5 (10 columns, 5 rows)
  • 5x5
  • 9x9
These built-in boxes use a default of alphabetic row labels and numeric column numbers, and by default columns and 5 display rows first, i.e. A-1. All of these default attributes can be edited, or you can add a new box with different attributes.

Click Add a New Box to add a new one. A box is limited to a maximum of 50 rows and 25 columns.

To expand the details for a box type, click the icon to expand it.

  • You can add a Storage unit description to assist your users.
  • Under Display Options you will see a Space label display preview, i.e. how the spaces in your box will be labeled, shown here "A-2".
    • Select either Show columns first or Show rows first. The default is to show rows first.
    • Specify for Column labels whether they are alphabetic or numeric. The default is numeric.
    • Specify for Row labels whether they are alphabetic or numeric. The default is alphabetic. If alphabetic is chosen and the number of rows is greater than 26, the rows after Z will be labeled AA, AB, AC, AD, etc.

To delete a box type, click the . If a given type is in use anywhere in the storage system, you cannot delete the type. You may delete the built-in types as well, if they are not in use.

Canes

Canes hold a number of samples typically in a vertical alignment. Click the Canes tab to see and add cane sizes. Built-in cane types are named for the sample capacity in the cane:

  • 4 Cane
  • 5 Cane
  • 6 Cane
Click Add a New Cane to add a new type of cane to hold a different number of samples. There is no system limit to the number of spaces available in a cane.

To delete a type of cane, click the . If a given type is in use anywhere in the storage system, you cannot delete the type. You may delete the built-in types as well if they are not in use.

To expand the details for a cane type, click the icon to expand it.

  • You can add a Storage unit description to assist your users.

Plates

Plates can be of different sizes and layouts, accommodating many types of instrument. Click the Plates tab to see and add plate types. Built-in plate types are:

  • 24 Well Plate (6x4)
  • 384 Well Plate (24x16)
  • 48 Well Plate (8x6)
  • 96 Well Plate (12x8)
These built-in plates use a default of alphabetic row labels and numeric column numbers, and by default display rows first, i.e. A-1. All of these default attributes can be edited for the built in plates, or you can add a new type of plate with different attributes.

Click Add a New Plate to add a new one customized to your needs. While our convention is to name plates by the total number of wells, this is not required by the system. Plate sizes are limited to a maximum of 25 rows and 25 columns.

To expand the details for a plate type, click the icon to expand it.

  • You can add a Storage unit description to assist your users.
  • Under Display Options you will see a Space label display preview, i.e. how the spaces in your box will be labeled, shown here "A-2".
    • Select either Show columns first or Show rows first. The default is to show rows first.
    • Specify for Column labels whether they are alphabetic or numeric. The default is numeric.
    • Specify for Row labels whether they are alphabetic or numeric. The default is alphabetic.

To delete a plate type, click the . If a given type is in use anywhere in the storage system, you cannot delete the type. You may delete the built-in types as well if they are not in use.

Tube Racks

Tube racks can vary greatly in size and layout. Click the Tube Racks tab to see and add the types you need. Built-in types are:

  • 4x5 Tube Rack
  • 4x6 Tube Rack
  • 6x12 Tube Rack
  • 6x6 Tube Rack
Tube racks use a default of alphabetic row labels and numeric column numbers, and by default display rows first, i.e. A-1. All of these default attributes can be edited for the built in types, or you can add a new tube rack with different attributes.

Click Add a New Tube Rack to add a new one customized to your needs. While our convention is to name the built-in tube racks by number of rows and columns, this is not required by the system. Rack sizes are limited to a maximum of 25 rows and 25 columns.

To expand the details for a tube rack type, click the icon to expand it.

  • You can add a Storage unit description to assist your users.
  • Under Display Options you will see a Space label display preview, i.e. how the spaces in your box will be labeled, shown here "A-2".
    • Select either Show columns first or Show rows first. The default is to show rows first.
    • Specify for Column labels whether they are alphabetic or numeric. The default is numeric.
    • Specify for Row labels whether they are alphabetic or numeric. The default is alphabetic.

To delete a tube rack type, click the . If a given type is in use anywhere in the storage system, you cannot delete the type. You may delete the built-in types as well if they are not in use.

Related Topics




View Storage Details


This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.

To view the details of what can be found in a specific storage system, click the name on the main menu or the Storage Dashboard. There are two tabs in the view of a storage system, plus a Manage menu:

Note that to add samples to storage, and perform other sample storage actions, the user must have been granted the Storage Editor and/or Storage Designer roles. This topic assumes the user has both.

Overview Tab

The overview page for a storage system shows a high level view of storage status and contents

Storage Status

Next to the storage name, the current status is shown in a colored block. Click the to select among the options: "Active, Defrosting, Backup".

Storage Details

Hover over the Details link to see the properties, including the temperature (if set), usage of this storage, and any advanced settings defined for this storage.

Overall capacity is shown in a bar, with the 'in-use' capacity as a shaded portion and the number of used and unused sample storage spaces listed above it.

Storage Contents

Below the header, you will see a split panel where you can browse the storage hierarchy and contents.

On the left, expandable sections for the top level storage units let you 'browse' the structure of this storage.

  • Click the to expand a section. (It will become a that you can click to collapse it again.)
  • You'll see the terminal storage unit type displayed, typically the size of the unit.
  • Click a section on the left to see the details for it on the right.
On the right, you see the details for the region of the storage selected on the left. If no section is selected, the overall storage details are shown. Here, we are looking at the details for a particular box:

  • A 'breadcrumb' trail along the top identifies the location of the unit being shown. Above we see a box on a rack in a shelf in a freezer.
    • You can click any level of this breadcrumb to open the details for that unit on the on the Storage View tab.
    • You can copy this "path" including the slash separators, and paste it to make it easier to build spreadsheets for import or other use.
  • A button to Go to Storage View is displayed. Click to open this unit on the Storage View tab.
  • Visual bars follow, summarizing the contents of this storage unit. They are colored using the label colors assigned to Sample Types.
    • Capacity: The shaded section indicates used spaces. The number and percent available are listed.
    • Sample Types: The breakdown of types of samples in this unit is shown visually using the label colors assigned. Hover over Legend to see which colors represent which types of sample.
    • Samples Checked Out: The number checked out is shown, under a bar indicating the type that are checked out.

Storage View Tab

The Storage View presents a more detailed look into the contents of this storage. Below the Storage Status and Storage Details panels, the storage section lets you browse through the storage hierarchy.

  • Select which level of storage to view.
  • Choose whether to view all samples, or only selected samples in the grid.
  • Switch to a tab for a specific sample type of interest. Here you can perform the same sample menu actions as on other sample grids.
  • Check the box for a specific sample to see its details on the right.

Sample Information in Grids

All storage units, from the overall storage system to a shelf to a plate or bag, show information about Samples in a grid in the Storage View, as shown above. Scroll to the right to see additional columns.

Select whether to view All Samples or Selected Samples in the grid. You can also use the tabs to select whether to view samples of all types ("All Samples" or samples of a chosen type; numbers on the tabs indicate how many of each type are available at this storage level. As with any grid, you can then sort and filter them or search to find a subset of interest.

The terminal storage units with assigned locations, i.e. boxes, plates, and tube racks, also include a layout interface with the sample grid below it.

Select Storage to View

The top row of the panel shows what location you are viewing and lets you select into the nested levels of the storage hierarchy.

  • Use the to open a menu of locations available.
  • Select one to view it. And if desired, go further by using the to select from the next level 'into' the storage.
  • When all of the locations are of the same type, such as when Shelf #1 only contains Boxes below, the menu will have the label of the type; when storage units are mixed, "Location" will be shown.

You can also 'jump' into a nested storage location from the buttons and breadcrumbs on the Overview tab.

Box, Plate, Tube Rack Detail Views

When looking at the Storage View for a Box, Plate, or Tube Rack, you will see a layout of rows and columns matching the definition of the storage unit, and color coded indications of the specifics of each cell, or place, in that layout.

  • Rows and columns are labeled alphabetically or numerically, depending on how you defined the storage unit.
  • The 'occupied' positions will show a color-coded dot.
  • Shading indicates positions that are reserved for samples that are currently checked out.
  • Hover over the Legend to see it.
  • Hover over any position in the grid to see a popup with details about it.

View Selected Samples in Box, Plate, or Tube Rack

  • Click any position (cell) to select the sample in it and see details, as well as actions, on the right.
  • The clicked/selected position is shaded blue, and if it contains a sample, the corresponding row is also selected in the data grid below the graphical layout.
  • If you select a position where a sample is checked out, shaded pink, you will see details about the sample that "belongs" in that position but is currently checked out, including a link to View sample timeline where you can learn more about who checked it out, when, and why.
  • If you are a storage editor or administrator, you will also see additional action buttons here.
If you select a range of spaces in a structured layout, any samples in those spaces will also be selected in the data grid below. You will see summary information in the details panel, and action buttons for users with sufficient permissions.

Hover over the colored dot for a tooltip about which Sample Type it represents, or use the Legend.

Sample Actions

Note that for many sample storage actions, the user must have been granted the Storage Editor and/or Storage Designer roles. This topic assumes the user has both.

Location History

When in the Storage View, if no specific position is selected, use the Location History tab to see a timeline of events for the storage unit you are viewing. For example, viewing a box after it has moved, you would see two events: the original creation, and later movement to elsewhere in the hierarchy.

Hover over the to see details for moves.

If a specific position in a box, plate, or tube rack is selected when you view the Location History tab, you will see the location history for that position in the layout. For example, here a sample was moved out and then back into the A-2 location:

Storage Description Labels

It may be useful to provide descriptions of individual storage units for your users. You can customize the name of the unit itself, or from within the Storage View, you can add a more verbose label or edit an existing one. For example, you could include more text from box labels here, or names of investigators or groups.

Below the name of the unit, click the to edit. Type the new label (or edit the existing label). Hit enter to save.

You can also define storage unit labels when you create the storage hierarchy, as described here:

Storage unit labels are shown with the unit name, and also in hover text when you hover over the 'breadcrumb trail' for the storage hierarchy.

Manage Menu

Use the Manage menu for the following actions:

Copy Storage Definition

Select Copy Storage Definition from the Manage menu of the storage you want to duplicate. Use this option to create a new storage system with the same initial properties and hierarchy. No storage contents will be copied.

You can use this as a shortcut to creating many similar storage systems, or adding a new one as you need additional storage capacity. Once copied, customize the new storage definition. At a minimum, each storage system must have a unique name. The default name of copied storage appends "(Copy)" to the end of the original name.

Delete Storage

Deletion of a storage system is permanent and cannot be undone.

  • The storage definition and all of its storage units will be permanently deleted.
  • If any samples are stored in it, you must have an "Administrator" role to delete the storage.
    • You will see a count of how many are stored. The samples themselves (the sample data) will not be deleted if you proceed, but all of the location information for those samples will be cleared.
    • Non-administrators must remove all the samples from storage before they can delete a storage system.
Select Delete Storage from the Manage menu while viewing the details for that storage system. Users authorized to delete will be asked to provide a Reason for Deletion if required or desired. Confirm by clicking Yes, Delete.

Deletion actions are recorded in the Storage Management Events section of the audit history.

Related Topics




Edit Storage Definition


An administrator or storage designer may edit both the properties and the composition of storage units within a given storage system like a freezer.

Open Storage Editing

You can edit a storage definition by first opening the desired storage from the main menu or storage dashboard, then selecting Manage > Edit Storage Definition.

Edit Storage Properties

The Storage Properties panel can be edited using the same interface as when it was originally created.

Edit Storage Hierarchy

Open the storage definition for editing, then click Storage Hierarchy. The interface for editing the hierarchy is the same as when you created it. Drag and drop units to where they should be. Use to expand sections in the hierarchy.

When storage is empty, i.e. before any Samples have been stored in it, you have more flexibility in changing the layout and storage location contents.

Once some samples are stored, you will see a icon marking storage units that cannot be deleted. You can still add additional storage units to "locked" non-terminal storage. For example, you can add more boxes to a rack that shows as "locked" because it already contains boxes containing samples, but you cannot delete the rack entirely.

Add New Storage Units

Drag and drop new storage units to the positions in the hierarchy where you want them. Adding additional storage will change the capacity and usage percentages for the storage.

Adjust Existing Storage Units

Edit the Name given to storage units to help your users identify the specific locations and containers they need. You can also add a descriptive Label for each unit. Both the name and label of the box are indexed making it easier to find a desired storage unit later.

Drag existing storage units to different parts of the hierarchy to move them within the current storage system. You can rearrange storage units even if they already contain stored samples.

Changing the position or name of a terminal storage unit will change the current information shown for all stored samples, but does not register as a timeline event for samples provided it stays in the same storage system.

Learn about moving a storage unit to a different storage system, which will be tracked as a timeline event for any samples it contains, in this topic: Move Stored Samples.

Remove Storage Unit

When removing a storage unit from a storage system, first check to ensure that the physical samples stored there have been moved to new locations in the system, otherwise you will lose the tracking data associated with the first location.

Learn more about moving samples in this topic: Move Stored Samples.

Change Storage Unit Type

If you find you need to change the type of a storage unit, either because the wrong initial type was created or because your labelling system has been changed, first create the new/corrected unit "parallel" to the one you are replacing.

  • If you are changing a non-terminal storage unit (such as replacing a shelf with a rack) you can drag the contents of the old unit into the new one.
  • If you are changing a terminal storage unit type, such as a box, you must specifically move the samples from the old to the new unit.
Once the "old" unit is empty, it can be removed.

Related Topics




Manage Storage Locations


Organizations managing multiple storage systems may find it helpful to organize them by Physical Location, particularly when they may be in different rooms, on different floors, or even in different buildings across a campus.

You could keep track of locations of your storage by using the "Description" field in the Storage Definition, but those details are only available in some areas. By configuring your Physical Location hierarchy within the application, all users can see this information in the application interface.

Notes:

Configure Location Options

Identify Hierarchy

To get started, identify the hierarchy of locations you need. For example, you might have two buildings with various possible storage locations in one and a single possible location in another. For example:

myInstitution

├───Building 101
│ ├───2nd Floor
│ │ ├───Room 2A
│ │ └───Room 2B
│ └───3rd Floor
│ ├───Lab - Rm 42
│ └───Storage Center

└───Building 202
└───Storage Center

Storage systems could be located at any level of this hierarchy, such as "Building 202", if you do not know (or need) details about which floor or room within the building.

Manage Locations

From the Storage List on the main or storage dashboard, click Manage Locations.

Similar to defining a hierarchy within a storage system, drag and arrange the locations you want to have available for placing storage systems. Four pre-defined "levels" are available, "Site, Building, Room, Other".

You don't need to use every level, and can rename any location type to suit whatever naming or structure you like. There can be multiple 'root' locations (such as "Building 101" and "Building 202" shown above). Once you've arranged your location hierarchy, click Finish Editing Locations to save it.

If any storage systems are already defined, you'll see them in the lower left and be able to drop them into any level of the hierarchy from here.

Again, click Finish Editing Locations to save.

Set Physical Location

Once you have set up your Physical Locations, you can either place existing storage systems into their locations, as shown above, or edit the definitions to specify a physical location for each storage system.

From the main menu or storage dashboard, click the name of the storage, then select Manage > Edit Storage Definition. Under Physical Location, click Select Location.

In the popup, browse the hierarchy to find the physical location for this storage.

  • You could also click Manage Locations here to add or change the location hierarchy. After making changes, you'll return to editing the storage definition.
  • Click to select the desired location, then click Apply.
Click Finish Updating Storage and notice that the Storage Details panel now lists all 'levels' of the selected location.

Use Physical Locations

Unlike any location information you might place in the description field, these locations will be shown on the storage dashboard and in the selection popups when deciding where to store or move samples.

When viewing storage details for a sample, you will see both the physical location of the storage it is in (in gray), and the storage location for that sample within that storage system (in blue). You can click the blue locations within the storage for a grid of all samples stored with the one you are viewing.

Both "paths" including the slash separators can be copied and pasted outside the server for use in building spreadsheets for import or other use.

Truncated Display of Long Location Paths

When a path is long, it will be truncated for easier display. The first and last locations will be shown with an ellipsis … representing all levels between them. Hovering over the truncated location will show the full location path.

Related Topics




Move Stored Samples


This topic describes how to move Samples from one storage location to another. Samples can be moved within a given storage unit, i.e. to a different position within a structured layout like a box or plate, or the entire storage unit can be moved at once to a new storage location.

To move samples in storage, the user must have been granted the Storage Editor role. To move entire storage units, i.e. to change the structure of the storage system, the user must have the Storage Editor role in the top level of the application.

The interface for moving samples is very similar to that for adding samples to storage originally.

Move One Sample

To move a single sample, you can select Manage > Move in Storage from the details page.

You can also click the current storage location to begin the move from the Storage View, making it easier to move the sample to another position within a given storage unit.

Move One or More Samples from Grid

Select the sample(s) from any sample grid and select Storage > Move in Storage. On narrower browsers, this option will be under the More > menu.

Move Samples From Storage View

Navigate to the Storage View of the place where the sample(s) are currently stored. If you are starting from the Sample details page, click the location box in the Storage Location panel.

You can also click the In storage link on the sample grid to go directly there.

From the Storage View, with the sample(s) selected, you will have a Move button if you are authorized to move samples.

Select New Storage Location

The popup for moving samples uses the same interface as originally adding samples to storage. In the first step, you'll select the new storage location. Use the search bar to find locations by name or label.

When you start from the storage view for a group of samples in the same box, plate, or tube rack, the current location will be preselected offering the option to move the selected samples within the same storage unit. You can browse to a new location if desired.

Once you select a location, click Select Positions. Options to for manually or automatically placing samples (choosing fill order, starting position, and fill order) are the same as when adding samples to storage originally. The default fill order is to use the Original Order prior to this move. Adjust the new positions of the samples before clicking Move to [Type of Storage Unit] to complete the move.

Move Samples to or from Multiple Locations

When selecting new storage locations for a selected group of samples, the same interface applies to adding samples to storage originally, in which if you select a new location that doesn't have room for all the samples you are moving, you'll be prompted to continue selecting additional locations for the remaining samples. Learn more in this topic:

If you want to move a collection of samples that are stored across multiple storage locations, either filter a sample grid to select them by any criteria that will identify them, or build a "Samples to Move" picklist to create an easy temporary grouping of the samples to move. When in the sample-move interface, you can then select one or more new sample locations as if the current group were not currently stored across multiple locations.

Move a Storage Unit

A storage unit can be moved to a new location either in the same storage system or in a different one by clicking Move Storage Unit. When any storage unit is moved, all the samples, as well as any other storage units contained 'within it' are also moved. When using multiple folders, moving storage units is only available to users with the Storage Editor role in the top-level home, i.e. the level where the storage system is defined.

View the unit you want to move, either in the storage overview, or the storage view for that unit, then click Move Storage Unit.

In the popup, use the to expand the storage list and location hierarchy to find the target location. Select it and click Move Here.

A success banner will be shown, giving you a quick link to navigate to View new location. Unless you click it, you will still be in the original storage location where the unit was previously.

  • If you move a storage unit containing samples, any samples it contains will stay with the same position assignment(s) within the storage unit.
    • See below for an alternative method for moving within a storage system.
Any move of a storage unit will be tracked as a "Storage Event" on the timeline for all the samples it contains. Learn more in this topic: View Storage Activity

Move Within Current Storage: Edit Definition Method

If you are moving a storage unit within a storage system, you can also edit the definition to relocate that box to its new location, as described here:

Open the storage details page by clicking the name on the main menu.

  • Select Manage > Edit Storage Definition.
  • Click the Storage Hierarchy section.
  • Use icons to expand sections.
  • Lock icons are shown on any storage units containing samples, indicating that you cannot change the size or type of the units, but you can move them within the storage here.
  • Locate the storage unit you want to move. Shown below, Box#1 - Green" used to be on Shelf #2/Rack #1 and is being moved to Shelf #1.
  • Click Finish Updating Storage.
Learn about how a move event is tracked for samples in this topic: View Storage Activity

Change a Storage Unit Type

In order to change the type of a storage unit, such as to change the size or layout of a box, you can edit the storage hierarchy prior to storing any samples in the unit. Once samples are stored, however, you cannot edit the unit type, but instead need to accomplish this change as a sample move. First create the new storage unit, then move the samples to it. In the case of moving samples from a smaller to a larger box, you could choose to maintain the row and column layout positions, but this is not required. The new unit can be in a different storage location or could be in the same location as the previous unit.

Note that while this operation is recorded as a move for the samples, there is no "location history" connection between the original box and the different sized box.

Related Topics




Manage Stored Samples


This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.

Many sample creation and management actions for samples in storage can be completed directly from the storage view, simplifying the process. This topic outlines these options for stored samples:

Video Walkthrough

Watch the process of working with stored samples, including checking them in and out and removing them to release the storage locations for other samples:

Create Samples from Stored Samples

When viewing samples in storage, you can create new derivatives, pooled samples, and aliquots directly. Use the grid view and select the Sample Type of the parent samples from which you want to create new ones. Choose the desired action from the Derive menu (under More > on some browser widths).

In the popup, select whether to create Derivatives, Pooled Samples, or Aliquots, specify how many new samples to create, then click Go to Sample Creation Grid. Enter the details as for other sample creation, then click Finish Creating ## Samples.

You'll see the green success banner and can immediately click Add them to storage if desired.

Add Stored Samples to Picklists and Jobs

To simplify storage workflows, you can also select samples in storage views and create new picklists and workflow jobs including them, or add them to existing picklists and jobs. You can use the tabs for the specific Sample Type, where you'll use the usual sample grid menus. Or from the "All Samples" tab or a storage grid view, select samples and choose the desired action from the Picklists or Jobs menu. Note that on narrower browsers, these buttons will be combined into a More menu.

Learn more about these processes in these topics:

Edit Storage Details

When a sample is initially added to storage, an initial freeze/thaw count can be provided (for temperature-controlled storage). The storage amount can be provided when the sample is first created or at any other time. If you need to edit these settings later, you can do so by clicking the sample, and clicking either icon in the Storage Details section to open an edit panel.

Update the information in the popup, enter a Reason for Update if required or desired, then click Update Sample to save your change. The reason will be retained in the audit log and timeline for the sample.

Remove Samples from Storage

The action of removing a sample from storage does not result in removal of the sample information from the system, only that it is taken from an "In Storage" state to a "Not in Storage" state and the freeze/thaw count and storage location are dropped. This could be related to the consumption of all of the sample, and thus it's no longer being available, or could be temporary and the sample could be returned to storage later.

If instead you want to delete all data related to a Sample, follow the instructions here: Delete Samples.

Removing samples from storage will:

  • Remove them from your storage location views.
  • No longer retain their freeze/thaw counts (or allow them to be updated).
  • Prevent any further check outs or check ins.
  • NOT delete the data stored in the system about the samples.
When you remove a Sample via any of the methods described here, you have the option to update the status and amount of the sample.

You can remove one or more Samples from Storage in many places throughout the application, including:

  • From the Sample details page, select Remove from Storage from the Manage menu.
  • From a grid of Samples, select samples using the checkboxes and select Storage > Remove from Storage.
  • From the Storage View of the Sample(s) location, select the sample(s), then click Remove.

Update Status and Amount of Removed Samples

In all methods of removal from storage, you will see a popup detailing the sample(s) you selected to remove. You'll see their locations, a color indicating type, and position information.

Use checkboxes to optionally update Sample details upon removal:

  • Set Sample Status: assign a new sample status at this time. By default, the status will be set to "Consumed" (as long as that status is defined). You can change this default as desired.
    • If you uncheck this box, all samples will be left with the status they had at the time of removal.
  • Update Sample Stored Amount: provide a new amount for all removed samples. For example, consumed samples might now have a zero amount.
    • If you uncheck this box, the samples will retain the amounts they have at the time of removal.
Enter a Reason for Removing to accompany the action, if required or desired, then click Yes, Remove Samples.

After removal, the Storage panel for a Sample will still show the amount set for the sample, and the time of removal, but will not retain the freeze/thaw count.

Export Storage Map

When viewing a terminal storage location, you can export a printable Storage Map to Excel. This can be useful when sharing with colleagues or to provide detailed data access for users going into a physical freezer location where there is no internet.

From the stored samples grid, choose > Storage Map (Excel).

The exported Excel file will provide a grid "map" matching the layout in the UI, providing details about the individual samples in each location. The default grid view of the Sample Type is used in this view, and on the right is a legend indicating the columns represented by each cell.

Related Topics




Check Out and Check In


This topic describes how a user would check a sample out of storage, such as for use in running an assay, and then check it back in later, recording the volume consumed as well as incrementing the freeze/thaw count where applicable. Note that to check samples in and out of storage, the user (or administrator) must have been granted the Storage Editor role.

Watch the process of working with stored samples, including checking them out and back in:

Check Out

To check out samples, you have many options in the interface:

  • Navigate to the storage location, select the sample or samples you want, and click Check Out.
  • From any grid of samples, use checkboxes to select the sample(s) you want and select Storage > Check Out. On a narrower browser, this option will be under the More > menu.
  • From the sample details page, select Manage > Check Out to check out a single sample.
In the popup, you will see the specific storage location, and be able to enter a Reason for Check Out that will be recorded with this action. In the Professional Edition, an administrator can set the system to require reasons be provided, otherwise they are optional. Note that when you check samples out of the system, their storage locations are reserved while they are checked out.

Click Check Out Sample(s).

While samples are checked out, they will show "Checked out" as their Storage Status in any grids. Click the linked "Checked out" message to go directly to the storage details for that sample.

Check In

When finished with a sample, you also have several options:

  • Navigate to the storage location, select the space(s) reserved for the sample(s) you are checking in, and click Check In (shown below).
  • You can check one or more samples in from a samples grid by selecting the row(s) for the sample(s) and choosing Storage > Check In.
  • From the sample details page for a sample that is currently checked out, you can select Manage > Check In.
  • In the popup:
    • Enter the Amount used during checkout.
    • By default, the system will Increment freeze/thaw count on check in, under the assumption that you thawed the sample to use it and it will freeze again. If this is not true, you may uncheck this box.
    • Enter Reason for Check In if required or desired.
  • Click Check In Sample(s).

Once your sample is checked back in, you will notice the Stored amount has been decremented by the amount you used, and the freeze/thaw count incremented by one unless you unchecked the box.

Note that the units for entering the amount you used defaults to the units set for the Sample Type, but this can be adjusted if needed, within the liter or gram set of units available (i.e. if you are measuring in mL, you could have used uL or L). The system will convert the measurement in the units you enter to decrement the correct amount from the stored total which will always be shown in the storage unit set for the type.

Related Topics




View Storage Activity


This topic describes how to view and audit Storage Activity of samples, including adding and removing samples from storage as well as check-in and check-out actions. Having an efficient way to keep track of where you have been working, or where others might be storing similar materials can help administrators make informed choices about where to store new samples.

Your Activity

From the main menu, click Storage, then click Your recent sample activity.

You can sort, filter, and search the grid to find items of interest.

  • Click a Sample Id to see the details for a sample.
  • Click a storage Status ("In" or "Out") to jump directly to the Storage View of the location for that sample, whether it is currently checked in or out.
    • Note that the Status column is always updated to the current storage status of the sample, not the status at the time of the activity in this grid. For example, samples that were "removed from storage" could still have the current status of "In" if they were re-added to storage later, perhaps in a different location.
You'll also see a subset of your most recent storage activity on the main Storage dashboard.

Stored Items

From the Storage dashboard, click the message View #### total samples in storage in the Sample Activity panel. Here you'll see a grid of all items in storage throughout the system. You can view all samples at once, or use the tabs for each sample type to access sample grid menus for samples of that type.

Scroll to see additional columns, including information about who completed the various storage activities listed.

You can also reach this page from Your recent sample activity by clicking the Stored Items tab.

Sample Timeline: Storage Activity

Like other events that happen for an individual sample, storage events will be included on the Sample Timeline, including adding samples to storage, checking in and out, updating storage data, moving the storage unit that contains the sample, and removing the sample from storage.

In the case of moving a storage unit from one location to another, the event details for all samples contained in that storage unit will give you a full 'breadcrumb' path to both the old and new locations of the individual sample.

Audit Log: Storage Management Events

Storage management events are logged in the application's Audit Log. From the pages for a storage system, select Manage > View Audit History to open the audit log filtered to that specific storage system.

Scroll for more columns, and as with other grids, you can create custom named views for the audit tables.

Related Topics




Migrate Storage Data into LabKey


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

Define Storage

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

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

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

If you have a large storage systems to define, you may be able to use the Storage Management API to do so programmatically.

Templates for Sample Storage

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

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

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

  • StoredAmount
  • Units
  • FreezeThawCount
  • StorageLocation (A slash-delimited "path" to the terminal storage location - see below)
  • StorageRow
  • StorageCol
  • StorageUnit (The type of the storage unit; required when defining new storage during import)
  • StorageUnitLabel (A label for a new storage unit)
  • EnteredStorage (Date)
  • CheckedOut (Date)
  • CheckedOutBy (UserID)
  • StorageComment

Data Format Requirements

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

Adjusting Storage Fields to Match Other Systems

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

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

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

Add a sample to storage

  • The StorageLocation and StorageRow columns must be present and valid.
  • If adding to a Box, the StorageCol column must be present and valid.
  • If adding to a Bag, the StorageCol column must be absent or empty.
  • Other fields may be present but are not required.
Add a sample to new storage created in this row of the spreadsheet
  • The StorageLocation column must be present and contain the path ending in the new terminal storage for this sample. Any locations along this path, including the freezer itself, will be created if they don't exist.
  • The StorageUnit column must be present and the value must match an existing storage unit type.
  • The StorageRow columns must be present and valid.
  • If adding to a Box, the StorageCol column must be present and valid.
  • If adding to a Bag, the StorageCol column must be absent or empty.
  • Other fields may be present but are not required.
Remove a sample from storage
  • SampleId column must be present and not empty.
  • At least the StorageLocation column must be present and empty.
  • If the StorageRow and StorageCol columns are present they should also be empty.
  • No other storage metadata columns should have values.
Update the metadata of an item in storage
  • SampleId column must be present and not empty.
  • The corresponding metadata columns should be present.
  • If the StorageLocation column is present, the StorageRow must be present and, when updating items in a box, the StorageCol column must also be present. All columns must have valid values. If updating items in a bag, the StorageCol column value should be empty if present.
Move a sample to a different location
  • SampleId column must be present and not empty.
  • The StorageLocation column and the StorageRow column must be present with valid values. If moving to a Box type, the StorageCol column must also be present with a valid value. If moving to a bag, the StorageCol column must be empty if present.
Check out a sample that is currently in storage: Here the behavior is slightly different than for the other actions because there are two columns involved and we allow a user to shortcut supplying one of the columns in order to use the current date or user for all the rows in the file.
  • SampleId column must be present and not empty.
  • Either the CheckedOut or the CheckedOutBy column must be present and not empty.
    • If the CheckedOut column is valid and the CheckedOutBy column is empty/absent, the item will be checked out by the current user.
    • If the CheckedOutBy column is valid and the CheckedOut column is empty/absent, the item will be checked out by the user in the CheckedOutBy column using the current date.
  • If both the CheckedOut and the CheckedOutBy columns are present, they must both have valid values.
  • If both the CheckedOut and the CheckedOutBy columns are empty, the system will not recognize this as a checkout action.
Check in a sample that is currently checked out
  • SampleId column must be present and not empty.
  • One of the CheckedOut or CheckedOutBy columns must be present and empty.
Storage Comments: The StorageComment will be attached to the operations that are happening for the import if the operation is also one the user can comment on in the UI. That is, for check out, check in, and removal actions, the comment will be attached. Otherwise, the comment will be ignored.

Notes:

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

Import of Samples with Storage Location Data

Once your spreadsheet is ready:

Work with Stored Samples

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

Related Topics




Workflow


Premium Feature — Available in the Professional Edition of Sample Manager and the Starter Edition of Biologics LIMS. Learn more or contact LabKey.

LabKey Sample Manager makes it easy to plan and track your tasks with these lab workflow features:

  • Create jobs to track and prioritize sequential tasks
  • Assign work to the right users
  • Use workflow templates to standardize common task sequences
  • Track progress toward completion

Administrators and users with the Workflow Editor role can create and edit workflow jobs and tasks. Only administrators can create job templates.

Topics

Tutorial

Get started with workflow in the Sample Manager tutorial step: Tutorial: Outline Workflow.

Related Topics




Start a New Job


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

Workflow jobs organize related tasks into a sequence of work to be completed. A set of samples to be worked on can be associated with the job, and it can include direct links to upload data for the necessary assay tests performed on those samples. You can start by selecting samples directly from a grid, or use a picklist as a starting place.

Administrators and users with the Workflow Editor role can create and edit workflow jobs and tasks.

To start a job, you can either start by selecting the samples you want worked on, or add them to the job later. It's also possible to have jobs that do not involve samples, if that supports your lab workflow.

Before creating a new job directly, consider whether you want to make the details, tasks, and files you'll use available as a template for creating similar future jobs. Samples are never part of job templates. Learn about creating job templates in this topic:

Start a Job

There are several ways to open the job creation wizard:

  1. From the home page, click Start a New Job.
  2. From the main menu, choose Workflow, then click Create Job.
  3. Select some samples, then use Jobs > Start a New Job from any Sample or Picklist grid. On narrower browsers, this option will be under the More > menu.
This final option is described next. If you are creating a job without pre-selecting any samples, skip ahead to the Job Details section.

Start a Job with Selected Samples

If you already know the set of samples you want to include, start from the Sample Type grid, storage view, or from a picklist containing the desired samples. This walkthrough illustrates using the Sample Type grid, but the process starting from other lists of samples is the same.

  • Select the sample type of interest from the Sample Types section of the main menu.
  • Use filtering and checkboxes to select the Samples of interest.
  • Select Jobs > Start a New Job from the menu above the grid. On narrower browsers, this section will be under the More > menu.

Job Details

On the first panel of the job creation wizard, enter details about the job:

  • Job Name: Provide a name for the job, or leave blank to have one generated for you.
  • Description: Include a description. Note that to include a newline, you must use Shift-Enter; using Enter without Shift will save the description value as a single line.
  • Job owner: This can be the user who "owns" the overall job completion, or the user to whom you assigned the first task.
  • Notify these users: Add users who should get notifications as this job progresses. Users on this list will be able to follow this job on their tracked jobs list.
  • Job start and due dates: Use the date picker to select the begin and end dates.
  • Priority level: Use the pulldown menu to select one of the options:
    • Low
    • Medium
    • High
    • Urgent
  • Attachments: Select or drag and drop any files needed for the job. For example, an SOP document, labels, or other instructions related to the job could be included here.
    • Any files you upload will be listed; if you need to delete one, click the to remove it.

Tasks

Click the Tasks section to open it.

Any job can be composed of several tasks to complete in sequence. Click Add Task to add each task and click to open the details panel.

For each task in your job, enter the details:

  • Name
  • Description: Note that to include a newline in your description, use Shift-Enter; using Enter without Shift will save the value.
  • Assign to
  • Assays to Perform (select as many as required for this task)
  • Due date
Use the six block handle on the left to reorder the tasks. Click to delete a task.

Input Samples

Click the Input Samples section to open it. If you created this job from a set of samples, it will open on the Included Samples tab and you will see them listed. If not, skip ahead to search for samples

Included Samples

  • Review the listed set of included samples; if necessary select one or more rows and click Remove from Job to remove them.
  • If you like, you can use the Search for Samples tab (described below) to add more samples.
  • When you are satisfied with the selection of samples, skip to the Finish Creating Job section.

Search for Samples

  • If you did not start creating this job from a selection of samples, when you open the Input Samples panel, click the Search for Samples tab (if it is not open by default).
  • You can search for names or attributes in the search box. Click Search.
  • Click Show Filters to see a set of selectors for filtering to find the samples you want. Options:
    • Of Sample Type
    • Created by
    • Date Range From/To
  • Make selections for some or all filters, then click Search. This will populate the search results in a grid below the filter section.
  • Scroll, or use filters and sorts to find desired samples.
  • Check the boxes to select the samples you want to include. Once samples are selected, the "Add to Job" button will be activated.
  • Click Add to Job.
Now, if you click the Included Samples tab, you will see the samples you added. You can return to Search for Samples again if you need to add more.

Finish Creating Job

Click Finish Creating Job to start the job. You will see the job overview. Note the tabs along the top edge for viewing Tasks, Samples, and Assays in addition to the Overview.

Create Job From Template

You can create a job from a template you have already saved, with or without the preselection of samples. Creating a job from a template follows the same wizard process, but the details and tasks are prepopulated.

  • At the top of the job creation page, click Choose Job Template.
  • Find the template you want to use; typing ahead will narrow the options.
    • If you have already defined any tasks before applying a template, you will be warned that the template will override any existing information in your job. Cancel to retain your current tasks.
  • Click to see details for any template, including creation details, number of tasks, and the description.
  • Click Choose Template.
When a template is applied, the template tasks will be prepopulated in the job wizard. You will see a From Template section on the Job Details. You can click in the banner to remove the template if desired.

Add Job Details and Priority

The template does not prepopulate the Job Details and Priority panel; complete it as when you are creating a job without a template as described above.

Define Job Tasks

The job tasks from the template are prepopulated in the job creation wizard. By default these tasks are locked. You can assign tasks to users and add due dates without editing tasks. If the template allows editing of the assays in jobs using it, the Assays to Perform box will be unlocked on all tasks so that you can define assays to run for this job.

If you want to make any changes in the tasks for this job, click Edit Tasks and edit using the same interface as when you create tasks without a template. Note that editing job tasks will remove the template association from the job details as well as remove any files associated with the template from this job. You'll be asked to confirm before proceeding.

Complete Wizard

When you are defining a job starting from a template, the section for Input Samples is the same as above for creating a job that did not start from a template.

When you have completed all the sections of the job creation wizard, finish as described above.

Jobs that were created from templates show the template name on the Overview tab of the job details. Click the job name to open the job details, then click the template name to open the template itself.

Related Topics




Manage Job Queue


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

Once jobs and tasks have been created and assigned to you, you will immediately see your own work queue from the home page in the Jobs List. You can also easily see information about jobs assigned to others.

Jobs List Dashboard Panel

On the home page, the Jobs List shows Your Job Queue by default. This is the list of jobs that are either assigned to you or include tasks assigned to you. Filter your queue by Priority Level using the dropdown.

You can switch to Active Jobs by clicking the tab, and the view will show jobs assigned to others as well.

Click the name of any job to see the job details and task list.

Workflow Home

Click Workflow Home or select Your Job Queue from the main menu to see the jobs list in grid form.

By default, you'll see Your Job Queue sorted by due date. Like other grids, you can use filtering, sorting, searches, and custom views on the grid of jobs.

The tabs each show the count of jobs in the different categories:

  • Your Job Queue: Jobs and tasks assigned to you.
  • Your Tracked Jobs: All Jobs in which you appear on the Notify List. This list is initially filtered to those jobs that are currently "In Progress".
  • All Active Jobs: Jobs that have not been completed, including but not limited to the ones in your own queue.
  • Completed Jobs: Jobs that have been completed.
  • All Jobs: All of the above.
Click the name of any job or template to see the details and task list.

Administrators have more options for managing jobs, as described in this topic: Manage Jobs and Templates.

Your Job Queue

At any time in the application, you can select Your Job Queue from the Workflow section of the main menu to jump to a detailed view of your own work assignments.

Your Tracked Jobs

You can access a grid of all jobs which include you on the Notify List by selecting Your Tracked Jobs from the Workflow section of the main menu.

By default your tracked jobs are filtered to show those with the status "In Progress". Hover over the filter and click the "X" to clear it.

Related Topics




Complete Tasks


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

This topic covers the process of marking tasks and jobs as completed. It is important to note that there is no checking that the work specified in the tasks in question was actually completed in the lab; these tools offer a tracking mechanism for humans completing their work.

Open a job by clicking the job name. Find it:

  • On the Jobs panel on the home dashboard under Your Queue if it is assigned to you. You can filter by priority to find the most pressing work.
  • If the job or current task is not assigned to you, you can click the Active Jobs tab on the home page.
  • Use the main menu from anywhere in the application. Click Jobs List under Workflow for the grid of all jobs.

Topics

Overview Tab

On the Overview tab, you will see the job details, assignments, and list of tasks with status of each task. Status values include:

  • In Progress: the current/active task to be completed
  • Pending: future tasks that need to wait for the 'in progress' task
  • Complete: completed tasks.

Learn about editing job details in this topic: Edit Jobs and Tasks

Tasks Tab

Switch to the Tasks tab to see a more detailed view of job progress. Each task is listed on the left, with details of the selected task on the right.

Completed tasks show a green check. Tasks that involve assays include links to View Data | Import Run.

Switch among tasks by clicking the task name on the left.

Comments

On the Tasks tab, you can enter Comments to accompany any task, including the ones marked completed. Click Start a thread to add a new comment.

Add your own comments or notes about the step in the box.

  • You can use markdown formatting, with the help of buttons for bold, italic, link, list, and numbered list formatting.
  • Switch the Markdown mode dropdown to Preview to see the formatted result.
  • Click the to attach files to comments.
  • Click Add Comment to save.
Once a task has one or more comments, you can reply to existing comments or start another new thread.

Email notifications will be sent when comments are added to tasks. The email will include a link to the task itself.

Complete Task

If the 'In Progress' task is assigned to you, and you have performed the actual work described, you can click Complete Current Task on the Overview tab (or Complete Task on the Tasks tab) to mark it completed. The task status changes to Complete and the next task on the list is now In Progress.

If the 'In Progress' task is not assigned to you, the button for completing the task will be inactive so that you cannot inadvertently complete others' tasks. Administrators are exempted from this restriction and can both mark any task as completed and reassign tasks as needed.

Complete Tasks with Samples

When your task involves samples, you can access and review them on the Samples tab. Samples of all types are shown on a shared All Samples tab, with common properties like storage information and status. The samples of an individual type are available on additional tabs ("Plasma" and "Serum" shown here), with the properties specific to that type.

Actions available on the tabbed sample grid:

  • Add Samples
  • Remove Samples
  • More: Other menus vary based on whether you are viewing all samples or samples of only one type. Learn more about the options in this topic:
  • Data Grid Basics

Complete Tasks involving Assay Import

On the Tasks tab, select the task that involves an assay. Under Assays, you'll see a pair of links for each assay involved in this task.

  • View Data: Once there has been data uploaded for this assay in this task, this link will take you to the filtered run.
  • Import Run: Open the importer for the requested assay.
    • If there are samples assigned to the job, by default you will see the Enter Data into Grid option, with rows prepopulated for the samples assigned, making it easy to manually enter values.
    • You can also use bulk insert, update, and Import Data from File methods if desired.
Once the import is complete, you can click here in the green banner to return to the workflow job you came from.

Reassign Task

From the Tasks view, users with sufficient permissions can reassign tasks that have not been completed by changing the Task Owner. Use the dropdown to select the new task owner.

Reopen Task

If you find you have closed a task by mistake, you can reopen it using the Reactivate Task button.

Related Topics




Edit Jobs and Tasks


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

This topic covers editing and updating workflow jobs and tasks. Administrators and users with the Workflow Editor role can edit workflow jobs and tasks.

Update Job Details

In the left-hand panel you can edit many common job details including Owner, Notify list, Priority Level, Start and Due Dates, and the Description. Use dropdowns or icons to edit. Click outside the selection area for an element to save changes.

You can also use Manage > Edit Job to edit all job details.

Rename a Job

To change the name of the job, click the next to the name, type the new name and hit return (or click away) to save.

Add or Delete Files from a Job

Files attached to a job are shown in the Attachments section on the Overview tab.

  • Add a new file using the Select file or drag and drop here box.
  • Use the menu to:
    • Download
    • Remove Attachment

Manage Menu

The Manage menu includes:

Edit Tasks: Add, Reorder, Edit, Delete

Note that you cannot edit any tasks that have been completed. You also cannot edit tasks in a job that was created from a template, or in a job from which a template was created. A banner message and icons will inform you when tasks are not editable. The process in this section applies to non-template jobs with tasks that may be edited.

To adjust the tasks involved in the job, select Edit Job from the Manage menu. You will see the same interface you used to define job details, tasks, and samples.

  • Click the Tasks section.
  • Any tasks that have been completed (or are part of a template) cannot be changed and will be shown with a icon.
  • Add more tasks via Add Task. (You cannot add tasks to a job created from a template.)
  • Reorder tasks by dragging and dropping the six-block handle on the left.
  • Delete a task by clicking the icon on the right.
  • Click a task panel to open the details for editing.

Make the necessary changes and click Finish Updating Job when you are finished.

Edit Samples Assigned to a Job

While editing job tasks, you can use the Input Samples section to adjust the set of samples within the job. You can also click the Samples tab from within the job and click Add Samples to open the same interface.

Follow the instructions in this topic to search for samples within the job wizard. If you only need to add or remove samples, it may be easier to follow the steps below to add or delete samples from jobs.

Add Samples to a Job

From the main menu, click the name of the type of samples you wish to add to open the grid of available samples. Alternatively, choose Picklists from the user menu and click the name of the curated picklist you want to use. Select the desired sample(s) using the checkboxes and select Jobs > Add to Job. In the popup, select the desired job by name from the dropdown. Click Add to Job.

If you attempt to add samples that are already included in the job, they will be skipped automatically and only new samples will be added.

Delete Samples from a Job

Open the job and click the Samples tab. Select the sample(s) you wish to delete and click Remove Samples.

Reactivate Closed Task

To reactivate a closed task, click the Tasks tab in the upper left, then click the name of the closed task to select it. It will be shown with a green check icon. In the following image, "Prepare Samples" is in a closed state. Click Reactivate Task.

You will be asked to confirm the action, and when completed, the checked box icon will disappear and the task will be restored to an "In Progress" state. You may also want to add a comment to the task when you reactivate it, explaining the reactivation.

Reactivate Completed Job

If you need to reactivate a job that was marked completed, find it by opening the Workflows page from the main menu and clicking Completed Jobs. Click the desired job name to open it.

Click Reactivate Job. You will be asked to confirm the action.

When you reactivate a job, the last task of the job is also automatically reactivated. If you would like to reactivate additional tasks, follow the steps above.

Delete Job

Learn about deleting a job in this topic:

Related Topics




Create a Job Template


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

Using job templates makes the creation of many similar workflow jobs simpler and more consistent. A template can include a common set of procedures and tasks, and new individual jobs can be created from this common template and refined as needed.

The job template creation wizard is very similar to the steps involved in creating a new individual job, with the exception that samples and job details will be added to an individual job separately. No work is assigned within a template. You can also create a template during the process of creating an individual job, as described in Start a New Job.

Only Administrators can create job templates.

Create a Job Template

To create a new job template:

  • Select Templates from the main header menu Workflow section.
  • Click Create Template.

Click each section in the wizard to define template details and job tasks.

After completing all sections, click Finish Creating Template to save.

Template Details

Enter the Template Name and Description. The name should be unique enough to help users find it on a menu.

In the Fields section, add any custom fields you want included. Learn more below.

In the Attachments section, upload any files that should be available to any jobs created from this template.

Tasks

Click the Tasks tab and define the tasks. For each, enter the Name and Description and select any Assays to Perform as part of that task. If you want to allow jobs that use this template to be able to change which assays should be performed, check the box to Allow Edit of Assays in Job.

Click Add Task to add additional tasks, use the six-block handle to reorder them, and click to delete an unneeded task.

Finish Creating Template

Click Finish Creating Template when finished. You'll see the new template overview.

Notice in the upper left that there are tabs for viewing any Files associated with the template and for viewing any Jobs created using it.

Custom Fields

Workflow job templates can include custom fields to support standardizing various workflows. These custom fields are defined using the standard field editor when creating or editing a template. You might include fields you want every user to complete, such as a billing code or site identifier. Custom fields can be required, and can be of any standard field type, including lookups and text choice fields for limiting user choices.

Custom fields will be shown to users in various places during workflow management:

  • During job creation when users choose a template, they'll see a summary of fields.

If desired, during job creation, fields can be assigned values.

  • The name of the section includes the name of the template.
  • Required fields do not need to be populated at this time; they must have values before the job is completed.
  • On the job details panel, you'll see and can populate custom fields by clicking the .

When you complete the final task for a job, if any required fields have not been completed, the user will see an error message like "Error while completing task: Cannot complete final task until all required job details are provided:..." with a list of the fields required.

Note that custom fields are included only in the jobs attached to the template where they are defined. If a user 'detaches' the job from the template (removes the association), they will be notified that any custom fields will also disappear.

When users view the Jobs tab for a source or sample, it will include a tabbed grid of all jobs for that entity, showing all jobs on the first tab, plus an additional tab for jobs from each specific template used (by name). These template-specific job grids show the custom fields for that template with values for the sample you are viewing.

Related Topics




Manage Jobs and Templates


Premium Feature — Available in the Professional Edition of Sample Manager. Learn more or contact LabKey.

This topic covers options available for administrators to manage jobs and templates. You will find the active lists of jobs and templates and manage options in the Workflow section.

Administrators and users with the Workflow Editor role can create and edit workflow jobs and tasks. Only administrators can create job templates.

Manage Jobs

From the home dashboard, click Workflow Home or from anywhere in the application, select from the main menu:

The All Jobs tab shows the full list of jobs. Other tabs provide subsets.

Edit Jobs

To open an individual job for editing, click the Job Name. Details of editing jobs and tasks are covered in this topic:

Delete Jobs

To delete one or more jobs, use the checkboxes on the Job List to select jobs for deletion, then click Delete.

If a job is referenced in a Notebook cannot be deleted. When deleting multiple jobs, if any of them cannot be deleted, you will see a warning and be able to proceed to delete the jobs that are not referenced.

You can also delete a single job by opening it and selecting Delete Job from the menu next to the name. Enter a reason for deletion if desired or required.

Manage Templates

Templates are managed by clicking Templates in the Workflow section of the main menu, or by selecting Manage > Job Templates from the workflow dashboard:

Open an individual template by clicking it's Name. The template overview shows a summary of tasks and assays. In the upper left, you can click the Files tab to see files that are part of the template and on the Jobs tab you'll see a listing of jobs created from this template.

Edit Template

To edit a template, open it as shown above and select Manage > Edit Job Template.

For any template, you can edit the Name and Description, and add (or remove) custom fields.

Before a template is used to create jobs, you will also see the Attachments panel where you can edit or add attachments. On the second panel of the editing wizard, you can also edit the tasks, letting you iterate and have others review a template before use. Once a template has been used to create a job, you cannot edit the tasks (or attachments) and will see a blue banner indicating this.

Once you've finished editing, click Save. Editing a template does not change any jobs that have already been created from the previous version of the template.

Copy Template

To make a new template using an existing one as a starting point, select Manage > Copy Job Template.

The initial name of the template will be the original name plus "(Copy)" and the description, tasks, and attachments will match the original template. You can edit the name and other aspects of the template before clicking Finish Creating Template.

Delete Templates

To delete a single template, open the details page as shown above and select Manage > Delete Job Template. Once a job has been created from a template, you can no longer delete it and this option will be inactive.

To delete one or more templates, select them on the Workflow > Templates dashboard page using the checkboxes, then click Delete.

Related Topics




Data Resources





Data Grid Basics


This topic describes how to navigate grids of data in LabKey Sample Manager, and how to filter, search, and sort your data.

Column Header Menus

Click the column header in a grid to access the column header menu:

You can also drag and drop column headers to new positions in the grid. Learn about creating custom grids in this topic:

Column Headers: Field Name and Tooltip

Hover over the column header in a grid to see the full field name. In the case of different labels, or ancestry lookups (or both shown here), it can be helpful to see the actual underlying name of the field:

If the field includes a Description, or other explanatory information, you will see a next to the name. Hover for a tooltip displaying more about the field.

Scroll Large Grids

When scrolling a grid horizontally, the leftmost column, typically the SampleID, will remain 'locked' or visible on the left, making it easy to understand which sample the visible fields are referring to.

When the data grid is long enough to scroll vertically, such as when using a long 'page size' the column headers will remain visible at the top.

Sample Grid Menus

Sample grid menus highlight the most common sample actions and group them by category:

Some menu options require row selection(s) and will be grayed out when no samples are selected. When the browser window is narrower, some menus will be collapsed under More, with sections for each category:

Select Rows

In LabKey Sample Manager, data is shown in grids, with a column of checkboxes on the left for selecting each individual row. Check the box in the header row to select all rows on the current page.

Once you've selected a page of rows, you will see buttons to select all the rows, or clear those already checked.

Page Through Data

Large sets of data are displayed on a paged grid. In the upper right, you see which rows you are viewing (here 1-20 of 824). Buttons give you the following control:

  • and : Step one page forward or back.
  • The page number you are on is shown with a dropdown menu.
    • You can jump to the first page or last page and see a count for the total number of pages.
    • You can also change the pagination. Options for number of rows per page: 20, 40, 100, 250, 400.

Customized paging settings for a grid will be maintained if you click away and later return.

Filter

Use the Filter option on any column header menu, or click the button above the grid to open the filter panel.

Select the column you want to filter on the left, then for any column, you can select one or two filtering expressions on the Filter tab. If your first filtering expression cannot be further filtered (such as "Is Blank") you will not see the second filter option.

For columns with a limited set of values, you can use checkboxes on the Choose Values tab to select the desired values.

You'll see a filter icon in the header when a column filter is applied, as well as a "lozenge" for each filter above the grid.

  • Filter settings for a grid will be maintained if you click away and later return to the same grid.
  • When you hover over a lozenge, the filter icon will become an X you can click to delete that filter.
    • Click Remove all to remove all the filters.

Sort by Column Value

In each header, click the to sort the grid by the values in that column. Select either ascending or descending sort.

Once you have sorted a column, an indicator icon ( or ) will be added to the column header.

  • Sort settings for a grid will be maintained if you click away and later return.

Search Grid

Enter your search terms in the Search box above the grid to search the text fields in the grid. Click the X to clear the search terms.

Multi-Tabbed Sample Grids

When a grid could contain samples of multiple types, such as on a picklist or the View All Samples grid, you'll see a separate tab for each Sample Type as well as an All Samples tab showing only properties common to all types, including the Sample ID, Status, and Storage information. There is a limited set of actions available on this tab that can be used for samples of multiple types, as shown in the first image below. Each individual sample type tab has the full set of grid actions, as shown in the second image.

When there is only one type of sample in the grid, it will open on the specific Sample Type tab. When there are several, it will open on the All Samples tab, as shown above.

Editable Grids

Editable grids can be found throughout the application for entering and editing data for Samples, Sources, Assays, etc. See an example of using editable grids here.

When using an editable grid, you can make use of the following options:

  • Any field that offers a selection menu (Sample Status, Text Choice, list lookups), will be shown with a .
    • Type ahead to narrow the choices and click or tab to select the highlighted value.
    • For example, the Status field in the image below shows an open menu.
    • Hover over the for the Status column to see a legend of available statuses.
  • Some validation, such as confirming data is of the expected type, will be performed as you enter values, giving you an immediate indication of errors.
  • Fields that support multi-select, like sources and parents, will show any existing selection as well as allow you to select more from the dropdown.
    • The Tutorial Labs field below already contains one value, and you can add an additional value as appropriate.

Editable grids provide "locking" of the sample ID column and column headers, so that it's easier to tell which cell is currently being edited.

Drag to Populate Columns

Entering a first value (or row of values), then using the 'drag handle' to apply them to multiple rows is a convenient way to populate a grid.

For a Text field, if you type some text in one field, then select it and grab the "cell-drag handle" in the lower right of the cell, you can drag to repeat it in the remaining cells.

Selecting a set of values and dragging down will repeat the section, including for lookup field selections.

For an Integer or Decimal number, enter two or more values, then select the series you want and drag the handle through the cells you want to fill with the same sequence. For example, below you see two versions of a Number column, one with a single-incrementing integer (1,2 -> 3,4,5) and a decimal incrementing by 2.1 (2.1, 4.2 -> 6.3, 8.4, 10.5).

Date and DateTime fields will also be incremented if you populate one row, then drag, the remaining rows will be one day later.

If your field contains a text prefix with an incrementing number, dragging a section will populate the rest of the column continuing the prefixed-number series.

Cut/Paste to Duplicate Cells

Pasting from a grid of cells, such as 2x2, into a 2x2 area will copy the grid as expected. Pasting into a larger area, such as 4x8, will replicate the pasted grid in the other cells as shown below. The target area may (but does not need to) include the originally selected cells.

Export Data

To export the data in a grid, click the (Export) button and select the format for export:

  • CSV
  • Excel: Learn about exporting a multi-tabbed grid below.
  • TSV
  • If BarTender label printing is configured, you can also export and print labels and templates from this menu.

Notice the menu indicates whether you are exporting rows you have selected or the entire grid. To export the full grid, select no rows.

Multi-Tab Excel Exports

When you export from a grid that contains multiple tabs, such as one containing samples of different types as shown below, the exported Excel file can also include multiple tabs (sheets). Select > Excel, then in the popup, you will see the per-tab Count and which View will be used for each tab. Check the boxes for the tabs you want included in the export and click Export.

Storage Map Exports

When viewing samples in a storage location, you can also export a Storage Map for sharing or offline use. Learn more here:

Related Topics




Data Import Guidelines


This topic covers some tips and tricks for successfully importing data to LabKey Sample Manager. These guidelines and limitations apply to uploading files, data describing samples and sources, and assay data.

Use Import Templates

For the most reliable method of importing data, first obtain a template for the data you are importing. You can then ensure that your data conforms to expectations before using either Add > Import from File or Edit > Update from File.

For Source Types, Sample Types, and Assay Results, click the category from the main menu. You'll see a Template button for each data structure defined.

You can also find the download template button on the overview page for each Sample Type, Source Type, Assay for downloading the template for that structure:

In case you did not already obtain a template, you can also download one from within the file import interface itself:

Use the downloaded template as a basis for your import file. It will include all possible columns and will exclude unnecessary ones. You may not need to populate every column of the template when you import data.

  • For a Sample Type, if you have defined Parent or Source aliases, all the possible columns will be included in the template, but only the ones you are using need to be included.
  • In cases of columns that cannot be edited directly (such as the Storage Status of a sample, which is defined by a sample having a location and not being checked out), these columns will be omitted from the template.
  • Note that the template for assay designs includes the results columns, but not the run or batch ones.

Background Import (Asynchronous Import)

When import by file is large enough that it will take considerable time to complete, the import will automatically be done in the background. Files larger than 100kb will be imported asynchronously. This allows users to continue working within the app while the import completes.

Import larger files as usual. You will see a banner message indicating the background import in progress, and a icon alongside that sample type until it completes:

Any user in the application will see the spinner in the header bar. To see the status of all asynchronous imports in progress, select > View all activity (this menu may be a spinner when imports are in progress).

Click a row for a page of details about that particular import, including a continuously updating log.

When the import is complete, you will receive an in-app notification via the menu.

Import Performance Considerations

Excel files containing formulas will take longer to upload than files without formulas.

The performance of importing data into any structure is related to the number of columns. If your sample type or assay design has more than 30 columns, you may encounter performance issues.

Batch Delete Limitations

You can only delete 10,000 rows at a time. To delete larger sets of sample or assay data, select batches of rows to delete.

Column Headers

Data column headers should not include spaces or special characters like / or \ slashes. Instead of spaces or special characters, try renaming data columns to use CamelCasing or '_' underscores as word separators. Displayed column headers will parse the internal caps and underscores to show spaces in the column names.

Once you've created a sample type or assay data structure following these guidelines, you can change the Label for the field (under Name and Linking Options in the field editor)) if desired. For example, if you want to show a column with units included, you could import the data with a column name of Platelets and then set the label to show "Platelets (per uL)" to the user.

You can also use Import Aliases to map a column name that contains spaces to a sample type or assay field that does not. Remember to use "double quotes" around names that include spaces.

For example, if your assay data includes a column named "Platelets (per uL)", you would define your assay with a field named "Platelets" and include "Platelets (per uL)" (including the quotes) in the Import Aliases box of the assay design definition.

Data Preview Considerations

Previewing data stored as a TSV or CSV file may be faster than previewing data imported as an Excel file, particularly when file sizes are large.

Previewing Excel files that include formulas will take longer to preview than similar Excel files without formulas.

Reserved Fields

There are a number of reserved field names used within LabKey for every data structure that will be populated internally when data is created or modified, or are otherwise reserved and cannot be redefined by the user:

  • Created
  • CreatedBy
  • Modified
  • ModifiedBy
  • RowId
  • LSID
  • Folder
  • Properties
In addition, Sample and Source Types reserve these field names:
Sample TypeSource Type
NameName
SampleIdSourceId
DescriptionDescription
SampleState ("Status") 
MaterialExpDate ("Expiration Date") 
FlagFlag
SourceProtocolApplication 
SourceApplicationInput 
RunApplication 
RunApplicationOutput 
ProtocolProtocol
AliasAlias
SampleSetDataClass
 ClassId
Run 
genIdgenId
InputsInputs
OutputsOutputs
 DataFileUrl
 QueryableInputs
SampleCount 
StoredAmount ("Amount")StoredAmount ("Amount")
Units (units associated with the StoredAmount field) 
SampleTypeUnits (units associated with the Sample Type) 
RawAmount: See below 
RawUnits: See below 
FreezeThawCount 
StorageStatus 
StorageLocation 
StorageRow 
StorageCol 
CheckedOutBy 
CheckedOut (Date) 
IsAliquot 
AliquotCount ("Aliquots Created Count") 
AliquotTotalVolume 

Inferral of Reserved Fields

If you infer a data structure from a file, and it contains any reserved fields, they will not be shown in the inferral but will be created for you. You will see a banner informing you that this has occurred:

Import to Unrecognized Fields

If you import data that contains fields unrecognized by the system for that data structure (sample type, source type, or assay design), you will see a banner warning you that the field will be ignored:

If you expected the field to be recognized, you may need to check spelling or data type to make sure the data structure and import file match.

Migration of Inventory Fields

In version 23.4, some fields from the inventory schema have been migrated and renamed. If you happen to be using the new names in your system as well, this migration can cause conflicts. It is recommended that you keep these field name changes in mind. If you are using any fields listed below for your own purposes, you should rename them prior to upgrading:

Old FieldAction TakenNew Field
inventory.item.volumemigrated (with existing data)exp.materials.StoredAmount
inventory.item.volumeUnitsmigrated (with existing data)exp.material.Units
inventory.item.initialVolumeremoved 

Amount/Units Display Details

The StoredAmount column is labeled "Amount"; the Units field is labeled "Units". Importing data via a file will map either "Amount " or "StoredAmount" to the StoredAmount field.

Both the "StoredAmount" and "Units" fields have display columns attached to them. When a Sample Type also has a display unit defined, the value displayed in the "StoredAmount" column will be the amount converted to those units. Because the display column prevents users from seeing the data as entered, we also provide two new columns "RawAmount" and "RawUnits", which present the data as stored in the database. These columns are hidden by default but can be added via customizing a samples grid.

Import of Samples and Sources via API

Sample Types and Sources are similar, with a few key differences. Sources are "data classes". Upload source data to the "exp.data" schema.

Sample Types are defined in the "exp" experiment schema, and some access to data will be through the "exp.materials" schema. However, all sample data should be uploaded to the "samples" schema.

Related Topics




Custom Grid Views


All users can now create their own customized grid views for optimal viewing of the data that they care about. Administrators can set default views for everyone, any user can create and save their own views most pertinent to them, and decide whether to share those named custom views with other users.

Customize Grid View

Quickly see data that pertains to you with custom saved grid views. Create a custom view of your data by rearranging, hiding or showing columns, adding filters or sorting data. With saved custom views, you can view your data in multiple ways depending on what’s useful to you.

You can quickly customize a grid view directly from the column header menus, or open the grid view customizer by selecting Grid Views > Customize Grid View to make many changes at once.

The Available Fields panel is on the left; fields Shown in Grid are listed in left to right order in the panel on the right. Check Show all system and user-defined fields to expose additional fields that are hidden by default. Expand "lookup" nodes to find more columns by clicking the . Details about changes you can make are below. You can revert changes any time by clicking Undo edits.

Click Update Grid to apply your changes to the visible grid.

Once you've changed the grid, either using the column headers or the grid customizer, you will see options to save the changes as a new named grid view you can access directly later. Learn about saving the grid below.

Change Column Order

Drag and drop column headers directly in the grid view, or open Views > Customize Grid View and using the sixblock handles to change the column order in the Shown in Grid panel.

Insert Column

Select Insert Column from any column header, or open Views > Customize Grid View. Click the in the Available Fields panel to add a new column to the grid.

Drag and drop the columns to the desired order.

Hide Column

Select Hide Column from any column header to hide that column, or open Views > Customize Grid View and click one or more 'X's for fields you want to delete (from the Shown in grid panel.

Edit Label

Edit the display label for a column. You can either select Edit Label from the column header and type the new label directly:

Or click the for the field within the view customizer and type the new label.

Include Sorts and Filters in Custom Views

When you save a grid view, any filters or sorts currently applied will be saved. Make the filtering and sorting adjustments you prefer prior to saving.

Include Ancestor Information

To include information about ancestors, use the Ancestor node in the grid view customizer to find specific types and properties of sample ancestors. Learn more in this topic:

Save Grid View

Once you've made changes, either directly using column headers or using the grid view customizer, you'll see a header banner on your grid view indicating that it has been editing and inviting you to:

  • Undo: revert to the default.
  • Save your changes.
  • Enter a Grid View Name in the box.
  • If you have the Editor role (or higher) you can share your grid with other users. Check the box to Make this grid view available to all users. Otherwise your named grid views will be visible only to you.
  • Select whether to Make this grid view available in all Folders.
  • Click Save again.
See below for additional options available to administrators.

Columns, sort order, and filters will be saved. You cannot use the names 'Default', 'Your Default', or 'My Default' to avoid confusion later with an administrator-settable default grid.

You'll now see your named grid on the Views menu for all grids of this type throughout the application. Learn more below.

Administrator Options for Saving Grid Views

For administrators, the options available are:

  • Save as default view for all users: Only available to administrators and their default.
  • Save as a custom view: As for any user, select this option to save a named custom grid view. When selected, you'll see the same options to give the grid a name, and select whether to share with other users and/or make it available in all Folders.
  • Click Save.

Note that it is possible to save a default view with a filter applied that may cause some samples to not be shown by default. They can still be found by users based on their data (such as by using the Sample Finder) but a customized filtered grid view may not show them automatically.

In addition, the "Edit in Grid" option uses the default view to present the samples to a user for editing, so if they select samples that are "filtered out" by a custom default view, those samples may be omitted from the edit grid.

To avoid these scenarios, administrators should use caution when saving filtered grid views as the default.

Use Saved Views

By saving a set of customized named views, you can create your own menu giving you quick access to whatever standardized groupings and details are relevant to your specific role. You might have different views filtering samples by attributes or storage location, and another showing only the shipping details needed for sets of samples.

In addition to Your Saved Views, you'll see Shared Saved Views that were created by other users listed separately.

Access both types of saved grids from the Views menu:

From a customized grid view, you can more easily create standardized reports about the samples in the system and export for downstream analysis or further processing. When you select a custom grid view, it will still be shown the next time you return to that grid.

Edit Saved Views

To edit a saved view, you simply select it from the menu, then make changes you want. The name of the grid you are viewing is shown in the header, and once you've made changes you'll see an "Edited" indicator and Undo and Save buttons. Editing a named view, you can also use the > Save as... option to save as a new grid view.

Manage Saved Views

Select Views > Manage Saved Views for a popup listing them. You can:

  • (Edit)
  • (Delete)
  • Administrators will be also see options to:
    • Revert an edited Default view to the system default.
    • Make default: Make an existing named view the Default view for all users.

Related Topics




Audit History


Administrators can view the audit history from numerous places within the application, including from > Audit Logs. Customized grids can present audit information in the way most useful to them.

View Audit History

Select > Audit Logs.

The audit log provides access to numerous audits of system activity, defaulting to Sample Timeline Events.

You can also access audit histories from many places in the application by selecting Manage > View Audit History. It will open on the log most relevant to where you were in the application when you opened it. This image shows Roles and Assignment Events, the default for the Permissions tab.

Available Audit Logs

Use the selection menu near the top of the page to see a full listing of other logs available to administrators, including:

  • Assay Events: Run import, deletion, and reimport.
    • Comments entered when assay data is deleted will be shown in the User Comment column.
    • Note that for reimport, two assay events are created: one for the 'old' run being replaced and one for the 'new' run representing the new import.
  • Attachment Events
  • Data Update Events: When a row is updated, the log will show the details of what changed in that row.
  • Domain Events: Tracks changes to columns in definitions (domains) of sample types, sources, and assays.
  • Domain Property Events: Changes to the properties of a column in a domain.
  • Folder Events: Folder editing events, including selective data exclusion for folders.
  • List Events
  • Notebook Events
  • Notebook Review Events
  • Query Update Events
  • Roles and Assignment Events
  • Sample Timeline Events: Records events for all samples.
    • Individual sample timelines show all events for each sample.
    • Detailed events for merge updates to sample data will show only the fields that were updated.
    • Sample registration, update, storage changes, and check in/out actions are all logged.
    • Comments entered when Samples are deleted will be shown in the User Comment column.
  • Sample Type Events: Creation and modification of Sample Types.
  • Sample Workflow Events: Job and task completion are recorded.
  • Sources Events: Including creation of Source Types and registration of Sources.
    • Comments entered when Sources are deleted will be shown in the User Comment column.
  • Storage Management Events: See View Storage Activity.
  • User Events: Creation of users; logging in and out.
Note that during folder import, data categories will be imported in "chunks" in a certain order. So, for example, all inventory data will be in one chunk and all job/task data in another chunk. Using folder import to load data into Sample Manager may result in sample timelines that do not represent actual usage for individual samples.

Customize Audit Views

Use the grid view customizer to change the columns shown, labels, and order, as well as apply filters and sorts to give you the specific view of each type of audit log that you need. You can either save as a personal named view, share the view with other administrators, or change the default view all administrators will see.

Learn more in this topic:

Require Users Provide Reasons for Certain Actions (Professional Feature)

The following actions allow users to enter a reason (aka a "comment") for the action, which will be recorded in the audit log:

  • Editing samples individually from a sample details page, in a grid, in bulk, or via update from file
  • Editing sources individually from a source details page, in a grid, in bulk, or via update from file
  • Editing lineage
  • Editing assay run or result data in a grid, in bulk, or via re-import
  • Deleting samples and sample types
  • Deleting sources and source types
  • Deleting assay runs and assay designs
  • Deleting jobs
  • Deleting storage
  • Updating sample amount or freeze/thaw count from a sample details page or on the sample details panel from the storage view
  • Checking samples in or out of storage
  • Removing samples from storage
  • Moving data between folders
  • Recalling a notebook submitted for review
By default, reasons are optional, but they can be configured to be required on an application-wide basis by an administrator.
  • Select > Application Settings.
  • Scroll down to the Audit Logging section.
  • Select Yes, reasons are required.

Users will now see the fields for reasons for the above actions as required and must enter a reason to complete the action.

Related Topics




Search


LabKey Sample Manager provides full search across data in your server. Search is secure, so you only see results that you have sufficient permissions to view.

This topic covers basic text searching:

Searching for samples by ID or barcode is covered in the topic: Using the Sample Finder to find samples by properties is covered here:

Search Basics

To search for samples, assays, and more, type the search terms in the box in the header of the application, or when the browser is narrow, the option will be on the search dropdown menu.

Searches will return both complete and partial matches for the term you enter. Results will be shown with the type and a few details. Click the item name in the search results to see the full item. Page through many results as needed.

Learn about the options for search terms and operators in this LabKey Server documentation topic:

Content Searched

  • Sample Types (Name and description)
  • Samples (SampleID and description)
  • Storage Units, such as boxes (Name and Label)
  • Source Types (Name and description)
  • Sources (SourceID and description)
  • Assay Designs (Name and description)
  • Jobs (Name and description)
  • Notebooks (Name, number, and contents)

Search for Storage Units

The Name and Label field for each storage unit are indexed so that you can easily search later for any particular storage. Instead of using the default/generic naming, customize the names of your storage or include any helpful text in the label (such as a barcode) that helps identify storage.

When you are searching later for a specific storage unit, you can find it by terms in the name or label.

In the search results, you will see the storage hierarchy where that box is located making it easy to find. The full path to the location is also indexed, so if, for example, you search for a shelf or freezer name, you'll see all the individual storage units within it.

Click any storage unit in the results to jump directly to the Storage View where you can add new samples or work with existing contents.

You can also search for storage units by name or label from the popup modal for adding samples to storage from a grid or list.

Related Topics




Field Editor


This topic explains how to use the field editor tool to create and customize fields in Sample Types, Sources, and Assay designs.

Create New Fields

Import or Infer Fields from File

When creating a sample type, source type, or assay design, you'll have the option to:

  • import fields from a specially prepared JSON file, OR
  • infer them from an example data spreadsheet matching the structure of your data.
Learn more about either option in the structure specific topics. In either case, after inferring or importing field definitions, you will see the manual field editor interface described below and can refine or add new fields.

Manually Define Fields

To use the Field Editor to create a new set of fields and their properties manually, click Manually Define Fields.

  • Open the field editor.
  • Click Manually Define Fields (or get started by importing or inferring fields, which will prepopulate the manual editor).
  • To define a new field, click Add Field.
  • Give the field a Name. Field names can contain a combination of letters, numbers, and underscores, should not contain spaces, and should start with a letter or underscore.
  • Use the menu to select the Data Type. The set of data types available may vary with your configuration and each has a different set of properties you can set. Once you have saved fields, you can only make limited changes to the type.
  • You can use the checkbox if you want to make it required that that field have a value in every row.
  • Continue to add any new fields you need - one for each column of your data.
  • Click the Finish Creating.../Save... button to save and exit the editor.

Edit Fields

To edit fields, reopen the editor and make the changes you need. If you attempt to navigate away with unsaved changes you will have the opportunity to save or discard them. When you are finished making changes, click Save.

Once you have saved a field or set of fields, you can change the name and most options and other settings. However, you can only make limited changes to the type of a field. For example, you can change among text types, but cannot change a text field into a number or a boolean.

Rearrange Fields

To change field order, drag and drop the rows using the six-block handle on the left.

Delete Fields

To one or many fields, select them using the checkboxes and click Delete. You can use the checkbox at the top of the column to select all fields in the section.

To delete a single field, you can click the .

In both cases, you will be reminded that deleting a field also deletes any data stored in it. Confirm the deletion if you want to proceed.

Save Fields

Click Save when finished.

Add/Edit Field Properties

Each field can have additional properties defined. The properties available vary based on the field type. To open the properties for a field, click the icon on the right (it will become a handle for closing the panel).

Fields of different types include some or all of these sections:

For example, the panel for a text field might look like this:

Sample Fields: Editable for Samples, Aliquots or Both

Fields in Sample Type definitions can specify whether they should be settable/editable for Samples, Aliquots, or both.

  • 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. Note that if you change an existing Sample Type field from "Editable for samples only" to this "Separately editable for samples and aliquots" option, any stored values for aliquots will be dropped.

Name and Linking Options

All types of fields allow you to set the following properties:

  • Description: An optional text description. This will appear in the hover text for the field you define.
  • Label: Different text to display in column headers for the field. This label may contain spaces. The default label is the Field Name with camelCasing indicating separate words. For example, the field "firstName" would by default be labelled "First Name".
  • Import Aliases: Define alternate field names to be used when importing from a file to this field. Multiple aliases may be separated by spaces or commas. To define an alias that contains spaces, use double-quotes (") around it.
  • URL: Use this property to change the display of the field value within a data grid into a link. Multiple formats are supported, which allow ways to easily substitute and link to other locations in LabKey. Learn more about using URL Formatting Options.

Validation Options

String-based fields offer regular expression validation. Numeric, date, and user fields offer range expression validation.

Create Regular Expression Validator

  • Click Add Regex to open the popup.
    • If you don't see this option, it is not supported for your field type.
    • If any regex validators are defined, you'll also see a link showing the number active and the button will read Edit Regex.
  • Enter the Regular Expression that this field's value will be evaluated against. All regular expressions must be compatible with Java regular expressions as implemented in the Pattern class.
  • Description: Optional description.
  • Error Message: Enter the error message to be shown to the user when the value fails this validation.
  • Check the box for Fail validation when pattern matches field value in order to reverse the validation: With this box unchecked (the default) the pattern must match the expression. With this box checked, the pattern may not match.
  • Name: Enter a name to identify this validator.
  • You can use Add Validator to add a second condition. The first panel will close and show the validator name you gave. You can reopen that panel using the (pencil) icon.
  • Click Apply when your regex validators for this field are complete.
  • Click Save or Finish in the editor.

Create Range Expression Validator

  • Click Add Range to open the popup.
    • If you don't see this option, it is not supported for your field type.
    • If any range validators are defined, you'll also see a link showing the number active and the button will read Edit Ranges.
  • Enter the First Condition that this field's value will be evaluated against. Select a comparison operator and enter a value.
  • Optionally enter a Second Condition.
  • Description: Optional description.
  • Error Message: Enter the error message to be shown to the user when the value fails this validation.
  • Name: Enter a name to identify this validator.
  • You can use Add Validator to add a second condition. The first panel will close and show the validator name you gave. You can reopen that panel using the (pencil) icon.
  • Click Apply when your range validators for this field are complete.
  • Click Save or Finish in the editor.

Advanced Settings

When using Sample Manager with a Premium Edition of LabKey Server, you may see additional options in the field editor that are not covered in this topic. For more information about these options, please see the companion topics in the LabKey Server documentation:

View Fields in Summary Mode

In the upper right, choose the Mode:

  • Detail: Fields can be expanded to edit properties.
  • Summary: Only a summary of fields are shown; limited editing is available.

In Summary mode, you see a grid of fields and properties, not all of which are relevant to Sample Manager usage. Scroll for more columns. Instead of having to expand panels to see things like whether there is a URL or formatting associated with a given field, the summary grid makes it easier to see and search large sets of fields at once.

You can add new fields, delete selected fields, and export fields (selected or all) while in summary mode. Click to switch back to Detail if you want to edit field properties.

Export Sets of Fields (Domains)

Once you have defined a set of fields (domain) that you want to be able to save or reuse, you can export it by clicking (Export).

If you want to only export a subset of the fields included, use the selection checkboxes to select the fields to export.

  • When any (or all) boxes are checked, only the checked fields are exported.
  • If no boxes are checked, all fields will be exported.

A Fields_*.fields.json file describing your fields as a set of key/value pairs will be downloaded. All properties that can be set for a field in the user interface will be included in the exported file contents.

You can use this file as a template to generate a set of field definitions for import elsewhere.

Note that importing fields from a JSON file is only supported when creating a new set of fields. You cannot apply property settings to existing data with this process.

Related Topics




Field Properties Reference


Each field in a data-structure design is associated with a set of properties of that field. This topic covers the options available and specific to fields of each data type. In addition, fields of all types have name and linking options and most include validation options, described in the common topic: Field Editor.

Type Specific Formatting Options

Text Options

Text Choice Options

A Text Choice field lets you define a set of values that will be presented to the user as a dropdown list. For example, you might offer a "Tube Type" field and let the user choose Heparin, EDTA, or Unknown.

  • Text Choice Options:
    • Add and manage the set of drop-down values offered for this field, as shown below.
  • Name and Linking Options
Click Add Values to enter the values to be presented for this field. Users will be able to choose from dropdown lists when entering or editing data.

Learn more about populating, editing, and managing text choice fields in the main LabKey documentation topic for Text Choice fields.

  • Up to 200 values can be included in the drop-down options. Values can be single- or multi-word.
  • You can change an existing Text field to the Text Choice type; the list of drop down values will be populated for you.
  • Values that are in use cannot be deleted. If they are in use by read-only data, they can neither be edited nor deleted.
  • All changes to the set of values for a text choice field are audited.

Multi-Line Text and Flag Options

  • Multi-line Text Field Options (or Flag Options):
    • Maximum Text Length. Sets the maximum character count for the field. Choose either "Unlimited" or "No longer than X characters", providing a value in the box. The default is 4000.
  • Name and Linking Options
  • Validation Options: Regular expression validators.

Boolean Options

  • Boolean Field Options: Format for Boolean Values: Use boolean formatting to specify the text to show when a value is true and false. Text can optionally be shown for null values. For example, "Yes;No;Blank" would output "Yes" if the value is true, "No" if false, and "Blank" for a null value.
  • Name and Linking Options

Integer/Decimal Options

Date, Time, and Date Time Options

For samples, sources, assay results and assay runs, three different field types are available, letting you choose how best to represent the data needed. Other types of fields in Sample Manager only support the DateTime combined field.

  • Date Time: Both date and time are included in the field. Fields of this type can be changed to either "Date-only" or "Time-only" fields, though this change will drop the data in the other part of the stored value.
  • Date: Only the date is included. Fields of this type can be changed to be "Date Time" fields.
  • Time: Only the time portion is represented. Fields of this type cannot be changed to be either "Date" or "Date Time" fields.

File/Attachment Options

Sources, samples, and assay designs (run and batch fields) support including file attachments, known in different structures as either File or Attachment fields.

  • Source Types use Attachment
  • Sample Types use File
  • Assay Designs allow File fields in batch and run field sections

Both field types offer:

In practice, these field types are very similar: both can accept files like PDF documents or images. The contents of these fields will display as thumbnails, open in a larger panel when clicked, and include a download option. Learn more about how these fields are used in this topic: The differences between File and Attachment include:

User Options

Sample Options

  • Sample Options: Select where to look up samples for this field.
    • You can choose All Samples to reference any sample in the container, or select a specific sample type to filter by.
    • This selection will be used to validate and link incoming data, populate lists for data entry, etc.
  • Name and Linking Options

Unique ID Options

A field of type "Unique ID" is read-only and used to house barcode values generated by LabKey. Learn more in this topic: Barcode Fields

Related Topics




Attach Images and Other Files


Attaching an image, document, picture, or other file to a data structure can help place key information where it is needed most. This topic describes how to include and work with files and attachments in Sample Manager.

Add File Field (Admin)

An administrator must add the field to the data structure. In Sample Types, the field is of type "File" and in Source Types, the field is of type "Attachment". In this example, the field is included in a Sample Type and named "Image".

Learn more about the properties of these fields here: Field Properties Reference

Upload File (Editor)

Now by editing the Details for any sample in the system, you will be able to upload a file by either clicking in the selection window or dragging and dropping from your desktop. Click the sample name on any grid to open the Overview tab. When you are editing sample details, you can click to select or drag and drop a file to upload it.

Click Save to save this change.

View Thumbnails and Expand Images (Reader)

A small thumbnail and the filename will be shown in the details panel and in the column of sample grids. Click the thumbnail or filename to open the image in a larger window.

Download File (Reader)

To download the file, select Download from the menu.

Remove or Change the File (Editor)

To change the attached file, reopen the sample details, click to open the Details panel editor and select Remove file from the menu. This option is only available in edit mode.

Once the 'old' file has been removed, you will be able to upload a new file. Note that you may need to refresh your browser window to update the image shown, as the original image may have been cached.

Missing Files

If a file is missing, whether because of an upload problem or later deletion, you will see a red warning symbol and hovertext will tell you the file is unavailable.

Related Topics




URL Field Property


Setting the URL property of a field turns the display value into a link to other content. The URL property setting is the target address of the link. You can link to a static target, or build a URL using values from any field in the row.

Substitution Syntax

You can use one or more field values as parameters when creating the URL link, using the ${ } substitution syntax. Put the name of the column whose value you want to use inside the braces. The field with the URL property defined on it is available, but so are any other fields in the data structure.

For example, if your data includes a "GeneSymbol" field displaying values like "BRCA", you could link to related information in The Gene Ontology by using a search URL. When the user clicked the value "BRCA", they would go to:

http://amigo.geneontology.org/amigo/search/ontology?q=BRCA

In this case the field value is passed as a search parameter, so to create the URL property on the GeneSymbol field, you would include the GeneSymbol field in the URL property definition:

http://amigo.geneontology.org/amigo/search/ontology?q=${GeneSymbol}

You could also define this URL property on a different field, letting you display the gene symbol unlinked and link a value in another field (like "Click to Search") to perform the search.

Substitutions are allowed in any part of the URL, either in the main path, in the query string, or both. For example, here are two different formats for creating links to an article in wikipedia, here using a "CompanyName" field value:

  • as part of the path:
  • as a parameter value:

Local Links

To link to content in the current LabKey folder, use the controller and action name. You can optionally prepend a / (slash) or ./ (dot-slash), but they are not necessary.

<controller>-<action>

For example, you can link to a specific item on a list. If you had a list (here listId=5) that mapped building numbers to details about them, you could create a column "Building" and use this URL property, letting your users click the "Building" value to open the details page.

list-details.view?listId=5&pk=${Building}

External Links

To link to a resource on an external server or any website, include the full URL link.

http://server/path/page.html?id=${Param}

URL Encoding Options

You can specify the type of URL encoding for a substitution marker, in case the default behavior doesn't work for the URLs needed. This flexibility makes it possible to have one column display the text and a second column can contain the entire href value, or only a part of the href.

The fields referenced by the ${ } substitution markers might contain any sort of text, including special characters such as question marks, equal signs, and ampersands. If these values are copied straight into the link address, the resulting address would be interpreted incorrectly. To avoid this problem, LabKey Server encodes text values before copying them into the URL. In encoding, characters such as ? are replaced by their character code %3F. By default, LabKey encodes all special character values except '/' from substitution markers. If you know that a field referenced by a substitution marker needs no encoding (because it has already been encoded, perhaps) or needs different encoding rules, inside the ${ } syntax, you can specify encoding options as described in the topic String Expression Format Functions.

Related Topics




Date, Time, and Number Formats


This topic covers formatting options for formatting the display of dates, times, and numbers within LabKey Sample Manager.

Set DateTime, Date, and Time Display Formats

An administrator can configure the way DateTime, Date, and Time field values are displayed in the application. This does not affect how values may be imported, but can be used to standardize or simplify the display to users, using the format strings outlined below.

There are three separate format strings available for Date-Times, Dates, and Times, as shown in the image below.

For example, the default display string for DateTime values is yyyy-MM-dd HH:mm. If your research is concerned only with dates and does not need to track or see the times as well, you can remove them from how these values are shown to users as follows:

  • Select > Application Settings.
  • Edit the Default display format for date-times to suit your needs. Shown here, the default without the time portion:
  • Click Save

This new format will be used to display all DateTime values in all folders in your application.

In this example, the "time" portion of the DateTime field is still present and can be shown later or in reporting. If you were to instead change the field type to "Date", the time portion of that value would be dropped.

Note that time zone values (z, Z, X) are not supported in Sample Manager or LabKey Biologics.

DateTime, Date, and Time Field Format Strings

Format strings used to describe dates, date-times, and times must be compatible with the format accepted by the Java class SimpleDateFormat. For more advanced options and examples, see the LabKey Server documentation. The following table has a partial guide to pattern symbols you may find useful in Sample Manager:

LetterDate/Time ComponentExamples
yYear'yyyy' = 1996; 'yy' = 96
MMonth in year'MMMM' = January; 'MMM' = Jan; 'MM' = 01
dDay in month'dd' = 10
aAm/pm markerPM
kHour in day (1-24)24
h .......Hour in am/pm (1-12) .......12 .......
mMinute in hour30
sSecond in minute33

Note that the LabKey date parser does not recognize time-only date strings. This means that you need to enter a full date string even when you wish to display time only. For example, you might enter a value of "2/2/09 4:00 PM" in order to display "04 PM" when using the format string "hh aa".

Number Format Strings

Format strings for Integer and Decimal fields must be compatible with the format that the java class DecimalFormat accepts. A valid DecimalFormat is a pattern specifying a prefix, numeric part, and suffix. For more information see the Java documentation. The following table has an abbreviated guide to pattern symbols:

SymbolLocationLocalized?Meaning
0NumberYesDigit
#NumberYesDigit, zero shows as absent
.NumberYesDecimal separator or monetary decimal separator
-NumberYesMinus sign
,NumberYesGrouping separator

Examples

The following examples apply to Date Type fields.

Format StringDisplay Result
yyyy-MM-dd HH:mm2008-05-17 01:45
yyyy-MM-dd HH:mm a2008-05-17 01:45 PM
yyyy-MM-dd HH:mm:ss.SSS2008-05-17 01:45:55.127
MMMM dd yyyyJanuary 17 2008

The following examples apply to Decimal fields.

Format StringDisplay Result
<no string>85.0
085
000085
.0085.00
000.000085.000
000,000085,000
-000,000-085,000

Java Reference Documents

Dates: https://docs.oracle.com/en/java/javase/12/docs/api/java.base/java/text/SimpleDateFormat.html

Numbers: https://docs.oracle.com/en/java/javase/12/docs/api/java.base/java/text/DecimalFormat.html

Related Topics




String Expression Format Functions


Reference

The following string formatters can be used when building URLs, or creating unique Sample IDs/names.

 NameSynonymInput TypeDescriptionExample
General
defaultValue(string)   any Use the string argument value as the replacement value if the token is not present or is the empty string. ${field:defaultValue('missing')}
passThrough none any Don't perform any formatting. ${field:passThrough}
URL Encoding
encodeURI uri string URL encode all special characters except ',/?:@&=+$#' like JavaScript encodeURI() ${field:encodeURI}
encodeURIComponent uricomponent string URL uncode all special characters like JavaScript encodeURIComponent() ${field:encodeURIComponent}
htmlEncode html string HTML encode ${field:htmlEncode}
jsString   string Escape carrage return, linefeed, and <>"' characters and surround with a single quotes ${field:jsString}
urlEncode path string URL encode each path part preserving path separator ${field:urlEncode}
String
join(string)   collection Combine a collection of values together separated by the string argument ${field:join('/'):encodeURI}
prefix(string)   string, collection Prepend a string argument if the value is non-null and non-empty ${field:prefix('-')}
suffix(string)   string, collection Append a string argument if the value is non-null and non-empty ${field:suffix('-')}
trim   string Remove any leading or trailing whitespace ${field:trim}
Date
date(string)   date Format a date using a format string or one of the constants from Java's DateTimeFormatter. If no format value is provided, the default format is 'BASIC_ISO_DATE' ${field:date}, ${field:date('yyyy-MM-dd')}
Number
number   format Format a number using Java's DecimalFormat ${field:number('0000')}
Array
first   collection Take the first value from a collection ${field:first:defaultValue('X')}
rest   collection Drop the first item from a collection ${field:rest:join('_')}
last   collection Drop all items from the collection except the last ${field:last:suffix('!')}

Examples

Function Applied to... Result
${Column1:defaultValue('MissingValue')} null MissingValue
${Array1:join('/')} [apple, orange, pear] apple/orange/pear
${Array1:first} [apple, orange, pear] apple
${Array1:first:defaultValue('X')} [(null), orange, pear]  X



Explore Sample Manager


Explore the features of LabKey Sample Manager on our website here: Register on our website, or contact us to:
  • 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
Get started with Sample Manager



Ontology Concept Annotations


Premium Feature — Available in the Enterprise Edition of LabKey Server. Learn more or contact LabKey.

Once ontologies have been loaded and enabled in your folder, you can use Concept Annotations to link fields in your data with their concepts in the ontology vocabulary. A "concept picker" interface makes it easy for users to find desired annotations.

Browse Concepts

Reach the grid of ontologies available by selecting (Admin) > Go To Module > More Modules > Ontology.
  • Click Browse Concepts below the grid to see the concepts, codes, and synonyms loaded for any ontology.
  • On the next page, select the ontology to browse.
    • Note that you can shortcut this step by viewing ontologies in the "Shared" project, then clicking Browse for a specific row in the grid.
  • Type into the search bar to immediately locate terms. See details below.
  • Scroll to find terms of interest, click to expand them.
  • Details about the selected item on the left are shown to the right.
    • The Code is in a shaded box, including the ontology prefix.
    • Any Synonyms will be listed below.
  • Click Show Path or the Path Information tab to see the hierarchy of concepts that lead to the selection. See details below

Search Concepts

Instead of manually scrolling and expanding the ontology hierarchy, you can type into the search box to immediately locate and jump to concepts containing that term. The search is specific to the current ontology; you will not see results from other ontologies.

As soon as you have typed a term of at least three characters, the search results will populate in a clickable dropdown. Only full word matches are included. You'll see both concepts and their codes. Click to see the details for any search result. Note that search results will disappear if you move the cursor (focus) outside the search box, but will return when you focus there again.

Search terms will not autocomplete any suggestions as you type or detect any 'stem' words, i.e. searching for "foot" will not find "feet".

Path Information

When you click Show Path you will see the hierarchy that leads to your current selection.

Click the Path Information for a more complete picture of the same concept, including any Alternate Paths that may exist to the selection.

Add Concept Annotation

  • Open the field editor where you want to use concept annotations. This might mean editing the design of a list or the definition of a dataset.
  • Expand the field of interest.
  • Under Name and Linking Options, click Select Concept.
  • In the popup, select the ontology to use. If only one is loaded, you will skip this step.
  • In the popup, browse the ontology to find the concept to use.
  • Click Apply.
  • You'll see the concept annotation setting in the field details.
  • Save your changes.

View Concept Annotations

In the data grid, hovering over a column header will now show the Concept Annotation set for this field.

Edit Concept Annotation

To change the concept annotation for a field, reopen the field in the field editor, click Concept Annotation, make a different selection, and click Apply.

Related Topics




Help Links





Click to Explore