Table of Contents

guest
2024-10-08
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
   Project Organization
     Cross-Project Actions
   User Accounts, Groups, and Roles
     My Account
     Permission Roles
     Manage Groups
     Manage Notifications
   Disallow User-Defined Names
   Sample Manager - FAQ
Samples
   Create a Sample Type
   Add Samples
     Create Samples from Grid
     Import Samples from File
   Sample ID Naming
   Sample Lineage / Parentage
   Aliquots, Derivatives, and Sample Pooling
   Sample Expiration
   Sample Timeline
   Manage Samples
   Manage Sample Status
   Edit Selected Samples
   Sample Finder
   Sample Search
   Integrate with BarTender
   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 and Number Formats Reference
   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. 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, select Help from the user menu.

More Answers

How Do I Know the Version of Sample Manager

An administrator can see which version of Sample Manager is running by going to the Administration option from the user menu, then clicking Settings. The version is shown in the upper right.




Get Started with Sample Manager


Welcome to LabKey Sample Manager

This topic will help you get started as an administrator using LabKey Sample Manager for sample tracking. First, complete the tutorial to learn to add sample information, define assays, and create the workflow processes you will follow. When you first create a LabKey Sample Manager project, it will be empty, so these topics are designed to populate each area of the application with tutorial examples.

Tutorial

After completing the tutorial, you can return to this page to follow this sequence to start adding your own data.

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.
  • 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.
  • Display stored amount in: 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 be on the Import Samples from File tab.
  • Confirm that "Tutorial Samples" is selected as the Sample Type.
  • 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.
    • 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 Administration from the user menu.
  • Click the Users tab to go to 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 or edit data related to samples, assays, and jobs.
  • Administrators: Have full control over the application, with the exception of the storage editor role. This includes user management, permission assignments, and creating and editing sample types, assays, and job templates.
  • Reopen user management if you closed it by selecting Administration from the user menu. Click the Permissions section.
  • All of our fake users are currently in the Reader role.
  • Click the for the Editors role 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.
  • You may also want to confirm that at least your own user account is assigned the Storage Editor role to explore freezer management features later.
Click Save.

View Audit History

This is a good time to mention that all actions in Sample Manager are logged for later use in an audit. The audit logs can be viewed from any tab within the Administration dashboard, and from many other places in the application. Select Manage > View Audit History. 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).
    • Check the boxes to select "Tutorial-018", "Tutorial-019" and "Tutorial-020". (A spreadsheet with some assay data for these specific samples is included below.)
    • Hint: clicking a name will clear all selections except that one, then add the other two by clicking the boxes.
    • 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 and Template

Before finishing job creation, consider whether you want to make this job available as a template for creating similar future jobs. Creating a template from a job is offered only during initial job creation.

  • Use the dropdown menu option Save as Template and Start Job to create a template and start this job.

In the popup, you will name the template and provide an optional description. For this tutorial, name the template "Tutorial Job Template 1."

  • Click Save Template.
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 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 Data button since the task involves importing data to the "Tutorial Assay".
  • Click Import Data.
  • Enter:
    • Assay Id: "Run2"
    • Date: Today's date (click the entry field to use the date picker)
    • Instrument: INS-01
  • 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 section, notice that the job is no longer shown in Your 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.

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 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 select 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.
  • Download this spreadsheet and drop it in the upload area: TutorialLabSources.xlsx
  • 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, select 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 Sample Type.

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 check the box to Allow new samples but for this tutorial, leave it unchecked.
  • 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.

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

  • Integration with BarTender to print labels.

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 your project. 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 in the following order instead of being arranged as shown above.

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:

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:

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.

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 Queue. A second tab will show you other Active Jobs. Learn more about jobs and workflow in this section:

Related Topics




Project Organization


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.

Projects allow users to organize and partition sensitive data into projects 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 Projects to work with data across different teams using Sample Manager Professional.

Overview

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

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

Home Project and "Sub" Projects

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

  • Sample Types, Source Types, etc. are defined in the home project to support lab-wide consistency. You will not see options for adding these definitions in subprojects.
  • Storage systems like freezers are also defined in the home project 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 project, summarizing all the data an individual user has access to.
  • Create shared resources like reagents in the home project so that they can be shared & viewed by all projects.
  • Use project permissions to partition each study from one another making it easy to operate in compliance with regulations.

Manage Projects

To manage projects, select Administration from the user avatar menu, then click the Projects tab. This tab is only available when you are in the home project and lists existing projects.

Create New Project

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

Click Create Project. When first created, only administrators can view the new project. This can be useful when configuring a new project for a team to ensure the users only access it when ready. Click Update project permissions if you want to grant access immediately. You can also reach this page by selecting the project from the menu, clicking Dashboard, then choosing Administration from the user avatar menu and clicking Permissions.

Delete Project

To delete a project, either:

  • Click it's name from the Projects dashboard (select Administration from the user menu in the home project, then click Projects).
  • You can also select Administration within the project you want to delete, then click the Settings tab.

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

Work within Projects

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

To navigate, select the desired project, then the page of interest from the main menu.

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

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

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

Learn about actions across projects in this topic:

Best Practices

  • Home Project
    • All users must have Read access to the top level project.
    • Recommended: Only assign non-admin users Read access (and Storage Editor as appropriate) in the top level Home project. (Edit/add permissions will be granted in individual projects.)
    • The Home project is the place to create Source Types, Sample Types, Assays, ELN & Workflow Templates
    • All storage must be defined here.
    • Add all "shared resources" here that you want to be able to access in other projects, such as shared reagent lists, etc.
  • Sub Projects
    • Project/Study/Team-based access to sources, samples, assay data, workflow & ELNs.
    • Within a sub project, users can edit/update their project data.
    • From the home project, users can read their project data (and all data they can access).
    • For data that is not shared, create a project that everyone has access to.

