• Store and manage sample inventories
• Link to associated assay and experiment result data
• Track laboratory workflows and sample processing
• Use Freezer Management tools to track samples in storage. (Learn more in the documentation.)

Explore LabKey Sample Manager. See what a working system looks like in our read-only example project:

• Explore Sample Manager

• Tour Sample Manager

Topics

• Tutorial: Learn Sample Manager: Step by step instructions to start using Sample Manager
• Get Started with Sample Manager
• Sample Manager Dashboard
• My Account
• Search

More Answers

• Release Notes - Sample Manager: What has changed in Sample Manager
• Sample Manager - FAQ

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

• Tutorial: Learn Sample Manager

Configure Freezers

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

• Freezer Management

Add Sample Inventories

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

• Create a Sample Type
• Create or Import Samples

Associate Sources

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

• Create Sources
• Associate Samples with Sources

Define Assays

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

• Describe Assay Data Structure
• Import Assay Data

Outline Workflow

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

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

Explore More

Now that you understand the basics, you can learn more about real use cases by exploring our read-only example of a LabKey Sample Manager application in active use.

• Explore Sample Manager
• Tour the Sample Manager Example

• Administrator Tutorial
• User Tutorial Sections

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

• Step 1: Tutorial: Add Samples
• Step 2: Define Assays
• Step 3: Add Users and Assign Roles
• Step 4: Outline Workflow
• Step 5: Track Sample Sources

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:

• Import Sample Data
• Associate Samples with Sources
• Import Assay Data
• Create (and Complete) Workflow Jobs and Tasks
• Explore Sample Lineage and Timelines

• View Sample Details
• View Assay Data by Run or for a Specific Sample
• View Picklists
• Complete Assigned Tasks and View Workflow Job Details
• View Storage Details

• Create a New Sample Type
• Define Sample Type Properties
• Define Sample Fields
• Import Samples from File
• Other Ways to Import Samples
• View Sample Details

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

• 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 volume.
• 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.
• The default panel 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 "Project" 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:
• TutorialSamples.xlsx
• The "Tutorial Samples" Sample Type is now available on the main menu. Click to open it.

• Select Create > Tutorial Samples.

• Click Import Samples from File.

• 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 we 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 in a grid or using bulk insert methods. Learn more in this topic:

• Create Samples from Grid

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)

Related Topics

• Create a Sample Type: More details about creating sample types.
• Create or Import Samples: More ways to create and import samples.
• Sample ID Naming: Sample ID naming

Start Over | Next Step (2 of 5)

• Create Assay Design
• Define Assay Properties
• Add Run Fields
• Add Results Fields
• Import Assay Data
• Upload Results from File
• Other Ways to Enter Results

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

• Download: TutorialAssay_Run1.xlsx

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 Upload Files tab is selected by default.
• 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. This grid allows you to 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:

• Import Assay Data

Related Topics

• Describe Assay Data Structure
• Import Assay Data

Previous Step | Next Step (3 of 5)

• Add Users
• Assign Roles
• View Audit History

Add Users

• To add one or more new users, select Administration from the user menu.

• You'll start on the User Management page, i.e. the Users tab.
• Click Create.

• 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, leave only the default Reader for now.
• Uncheck the box to Send notification emails to all new users since these are not real email addresses.

• Click Create Users.

Assign Roles

Once users have been defined, an administrator can assign them one of the three available permission levels:

• 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 below. This includes user management, permission assignments, and creating and editing sample types, assays, and job templates.
• 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.

• Reopen user management if you closed it by selecting Administration from the user menu. Click the Permissions section.

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

• Manage Users

Previous Step | Next Step (4 of 5)

• Create a Job with Selected Samples
• Job Details
• Define Job Tasks
• Assign Samples
• Finish Creating Job and Template
• Complete Job Tasks
• View Timeline

Create a Job with Selected Samples

• Select "Tutorial Samples" from the Sample Types section of the main menu.

• Check the boxes to select "Tutorial-018", "Tutorial-019" and "Tutorial-020".
• We're including some assay data for these specific samples below.
• Select Jobs > Start a Job with Selected Samples from the menu above the grid.

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: Use the pulldown menu to 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

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.

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.

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.

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

• Get Started with Sample Manager
• Workflow
• Edit Jobs and Tasks
• Create a Job Template

Previous Step | Next Step (5 of 5)

• Physical like labs, vendors, locations, studies, etc.
• Biological like patients, mice, trees, cell lines, etc.

• Create a Source Type
• Create Sources (Populate a Source Type)
• Create and Populate a Second Source Type
• Associate Samples with Sources
• View Lineage
• View Timeline

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 reserved fields were found and are not shown. This refers to the "SourceId" field that is present in the data file and cannot be "defined again."

• 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 Create > Tutorial Labs.
• Click Import Sources 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.

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 directly editing each individual Sample. 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 > 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 Create > Tutorial Samples.
• Click Import Samples from File.
• Check the box to Update data for existing samples during this file import.
• Download this file: TutorialSamplesWithSources.xlsx then drop it into the target area.
• You'll see a preview:

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

• Samples
• Sources
• Experiment / Assay Data
• Workflow

Previous Step

This topic details changes and enhancements in each release as a guide to help users track changes.

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)

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 (docs)
• 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)
• Contact us to have your Freezer Location hierarchy configured.
• Manage all samples and aliquots created from a source more easily. (docs)
• Comments on workflow job tasks can be formatted in markdown and multithreaded. (docs)
• Redesigned job tasks page. (docs)

Release 21.9, September 2021

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

Release 21.8, August 2021

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

Release 21.7, July 2021

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

Release 21.6, June 2021

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

Release 21.5, May 2021

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

Release 21.4, April 2021

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

Release 21.3, March 2021

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

Release 21.2, February 2021

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

Release 21.1, January 2021

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

Release 20.12, December 2020

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

Release 20.11, November 2020

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

Release 20.10, October 2020

• Integration with BarTender to print labels.

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!

• Dashboard Insights
• Jobs List
• Freezer List

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:

• Sample Finder

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.

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

Learn more about samples in this section:

• Samples

Jobs List

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:

• Workflow

Freezer List

The freezer list presents a quick summary of your freezers, 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 freezer.

• Manage Freezers

Related Topics

• Get Started with Sample Manager

• Sign In and Out
• Session Expiration
• Edit Your Profile

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.

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:

• Manage Users

• Apply Naming Prefix
• Force Usage of Naming Patterns for Consistency

Apply Naming Prefix

This prefix is typically short, must be unique site-wide, and should be recognizable to your users. Before setting one, make sure you understand what will happen to the naming patterns and names of existing entities in your project.

• All Naming Patterns for Sample Types and Source Types will be updated to include the new prefix.
• New samples and sources created after the addition of the prefix will have names that include the prefix.
• Existing samples and sources created prior to the addition of the prefix will not be renamed and thus will not have the prefix (or might have a different previously-applied prefix).
• Sample aliquots are typically created and named including the name of the sample they are aliquoted from. This could mean that after the prefix is applied, new aliquots may or may not include the prefix, depending on whether the originating sample was created before or after the prefix was applied. Learn more about aliquot naming here: Aliquot Naming.