Related Topics




Cross-Project Actions


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 will handle actions across projects

Cross-Project Actions

Summary of Functionality

This summary covers high-level behavior of for Samples and Sources (or other Data Classes), collectively referred to as "entities" when Projects are in use.

Reading of entities: You can read the current project's entities as well as the ones in the Home Project and "subprojects" you have permissions to read.

Referencing entities for lineage-type relationships: You can reference entities in the current project and the Home Project (assuming you have permissions to). You cannot reference entities in subprojects.

Creating entities: Entities are created in the effective project the user is viewing at the time the action is initiated. When viewing an individual entity, the project in which it was created is the effective project. When viewing a grid of data, the effective project is the project chosen in the project menu (that is, the one in the URL).

Updating entities: An entity can be updated from the (effective or actual) project in which it was created. We do not allow updating of multiple entities from different projects at the same time or from a project that entity was not created in.

Deleting entities: An entity can be deleted from the (effective or actual) project in which it was created. We do not allow updating of multiple entities from different projects at the same time.

Lookups: You can look "UP" but not down the project hierarchy. In the home project you will see only values defined in the home project. In a child project you will see values in both the current and home project.

  • An exception to this is the Sample Status dropdown which will show only status values as configured in the current project; it will not include home project options.

Detailed Cross-Project Actions

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

  • Samples:
    • Individual sample creation in a grid allows parent types from the current project and projects above it. You cannot select parents from a "child" project of the current one.
    • Grid edit, sample derivation and deletion: Only works for entities in the current project.
    • File import only allows sample parent type and parent selection from the current project, as for grid editing.
    • Editing parent details for an individual sample only works when adding parents from the current project.
    • Derived or Aliquoted samples end up in the project where they are derived/aliquoted.
  • 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 project or projects above it in the hierarchy. You cannot select parents from a "child" project of the current one.
    • Editing in a grid or in bulk is only allowed for entities in the current project. To do editing, you must be in the project the entity belongs to and will see an error if you attempt to edit in the wrong location
    • Deleting is only allowed for entities in the current project.
    • Deriving samples from a data class (source, bioregistry type, or some media) allows parent data class objects from only the current project or a project above it.
  • Assay:
    • Imported assay data can reference samples in the current project or any 'higher' (parent) project, but cannot reference samples in sibling or 'lower' (child) project.
    • Imported assay data can also reference samples defined in the Shared project.
  • Storage:
    • Freezers (or other storage) can only be defined in the home project.
    • Learn more about shared freezers in this topic: Shared Freezers
  • Workflow:
    • Creation of workflow jobs using samples from different projects is possible both from any project.
    • The job that is created will belong to the project in which it was created, regardless of the samples included.
    • Additional samples from all visible projects can be added to existing jobs.
  • Picklists:
    • Creation of picklists using samples from different projects is possible from any project.
    • The picklist that is created will belong to the project in which it is created, regardless of the samples included.
    • The picklist will be visible in only the project in which it was created.
    • Additional samples from all visible projects can be added to existing picklists in the current project.
  • Notebooks:
    • Notebooks can reference entities from all projects visible in the current context.
    • Notebooks created from a parent project are also visible from any child project, and vice versa.
    • Notebooks created in any project can be submitted for review, or accessed for review, from any project.

Related Topics




User Accounts, Groups, and Roles


This topic covers management of user access in LabKey Sample Manager. Administrators can perform these actions via the Administration option on the user menu.

Related Topics:

Add Users

To add one or more new users, an administrator first selects Administration from the user menu, then clicks Users, then 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. 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 Administration from the user menu, then clicks Users.

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

User Details Panel

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

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

  • Reset Password: Send this user an email with a link to set a new password in order to access the site.
  • Deactivate
  • Delete

Deactivate Users

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

To deactivate a user, an administrator has two options:

  1. Check the box to select a single user you want to deactivate. Click Deactivate in the User Details panel on the right.
  2. You may also select one or more users simultaneously using the checkboxes in the grid, then select Manage > Deactivate Users.
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 project 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 Administration > 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 menu in the upper right.

To sign in, enter your email address and password on the next 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.

When you are signed out, you will be able to view the contents as a guest user would - you can read but not edit or create anything.

If you are using a hosted 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 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 at least six characters cannot contain spaces or match your email address. Click Submit to save the new password.

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:

  • 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.
  • Readers: Have a read-only view of the application.
  • Administrators: Have full control over the application, with the exception of the storage related roles. This includes user management, permission assignments, and creating and editing sample types, assays, and job templates.
    • 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.
  • Storage Editors: Storage Editors may read, add, edit, and delete data related to items in storage, picklists, and jobs.
  • Storage Designers: Storage Designers may read, add, edit, and delete data related to storage locations.
  • Workflow Editor: This role allows users to be able to add, update, and delete picklists and workflow jobs.
    • It does not include general "Reader" access, or 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.

Assign Roles to Users and Groups

Open user management by selecting Administration from the user avatar menu. Click the Permissions tab.

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.

Assign Administrator Role

Administrators have full control over the application, with the exception of the two storage-specific roles that must be separately granted. Admins can perform user management, permission assignments, and create and edit sample types, assays, and job templates.

Note that administrator permissions work differently when Sample Manager is used with a premium edition of LabKey Server. They are assigned on the same Permissions tab as other roles. Learn more in this topic:

The first user login created on the Sample Manager application is always an administrator. To assign the administrator role to other users or groups, any administrator can choose Administration from the user menu, then click the Settings tab.

Click the Application Administrators role panel and use the Add member or group... dropdown to select to whom to assign the administrator role. Type ahead to narrow the dropdown menu list.

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 Administration from the user menu, then click the Groups tab. All existing project level 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 in every project, sometimes used to represent every user with any access to the project, though this is not automatic. Users or groups must be explicitly added to this project group. For example, you might add all the groups you define to this 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.

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




Disallow User-Defined 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.

Force Usage of Naming Patterns for Consistency

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/new ID/Name is encountered.
To disallow User-defined IDs/Names:
  • Select Administration from the user avatar menu.
  • Click the Settings tab.
  • 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.

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

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 example project 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.

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) project. If the creation button is missing, navigate first to the home project.

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.
  • Units
  • Stored Amount
  • 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 open it.
  • You can collapse the Default System Fields section to hide it.

There are several methods available when adding the first custom fields.

Import or Infer Fields from File

The default is Import or infer fields from file, shown at the bottom of the previous image:

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 (adding either manually or from a file), or go to the home page dashboard and click Add Samples.

Choose Desired Sample Type and Import Method

  • Click the tab for your import method:
  • Select the Sample Type you are creating using the dropdown. You can type ahead in the box to narrow the selections when the list is long.

You will now be creating samples of that type and the creation interface will reflect your method.

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

Create Samples From Grid

Using the Create Samples From Grid tab 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.

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, you can import them directly from a file. Update and merge from file are also supported.

Learn more in this topic: Import Samples from File

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 Create Samples From Grid tab 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 click Create Samples on the home dashboard, choose the desired Sample Type, then stay on the default Create Samples from Grid tab.

Add Parent (Optional)

If the samples you are adding have one or more Parent samples, click Add Parent to add parentage information. 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 samples you are adding have one or more Sources, click Add Source to add a column for each Source Type you will associate with samples of this type. Select the Source Type from the dropdown.

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.
  • 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 the Import Samples From File tab) 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.
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 overview page for your sample type and select Add > Import from File.

  • Set the Sample Type for the Samples you will import (if it is not already selected).
  • Use the Template button if you didn't already download a template file for your data.
  • Drag and Drop the file directly into the window 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:

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.

  • 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.
    • Note that you cannot update an existing sample to make it an aliquot of another sample.
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.

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 Allow new samples checkbox controls whether you will be able to merge the incoming file or simply update existing rows.

  • When unchecked, the default, the update will fail if rows are included that do not match existing samples already in the system.
  • When checked, any rows for samples that do not yet exist will add them as new samples.

Related Topics




Sample ID Naming


Each sample in the system must have a unique name/id within its Sample Type. The unique sample 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 of sample, 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

genId is an incrementing counter which starts from 1 by default, and is maintained internally for each sample type (or source type) in a container. 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.

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/Ancestor Names

The above lineage lookup syntax applies to parent or source details, i.e. the "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}

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.Current Sample Type
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 and Number Formats Reference

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

Default Values

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')}

Incrementing Sample Counters

Some auto-incrementing counters calculate the next value based on all samples and sources across the entire site, 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 site-based, within a given container values will be sequential but not necessarily contiguous.

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 any column value when you add new samples. 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. Using :withCounter will guarantee unique values, meaning that if a name with counter would match an existing sample, that counter will be skipped.

The syntax for using :withCounter is to prefix it with an expression that will be evaluated first, then surround the outer modified expression in ${ } brackets so that it too will be evaluated at creation time. 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. Given the example shown for an XML counter in the next section, names like Blood-A-1, Blood-A-2, etc would be generated with this expression:

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

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