To set a prefix:

• Select Administration from the user avatar menu.
• Click the Settings tab.
• Scroll down to the ID/Name Settings section.
• Enter the prefix to use. You will see a preview of what a naming expression with the prefix applied might look like using a representative pattern, Blood-${GenId}, as an example.

• Click Apply Prefix to apply it.
• This action will change the Naming Pattern for all new and existing Sample Types and Source Types. No existing IDs/Names will be affected. Are you sure you want to apply the prefix?
• Click Yes, Save and Apply Prefix to continue.

Force Usage of Naming Patterns for Consistency

To maintain consistent naming, particularly when using container-specific naming prefixes, you may want to restrict users from entering their own names for samples and sources. This requires that all types have a naming pattern that can be used to generate unique names for them.

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

Additionally:

• Attempting to import new data will fail if an ID/Name is encountered.
• Attempting to update existing rows during file import will also fail if an unrecognized/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 ID Naming

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

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

Data Ownership and Audit

If I store my data in hosted 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 hosted 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 a hosted Sample Manager application?

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

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

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

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

• Sample Timeline

Sample Identification

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

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

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

Does Sample Manager handle replicates?

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

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

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

• Sources

Does Sample Manager support using a barcoding system?

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

• Barcode Fields

• Integrate with BarTender

Freezer Management

Does Sample Manager provide a freezer management solution?

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

• Freezer Management

Data Structures for Assays and Samples

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

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

Are the Assays customizable? Can I create my own assays?

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

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, users have the option to let the application infer fields in the data structure from the columns in a spreadsheet.

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.

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.

Jobs, Tasks, and Templates

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 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 Sample Manager application, 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 the hosted Sample Manager application will export the managed sample data for analysis and reporting. In the future, analysis and reporting will be added within the application.

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

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

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

Related Topics

• Data Import Guidelines

More Questions?

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

• Contact Us

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

Topics

• Create a Sample Type
• Create or Import Samples:
• Create Samples from Grid
• Import Samples from File
• Sample ID Naming
• Sample Lineage / Parentage
• Aliquots, Derivatives, and Sample Pooling
• Sample Timeline
• Manage Samples
• Manage Sample Status
• Edit Selected Samples
• Sample Finder
• Sample Search
• Integrate with BarTender
• Barcode Fields
• Sample Picklists

Tutorial

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

Related Topics

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

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
• Define Sample Type Properties
• Naming Pattern
• Aliquot Naming Pattern
• Storage Settings
• Barcodes
• Define Sample Type Fields
• Built-In Sample Type Fields
• Add Sample Type Fields
• Edit Sample Type Design
• Label Colors
• Resource: Sample Naming Pattern Examples

Create a New Sample Type

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

Define Sample Type Properties

• The Name of the Sample Type is required, must be unique, and cannot be changed later.
• 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". For each Sample Type, determine whether you will provide these sample IDs or whether you want the system 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", 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 an incrementing counter.

Aliquot Naming Pattern

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

${${AliquotedFrom}-:withCounter}

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

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

${${AliquotedFrom}.:withCounter}

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

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)

Barcodes

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

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

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

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

Learn more about creating and using barcodes in this topic: Barcode Fields

Define Sample Type Fields

Built-In (Reserved) Fields

Every Sample Type is created with several default fields (columns) built in. You do not add and cannot change these fields; these are "reserved fields" and are always created in a new Sample Type:

• SampleID: The name 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.
• SampleState: Tracks the status of the sample.
• Created & CreatedBy: These are populated with the userID and time of creation.
• Modified & ModifiedBy: These are populated with the userID and time of modification.
• Stored Amount
• Freeze/Thaw Count
• Storage Status
• Checked Out By & Checked Out: These are populated with the userID and time of checkout.

Add New Sample Type Fields

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

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

• Import or Infer Fields from File
• Manually Define Fields

Import or Infer Fields from File

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

Manually Define Fields

Instead of using a file, click the text 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. Learn more in this topic.
• Select the Data Type. Learn more about types and their properties here.
• 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.

Finish Creating Sample Type

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

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 the menu. Reopen the Sample Type design for editing by choosing Edit Sample Type Details from the menu.

You cannot change the name of the Sample Type, and should use caution if changing the naming pattern to ensure SampleIDs remain unique.

After completing edits, click Finish Updating Sample Type in the lower right.

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.

Resource: Sample Naming Pattern Examples

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

Learn more about building naming patterns in this topic: Sample ID Naming

Related Topics

• Barcode Fields
• Tutorial: Add Samples
• Get Started with Sample Manager
• Sample ID Naming
• Attach Images and Other Files
• Create or Import Samples
• Samples
• Field Editor

Once you have created the Sample Type, you can create the samples themselves in several ways. Import an existing inventory spreadsheet, create 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

• Choose Desired Sample Type and Import Method
• Create Samples from Grid
• Import Samples from File
• Work with New Samples
• Create Derivatives, Pooled Samples, and Aliquots

Choose Desired Sample Type and Import Method

To create new samples, you specify the type of sample you are creating. Most Create menus give you a Samples option where you can choose the type of sample to create by selecting Create > [Sample Type].

• The most general method is to go to the home page dashboard and click Create Samples. (On narrow browser windows you may need to scroll down to find the Dashboard Insights panel.)

• Click the tab for your import method:
• Create Samples from Grid (Default)
• Import Samples from File
• 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.

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.

Learn more in this topic: Import Samples from File

Work with New Samples

After creating samples, the banner message shows the number newly imported and offers the options to click to either add them to storage now or select them in the grid.

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

Create Derivatives, Pooled Samples and Aliquots

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

• Sample Lineage / Parentage
• Aliquots, Derivatives, and Sample Pooling

Related Topics

• Create a Sample Type
• Manage Sample Status
• Attach Images and Other Files
• Sample Lineage / Parentage
• Associate Samples with Sources: Create new samples from Sources of those samples.
• Aliquots, Derivatives, and Sample Pooling
• Data Import Guidelines
• Store Samples in Freezers
• Migrate Storage Data into Freezer Management

• Create Samples from Grid
• Add Parent (Optional)
• Add Source (Optional)
• Add Samples Individually
• Bulk Insert
• Bulk Insert with Parent(s)
• Bulk Update

Create Samples From Grid

Open the grid method for creating new Samples from the home dashboard by clicking Create Samples, choosing 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 the samples you want to create. Enter the number of samples you want to add 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.
• Fields that offer user dropdowns (such as Sample Status, list lookups, and Text Choice fields) will show an indicator to guide the user to open the selection menu.
• Hover over the for the Status column to see a legend of available statuses.

You will see the sample grid for that type, with a 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 workflow job. You can also click Add them to storage to immediately add the new samples to freezer storage locations.

Reopen to add more samples by selecting Create > [Sample Type].

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.
• Note that if you have included a parent field, you will have additional options here.
• Enter values for any or all of the properties listed.
• Click Add Samples To Grid.

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

Bulk Insert with Parent(s)

If you added one or more parent fields before clicking Bulk 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 parent(s).
• Aliquots, specifying the number of aliquot copies per parent.

• 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

• Create or Import Samples
• Import Samples from File

• Import Samples from File
• Update Existing Samples

Import Samples From File

Open the grid method for creating new Samples from the home dashboard by clicking Create Samples, then click the Import Samples from File tab.

• Set the Sample Type for the Samples you will import.
• Use the Template button to download a template file showing the expected data structure for the type.
• 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 only the one you want to use needs to be populated.
• A checkbox is provided to Update data for existing samples during this file import. Learn more below.
• 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.

Update Existing Samples

During file import, a checkbox is provided to Update data for existing samples during this file import.

• When checked, you can include data for samples that already exist in the system.
• 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.
• If you don't check this box, the upload will be "insert only" and will fail if you attempt to import data for existing sample IDs.

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 Freezer Management

Related Topics

• Create or Import Samples
• Create Samples from Grid

• Unique Sample Names are Provided: Unique sample names are provided to the system
• Column Name is "SampleID" or "Name"
• Column Name is Something Else
• Generate Names with Naming Patterns: Generate unique names within the system
• Default Naming Pattern
• See and Set genId
• Date Based Naming
• Incorporate Column Values
• Incorporate Lineage Lookups
• Naming Pattern Elements/Tokens
• Formatting Values
• Default Values
• Incrementing Sample Counters
• :withCounter Modifier
• Naming Pattern Validation
• Examples

Unique Sample Names are Provided

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

Naming Column is "SampleID" or "Name"

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

Naming Column is Something Else

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

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

${Identifier}

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

Generate Names with Naming Patterns

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

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

Default Naming Pattern

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

S-${genId}

The first few samples would be:

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

See and Set genId

genId is an incrementing counter which starts from 1 by default, and is maintained internally for each 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 container 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.

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

To include properties of sample sources or parents in sample names, use lookups into the lineage of the sample.

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

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

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

If there might be multiple parent samples, you could choose the first one in a naming pattern like this:

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

Naming Pattern Elements/Tokens

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

Formatting Values

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

${genId:number('000')}

Learn more about formatting numbers and date/time values in this topic: Date 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

The sample counters are incremented for the date when the sample is inserted, but can use a different date by attaching the counter to a date column. For example, ${SampleDate:dailySampleCount} will use the date found in the row's "SampleDate" column or today's date if the column has no value.

Some auto-incrementing counters calculate the next value based on all samples in a given container, while others calculate based on only the current Sample Type. See the Scope column for the specific incrementing behavior. When the scope is container-based, within a given Sample Type, values will be sequential but not necessarily contiguous.

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

• Aliquot Naming Patterns

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

Naming Pattern Validation

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

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

Errors reported include:

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

Caution: Using Numbers-Only as Sample IDs

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

Examples

Example String Modifiers

The following naming patterns show usage of string modifiers.

Related Topics

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

• Add Parent Alias
• Add Source Alias
• Create Aliquots, Derivatives, and Pooled Samples
• Create from Samples Grid
• Create from Sources Grid
• Import from File
• Explore Sample Lineage Graph
• Explore Sample Lineage Grid

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:

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

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 Create > [Name of Sample Type].
• In the popup, specify whether you want to create:
• Derivatives: Create multiple output samples per parent.
• Pooled Samples: Put multiple samples into pooled outputs.
• Aliquots: Create aliquot copies from each parent sample.
• 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:

• Aliquots, Derivatives, and Sample Pooling

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.

Learn more about the specific fields to populate in this topic: Aliquots, Derivatives, and Sample Pooling

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.

Explore a more complex lineage example in our "Explore Sample Manager" demo project.

Lineage Grid

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

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

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

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

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

Troubleshooting

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

Related Topics

• Create a Sample Type
• Samples
• Sources
• Aliquots, Derivatives, and Sample Pooling

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

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

Derive Samples from Selected Parents

If you have already created the parent samples in the system and want to create new samples with specific parents (i.e. derive new samples), 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 Create > [Name of Sample Type].
• In the popup, if you selected multiple parent samples, specify whether you want to create:
• Derivatives: Create multiple output samples per parent.
• Pooled Samples: Put multiple samples into pooled outputs. Covered in the next section.
• 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 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 Create > [Name of Sample Type].
• In the popup, select Pooled Samples: Put multiple samples into pooled outputs.
• 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.

Create Aliquots

To create aliquot portions of samples, each with copied properties from the parent sample, follow the same initial process. 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 Create > [Name of Sample Type].
• In the popup, select Aliquots: Create aliquot copies from each parent sample.
• Add the desired number of Aliquots per parent by entering the number and clicking Go to Sample Creation Grid.

• You will see the Samples you had selected prepopulated as parents in every row of the 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 any remaining sample information 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.

Show Samples, Aliquots, or Both in Grids

To make it easier to work with aliquots, all sample grids include an "Is Aliquot" column, showing 'true' for aliquots. You can use grid filtering on this column in the omnibox, or use the checkboxes on the Show Samples menu above the grid to control whether to see:

• Samples and Aliquots
• Samples Only
• Aliquots Only

The name of this menu will reflect the current selections, and the filter will be shown if applicable. For example, Aliquots Only would filter to "Is Aliquot = true" and look like:

Import Aliquots, Derivatives, and Pooled Samples from File

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

Aliquots

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

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

Derivatives

Pooled Samples

Work with Aliquots

View Aliquots of a Sample

When viewing sample details (click the name of the sample on the grid) you will see a panel showing 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 Lineage / Parentage
• Manage Samples: Edit lineage for a single sample.
• Edit Selected Samples: Edit parents and sources for multiple selected samples.
• Manage Sample Status

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

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

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

View Sample Timeline

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

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

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

Current Status

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

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

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

Event Details

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

Listing Order

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

Filter Timeline

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

Use checkboxes to filter events to show any combination of:

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

Export Timeline

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

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

Related Topics

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

• View All Sample Types
• Grid (Default)
• Heatmap
• Cards
• View Samples of One Type
• Sample Type Details
• Sample Insights Panel
• Menu
• Manage Menu
• Jobs Menu
• Storage Menu (Available to users with the Storage Editor role.)
• View Individual Sample Details
• Edit Sample Details
• Edit Sample Lineage
• More Sample Editing
• Delete Samples

View All Sample Types

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

You can select between several ways to view all the samples in the system.

Grid

The grid view of all Sample Types lists the name, description, and other details about each type of sample in the system.

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

Heatmap

The heatmap shows a 12 box row for each type, representing 12 months of sample collection. Darker shades are used for months where more samples were collected. Hover over any square for more details.

Click a square to open a grid view of data filtered for that month and Sample Type.

Cards

The card view of all samples indicates the total number of samples for that type.

Click a card to see the grid of data for that Sample 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 one of the ways to view all Sample Types listed above
• Click the graph bar for that Sample Type on the main dashboard
• Clicking 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

Below the details and insights, the grid of Samples can be filtered, sorted, and searched using the omnibox selection field. You'll see the Status of each sample with color coding of different types of status.

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.