You can use a starting value and number formats 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')}

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 (e.g, "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.

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




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.

When importing samples of this type, include parent information in one of the aliased columns. As shown below, the "MyParent" column contains the parent identifier.

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.

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 Parent 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, 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
BloodDraw DateBlood Draw Dateright of Processing Operator
MiceStrainMouse Strainright of Blood Draw Date

You could then filter, sort, and search based on that parent metadata. Shown below, we're showing only samples that come from "BALB/c" mice.

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 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.
    • 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 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 Volume: Aggregates the total available volume of all aliquots and subaliquots of this sample which are both in storage and not checked out.
  • 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.

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 Aliquot Details, if any aliquots of this sample exist.

  • Total aliquots created, including subaliquots.
  • Available vials: Availability means that an aliquot is currently in storage (a location is assigned and it is not checked out).
  • Current amount available: based on the combined stored amounts for all available aliquots. Shown here, 5 aliquots have been created but not yet added to storage.
  • 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 aliquoted sample.

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.

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 Samples Expiring or About to Expire

To locate Samples and filter or sort by expiration date, open the Sample Type of interest. Build the desired filter on the Expiration Date. You can save as a named grid to access later.




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.
Storage Management Available

You can track the storage and usage of samples through the Storage Management feature. Learn about storing samples in freezers, incubators, and non-temperature controlled systems here:

View All Sample Types

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

The grid view of all Sample Types 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 Details are shown in the left hand panel, including the Description, Naming Pattern, Metric Unit, Parent Import Alias(es), and Source Import Alias(es). The right hand panel shows sample type insights and the Manage menu offers various actions.

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

Sample Type Insights

The panel of Insights 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, shown here, how many samples are checked out. 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" 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 as well
  • 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 check it out or discard it. 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 include:
  • Storage Location: Shows the current location, checkout status, and storage details.
  • Aliquots: Details about any aliquots created of this sample.
  • 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.
  • Parent Details: Information about parents of this sample.

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. Remember to click to Save your changes.

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.

Edit Sample Lineage

You can edit the source and parent information (i.e. the lineage) for a sample 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. Remember to click to Save your changes.

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 Reason(s) for deleting which will be included in the audit log.
  • 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(s) for deleting which will be included in the audit log.
  • 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.

Related Topics




Manage Sample Status


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 values, Available, Consumed, and Locked, and an administrator can add additional statuses in any of these categories 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 statuses, also representing three main types of status:

  • Available: Can be used.
  • Consumed: Used up, and no longer can be aliquoted or checked out, but remains in the system for analysis and tracking.
  • Locked: Not currently available, but may later become available.
From the main menu, click Sample Types then select Manage > Sample Statuses.

Scroll down to find the current set of defined statuses. 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 that mean the same things. 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, 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.

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 status of a sample 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 prompted to set the storage status to "Discarded".

When editing a single sample's details, use the checkbox to also Discard sample, optionally adding a comment:

When editing in bulk, saving will open a popup where you can check Yes, discard the sample(s) and optionally enter a comment:

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, with the color applied based on the type of status it is:

  • Available: green
  • Consumed: yellow
  • Locked: red

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. Sample statuses of the same main type (such as "Available" and "Received" in this image) will share the same color (in this case, green).

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.

  • The contents of any grid can be exported in CSV, TSV, or Excel format.
  • Some fields offer a selection menu, indicated with a . Type ahead to narrow the choices and click or tab to select the highlighted value.
  • Auto-fill text or number columns using the "cell-drag handle" for the first field or fields.
  • Learn more about these and other 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 be grayed out here.

Storage Details: Storage Editors can edit the storage information for the selected samples.

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.
Click Finish Updating # Samples when finished editing.

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 "Provider" 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.

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.

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 properties 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 update since the making of this video means that you select Reports > Find Derivatives in Sample Finder to open this report.

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 to find samples by:

  • Source Properties
  • Parent Properties
  • Assay Properties (Professional Edition Feature)
Click a tile to add a new sample filter based on that category of criteria.

In the popup, choose the specific type (of source, parent, or assay), 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.

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.

Edit Criteria

Once you've defined any sample finding criteria, you can use the Source Properties and Parent Properties buttons in the upper right to add more filters on other columns.

Each parent or source type 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.

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 here. If none exist "No Saved Search" will be shown.
  • Manage saved searches
  • Save as custom search

Save Search Button

Switching to a previous search result (such as "Searched 2022-06-21 10:27" in the above) will add a Save Search button to the header.

If you make changes to an existing saved search, you'll be able to use the Save Search button as usual, or select the dropdown and Save as... a new named search.

Manage Saved Searches

When you click Manage Saved Searches you can edit the name of other searches, or delete them. You cannot edit (or delete) the currently active search; it is shown with a lock icon.

Related Topics




Sample Search


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 the Barcodes or Sample IDs, each on its own line (i.e. separated by new line/carriage return), 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




Integrate with BarTender


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

This topic describes how to integrate LabKey applications, including Sample Manager and Biologics LIMS, with BarTender for printing labels for your samples. Note that an administrator must complete the one-time steps to configure BarTender Automation edition before use. Once configured any user may send labels to the web service for printing.

Print BarTender Labels for Samples

Before you can print labels, an administrator must have completed the one-time setup steps detailed below, and configured LabKey to print labels. The admin will have identified a site wide 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. You can type ahead to search. The default is the label template file configured above.
  • 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 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 is the label template file configured above.
  • Click Yes, Print to send the print request to BarTender.
The labels will be sent to the web service. See below for information about error reporting

Configure BarTender Integration

BarTender integration is supported for BarTender Automation edition. We have tested versions 2019 and 2021.

Note that these docs were written for BarTender 2019, which contains Print Portal by default. To configure BarTender 2021, also review the section below: Additional Setup for BarTender 2021

Begin in the BarTender application where 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 site-wide default label file, but also allow the user to specify a different variant at the time of printing.

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 BarTender Print Portal web application from the exe/msi installer.
  • Setup the BarTender Print Portal with HTTPS in IIS 7. This guide provides step-by-step instructions on how to do this, 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 setup, but is otherwise optional since we aren't doing any auth.
  • Setup 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
  • Setup 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

Special Set Up for BarTender 2021

If you are using BarTender 2021, the Print Portal is not installed by default. To add Print Portal to an existing installation of BarTender, re-open the original installer file, select Modify, and select BarTender with Print Portal.

Additionally, in BarTender 2021, 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:

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 the Administration option from the user menu, then click the Settings tab.

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.
  • Use Test Connection to test your configuration.
  • Click Save to save it.

Manage Label Templates

Click Add New Label Template for each template you want your users to be able to use. Give the template an identifying name and provide the path to the label file to use. The path should be relative to the default folder configured for the BarTender web service specified above.

Once templates are defined, you can return to this page to manage them. Click a template name to see or update details. 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. Team Picklists can be shared with others.

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 (or team 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 with your team.

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. Team picklists are shown on a separate tab, with team picklists you created yourself shown on the "My 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 My Picklists tab shows the picklists you have created. The Sharing column indicates whether you've shared them with your team ("public") or kept them private.
  • Click Team 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. Each sample type present in the list can be seen on an individual named tab (DNA and Tutorial Samples below), with detailed properties for that sample type. The All Samples tab shows the built in common properties, including the Sample ID, Status, and Storage information.

In the next section, learn about the various menus of actions available.

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.

Team Picklists and Permissions

When the Share this picklist with team members box is checked for a picklist, it will appear for all team members on the Team 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. 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. When you create your first source type, there is a shortcut to Create a source type on the main menu. Any time, you can click Create Source Type. Note that you can only create Source Types in the home (top-level) project. If the creation button is missing, navigate first to the home project.

  • 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.
  • As for sample types, define the Fields for this Source Type. 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.
    • Every Source Type includes built-in fields "SourceId", "Description", "Created/CreatedBy", and "Modified/ModifiedBy". You do not add these reserved fields and will not see them in the wizard. Find a full list of reserved and internal field names in this topic: Data Import Guidelines
    • 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 'Creature' source could use the pattern "Creature-${genId}" and have names like "Creature-1, Creature-2, etc."

Create or Import 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.

First, open 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. Select either:

Shown here we add 3 source 'creatures' directly in a grid.

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 Allow new sources box should be checked if you want to merge updating existing sources with also adding any new sources. When unchecked, the update will fail if any rows in the file don't match existing Source IDs.

Only the fields that are changing in the existing Source IDs need to be included in the upload.

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.

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 details of 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.
  • 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 samples.
  • 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.

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 of any type.
  • 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.
  • 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 tab for a source to see the other information associated with this particular source.

Lineage: See the lineage of 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, not for the source itself.

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.

Edit Multiple Sources

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

  • Edit > Edit in Grid: Edit values directly in a grid.
  • Edit > Edit in Bulk: Assign the same value to one or more fields in the batch of selected rows.

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, you can enter Reason(s) for deleting which will be included in the audit log.
  • 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. Again, you can enter a deletion comment for the audit log before confirming.

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.

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) project. If the creation button is missing, navigate first to the home project.

  • Give the assay design a Name (Required). The name must be unique and cannot be changed after the design is created.
  • 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 rows 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 expansion icon.

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

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.

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 "Disabled/Enabled" slider to activate updating any row and enter the new value. Values in columns which are disabled in the update will remain unchanged.

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 overview page for that assay. You will see the assay description, as well as a grid of runs.

In addition to the overview tab, tabs for runs and results for the assay are available in the upper left. 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 overview page.

  • To edit the design select Manage > Edit Assay Design.
  • The panels for editing properties and fields in your assay will open.
  • 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 overview 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.
  • 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. Click the Runs tab in the upper left to manage runs.

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.

Click 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 and click 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 or Overview tab, select one or more runs and choose Edit > Delete.
  • In the popup, you can enter Reason(s) for deleting which 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.

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. Click Finish Updating # Results to save your 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; choosing Enabled 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 leave 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, you can enter Reason(s) for deleting which 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) project. If the creation button is missing, navigate first to the home project.

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.
  • Label: Optional text description that will be shown with the name to help users.
  • 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.

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.

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. It summarizes the details, capacity, and will later show the contents. Learn more about the overview page 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.

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. This applies to administrators as well as other users. This topic assumes the user has this role.

Start from the Storage System

Start from a Picklist or Grid of Samples


Start from the Storage System

Find Available Space

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

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.
    • OR, click Add Samples without making any selection. All available positions will be eligible for placing samples.

Position Already Occupied

If you select a range of cells and one (or more) are already occupied by samples, you will see sample details for them on the right. When you click Add Samples, you will still see the selected rows in the grid, but the occupied rows are shaded red and cannot be edited or used to place new samples.

Identify Samples to Store

Once you have clicked Add Samples, the right side of the panel becomes your sample identification region.

Edit Location Properties

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

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 (or create a new one) and can then assign them to locations.

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:

  • From Source: Select a specific source to see samples derived from it.
  • From Parent: Select a sample to show all its child samples.
  • 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. By default the samples will be placed in the first available layout positions (using left to right, top to bottom sequencing). You can adjust these default assignments by moving the row in the grid to the row for another available position in the layout.
  • 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:

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

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.

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.

Use the icons to expand the hierarchy of the storage of your choice, seeing available spaces at each level. When you find the desired terminal storage unit, click Select.

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

Once you have selected a single storage location with enough space for all selected samples, you can now click Continue to go to the same interface for assigning locations to your selected samples as if you had started from the storage system to store them.

  • Populate the grid.
  • For boxes, plates, and tube racks, the samples will default to the first available slots in the structured layout.
    • Move the rows to other grid positions to change where in the unit you will store them.
  • Click Add to [Storage Type] to complete the position assignments.

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 Continue. The Select button will change to Clear once you've clicked it in case you change your mind. In this example, we have 9, so only 3 more for the next 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 Samples 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 Storage List offers administrators two action buttons, above the list of storage systems:

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

To manage storage units, select Storage from the main menu and click Manage Storage Units in the Storage List panel. 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 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 25 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 preview of how the spaces in your box will be labeled (shown here "A-1").
    • 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 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 preview of how the spaces in your plate will be labeled (shown here "A-1").
    • 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 preview of how the spaces in your rack will be labeled (shown here "A-1").
    • 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


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 storage details shows a high level view of storage status, details, and contents

Storage Status

The Storage Status panel shows the current status in a colored block. Click the to select among the options: "Active, Defrosting, Backup". It also highlights the set-point temperature and usage of 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 Details

The Storage Details panel lists the properties, including advanced settings, defined for this storage.

Storage Contents

Below the status and details panels, 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.)
  • 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:

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

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