Menu

The menu in the upper right (expanded above) 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. Note that you cannot edit the Name of the type, and use caution if you change the naming pattern that you will maintain unique names for each sample.
• Edit Details
• Edit Fields
• 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.

Manage Menu

Actions on the Manage menu for a Sample Type include:

• Import Samples
• Delete Samples
• Edit Selected Samples in Grid: Edit the selected rows in a grid.
• Edit Selected Samples in Bulk: Assign the same value to one or more fields of a batch of selected rows.
• Edit Sources for Selected Samples in Bulk
• Edit Parents for Selected Samples in Bulk
• Add to Picklist

Jobs Menu

The Jobs menu offers the following options. Learn more at the links:

• Start a Job
• Start a Job with Selected Samples
• Add Samples to Existing Job

Storage Menu

The Storage menu offers users with the Storage Editor role the following options. Learn more at the links:

• Add to Storage
• Check Out
• Check In
• Discard from Storage

View Individual Sample Details

Click the Sample ID for any sample to view the details entered about it. Panels for Storage Location, Aliquots, and Details give you the specifics for this sample. From the (bars) 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.

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.
• Details: Details about this sample.
• For an aliquot, this panel will include details about the aliquot and about the original sample.
• Source Details: Information about sources of this sample.
• Parent Details: Information about parents of this 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.

Edit Sample Details

To edit the details for this sample, including the description, 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.

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:

• Edit Selected Samples

Delete Samples

Deletion of samples may be necessary for a variety of reasons, and once completed, deletion cannot be undone. You can delete a single sample while viewing it's details page.

• From the detail page for the sample to delete, open the (bars) menu on the right.
• Select Delete Sample.

• You will be asked to confirm the deletion.

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 Manage > Delete Samples.

• You will be asked to confirm the deletion.

If any of the samples you attempt to delete were used to derive other samples (i.e. are parent samples) or are associated with assay runs (i.e. linked as lookups from data you have imported) you will not be able to delete them. 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. On affected picklists, users will see a blank row where the deleted sample used to be.

Related Topics

• Samples
• Aliquots, Derivatives, and Sample Pooling
• Edit Selected Samples
• Manage Sample Status

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
• View or Edit Status Details
• Add New Status
• Assign Sample Status
• Change Status to Consumed
• Sample Status Legend
• View Sample Status
• Status of Samples in Storage
• Status of Samples on Picklists
• Sample Count by Status Dashboard

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.

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

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

Status of Samples in Storage

These color codes are also used in storage views to indicate status. Hovering will give you more detail, as shown below for a locked sample.

Status of Samples on Picklists

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

• Samples

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

• Edit Selected Samples in Grid
• Sample Data
• Storage Details (Available to users with the Storage Editor role)
• Lineage Details
• Edit Selected Samples in Bulk
• Edit Sources for Selected Samples in Bulk
• Edit Parents for Selected Samples in Bulk

Edit Selected Samples in Grid

When using the grid editor, there are three tabs available with grids of details.

• 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 first image below shows an open menu.
• 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.
• For example, the Tutorial Labs field in the third image below already contains one value, and you can add an additional value as appropriate.
• Hover over the for the Status field to see a legend of available statuses.

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.

Edit Selected Samples 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 "Project" 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 for Selected Samples in Bulk

When you Edit Sources for Selected Samples in Bulk, 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.

Edit Parents for Selected Samples in Bulk

When you Edit Parents for Selected Samples in Bulk, 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.

Related Topics

• Manage Samples
• Aliquots, Derivatives, and Sample Pooling
• Permission Roles

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.

• Sample Finder
• Choose Values
• Filter
• Edit Criteria
• Search Results

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.

Click to find samples by either:

• Source Properties
• Parent Properties

Click either the Source or Parent tile to add a new sample filter.

In the popup, choose the specific type (of source or parent), 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 Project is either A or W:

Filter

You can also use the Filter tab to specify a filtering expression and enter a value.

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 an additional filter on a different field of any parent or source filter you already created.

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.

Like with other sample grids, you can also use the omnibox to add further filters and sorts on the columns displayed until your grid shows the samples you want. You can view All Samples or just samples or aliquots.

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
• Adding to picklists or workflow jobs
• Storage Editors can manage storage status, including checking out the found samples

Related Topics

• Sample Search
• Search

• Sample ID
• Barcode: Barcodes include both:
• Unique Storage ID fields and
• Other data fields specifically designated as containing barcodes

If you want to search for samples by properties of their source or parent, you can use the Sample Finder.

If you are only looking for a single sample, you can use the site-wide search box with a single Sample ID or Barcode.

Topics:

• Find Samples in Bulk
• Find Samples by Barcode
• Find Samples by ID
• Add More Samples
• Clear Search Results
• Work with Found Samples

Find Samples in Bulk

Click the right edge of the search bar or the icon on narrower browsers and select:

• Find Samples by Barcode
• Find Samples by ID

Depending on which selection you made, one of the following will be selected in the popup. (You can change to the other method if desired.)

• Barcodes: Search for values in all fields designated as "Barcode Fields" across all Sample Types. This includes:
• All fields of type Unique ID.
• Any text fields designated as Barcode Fields; i.e. those which have the box "Search this field when scanning samples" checked.
• Sample IDs: Search all fields of type Sample.

List the Barcodes or Sample IDs, 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.

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 the following actions. All search result Samples are selected by default.

• Picklists:
• Create Picklist
• Add to Picklist
• Jobs:
• Start a Job with Selected Samples
• Add Samples to Existing Job
• Storage:
• Add to Storage
• Check Out
• Check In
• Discard from Storage
• (Export): Export the grid to a CSV, TSV, or Excel file.

Related Topics

• Sample Finder
• Search
• Barcode Fields

• Print BarTender Labels for Samples
• Print Labels for a Single Sample
• Print Labels for Multiple Samples
• Configure BarTender Integration
• Enable HTTPS Endpoint for BarTender
• Example BarTender Configuration File
• Error Reporting

Print BarTender Labels for Samples

Before you can print labels, an administrator must have completed the one-time setup steps detailed below. 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 menu.

In the popup, specify (or accept the defaults):

• Number of copies: Default is 1.
• Label template: If you want to specify a different template for printing this label, enter it here. The path you provide should be relative to the default folder configured for the web service. 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: If you want to specify a different template for printing this label, enter it here. The path you provide should be relative to the default folder configured for the web service. Default is the label template file configured above.

• Click Yes, Print to send the print request to BarTender.

Configure BarTender Integration

Note that these docs were written for BarTender 2019, which contains Print Portal by default. 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.

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. Sample Manager accepts a site-wide default label file, but also allows the user to specify a different variant at the time of printing.