Select Delete Storage from the Manage menu while viewing the details for that storage system.

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 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.
  • You will be asked to confirm this action before it is deleted.

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.

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 contacting LabKey, we can configure your physical location hierarchy within the application for you, so that you can set the Physical Location, and then all users can see this information in the application interface.

Note that this is distinct from the storage unit hierarchy within the storage, which local administrators can configure themselves.

Configure Location Options

Currently, LabKey will set up your physical storage location options for you.

To get started, contact your Account Manager with 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

With this information, LabKey will configure the necessary Physical Location hierarchy for you to use. Storage 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.

Set Physical Location

Once LabKey has set up your Physical Locations, you will be able to edit existing storage 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. Click to select it, 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.

Related Topics




Move Stored Samples


This topic describes how to move Samples from one storage location to another. To move samples in storage, the user must have been granted the Storage Editor role.

A location that can hold samples directly (like a box or plate) is called a "terminal storage unit". A location which contains other storage units but cannot directly hold samples (such as a shelf) is a "non-terminal storage unit". Some terminal storage units, like boxes and plates, have a row and column structure, referred to here as a "layout" giving each sample as specific spot. Others, like bags, are not structured.

Move One Sample

To move a single sample, first, find it in storage. You can navigate the storage hierarchy to find the Storage View of the place where it is stored, or 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 selected, you will have a Move button if you are authorized to move samples.