• BarTender by Seagull Scientific

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:
• https://blogs.msdn.microsoft.com/rakkimk/2007/05/25/iis7-how-to-configure-a-website-for-https/
• (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

Example BarTender Configuration File

Download this example to help you get started:

• labkeyBT-2021.btin

• labkeyBT.btin

https://localhost/Integration/LabKeyBarTenderService/Execute

For versions prior to Bartender2021, use this URL:

https://localhost/BarTender/API/Integration/LabKeyBarTenderService/Execute

Configure Sample Manager to Print BarTender Labels

Return to Sample Manager 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.
• Label Template File: Specify the label file to use when printing labels with BarTender. The path should be relative to the default folder configured for the BarTender web service specified above.

• Use Test Connection to test your configuration.
• Click Save to save it.

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

• Samples

Once a sample has either type of Barcode Field, you'll be able to search for it using these values.

• Add UniqueID Field for LabKey-Managed Barcodes
• Generate UniqueID Barcodes
• Use Existing Barcode Values
• Search by Barcode

Add UniqueID Field for LabKey-Managed Barcodes

To support barcodes generated and managed by Sample Manager, you will need a field of type "UniqueID" in your Sample Type. When you create a new Sample Type, you will be prompted to include such a barcode field.

To add a "Unique ID" field to an existing sample type, open it for editing. In the Sample Type Properties section, you will see under Barcodes, a blue banner inviting you to create the field necessary. Click Yes, Add Unique ID Field.

By default, it will be named Barcode. If you wish, you can click the Fields section to open it and edit the field name.

Click Finish Updating Sample Type. Barcodes will be automatically generated for any existing samples of this type, as described in the next section.

Generate UniqueID Barcodes

When you add a UniqueID field to a Sample Type that already contains samples, as you finish updating the sample type, you will be prompted to confirm that adding this field will generate barcodes for existing samples.

Click Finish Updating Sample Type to confirm, then view the grid of samples to see the generated barcode values.

In addition, when any new samples are added to this Sample Type, barcodes will be generated for them. You cannot provide values for a UniqueID field, or edit them.

UniqueID generated barcodes are 9+ digit text strings with leading zeros ending in an incrementing integer value. Ex: 000000001, 000000002, etc. 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.

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 use the omnibox to search or filter a grid of samples, or use the global search option in the header throughout the application to find a single barcode value.

To more easily find samples by barcode value, you can use the Find Samples option.

Enter values by typing or using a scanner, then click Find Samples to search for them.

Learn more in this topic:

• Sample Search

Related Topics

• Create a Sample Type
• Sample Search

A user can build a picklist privately, adding and removing samples until the correct set are defined. Samples of different types can be included on the same picklist. The completed list may be kept private or shared with other team members for use when performing other tasks.

• Create New Picklist from Samples
• Create Empty Picklist
• Add Samples to Picklist
• Manage Picklists
• View a Picklist
• Refine and Use a Picklist
• Export Picklist
• Team Picklists and Permissions

Create New Picklist from Samples

Select the desired samples on a grid and select Create > Picklist.

Give it a name, optional description, check the box if you want to immediately 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 if you want to navigate to the new picklist.

Create Empty Picklist

You can also create a new picklist from most places in the application. Select Create > Picklist to see the same popup as if you were creating one while adding samples to it. If you access this option from a grid of samples with samples selected, they will be added to your new picklist as described above. If you access this option without samples selected, you will create an empty picklist, which will be available for adding samples later.

Add Samples to Picklist

When you select samples and choose Manage > 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 use the search bar to narrow the list. Click to select the desired picklist. You'll see the existing number of samples already on the list.

Manage Picklists

Select Picklists from the user menu (or from the main menu under Your Items) to manage, add, and edit Picklists.

• Select Create > Picklist to create a new empty one.
• The primary My Picklists tab shows the picklists you have created but not shared with your team.
• 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.

Note that if a sample is deleted from the system, it will be also be removed from any picklists it was previously added to.

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.

Use the menu on the right to show "All Samples, Samples Only, Aliquots Only" in the grid.

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

Refine and Use a Picklist

Actions available for picklists include:

• menu
• Edit Picklist: Change the name, sharing, and description of the list in a popup.
• Delete Picklist: This removes the picklist, but does not delete any sample data.
• Check the box above the menus to Share this picklist with team members. When the box is not checked, the list is private to you.
• Manage: Select one or more samples to:
• Remove from Picklist
• On the tabs for individual samples, you can also use bulk editing actions on selected samples.
• Jobs:
• Start a Job: This option will not include any samples from the picklist automatically.
• Start a Job with Selected Samples
• Add Samples to Existing Job
• Storage: Select one or more samples to:
• Add to Storage
• Check Out
• Check In
• Discard from Storage

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

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, add picklists to jobs, and use picklists for adding and managing freezer storage of samples.

Related Topics

• Start a New Job
• Store Samples in Freezers

• Physical Sources like labs, vendors, locations, studies, etc.
• Biological Sources like patients, mice, trees, cell lines, etc.

For instance, multiple types of sample might be taken from a single source subject, i.e. blood and urine from the same mouse. Relating data from different assays performed on the different types of sample might turn up trends or correlations not available from a single sample.

Similarly, each sample might have multiple sources, such as a blood sample from a certain patient who visited a certain lab location during participation in a specific study. If that patient were part of other studies, or changed which lab they visited to submit samples, tracking sources would provide additional context to your data.

Topics

• Create Sources
• Associate Samples with Sources
• Manage Sources
• Sample and Source Lineage

Tutorial

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

• Create Source Type
• Source Naming Patterns
• Create (or Import) Sources
• Merge of Sources During Import

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 select Create > Source Type.

• Enter a Name (Required) for this Source Type, shown here 'Creature'.
• 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}

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.

First, open the desired Source Type by clicking it's name on the main menu or Source Types page. Select Create > [Name of Source Type] to open the creation wizard.

Confirm that the correct Source Type is selected, or use the dropdown to change it. As for samples, you can Create Sources from Grid or Import Sources from File. 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.

Merge of Sources During Import

By default, importing from a file will create new sources using the data in the file. If there is data for any existing Source IDs, the import will fail.

To merge sources, use the checkbox to Update data for existing sources during import.

When this box is checked, data for any Source IDs which have already been created within the system will be merged. Only the fields that are changing in the existing Source IDs need to be included in the upload. Data for new Source IDs will be used to create new IDs.

Related Topics

• Tutorial: Track Sample Sources
• Associate Samples with Sources
• Manage Sources
• Sources
• Attach Images and Other Files

• Associate Samples with Sources During Sample Creation
• Create Samples from Sources
• View Source Association
• View Source in Lineage
• Associate Existing Samples with Sources
• Edit/Remove Source Associations

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.

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
• Tutorial: Track Sample Sources
• Create Sources
• Create Samples from Grid

• View All Source Types
• Manage a Source Type
• Manage a Single Source
• View Lineage, Samples, Assays, and Jobs
• Samples Created from this Source
• Edit Sources
• Edit a Single Source
• Edit Multiple Sources
• Delete Sources
• Delete a Single Source
• Delete Multiple Sources

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:

As with sample types and assay designs, you can select among different views of the source types: grid, card, and heatmap.

You'll see the name and description of each source type, as well as the number of sources that have been created.

From the Grid Views menu on the right, you can also select a "NameOnly" grid view which will hide the creation, modification, and number of sources information.

Manage a Source Type

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

• Edit Source Type Design: Reopen the source type creation wizard to change details or fields. Note that you cannot change the name of a source type.
• 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.

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.
• 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 > 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 (circled above) 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.

Use the menu on the right to show "All Samples, Samples Only, Aliquots Only" in the grid.

When viewing samples on a sample-type specific tab, all of the following menus and actions are available. When viewing the tab containing samples of all types, the Manage actions specific to a type are not available (like bulk editing properties and lineage).

• Create:
• Samples of Any Existing Sample Type
• Assay Data of Any Existing Type
• Picklist
• Sources of Any Existing Type
• Manage:
• Import Samples
• Delete Samples
• Edit Selected Samples in Grid
• Edit Selected Samples in Bulk
• Edit Sources for Selected Samples in Bulk
• Edit Parents for Selected Samples in Bulk
• Add to Picklist
• Jobs:
• Start a Job
• Start a Job with Selected Samples
• Add Samples to Existing Job
• Storage: Select some or all of the samples and choose among:
• Add to storage
• Check out
• Check in
• Discard from storage

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:

• Manage > Edit Selected Sources in Grid: Edit values directly in a grid.
• Manage > Edit Selected Sources 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). Deleting a source cannot be undone.

Delete a Single Source

You can delete a single source from it's details page by selecting > Delete Source. If the source has descendants, 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 Manage > Delete Sources.

If the group of selected sources includes any that cannot be deleted, you will see a popup message clarifying that only sources without associated samples can be deleted. If some sources can be deleted, you have the option to complete the partial deletion. Deletion of sources cannot be undone.

Related Topics

• Create Sources
• Associate Samples with Sources
• Sources

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

• Describe Assay Data Structure
• Import Assay Data
• Manage Assay Designs
• Manage Assay Data

Tutorial

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

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
• Add Run Fields
• Add Results Fields
• Map to Samples

Create Assay Design

From the main menu, select Assays and then select Create > Assay Design. (Before any assays have been created, you will see a direct link to "Create an assay design" on the menu.)

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

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.

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

• Tutorial: Define Assays
• Import Assay Data
• Experiment / Assay Data

• Import Data
• Enter Run Details
• Enter Data (Results)
• Upload Files
• Copy-and-Paste Data
• Enter Data into Grid
• Bulk Insert
• Bulk Update
• Complete Import and Review Data

Import Data

Locate the correct assay design and click Import Data. You can select it by name from the assays list on the main menu or using the dropdown in the Recent Assay Data panel on the home page.

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

• Upload Files
• Copy-and-Paste Data
• Enter Data into Grid

Upload Files

Drag and drop the file(s) containing your result data into the target area or click the region to select a file. If needed, you can first download a template file of the expected format by clicking Template.

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.

Copy-and-Paste Data

If drag and drop upload is not convenient, you can copy and paste a tab-separated set of values directly into the box on the Copy-and-Paste Data tab. The column headings must be included in what you paste.

Click Import to import the data. If your copy is more than 1000 rows, 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. Note that when you begin typing into the field you have defined as mapping to samples (shown here "SampleID") it will show the set of samples available. Select the correct mapping for each row.

Note that any columns that are required will be marked with an asterisk (*). Before you can import the data, these columns will need a valid value in every row.

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

• Get Started with Sample Manager
• Describe Assay Data Structure
• Data Grid Basics
• Data Import Guidelines

• View All Assay Designs
• Manage Assay Design
• Edit Assay Design
• Delete Assay Design
• Archive Assay Design

View All Assay Designs

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

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

Select Heatmap from the View menu to see a visual representation of relative count of runs over the past 12 months for each assay. Darker blocks indicate more runs. Hover over any block for details.

Manage Assay Design

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

Use the (three bar) menu in the upper right to edit or delete the assay design. Administrators can also view the audit history for this assay.

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

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

• Active: When this box is unchecked, the design is archived and hidden in certain views.

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
• Describe Assay Data Structure
• Import Assay Data
• Field Editor

• Manage Runs
• Edit Run Details
• Re-Import Run
• Delete Run
• Manage Results
• Edit Selected Results in Grid
• Edit Selected Results in Bulk
• Delete Results
• View Assay Data for a Sample

Manage Runs

First open the assay design of interest, by using the main menu and clicking the assay name, then click the Runs tab in the upper left to manage runs. From this page, users with "Editor" or "Admin" access can reimport a run, and delete runs if needed.

Edit Run Details

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

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.

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

Delete Run

To delete a run, either:

• Start from the run details page and use > Delete Run
• OR, select the checkbox for the run on either the Overview or Runs tab and select Manage > Delete Run.

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 Manage > Edit Selected Results 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.

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 Manage > Edit Selected Results 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 Manage > Delete Results.

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

View Assay Data for a Sample

On the details page for any Sample, click the Assays tab to see data about that specific sample. A tab for each assay type, showing the count of results available for that sample for that assay, let you browse the collected profile of results.

Use the sample selection menu to show data for:

• Sample or Aliquots
• Sample Only
• Aliquots Only

Related Topics

• Manage Assay Designs
• Import Assay Data
• Data Grid Basics

• 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

Topics

• Start a New Job
• Manage Job Queue
• Complete Tasks
• Manage Notifications
• Edit Jobs and Tasks
• Manage Users
• Permission Roles
• Create a Job Template
• Manage Jobs and Templates

Tutorial

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

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
• Start a Job with Selected Samples
• Job Details
• Tasks
• Input Samples
• Finish Creating Job
• Create Template from Job
• Create Job From Template

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 select Create > Job.
3. From most dashboards you can select Create > Job.
4. You can also select Jobs > Start a Job from any Sample or Picklist grid.
5. Select some samples and then use Jobs > Start a Job with Selected Samples.

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.
• If Samples are in storage, you can use Storage Status as part of your selection criteria here. If you want to use storage location, start from the freezer where they are stored instead.
• Select Jobs > Start a Job with Selected Samples from the menu above the grid.
• Note that if you select Jobs > Start a Job, the new job will not include the selected samples.

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
• 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
• Assign to
• Assays to Perform (select as many as required for this task)
• Due date

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 using the omnibox (entry box reading "Select...") to sort and filter, and 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 the omnibox to sort and filter to find desired samples.
• You can also change the Filters above the grid and click Search again if you haven't found what you need.
• 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.

Finish Creating Job

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.

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

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.

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

Note that you can only create a template during initial job creation - once the job has been started, you cannot generate a template from it.

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 description, tasks, and other details are preconfigured.

• 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, you will be warned that applying a 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.

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

• Get Started with Sample Manager
• Workflow
• Edit Jobs and Tasks
• Create a Job Template
• Sample Picklists

• Jobs List Dashboard Panel
• Jobs Home
• My Queue

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 Jobs Home or select Workflow List from the main menu. There are two ways to view the job data.

Job List

By default you see the Job List grid view:

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.

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

Heatmap

You can also view the workflow data as a heatmap. You will see color blocks representing the number of jobs created from each template over the past year. Jobs not created from templates are grouped together. Hover over a block for details, click to see a filtered grid.

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