Move Within Current Terminal Storage Unit

When moving within a box, plate, or tube rack, you will now see two layouts, allowing you to click a location in the right panel to select it as the "destination" for the sample you are moving (from the highlighted section in the left panel). Color coding is repeated so that you can see at a glance which spaces are available.

Click the new location for your sample to select it.

When moving within a cane, there is no layout, you use the Location/SampleId table. Start to type the Sample Id of the sample you are moving into the desired cane position. When shown in the completion menu, select the Sample Id to place it.

Once you select a location on the right for any type of storage, your button options will be:

  • Move Here: Complete the move to the selected location.
  • Change Destination: Opens a menu for navigating the available storage hierarchies to find another storage location.
    • If you only wanted to pick a different space in the local layout, you could just click it or edit the table.
  • Cancel Move: Leave the sample(s) in the original storage location(s).

Move to Another Storage Location

When you want to move a Sample to another location, you will navigate the storage hierarchy in a series of expandable sections to find the desired destination. Available capacity is shown as you navigate. Use to expand the sections and click Select when you find the desired location.

If the target location is a bag or cane, you will see your new sample added to the location listing. If the destination is a plate, box, or tube rack, you will select a new position in the layout.

The options are the same as for local moves:

  • Move Here: Complete the move to the selected location.
  • Change Destination: Opens a menu for navigating the available storage hierarchies to find another storage location. If you only wanted to pick a different space in the local layout, you could just click it.
  • Cancel Move

Move a Group of Samples

To move a group of Samples, start from the Storage View of where they are currently located. Either drag or click within the layout, or use checkboxes to select the samples you want to move.

You'll see an abbreviated set of details and the same Move menu as for a single sample:

  • Move within this location: The same process as for moving a single sample locally, except that you will select as many target locations as needed for the group.
    • You can move samples back into the same locations as they originally occupied (such as in a different sequence) if desired.
  • Move to another storage location: The same process as for moving a single sample to another location.
    • If you choose a location without enough room for all the samples, you will be warned and be able to choose a different location.
  • To change the size of a terminal storage unit, such as to move a box of samples to a different sized box, create a new unit of the new size, then use this option to move the group of samples.
For moving a group of samples, by default, the moved samples will be placed "in order" as you click the new locations. You can adjust which sample goes to which cell (if needed) using the Location/SampleID table below the target grid, as shown here:

Move a Storage Unit

To move an entire storage unit, whether it contains samples or not, you might create a new storage unit in the new location and use the steps above to move a group of samples to a new location. You must use this option if you wish to change the definition of the unit, such as to move a box of samples to a different sized box. However, this option does not preserve the location history for the storage unit across this change.

Move to Any Storage

A storage unit, whether empty or full, can be moved to a new location either in the same storage system or in a different one by clicking Move Storage Unit from most views of the storage unit. You can move both individual terminal storage units, (such as boxes) and 'container' storage units (such as racks or shelves), which will also move all the units they contain.

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 within the current storage, any samples it contains will stay with the same position assignment within the storage unit.
    • See below for an alternative method for moving within a storage system.
  • If you move a storage unit containing samples to a different storage system, the samples will still retain their position assignments within terminal storage units.
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 terminal 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

Related Topics




Manage Stored Samples


Many sample creation and management actions for samples in storage can be completed directly from the storage view, simplifying the process for sample managers. This topic outlines these options for stored 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 More > Derive and the desired action.

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 amount (with units) and initial freeze/thaw count are usually provided (for temperature-controlled storage). If they are missing, or if you need to edit this information later, you can do so by clicking the sample, and clicking either icon in the Storage Details section to open an Edit Storage Fields panel.

Update the information in the popup, enter a comment to explain the adjustment you're making (optional), then click Update Sample to save your change. The comment will be retained in the audit log and timeline for the sample.

Discard Sample from Storage

The action of discarding 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 details about stored amount and freeze/thaw counts 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.

Discarding samples will:

  • Remove them from your storage location views.
  • No longer retain their stored amounts or 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.
You can discard one or more Samples from Storage in many places throughout the application, including:
  • From the Sample details page, select Discard from Storage from the Manage menu.
  • From a grid of Samples, select samples using the checkboxes and select Storage > Discard from Storage.
  • From the Storage View of the Sample(s) location, select the sample(s), then click Discard.

Update Status During Discard

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

You can also check the Set Sample Status checkbox to assign a new sample status at this time. For example, discarding a sample often means it has been "Consumed".