• Workflow
• Start a New Job
• Manage Notifications
• Edit Jobs and Tasks
• Create a Job Template
• Manage Jobs and Templates

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, or the Jobs Home link for a grid of all jobs.
• Use the main menu from anywhere in the application. Click Workflow for the grid of all jobs.

Topics

• Overview Tab
• Tasks Tab
• Comments
• Complete Tasks
• Complete Tasks with Samples
• Complete Tasks involving Assay Import
• Reassign Task
• Reopen Task

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 an Import Data button.

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.

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

Use the menu on the right to select whether to show "All Samples, Samples Only, Aliquots Only" in the grid.

When viewing samples on a sample-type specific tab, all of the following menus and actions are available. When viewing the tab containing samples of all types, the Manage actions specific to a type are not available (like bulk editing properties and lineage). Actions available on the All Samples here:

• Create:
• Picklist
• Manage:
• Add to Picklist
• Edit Selected Samples in Grid
• Edit Selected Samples in Bulk
• Edit Sources for Selected Samples in Bulk
• Edit Parents for Selected Samples in Bulk
• Jobs:
• Add More Samples to Job
• Remove Samples from Job
• Storage:
• Add to Storage
• Check Out
• Check In
• Discard from Storage

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.
• By default you will see the Enter Data into Grid option, with rows prepopulated for the samples assigned to this job task, making it easy to manually enter values.
• You can use bulk insert, file upload, or copy/paste import methods if desired.

Reassign Task

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

Reopen Task

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

Related Topics

• Workflow
• Manage Job Queue
• Edit Selected Samples

• In-app Notifications
• Email Notifications

In-app Notifications

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

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

Email Notifications

Users can control whether they receive email when events occur regarding jobs or tasks assigned to them or which they are following. Email notifications allow users to learn about important events without having to manually check job status.

For example, some events that trigger 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 events that occur regarding jobs and tasks that they are part of, or are following.

Users can choose to opt out of all email notifications by disabling this setting.

Select Settings from the user menu, then check the box for Receive email notifications to receive them. Uncheck the box to disable receiving email notifications.

Click Finish to save this setting.

Related Topics

• My Account

• Update Job Details
• Add or Delete Files from a Job
• Job Menu
• Rename a Job
• Edit Job Tasks: Add, Reorder, Edit, Delete
• Edit Samples Assigned to a Job
• Add Samples to a Job
• Delete Samples from a Job
• Reactivate Closed Task
• Reactivate Completed Job
• Delete Job

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.

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.
• Delete a file by selecting > Remove attachment from its tile.

Job Menu

Click the next to the name for the job menu including:

• Rename
• Edit Job Tasks
• View Audit History
• Delete Job

Rename a Job

To change the name of the job, click the and choose Rename. Type the new name and hit return (or click away) to save.

Edit Tasks: Add, Reorder, Edit, Delete

To adjust the tasks involved in the job, select Edit Job Tasks from the menu next to the name. You will see the same interface you used to define job tasks.

• 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 select Manage > Add More Samples to Job 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 Samples to Existing 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 select Manage > Remove Samples from Job.

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 checked box icon, in the following image, "Prepare Samples" is in a closed state.

Select Reactivate Task from the drop down menu to reactivate it.

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. Enter the comment in the box and click Comment to save it.

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.

Select Reactivate Job from the drop down menu. 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 > Delete Job in the job header.

Related Topics

• Start a New Job
• Sample Picklists

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

• Roles and Permissions

Add Users

To add one or more new users, an administrator first selects Administration from the user menu, then clicks Create.

In the popup:

• Enter one or more email addresses, each on it's 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.
• Leave the box checked if you want to Send notification emails to all new users. These invitation emails will include a link for the new user to create a password and log in.
• If you uncheck this box, no email will be sent.
• Optional Message: If you have checked the box to send email, you can add an optional additional message to include in the invitation email to your new users.
• Click Create Users.

The new user will receive an email with a link to set a password and log in. 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.

Manage Users

To manage users, an administrator selects Administration from the user menu.

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.

View User Details

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.

Delete Users

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

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

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

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

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

View Inactive Users

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

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

On the grid of interactive 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.

Related Topics

• Permission Roles
• Audit History
• Tutorial: Add Users and Assign Roles
• Workflow

• Available Roles
• Assign Roles to Users
• Assign Administrator Role

Available Roles

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

• Editors: May add new information or edit data related to samples, assays, and jobs.
• 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.

Assign Roles to Users

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

To add a user to any role:

• First click the role section. You'll see the current members of that role.
• Click the Add member dropdown and select each user to add by email address. Start typing to narrow the list.
• Selected users 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 creating and editing sample types, assays, and job templates.

The first user login created on the Sample Manager application is always an administrator. To assign the administrator role to others, 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 dropdown to select the user to assign the administrator role.

Remove Users from Roles

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

Related Topics

• Manage Users
• Security Roles Reference
• Freezer Storage Roles
• Sample Manager Permissions with Premium Editions of LabKey Server

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.

• Create a Job Template
• Template Details
• Tasks
• Finish Creating Template

Create a Job Template

To create a new job template:

• Select Job Templates from the main header menu.

• Click Create New Template. You can also select Create > Job Template from many other menus in the application.

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

• Template Details
• Tasks

Template Details

Enter the Template Name and Description. The name should be unique enough to help users find it on a menu.

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.

Related Topics

• Start a New Job
• Manage Jobs and Templates

• Manage Jobs
• Edit Job
• Delete Jobs
• Manage Templates
• Edit Template
• Delete Templates
• Workflow Heatmap

Manage Jobs

From the home dashboard, click Jobs Home or from anywhere in the application, select Workflow List from the main menu.

Click All Jobs to see 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: Edit Jobs and Tasks

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 selecting Workflow Templates from the main menu, or by clicking Manage Workflow Options from the Jobs Home:

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 Edit Job Template from the menu.

You can edit the Name and Description, but not 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 > 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 Manage Workflow Options page using the checkboxes, then click Delete.

Workflow Heatmap

You can also view workflow jobs in a heatmap format. There is a row for tracking the count of jobs created from each template and all jobs not created from templates are grouped together in an additional row, "Jobs not from templates."

Related Topics

• Start a New Job
• Create a Job Template
• Edit Jobs and Tasks

• Match your digital storage to your physical storage.
• Represent your exact physical freezer system, with shelves, racks, boxes, canes, bags, etc.
• Track overall available freezer 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.
• Move samples as needed and track each location change, including updating freeze/thaw counts and tracking amounts used.
• Control access to physical samples using storage-specific roles.

Topics

• Freezer Storage Permission Roles
• Create a Freezer
• Store Samples in Freezers
• Manage Freezers
• Manage Storage Unit Types
• View Freezer Details
• Edit Freezer Definition
• Manage Freezer Locations
• Move Stored Samples
• Manage Stored Samples
• Check Out and Check In
• View Storage Activity
• Migrate Storage Data into Freezer Management

• Create a Freezer
• Freezer Properties
• Advanced Freezer Settings
• Freezer Hierarchy
• Storage Unit Names
• Storage Description Labels
• Clone Units
• Bulk Add Storage Units