Enter a comment to accompany the action, if desired, and click Yes, Discard Samples.

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.

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 Comments on check out that will be recorded with this action. 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 Comments on check in to be recorded (Optional).
  • 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 "discarded 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 discarding 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 details 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 must create the virtual storage in Sample Manager or Biologics first. 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.

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
  • 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.
  • 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.
  • EnteredStorageDate
    • Must be a valid date or date-time value.
    • Represents when the sample was stored in the physical storage system.
    • If omitted, the time of the data import, i.e. the time of entering the management system is used.
  • CheckedOut
    • Must be a valid date or date-time value.
    • If omitted and a CheckedOutBy user is provided, the current date will be used.
  • CheckedOutBy
    • Must be a valid email address, username, or userID for a user in the system with sufficient permissions to check out samples. Learn about adding users here: User Accounts, Groups, and Roles.
    • Leading spaces and quote marks are not tolerated.
    • If omitted and a CheckedOut date is provided, the sample will be checked out by the user importing the data.
  • StorageComment
    • Always optional.
    • Will be ignored if the action for the import is not checking in, checking out, or discarding.

Adjusting Storage Fields to Match Other Systems

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

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

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

Add a sample to storage

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

Notes:

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

Import of Samples with Location Data

Once your spreadsheet is ready:

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.

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

Once you have added tasks to a job, the button near the top to Save as Template will be activated. If you want to save the current set of tasks as a new named template, click this button. Note that this will exit the job creation editor and a new job will not be created at this time.

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
    • From Parent
    • From Source
    • 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

Before finishing job creation, consider whether you want to make the details, tasks, and files of this job available as a template for creating similar future jobs. Samples are never part of job templates. Creating a template from a job is offered only during initial job creation.

  • Click Finish Creating Job to start the job without creating a template.
  • Use the dropdown menu option Save as Template and Start Job to create a template and start this job.
Once the job is started, 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 Template from Job

As you finish creating a job, you could select either one of two alternate ways to save the job as a template. Once the job has been started, you cannot generate a template from it.

  • Save as Template
  • Save as Template and Start Job

Either of these options will turn the task sequence you just created into a template that can be used to create future similar jobs. In a popup, you will name the template and provide an optional description.

Learn more about creating job templates in this topic: Create a Job Template

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

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, you have the same options for finishing as described above. Your new job created from a template can be used to create a new template, just be sure to give that new template a new name.

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

Jobs Home

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

By default, you'll see Your 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 Queue: Jobs and tasks assigned to you.
  • 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.

My Queue

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

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 leave a comment when you reactivate a task, explaining the action.

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

To delete a job that is no longer necessary, select Manage > Delete Job.

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 edited or 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.

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:

  • Workflow: Open the dashboard on "Your Queue".
  • Jobs List: Open the dashboard on "All Jobs"

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.

You can also delete a single job by opening it and selecting Delete Job from the menu next to the name.

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.

You can edit the Name and Description, and add (or remove) custom fields. You cannot edit the tasks associated with the template.

Editing a template does not change any jobs that have already been created from the previous version of the 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


This section includes resources for structuring and working with data within LabKey Sample Manager.

Topics




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:

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, the secondary menus will be collapsed into a More menu 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.

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.

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

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.

Editable Grids

Editable grids can be found throughout the application for entering and editing data for Samples, Sources, Assays, etc. When using an editable grid, you can make use of the following options:

  • The contents of the grid can be exported by clicking the button. Choose CSV, TSV, or Excel format exports. Fields from all tabs of the editable grid will be included in the export.
  • 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.
  • 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.

Drag to Populate Column with Text or Numbers

Fields of type Text (String) and Integer offer special options for populating them.

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.

For an Integer or Decimal number, enter two or more numbers, then select both and drag the handle through the remaining cells you want to fill with the same sequence. For example, below you can 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).

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
  • Label: If BarTender label printing is configured, you can also export and print labels 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.

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, choose Background Imports from the user menu.

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 '///' 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 the system 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
  • Name
  • RowId
  • LSID
  • Folder
  • Properties
In addition Sample and Source Types reserve these field names:
  • Description
  • SampleId & SourceId
  • SampleState (surfaced as "Status" in the application)
  • MaterialExpDate (surfaced as "Expiration Date" in the application)
  • Flag
  • SourceProtocolApplication
  • SourceApplicationInput
  • RunApplication
  • RunApplicationOutput
  • Protocol
  • Alias
  • SampleSet & DataClass
  • Run
  • genId
  • Inputs
  • Outputs
  • SampleCount
  • StoredAmount
  • SampleTypeUnits
  • Units
  • Freeze/Thaw Count
  • StorageStatus
  • StorageLocation
  • StorageRow
  • StorageCol
  • CheckedOutBy
  • CheckedOut (Date)
  • IsAliquot
  • AliquotCount (surfaced as Aliquots Created Count in the application)
  • 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.

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, or users can create and save their own views most pertinent to them.

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. 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 select a new column to add 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.

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.

Give your grid view a name, and click Save.

You'll now see your named grid on the Views menu. Learn more below.

Note that unless you are an administrator, you cannot update the default view. You also cannot use the name 'Default' and administrators should not use the name 'My Default' to avoid confusion on the menu later.

Administrators Only: Change the Default View

Administrators saving changes to a grid will see a checkbox offering them the option to save their changes as the default grid view for all users.

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.

Access your 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.

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 named 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 any tab within the Administration dashboard. Customized grids can present audit information in the way most useful to them.

View Audit History