Create a Freezer

To create a new freezer, click Storage on the main menu, then click Create New Freezer. When creating your first freezer, you'll have an option to Create a freezer on the main menu.

To create additional freezers, again click Create New Freezer from the Storage Dashboard or you may copy an existing freezer.

Freezer Properties

Under General Properties define the following:

• Name: Any string name that will clearly identify the physical freezer; it must be unique in the system.
• Label: Optional text description that will be shown with the name to help users.
• Manufacturer: Optional string for the company name or maker of this freezer.
• Freezer Model: Optional string for the manufacturer-assigned model number or name.
• Temperature: Optionally include the set-point or consistent operating temperature of this freezer when in use. When giving a temperature, specify Celsius or Fahrenheit.
• Freezer Location: If any freezer locations have been configured, you can specify here where to find this freezer.

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

Advanced Freezer Settings

Click Advanced Settings to set the following properties for this freezer. 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 freezer 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 as part of a maintenance routine. Options:
• Active
• Backup
• Defrosting

Freezer Hierarchy

Click the Freezer Hierarchy section to open it. Add the specific Storage Units available in your physical freezer 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.

• 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 selections or add new ones by clicking Manage storage unit types. Note that your work in progress creating this freezer will be lost if you click away now. Consider saving your work and returning to edit the freezer 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 freezer, 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 freezer. 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:

• Bulk Add for creation of new storage units.
• Click icon to clone a unit, adding another copy of it at the same hierarchical level (including any nested storage units it contains).

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. Unit names must be unique at any given level in the hierarchy. It is good practice to use unique names throughout the freezer to avoid confusion, particularly where there are many similar structures within your freezer.

Storage Description Labels

You can include a more verbose descriptive Label for every level of your freezer 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 freezer 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 freezer 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 Freezer.
• Note that you can return to edit your freezer 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.

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 freezer has no terminal storage units configured", with a quick link to edit the freezer 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 freezer that includes some terminal storage locations, you can proceed to store samples in freezers.

Related Topics

• View Freezer Details
• Manage Freezer Locations
• Freezer Management
• Store Samples in Freezers
• Manage Storage Unit Types
• Edit Freezer Definition

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 Freezer

• Find Available Space
• Select Space to Fill
• Location Already Occupied
• Identify Samples to Store
• Paste into Grid
• Search for Samples
• More Filters
• Assign Positions
• Add to Storage

Start from a Picklist or Grid of Samples

• Select Samples to Store
• Find Storage Location for Samples

Start from the Freezer

Find Available Space

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

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

• Here you'll see the top level of the storage hierarchy you defined (in this example three shelves).
• Click the to expand the nested hierarchy.
• Click any level to see the available capacity in the panel on the right.

Continue to use the to expand until you find enough capacity in terminal storage units where samples can be stored, such as bags as shown above.

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. In this case we choose a bag on the top shelf.

• Click Go to Storage View to open it, shown here "Go to Bag #1 - Left".
• 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 freezer, 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 still see the relevant rows in the Add Samples 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.

Paste into Grid

You can Paste into 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 their data to a Sample Type (or create a new one) and can then assign them to locations in a freezer.

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:

• Use the omnibox for filtering, sorting and searching to find the samples you want.
• Click More Filters to flip to a filters panel, described below.

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.

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.

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 Freezer, as described above, you can add Samples to freezer 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 to a freezer

Use checkboxes to select the Samples, then select Storage > Add to storage above the grid.

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

Find Storage Location for Samples

In the Assign Samples to Storage popup, you will see freezers 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. Any locations without sufficient capacity to hold the samples you selected will show a red icon.

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

You will see the same interface for assigning locations to your selected samples as if you had started from the freezer 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.

Related Topics

• View Freezer Details
• Manage Storage Unit Types
• View Storage Activity
• Sample Picklists
• Move Stored Samples

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

• Sample Activity
• Storage Overview
• Freezer List

Sample Activity

The Sample Activity panel shows the number of samples checked out by all users. When non-zero, this is a clickable link taking you to the Stored items page filtered to show "Storage Status = Checked out". Learn more in the topic: View Storage Activity

You will also see a grid of details about recent activity for the current user, showing up to 10 recent actions. Included here:

• Adding samples to storage
• Checking samples in or out
• Discarding samples from storage

You can view the full listing of all your sample Storage Activity by selecting Storage Activity from the user menu. 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 your freezers. 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 freezers 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.

Freezer List

The freezer list offers administrators two action buttons, above the list of freezers:

• 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 and storage layouts.
• Create New Freezer: Add another freezer.

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

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

Related Topics

• Manage Storage Unit Types
• Create a Freezer
• View Freezer Details
• Edit Freezer Definition
• View Storage Activity

An administrator can define the storage unit sizes, layouts, and labelling systems that will be available when creating a freezer in the system.

• Bags
• Boxes
• Canes
• Plates
• Tube Racks

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

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

To delete a type of cane, click the . If a given type is in use anywhere in the freezer 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)

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

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 freezer system, you cannot delete the type. You may delete the built-in types as well if they are not in use.

Related Topics

• Create a Freezer
• Freezer Management

• Overview Tab
• Freezer Status
• Freezer Details
• Freezer Contents
• Storage View
• Sample Information in Grids
• Select Storage to View
• Box, Plate, Tube Rack Detail Views
• View Selected Samples in Box, Plate, or Tube Rack
• Sample Actions
• Location History
• Storage Description Labels
• Freezer Details Menu: Edit, Copy, Delete, or View Audit History

Overview Tab

The overview page for freezer details shows a high level view of freezer status, details, and contents

Freezer Status

The Freezer 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 freezer. 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.

Freezer Details

The freezer details panel lists the properties, including advanced settings, defined for this freezer.

Freezer Contents

Below the status and details panels, you will see a split panel where you can browse the freezer hierarchy and contents.

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

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

• A 'breadcrumb' trail along the top identifies the location of the unit being shown. Above we see Box #1 on Shelf #1 in Freezer -4C.
• You can click any level of this breadcrumb to open the details for that unit on the on the Storage View tab.
• A button to Go to [unit name] is displayed. Click to open this unit on the Storage View tab.
• Visual bars follow, summarizing the contents of this storage unit. They are colored using the label colors assigned to Sample Types.
• Capacity: The shaded section indicates used spaces. The number and percent available are listed.
• Sample Types: The breakdown of types of samples in this unit is shown visually using the label colors assigned. Hover over Legend to see which colors represent which types of sample.
• Samples Checked Out: The number checked out is shown, under a bar indicating the type that are checked out.

Storage View Tab

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

Sample Information in Grids

All storage units, from the overall freezer 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 sort and filter them using the omnibox to find a subset of interest.

Use a checkbox to select a sample and details will be shown in a panel on the right.

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.

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

Sample Actions

• Learn about adding samples to storage in this topic: Store Samples in Freezers
• Learn more about checking samples in and out in this topic: Check Out and Check In
• Learn about moving and discarding samples in this topic: Move Stored Samples
• Learn how to edit storage details in this topic: Manage Stored Samples