Select Administration from the user avatar menu; you'll land on the Audit Logs tab.

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.
  • Freezer Management Events: See View Storage Activity.
  • List Events
  • Notebook Events
  • Notebook Review 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.
  • 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, or change the default view all administrators will see.

Learn more in this topic:

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. Results are ordered by relevance. This topic describes site wide search behavior and options. Searching for samples by ID or barcode is covered in the topic: Sample Search To find samples in bulk, by barcode or sample ID, use this topic:

Search Basics

To search for samples, assays, and more, type the search terms in the box in the header of the application. When the browser is narrow, the option will be on the search dropdown menu.

The search results will be shown with a few details about the type of item matching the search, shown below a sample and a workflow job are found when we search for "020". Click the item block in the search results to see the full item.

Search Terms and Operators

To search, enter terms (search words) and operators (search modifiers) in the search box using the following guidelines:

Terms

  • The words or phrases you enter are searched as if they have "OR" between them by default. This means results returned will include at least one of the terms.
    • Example: a search for Blood test returns all pages that contain at least one of the terms "Blood" and "test". Pages that contain both will appear higher in the results than pages that contain just one of the terms.
  • Double quotes around phrases indicate that they must be searched as exact phrases instead of as individual terms.
    • Example: Searching the quoted phrase "Blood test" returns only pages that include this two word phrase.
Operators
  • AND: Use the AND operator to limit results to pages with both terms.
    • Example: Blood AND test returns all pages that contain the term both the term "Blood" and the term "test", in any order.
  • +: A search term preceded by the + operator must appear on returned pages.
    • Example: Blood +test returns pages that must contain the term "test" and may contain the term "Blood".
  • NOT: Use NOT before a search term that must not appear on returned pages.
    • Example: Blood NOT test returns pages that contain the term "Blood" but do not contain the term "test".
  • -: Use like the NOT operator; a term preceded by - must not appear on returned pages.
    • Example: Blood -test returns all pages that contain the term "Blood" but do not contain the term "test".
Note: If you use a '-' hyphen as a SampleID separator element (as in the default naming pattern "S-${genId}") be aware that you need to surround a search for one of these sampleIDs with double quotes.
  • Searching for "S-11" will find the sample named S-ll.
  • Searching for S-11 without the quotes will return results that contain "S" and not "11", i.e. will not find the desired sample.

Other Guidelines

  • Capitalization is ignored.
  • Parentheses can be used to group terms.
  • Extraction of root words, also known as stemming, is performed at indexing and query time. As a result, searching for "study", "studies", "studying", or "studied" will yield identical results.
  • Wild card searches
    • Use the question mark (?) for single character wild card searches. For example, searching for "s?ed" will return both "seed" and "shed".
    • Use the asterisk character (*) for multiple character wild card searches. For example, searching for "s*ed" will return both "seed" and "speed".
    • Wild card searches cannot be used as the start of the search string. For example, "TestSearch*" is supported, but "*TestSearch" is not.
    • Note that stemming (defined above) creates indexes only for root words, so wild card searches must include the root word to yield the intended results.

Content Searched

  • Sample Types (Name and description)
  • Samples (SampleID and description)
  • Source Types (Name and description)
  • Sources (SourceID and description)
  • Assay Designs (Name and description)
  • Jobs (Name and description)

Search Refinement and Filtering

When searches yield very large result sets, using filtering and search refinement can help locate the set of results you want.

Click Show filters > to open the filters panel. You can:

  • Filter by type: check the boxes for the types of results you want to see (as many as apply). You'll see how many results there are of each type in parentheses.
    • Samples, Sample Types
    • Sources, Source Types
    • Assay Designs
    • Jobs
  • Refine results for:
    • Use the wide dropdown menu to narrow results by category, date, and user. Category options for refining add additional filters below the "By User" menu shown for all selections.
      • All (Default)
      • Samples (adds "Of sample type" and "Has assay runs for")
      • Assay Runs (adds "Has assay runs for")
      • Sources (adds "Of source type")
      • Jobs (adds "Job status")
    • Select one of Created/Modified from the dropdown, then enter "From" and "To" dates.
    • By User: Select a user and see only results associated with that user.
  • Click Clear to clear filters.
  • Click Show Results to apply them.

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. Each data type 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 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, a slider marked Detail mode indicates that all of the above options have been shown in the field detail mode. Click the slider to switch to Summary Mode.

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 the slider to switch back to Detail mode 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 an assay 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 Options

  • Text 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 Options

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

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 and Number Formats Reference


This topic covers formatting options for dates, times, and numbers within LabKey Sample Manager.

Date and DateTime Format Strings

Format strings used to describe dates and date-times must be compatible with the format accepted by the Java class SimpleDateFormat. For more information see the Java documentation. The following table has a partial guide to pattern symbols.

LetterDate/Time ComponentExamples
GEra designatorAD
yYear1996; 96
MMonth in yearJuly; Jul; 07
wWeek in year27
WWeek in month2
DDay in year189
dDay in month10
FDay of week in month2
EDay in weekTuesday; Tue
aAm/pm markerPM
HHour in day (0-23)0
kHour in day (1-24)24
KHour in am/pm (0-11)0
h .......Hour in am/pm (1-12) .......12 .......
mMinute in hour30
sSecond in minute33
SMillisecond978
zTime ZonePacific Standard Time; PST; GMT-08:00
ZTime Zone-0800
XTime Zone-08; -0800; -08:00

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:mmaa2008-05-17 01:45PM
yyyy-MM-dd HH:mm:ss.SSS2008-05-17 01:45:55.127
MMMM dd yyyyMay 17 2008
hh:mmaa zzzz01:45PM Pacific Daylight Time

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.



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