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

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

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

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

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

• LabKey Sample Manager

Topics

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

More Answers

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

How Do I Know the Version of Sample Manager

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

Using Sample Manager with Google Translate

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

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

Welcome to LabKey Sample Manager

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

Getting Started, Step by Step

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

More Video Overviews and Demos

Each will open in a new tab.

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

Configure Freezers and Other Storage

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

• Storage Management

Add Sample Inventories

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

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

Associate Sources

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

• Create Sources
• Associate Samples with Sources

Define Assays (Premium Feature)

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

• Describe Assay Data Structure
• Import Assay Data

Outline Workflow (Premium Feature)

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

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

Use Electronic Lab Notebooks (Premium Feature)

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

Learn more in this section:

• Electronic Lab Notebook (ELN)

• 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 (Premium Feature)
• Step 3: Add Users and Assign Roles
• Step 4: Outline Workflow (Premium Feature)
• 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 (Premium Feature)
• Create (and Complete) Workflow Jobs and Tasks (Premium Feature)
• Explore Sample Lineage and Timelines

• View Sample Details
• View Assay Data by Run or for a Specific Sample (Premium Feature)
• View Picklists
• Complete Assigned Tasks and View Workflow Job Details (Premium Feature)
• 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 click Create Sample Type.

Define Sample Type Properties

• Enter the Name: "Tutorial Samples"
• Replace the default contents of the Naming Pattern box with the following, so that samples of this type will be clearly identified as part of this tutorial:

  Tutorial-${genId:number('000')}

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

Define Sample Fields

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

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

• For this tutorial, click Manually Define Fields.

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

• Click Finish Creating Sample Type.

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

Import Samples from File

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

• Download this spreadsheet to use:
• TutorialSamples.xlsx
• The "Tutorial Samples" Sample Type is now available on the main menu. Click to open it.

• Click Add, then choose Import from File.

• You'll see the Sample Type selection of Tutorial Samples sample only. Disregard for now the Storage Options, as we have not created any storage and do not include any storage details in our file.
• Drag and drop the "TutorialSamples.xlsx" file into the target area.

• You will see a preview of the data file as it will populate rows in the type. A unique "Sample ID" will be generated for each line based on the naming pattern provided.

• Click Import.

• When complete, you will see the samples listed.
• The generated Sample IDs for each row may vary if other samples have already been created on your system.
• There are a number of additional built-in columns created for you, including but not shown below, the creation date and user.

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

Other Ways to Import and Create Samples

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

• 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.
• Add Samples: More ways to create and import samples.
• Sample ID Naming: Sample ID naming

Start Over | Next Step (2 of 5)

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

• Create Assay Design
• 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 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.
• Workflow Task would let you link this run to a specific workflow task. Leave this blank for the tutorial.
• Date: Enter "2019-10-01" or click the field to use the day/time date picker.
• Instrument: Enter "INS-01"

Upload Results from File

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

• Click Import.

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

Other Ways to Enter Results

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

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

• On the User Management page, 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, you can use only the default Reader, or add Storage Editor if you want to experiment with freezer storage actions.

• Click Create Users.

Assign Roles

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

• Readers: Have a read-only view of the application.
• Editors: Have the Readers' access, and can also add new information and edit or delete data related to samples, assays, and jobs.
• Administrators: Have full control over the application. This includes user management, permission assignments, storage actions, and creating and editing sample types, assays, and job templates.

• Open > Permissions.

• All of our fake users are currently in the Reader role.
• Click the Editor role panel to open it.
• Click the Add member... dropdown and select "team_lead".
• Selected users will be shown in the panel for the role as you go.
• Click Add member... again and select "lab_technician".
• Each time you select a user, the details for that user will be shown on the right.
• In the image below, the Editor role is being granted to the team lead and lab technician; all three fake users we added are still also members of the Reader role.

• Click Save.

View Audit History

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

Learn more in this topic: Audit History

Related Topics

• User Accounts, Groups, and Roles
• Permission Roles

Previous Step | Next Step (4 of 5)

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

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

Create a Job with Selected Samples

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

• Click the button to open a filter panel.
• Select SampleID (if it is not selected by default).
• Select "Tutorial-018", "Tutorial-019" and "Tutorial-020". (A spreadsheet with some assay data for these specific samples is included below.) First clicking one label, then clicking the other two checkboxes is one quick way to accomplish this.

• Click Apply.
• Click the checkbox at the top of the column to select all three.
• Select Start a New Job from the Jobs menu above the grid. On narrower browsers, this will be a section of the More menu.

Job Details and Priority

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

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

• Attachments: For this tutorial, you can ignore this field. In practice, you could upload a protocol document, detailed instructions, label image file, or any other file attachment required for the job.

Define Job Tasks

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

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

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

• Name
• Description
• Assign to: Select a user from the dropdown
• Assays to perform: Select one or more assay here
• Due date: For this specific task

Assign Samples

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

Finish Creating Job

• Click Finish Creating Job.

Complete Job Tasks

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

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

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, in this case, 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 click Create Source Type.

• Enter:
• Name: Tutorial Labs
• Delete the default Naming Pattern that is provided (and ignore the placeholder text). We will provide unique source names when we create them.
• Click the Fields section to open it.
• You'll see the Default System Fields for Sources (Name and Description). Click the to collapse this section.

• Download this spreadsheet: TutorialLabSources.xlsx
• Drop it in the upload area under Custom Fields.
• You will see the inferred fields.
• Notice the blue banner informing you that your file contained fields with reserved names which are not shown. This refers to the "SourceId" field that is present in the data file and cannot be "defined" again, though you will be able to populate it in the next step..

• Click Finish Creating Source Type.

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

Create Sources (Populate a Source Type)

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

• Click Import to import the file and create these sources.

Create and Populate a Second Source Type

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

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

Associate Samples with Sources

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

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

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

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

• Click Finish Updating Tutorial Samples.

We now will update the samples we created earlier.

• If any samples are currently selected, click Clear All.
• Select Edit > Update from File.
• Download this file: TutorialSamplesWithSources.xlsx then drop it into the target area.
• You'll see a preview:

• Note that if our spreadsheet included both existing samples to update and new samples to create, you'd need to select Create new samples too but for this tutorial, leave only the default selections.
• You can enter a Reason for Update if desired or required.
• Click Import.

The existing samples have now been updated with source information.

View Lineage

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

View Timeline

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

Learn more about the timeline here: Sample Timeline

Congratulations!

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

• Samples
• Sources
• Experiment / Assay Data
• Workflow

Previous Step

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

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

Release 24.7, July 2024

Maintenance Release 24.7.3, August 2024

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

Release 24.7.0, July 2024

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

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

Release 24.6, June 2024

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

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

Release 24.5, May 2024

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

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

Release 24.4, April 2024

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

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

Sample Manager User Conference - March 28, 2024

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

• Sample Manager User Conference 2024

Release 24.3, March 2024

Maintenance Release 24.3.5, May 2024

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

Version 24.3.0, March 2024

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

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

Release 24.2, February 2024

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

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

Release 24.1, January 2024

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

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

Release 23.12, December 2023

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

Release 23.11, November 2023

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

Release 23.10, October 2023

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

Release 23.9, September 2023

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

Release 23.8, August 2023

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

Release 23.7, July 2023

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

Release 23.6, June 2023

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

Release 23.5, May 2023

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

Release 23.4, April 2023

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

Release 23.3, March 2023

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

Release 23.2, February 2023

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

Release 23.1, January 2023

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

Release 22.12, December 2022

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

Release 22.11, November 2022

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

Release 22.10, October 2022

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

Release 22.9, September 2022

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

Release 22.8, August 2022

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

Release 22.7, July 2022

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

Release 22.6, June 2022

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

Release 22.5, May 2022

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

Release 22.4, April 2022

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

Release 22.3, March 2022

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

Release 22.2, February 2022

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

Release 22.1, January 2022

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

Release 21.12, December 2021

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

Release 21.11, November 2021

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

Release 21.10, October 2021

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

Release 21.9, September 2021

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

Release 21.8, August 2021

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

Release 21.7, July 2021

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

Release 21.6, June 2021

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

Release 21.5, May 2021

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

Release 21.4, April 2021

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

Release 21.3, March 2021

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

Release 21.2, February 2021

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

Release 21.1, January 2021

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

Release 20.12, December 2020

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

Release 20.11, November 2020

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

Release 20.10, October 2020

• Integration with BarTender to print labels. (docs)

Release 20.9, September 2020

• A new tutorial is available to help you get started with a new/empty instance of sample manager. Try it here: Tutorial: Learn Sample Manager
• Label colors are shown in the samples section of the main dashboard.
• In anticipation of future support for Freezer Management, underlying functionality like the ability to access storage locations from the main menu have been added.

Release 20.8, August 2020

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

Release 20.7, July 2020

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

Release 20.6, June 2020

• Bug fixes and small improvements

Release 20.5, May 2020

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

Release 20.4, April 2020

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

Release 20.3, March 2020

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

February 2020

• LabKey Sample Manager is Launched!

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

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

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

Release Announcement Banner

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

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

Dashboard Insights

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

Select from the leftmost dropdown to show:

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

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

Learn more about samples in this section:

• Samples

Exclude Sample Types from Dashboard Insights

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

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

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

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

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

Sample Finder

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

• Sample Finder

Storage List

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

• Hover over the Legend to see which colors are associated with which sample types.
• Hover over any bar segment for details about what it represents, and click to jump to the storage view of those samples in that storage.

• Manage Storage

Main Menu

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

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

Header Menus

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

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

Notebooks (Professional Edition Feature)

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

Learn more in this section:

• Electronic Lab Notebook (ELN)

Jobs List (Professional Edition Feature)

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

• Workflow

Related Topics

• Get Started with Sample Manager

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

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

Video

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

Note that there have been improvements to the interface and user experience for working in Projects since the making of the video.

Overview

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

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

Home Project and "Sub" Projects

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

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

Manage Projects

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

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

Create New Project

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

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

• Data in Project: Select Types of Data in Project
• Dashboard: Exclude Sample Types from Dashboard Insights
• Project Storage: Select Project Storage

Set Project Permissions

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

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

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

Learn about configuring permissions in this topic:

• Permission Roles

Edit Project

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

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

Delete Project

To delete a project, either:

• Click it's name from the Projects dashboard (select > Projects).
• Click Delete Project.

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

Select Data in Project

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

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

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

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

Exclude Sample Types from Dashboard Insights

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

Learn more in this topic:

• Sample Manager Dashboard

Select Project Storage

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

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

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

Work within Projects

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

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

• Dashboard
• Administration

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

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

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

Learn about actions across projects in this topic:

• Cross-Project Actions

Best Practices

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

Related Topics

• ID and Name Settings
• Cross-Project Actions

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

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

Cross-Project Actions

Summary of Functionality

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

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

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

Creating entities: Entities are created by default in the project the user is viewing at the time the action is initiated. Users with appropriate permissions can choose to create entities in other projects they have access to.

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

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

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

Detailed Cross-Project Actions

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

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

Restricted Visibility of Inaccessible Data

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

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

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

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

Add or Edit Entities Across Projects

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

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

• When editing in bulk, the project is not shown (and not editable). Lookup and file fields are not editable when samples from multiple projects are selected.
• When editing in a grid, the project to which the sample belongs will be shown read-only. If any selected Samples that belong to projects the user is not authorized to edit, they will not be listed for editing.

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

Move Samples, Sources, and Assay Runs Between Projects

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

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

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

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

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

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

Move from Details Page

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

Move Notebooks Between Projects

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

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

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

Storage Shared Across Projects

• Set Up Shared Storage
• Storage Occupied by Inaccessible Samples

Set Up Shared Storage

To share storage, create it in the home project, defining the properties and hierarchies as usual. It will then be visible in all subprojects.

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

In shared storage where a user has permission to see data from all projects using it, the user will see data from all containers as if all the samples were local. When viewing details of a sample, you'll see a note in the detail panel if it belongs to another project, but can still perform actions upon it.

Storage Occupied by Inaccessible Samples

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

The same icon is shown when users move samples, ensuring both that spaces are never occupied by multiple samples and that data is only shared with authorized users.

Related Topics

• Project Organization

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

Administrators can perform these actions via > Users.

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

• Manage Groups
• Permission Roles

Add Users

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

In the popup:

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

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

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

View User Details

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

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

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

Manage Users

To manage users, an administrator selects > Users.

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

User Details Panel

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

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

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

Deactivate Users

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

To deactivate a user, an administrator has two options:

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

Delete Users (Not recommended)

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

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

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

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

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

View Inactive Users

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

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

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

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

User Limit Alerts

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

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

• Limit Active Users

Related Topics

• My Account
• Manage Groups
• Permission Roles
• Audit History
• Tutorial: Add Users and Assign Roles
• Workflow

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

Sign In and Out

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

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

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

Session Expiration

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

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

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

Edit Your Profile

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

Edit User Details

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

Upload Avatar

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

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

Change Password

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

API Keys (Professional Edition Feature)

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

• API Keys

• Scroll down to the API Keys section.
• Click Generate API Key to obtain one.

• The new key will be shown in the window and you can click the button to copy it to your clipboard for use elsewhere to authenticate as your userID on this server.
• Important: the key itself will not be shown again and is not available for anyone to retrieve, including administrators. If you lose it, you will need to regenerate a new one.
• You'll see the creation and expiration dates for this key in the grid. The expiration timeframe is configured at the site level by an administrator and shown in the text above the grid.

Later you can return to this page to see when your API keys were created and when they will expire, though the keys themselves are not available. You can select any row to Delete it and thus revoke that key. An administrator also has the ability to revoke API keys for other users if necessary.

Manage API Keys (Administrators)

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

Learn more here:

• Site Settings for API Keys
• Manage API Keys

Related Topics

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

• User Accounts, Groups, and Roles

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

Available Roles

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

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

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

Assign Roles to Users and Groups

Open permissions management by selecting > Permissions.

To add a user or group to any role:

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

Click Save.

Remove Users and Groups from Roles

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

Related Topics

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

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

User Groups

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

Create Group

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

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

Add Users to Groups

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

Click Save to update groups and assignments.

Grant Permission Roles to Groups

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

• Permission Roles

The "Users" Group

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

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

Delete Group

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

Related Topics

• User Accounts, Groups, and Roles
• Permission Roles

• In-app Notifications
• Email Notifications

In-app Notifications

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

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

Email Notifications

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

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

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

Receive Email Notifications

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

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

Related Topics

• My Account

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

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

Data Ownership and Audit

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

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

Will privacy be maintained if I use Sample Manager?

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

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

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

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

• Sample Timeline

Sample Identification

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

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

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

Does Sample Manager handle replicates?

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

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

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

• Sources

Does Sample Manager support using a barcoding system?

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

• Barcode Fields

• BarTender Integration
• Print Labels with BarTender

Freezer Management

Does Sample Manager provide a freezer management solution?

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

• Storage Management

Data Structures for Assays and Samples

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

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

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

How does a user know what columns are expected?

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

Can I build in customized data integrity checks?

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

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

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

What export types are supported?

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

Are there predefined templates for data in Sample Manager?

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

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

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

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

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

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

Jobs, Tasks, and Templates (Professional Edition Feature)

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

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

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

Sample Manager and LabKey Server

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

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

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

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

Future Plans

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

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

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

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

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

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

Related Topics

• 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
• Add Samples:
• Create Samples from Grid
• Import Samples from File
• Sample ID Naming
• ID and Name Settings
• Sample Lineage / Parentage
• Aliquots, Derivatives, and Sample Pooling
• Sample Expiration
• Sample Timeline
• Manage Samples
• Manage Sample Status
• Edit Selected Samples
• Sample Finder
• Built-in Sample Reports
• Sample Search
• Print Labels with BarTender
• BarTender Integration
• Barcode Fields
• Sample Picklists

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

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

Video Overview

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

Create a New Sample Type

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

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

Define Sample Type Properties

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

• To declare a field that will identify a parent sample, click Add Parent Alias. Enter the field name and select the Sample Type where the parent information will be found. It can be the current type or a different one.
• If there are Sources defined in the system, you will have a similar option to Add Source Alias here.
• Set Storage Settings
• Define a Barcodes field if desired.
• Before you click Finish Creating Sample Type, determine whether you need to add Fields.

Naming Pattern

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

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

Aliquot Naming Pattern

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

${${AliquotedFrom}-:withCounter}

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

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

${${AliquotedFrom}.:withCounter}

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

Storage Settings

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

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

Label Color

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

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

Define Sample Type Fields

Click the Fields section to open it.

Default System Fields

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

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

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

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

Add Custom Sample Type Fields

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

There are options for adding Custom Fields:

• Import or Infer Fields from File
• Manually Define Fields

Import or Infer Custom Fields from File

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

Manually Define Fields

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

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

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

Barcodes

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

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

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

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

Learn more about creating and using barcodes in this topic:

• Barcode Fields

Configure Sample/Aliquot Field Inheritance

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

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

Finish Creating Sample Type

• Click Finish Creating Sample Type when finished.

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

• Field Editor

Edit Sample Type Design

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

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

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

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

Resource: Sample Naming Pattern Examples

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

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
• Add Samples
• Samples
• Field Editor

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

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

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

Create New Samples

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

• Add Manually
• Import from File

Create Samples From Grid

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

Learn more in this topic: Create Samples from Grid

Import Samples From File

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

Learn more in this topic: Import Samples from File

Assign Amount and Units

During Sample creation, you can assign the Amount of that Sample, with Units. Previously these values were provided and tracked when the Samples were in storage.

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

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

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

Work with New Samples

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

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

• Manage Sample Status

• Sample Grid Menus

Create Derivatives, Pooled Samples and Aliquots

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

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

Related Topics

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

• 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 desired Sample Type by selecting Add > Add Manually.

You can also choose Add Samples > Add Manually on the home page or the Sample Types dashboard, choose the desired Sample Type from the dropdown.

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

Add Parent (Optional)

If the Sample Type has one or more Parent samples, you will see a prepopulated parent field. To add more, click Add Parent. Select the Sample Type of the parent(s). If you will have parents of different types, add one for each type of parent.

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

If you add but then want to remove a parent linkage, you can delete it by clicking the X next to "Remove Parent #" on the right.

Add Source (Optional)

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

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

If you add but then want to remove a source linkage, you can delete it by clicking the X next to "Remove Source #" on the right.

Add Samples Individually

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

A grid with the requested number of rows will be created, with a Status column plus a column for each field included in your Sample Type (not including any "File" fields).

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

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

Bulk Insert

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

• Specify the number of New Samples.
• 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 pooled parent(s).

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

Bulk Update

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

Related Topics

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

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

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

Obtain File Import Template

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

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

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

Import Samples From File

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

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

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

Additional examples and details are available here:

• Import Samples with storage locations
• Import Samples with lineage

Import Samples Across Multiple Sample Types

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

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

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

Import Samples and Create New Storage

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

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

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

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

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

Update Existing Samples

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

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

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

Merge by Allowing New Samples

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

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

Related Topics

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

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

Unique Sample Names are Provided

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

Naming Column is "SampleID" or "Name"

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

Naming Column is Something Else

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

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

${Identifier}

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

Generate Names with Naming Patterns

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

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

Default Naming Pattern

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

S-${genId}

The first few samples would be:

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

See and Set genId

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

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

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

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

Date Based Naming

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

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

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

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

Incorporate Column Values

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

${ParticipantID}-${genId}

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

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

Incorporate Lineage Lookups

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

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

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

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

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

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

Include Grandparent/Ancestor Names

The above lineage lookup syntax applies to parent or source details, i.e. the "parent" generation. In order to incorporate lookups into the "Grandparent" of a sample, use the ".." syntax to indicate "walking up" the lineage tree. Here are a few examples of syntax for retrieving names from deeper ancestry of a sample. For simplicity, each of these examples is shown followed by a basic ${genId} counter, but you can incorporate this syntax with other elements. Note that the shortened syntax available for first generation lineage lookup is not supported here. You must specify both the sample type and the "/name" field to use.

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

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

To use another propertyColumn from a specific grandparent sample type:

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

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

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

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

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

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

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

Naming Pattern Elements/Tokens

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

Formatting Values

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

${genId:number('000')}

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

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

:defaultValue Modifier

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

${ColumnName:defaultValue('value')}

:minValue Modifier

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

S-${sampleCount:minValue(100)}

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

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

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

Names Containing Commas

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

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

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

Incrementing Sample Counters

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

sampleCount Token

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

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

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

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

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

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

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

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

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

rootSampleCount Token

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

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

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

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

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

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

Date Based Sample Counters

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

• dailySampleCount
• weeklySampleCount
• monthlySampleCount
• yearlySampleCount

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

:withCounter Modifier

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

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

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

${${AliquotedFrom}-:withCounter}

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

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

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

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

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

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

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

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

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

• Aliquot Naming Patterns

Naming Pattern Validation

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

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

Errors reported include:

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

Caution: Using Numbers-Only as Sample IDs

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

Examples

Example String Modifiers

The following naming patterns show usage of string modifiers.

Related Topics

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

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

User-defined IDs/Names

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

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

Additionally:

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

To disallow User-defined IDs/Names:

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

Naming Pattern Elements/Tokens

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

Related Topics

• Sample ID Naming

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

Add 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 Manage > Edit Sample Type Details.
• Click Add Parent Alias.

• Enter an alias for import: Name the column containing parentage information that will be in the file. The column name is case sensitive.
• Select a sample type...: Select the Sample Type where the parent resides. This may be in the "(Current Sample Type)" or another one that has been defined.

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

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

Define Lineage When Creating Samples

When creating samples of this type, include parent information in one of the aliased columns. When you use a template to import from file columns for all parent aliases will be included. As shown below, the "MyParent" column contains the parent identifier.

If you add samples manually in a grid, a parent of the selected type will included by default, though the column name from your alias will not be shown in the UI. Instead it will be named for the selected sample type plus the word "Parents", i.e. "Blood Parents".

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

Add Source Alias

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

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

Give the name of the source alias column and select the source type from the dropdown, as for parent samples. You can include multiple source aliases as needed. When you use an import template or add samples manually in a grid, columns for all source aliases will be included.

Learn more about sources in this section:

• 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 the desired option from the Derive menu. On narrower browsers, this will be a section of the More menu:
• Aliquot Selected: Create aliquot copies from each selected sample.
• Derive from Selected: Create multiple output samples per selected parent sample. Select the type to derive.
• Pool Selected: Created one or more pooled outputs from the selected samples.
• Add the desired number of new samples and click Go to Sample Creation Grid.

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

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

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

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

Include Ancestor Metadata in Sample Grids

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

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

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

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

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

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

Explore Sample Lineage Graph

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

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

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

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

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

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

Lineage Generations in Graph

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

Lineage Grid

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

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

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

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

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

Troubleshooting

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

Related Topics

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

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

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

Create Samples from Selected Parents

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

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

Derive from Selected Samples

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

• Add the desired number of "Derivatives per parent" by entering the number and clicking Go to Sample Creation Grid.
• You will see the Samples you had selected prepopulated as parents in the grid, with as many rows per parent as you specified.

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

Pool Selected Samples

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

• Select the Sample Type of interest from the main menu.
• Select the 'parent' samples using the checkboxes.
• If you only select one parent sample, the pooling option will not be shown.
• Select Derive > Pool Selected.
• In the popup, add the desired number of New samples per parent group by entering the number and clicking Go to Sample Creation Grid.

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

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

Aliquot Selected Samples

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

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

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

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

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

Aliquot Naming

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

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

${${AliquotedFrom}-:withCounter}

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

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

${${AliquotedFrom}.:withCounter}

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

Aliquot Information in Grids

When viewing a grid of samples, you will see the following calculated columns related to aliquots. Both of these columns are populated only for the original samples; they are set to null for aliquots themselves.

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

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

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

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

Find Original Sample Details for an Aliquot

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

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

Aliquots in Lineage

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

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

Related Topics

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

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

Enable Expiration Date Field

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

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

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

Disable Expiration Date for a Sample Type

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

Assign Expiration Dates to Samples

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

Find Expired Samples or Samples About to Expire

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

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

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

• Samples Expiring in the Next 7 Days

Related Topics

• Samples
• Sample Finder
• Built-in Sample Reports

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

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

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

View Sample Timeline

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

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

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

Current Status

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

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

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

Event Details

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

Listing Order

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

Filter Timeline

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

Use checkboxes to filter events to show any combination of:

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

Export Timeline

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

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

Related Topics

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

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

View All Sample Types

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

The Sample Types dashboard lets you:

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

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

View Samples of One Type

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

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

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

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

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

• Sample Grid Menus

Sample Type Insights

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

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

Manage Menu

The Manage menu in the upper right offers these options:

• Edit Sample Type Design: Reopen the existing details and fields; edit using the same interface as you used to create the Sample Type.
• Delete Sample Type: Note this will delete all sample data and dependencies as well. Deletion cannot be undone. The administrator deleting a Sample Type can provide a Reason for Deleting if required or desired, and must confirm the action.
• View Audit History: Administrators can view the audit history for this Sample Type from this link.

• Sample Grid Menus

View Individual Sample Details

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

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

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

Panels on the Overview Tab

Panels on the Overview tab include:

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

Edit Sample Details

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

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

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

Edit Sample Lineage

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

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

More Sample Editing

Learn more about editing samples in this topic:

• Edit Selected Samples

Delete Samples

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

Deletion Prevention

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

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

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

Delete One Sample

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

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

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

Delete More Samples

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

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

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

Partial Deletion

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

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

Move Samples (Premium Feature)

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

Learn more in this topic:

• Move Samples Between Projects

Related Topics

• Add Samples
• Samples
• Aliquots, Derivatives, and Sample Pooling
• Edit Selected Samples
• Manage Sample Status
• Sample Grid Menus
• Store Samples

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

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

Manage Sample Statuses

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

• Available: Can be used. This status type is also used to determine calculations of available amounts.
• Consumed: Used up, and no longer can be aliquoted or checked out, but remains in the system for analysis and tracking.
• Locked: While locked, a sample cannot be edited, have its storage updated, be moved between projects, or be added to workflows. The status can later be changed to another type of status.

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

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

View or Edit Status Details

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

Add New Status

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

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

Choose Status Color

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

Assign Sample Status

Users can assign statuses to their samples throughout the system:

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

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

Change Status to Consumed

When you change the Sample Status to "Consumed" (i.e. to any named status of the "Consumed" type), this typically means that there is no more of the sample to be used. If the sample is in storage, the user will also be 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, using the color-coding you have assigned.

Sample Status and Storage Status

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

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

Sample Count by Status Dashboard

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

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

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

Related Topics

• Samples

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

• Edit in Grid
• Sample Data
• Storage Details (Requires the Storage Editor role)
• Lineage Details
• Edit in Bulk
• Edit Sources
• Edit Parents
• Edit Sample Name

Edit in Grid

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

• Fields that cannot be edited are grayed out.
• Some fields offer a selection menu, indicated with a . Type ahead to narrow the choices and click or tab to select the highlighted value.
• Auto-fill text or number columns using the "cell-drag handle". Enter a first value (or values) and drag to populate more rows.
• Users can provide a Reason for Update if desired or required.
• Learn more about these and other options for editing data in grids in this topic:
• Editable Grids

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

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

Lineage Details: Edit the sources and parent samples for the selected samples.

• To edit or add a selection to an existing column, click the or start typing, you will see a dropdown of matching options to choose from.
• Note that lineage for aliquots cannot be changed after they are created. Rows for any selected aliquots will be grayed out here.

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

Edit in Bulk

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

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

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

Click Update Samples when finished editing.

Edit Sources

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

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

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

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

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

Edit Parents

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

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

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

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

Click Update Parents when finished.

Edit Sample Name

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

Related Topics

• Update Samples via File Import
• Manage Samples
• Aliquots, Derivatives, and Sample Pooling
• Permission Roles
• Data Grid Basics

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

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

Video Tutorial

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

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

Open the Sample Finder

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

Find Derivatives in Sample Finder

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

Sample Finder

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

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

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

Click Find Samples to add your filter.

Filtering Criteria

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

Choose Values

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

Filter with Expressions

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

If your first filtering expression fully constrains the result (such as an "Equals" filter) you will not have the option to add a second expression.

Find Samples with Multiple Common Ancestors

Use the specialty Equals All Of filter operator to find samples that share all of a provided set of multiple ancestors of a given type in common. This option is only available on the Parent Properties and Source Properties cards and can only be used for ID fields, including Sample ID and Source ID. For example, if you wanted to find samples who had both Mouse-1 and Mouse-2 as ancestors, you could use this filter operator. Up to 10 IDs can be provided separated by either new lines or semicolons.

All samples which have all of the provided IDs as ancestors will be returned.

Edit Criteria

Once you've defined any sample finding criteria, you can use the buttons in the upper right to add more filters on other columns of any other available type.

Each type that you filter on will have a tile, listing the active filters on columns in that type.

You can use the for any tile to edit the criteria it will use to find samples. For example, you could add additional filters on other fields of a parent or source filter you already created.

To add search criteria for another type of source or parent, start from the Source/Parent Properties button.

• Each type will have a separate "tile" showing filters applied. When a filter includes "does not equal", you will see the values with strikethrough styling.
• To set a filter to simply require that the sample have any parent of a given type, use "SampleID is not blank" for that filter.

To delete all criteria associated with a given source or parent, click the for that tile.

Search Results

As you build your set of criteria, you will see the results grid below the tiles. There is a tab for All Samples as well as individual tabs for all defined sample types. Each shows the count of samples of that type that were found using your criteria.

The data grid will show the parent and source columns included in your criteria, as well as common properties of the samples themselves, such as status and creation date. You can use these results to refine the sample finder criteria tiles. When ready, you can save your current search criteria so that you can apply them later. If you want to save a given result set of samples, use a picklist.

Learn about options for actions, filtering, searching, and sorting sample grids in this topic:

• Sample Grid Menus

• Creating new derivatives or aliquots (only available on the tab for a specific sample type)
• Importing assay data
• Adding to picklists or workflow jobs
• Storage Editors can manage storage status, including checking out the found samples

Saved Searches

To save a Sample Finder search, click the Save Search button (only shown when you have generated a set of search criteria).

Give your search a name, then click Save in the popup. This name will be used to retrieve this set of criteria later, and perform a new search using them, possibly finding a different set of samples depending on how your data has changed over time.

You'll now see the name of your custom search as the name of the Saved Search menu. Options:

• Most Recent Search:
• The date and time of your most recent search is shown; click to open it.
• Saved Searches:
• You'll see a list of any named saved searches you've created here.
• Note that saved searches are not shared with other users.
• Other Reports
• Built in sample reports are listed here. Learn more in this topic: Built-in Sample Reports
• Manage saved searches
• Save as custom search

Save Search Button

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

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

Manage Saved Searches

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

Related Topics

• Sample Search
• Search
• Built-in Sample Reports

In all cases, these built in reports can be a starting place for further refining results and saving new named sample searches to create your own custom reports.

• All Samples Created by Me
• All Samples Created by Other Users
• All Samples Created in the Last 7 Days
• Samples Expiring in the Next 7 Days
• Samples with Fewer than 5 Aliquots Available

All Samples Created by Me

This report is the equivalent of filtering Sample Properties for All Sample Types where Created By is the current user.

All Samples Created by Other Users

This report is the equivalent of filtering Sample Properties for All Sample Types where Created By is NOT the current user.

All Samples Created in the Last 7 Days

This report filters All Sample Types where the Created date is greater than or equal to 7 days ago. Notice the use of the syntax "-7d" to mean 7 days ago in this report.

Samples Expiring in the Next 7 Days

This report selects Samples where both conditions are true:

• They are not already expired, i.e. their Expiration Date has not passed.
• They have an Expiration Date in the next seven days.

When maintaining a stock of Sample materials, using this report can help you rotate and efficiently prioritize using the Samples before they expire.

Learn more about expiration dates in this topic:

• Sample Expiration

Samples with Fewer than 5 Aliquots Available

This report filters the Available Aliquot Count to find those with fewer than 5. In order to be included in this report, the aliquot(s) must have a sample status of the "Available" type.

Related Topics

• Sample Finder
• Save Your Own Sample Reports (Named Searches)

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

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

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

Topics:

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

Find Samples in Bulk

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

• Find Samples by Barcode
• Find Samples by ID

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

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

List up to 1000 Barcodes or Sample IDs, each on its own line, then click Find samples.

All the samples located will be listed in a grid, where you can immediately work with them or add more to the list.

If any samples you requested were not found, you will see a notification message. Click Show all to see the IDs that were not found. In the case of a typo or incorrect type of search, you can use Add More Samples to find additional samples to add to the list.

Click Reset to start a new search from scratch.

Add More Samples

Once you have found some Samples, you can click Add More Samples to add to the list. As in the original search, you can input either Barcodes or Sample IDs. This allows you to create a set of results that blend the two search methods.

Click Find Samples to search for these new IDs and add them Samples to your list if found.

Clear Search Results

To clear the set of search results in the grid, click Reset. This may be a useful option in the case of entering a large number of incorrect samples or other issues.

Work with Found Samples

Once you've built your list of Samples in the grid on the search page, you can use the menus for many actions on the All Samples tab. All search result Samples are selected by default.

You can also switch to any Sample Type-specific tab to use the other actions available on sample grids, including the ability to customize the grid view.

Related Topics

• Sample Finder
• Search
• Barcode Fields

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

• Print BarTender Labels for Samples
• Print Labels for a Single Sample
• Print Labels for Multiple Samples
• Troubleshooting

• BarTender Integration

Print BarTender Labels for Samples

Before you can print labels, an administrator must have completed the one-time setup steps in this topic, and configured LabKey to print labels. The admin can also specify a project-specific default label file. When printing, the user can specify a different variant to use.

After configuring BarTender, all users will see the options to print labels in the user interface.

Print Single Sample Label

Open the Sample Type from the main menu, then open details for a sample by clicking the SampleID.

Select Print Labels from the Manage menu.

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

• Number of copies: Default is 1.
• Label template: Select the template to use among those configured by an admin. If the admin has set a default template, it will be preselected here, but you can use the menu or type ahead to search for another.

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

Print Multiple Sample Labels

From the Sample Type listing, use checkboxes to select the desired samples, then select Label from the (Export) menu.

In the popup, you have the following options:

• Number of copies: Specify the number of labels you want for each sample. Default is 1.
• Selected samples to print: Review the samples you selected; you can use the Xs to delete one or more of your selections or open the dropdown menu to add more samples to your selection here.
• Label template: Select the template to use among those configured by an admin. You can type ahead to search. The default label template file can be configured by an admin.

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

Troubleshooting

If you have trouble printing to BarTender from Chrome (or other Chromium-based browser), try again using Firefox.

Error Reporting

If there is a problem with your configuration or template, you will see a message in the popup interface. You can try again using a different browser, such as Firefox, or contact an administrator to resolve the configuration of BarTender printing.

Related Topics

• BarTender Integration
• Samples

This topic describes how an administrator can configure LabKey applications, including Sample Manager and Biologics LIMS, to use BarTender for printing sample labels. Once configuration is complete, any user can send sample labels to the web service for printing.

• Configure BarTender Integration
• Include Print Portal
• Enable HTTPS Endpoint for BarTender
• Example BarTender Configuration File(s)
• Configure LabKey to Print BarTender Labels
• Manage Label Templates
• Error Reporting

Configure BarTender Integration

BarTender integration is supported when used with a BarTender Automation license. We have tested versions 2019, 2021, and 2022.

In the BarTender application, you will identify the web service URL and create the label file(s) for printing. The label file has the extension .btw. LabKey applications accept a default label file, but also allow the user to specify a different variant at the time of printing.

• BarTender by Seagull Scientific

Include Print Portal

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

Enable HTTPS Endpoint for BarTender

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

• Install and set up the BarTender Print Portal web application from the exe/msi installer.
• Set up the BarTender Print Portal with HTTPS in IIS 7. This guide provides step-by-step instructions, including obtaining the certificate and configuring the SSL port:
• 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 set up, but is otherwise optional since we aren't doing any authentication.
• Set up your web service integration in Integration Builder and deploy it as usual.
• Key step: Deploy the Integration service on port 80, instead of a custom port.
• This is a stock file that just needs deployment via the BarTender tooling
• Set up the Label template folder location(s) in the Administration console.
• The BarTender portal service URL is then:

  https://<your host>/Integration/<integration service name>/Execute

• For versions prior to BarTender 2021, use this URL:

  https://<your host>/BarTender/API/Integration/<integration service name>/execute

1. First following these steps: Turning on Integration Passthrough

2. Use this BarTender URL in LabKey:

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

Example BarTender Configuration File

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

• labkeyBT-2021.btin

• labkeyBT.btin

https://localhost/Integration/LabKeyBarTenderService/Execute

For versions prior to Bartender2021, use this URL:

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

Configure LabKey to Print BarTender Labels

Return to the LabKey application (Sample Manager or Biologics LIMS) and select > Application Settings.

In the BarTender Web Service Configuration panel, enter:

• BarTender Web Service URL: This is the URL of the web service to use when printing BarTender labels.

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

Manage Label Templates

Click Add New Label Template for each template you want your users to be able to use. If you are using multiple Projects, templates can only be defined in the home project.

• Name: Give the template an identifying display name your users will recognize.
• Description: The description can provide more detail.
• File Path: Provide the path to the label template file to use. The path should be relative to the default folder configured for the BarTender web service specified above.
• Set as Default: Click the selector if you want this template to be the default.
• You are not required to set a default, but if you do, it will be preselected when users print labels.
• For users of multiple Projects, there can be a different default template in each project.

Once templates are defined, you can return to the > Application Settings page to manage them.

• Click a template name to see or update details, including whether the template is the default.
• Select and then click Delete to delete a template.

Error Reporting

If there is a problem with your configuration or template, you will see a message in the popup interface allowing you a chance to verify or change the label template you've selected. If a change needs to be made to the underlying URL configuration, contact an administrator to retry the configuration process.

Related Topics

• Print Labels with BarTender

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

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

Add UniqueID Field for LabKey-Managed Barcodes

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

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

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

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

Generate UniqueID Barcodes

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

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

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

UniqueID generated barcodes are 9+ digit text strings with leading zeros ending in an incrementing integer value. Ex: 000000001, 000000002, etc. Generated barcodes are unique across the Sample Manager application, i.e. if you use UniqueID barcodes for several different Sample Types, every sample in the system will have a unique barcode. When more than a billion samples are defined, the barcode will continue to increment to 10 digits without leading zeros.

Once generated by the system, barcodes in a UniqueID field cannot be edited and if data is imported into one of these fields, it will be ignored and an automatic barcode will be generated. If you need to provide your own barcode values or require the ability to edit them, do not use a UniqueID field.

Use Existing Barcode Values

If you have barcodes in your Sample data already, and do not want them generated or managed by LabKey, you can include a field of type "Text" or "Integer" in your Sample Type, and check the Barcode Field box for "Search this field when scanning samples".

This field may be named "Barcode" if you like, but will not be managed by LabKey, or shown as the Barcode property of the Sample Type. It will have the "scannable" field property set to true.

Users can locate samples using the barcode values in this column, but must manage uniqueness and generate new barcode values for new samples outside of the application.

Search by Barcode

Once your samples have a barcode column of either type, you can search for the value(s) to locate the sample(s). To find by a single barcode, you can search, sort, and filter the samples grid, or use the global Search option in the header throughout the application to find a single barcode value.

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

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

Learn more in this topic:

• Sample Search

Related Topics

• Create a Sample Type
• Sample Search

Administrators and users with the Workflow Editor role can create and edit picklists.

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

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

Create a New Picklist from Samples

Select the desired samples on a grid and select Picklists > Create a New Picklist. On narrower browsers, this option will be under the More > menu:

Give the picklist a name, optional description, check the box if you want to share it with team members, then click Create Picklist. The selected samples will be added to the new picklist.

You will return to the sample grid, with a banner available offering a quick link to View picklist.

Create Empty Picklist

You can also create an empty picklist and add samples later. Click Picklists on the main menu, then click Create Picklist. Give it a name, optional description, and check the box if you wish to share it.

Add Samples to Picklist

When you select samples in a grid and choose Picklists > Add to Picklist (or More > Add to Picklist), you will see all the Picklists available. If no picklists exist yet, you will be able to click create a new one here.

When the number of picklists is long, you can narrow the list by typing in the "Find a picklist" box. Shared picklists are shown on a separate tab, with shared picklists you created yourself shown on the "Your Picklists" tab with a icon.

Click to select the desired picklist. You'll see the existing number of samples already on the list.

Click Add to Picklist to add your selected samples to it.

Manage Picklists

Click Picklists on the main menu.

• Click Create Picklist to create a new empty one.
• The primary Your Picklists tab shows the picklists you have created. The Sharing column indicates whether you've shared them ("Yes" or "No").
• Click Shared Picklists to see shared ones created by you or other team members.
• Click the Name of a picklist to open it for review or editing. Learn more about using picklists below.

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

View a Picklist

From the Picklists dashboard, click the name of a picklist to open it in grid form. You will see the samples on the list, available on a series of tabs.

Learn more about multi-tabbed sample grids here.

Refine and Use a Picklist

Actions available for picklists include:

• Manage
• Edit Picklist: Change the name, description, and whether the list is shared with your team.
• Delete Picklist: This removes the picklist, but does not delete any sample data.

• Remove from Picklist
• Use options on the Assay/Jobs/Storage/Reports menus

• Sample Grid Menus

Export Picklists

To export a picklist, such as to use as a guide for physically removing samples from the freezer, click the icon above the list of samples in the picklist. If any sample rows are selected, only selected rows will be exported. If no rows (or all rows) are selected, the entire picklist will be exported.

Export formats include:

• CSV
• Excel: For multi-tabbed picklists, you can select which tabs to include in your Excel export.
• TSV

Shared Picklists and Permissions

When the Share this picklist box is checked for a picklist, it will appear for all team members on the Shared Picklists tab of the Picklist dashboard.

• Only the creator of a picklist may edit the name, description, and whether the list is shared with the team.
• All users with the Reader role in Sample Manager can read a team picklist and export the data for completing tasks.
• Any user with Editor or Admin permissions may also add or remove samples from team picklists and add picklists to jobs.
• Storage Editors can use picklists for adding and managing freezer storage of samples.

Related Topics

• Start a New Job
• Store Samples

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

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

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

Topics

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

Tutorial

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

• Create Source Type
• Source Naming Patterns
• Add Parent Source Alias
• Add Sources
• Update or Merge Sources from File

Create Source Type

Describe the type of source. Within the system, you might have several different types of source from which samples are taken, such as biological sources like animals or cell lines and physical sources like labs or vendors.

From the main menu, select Source Types and click Create Source Type. When you create your first Source Type, there is a shortcut to Create a source type on the main menu. Note that you can only create Source Types in the home (top-level) project. If the creation button is missing, navigate first to the home project.

• Enter a Name (Required) for this Source Type, shown here 'Creature'. You can edit the Source Type to change this name later; the SourceIDs/Names of existing sources will not change.
• Enter an optional Description.
• Like with samples, all individual sources must have a unique name. You can either:
• Provide these with your data in a column named "SourceId" or
• Ask the system to generate them using a Naming Pattern.
• The default pattern is the word 'Source' followed by an incrementing number:

  Source-${genId}

• Either accept this default, specify another pattern, or delete it (and ignore the placeholder text) if you plan to supply source names.
• If you want to include lineage relationships (parent sources) for this type of source, and want to be able to import them from spreadsheets, click Add Parent Source Alias

• As for sample types, click the Fields section to open it.
• Every Source Type includes Default System Fields "SourceId" (Name) and "Description". You can use the checkbox to disable the description, but the name/sourceID is always required. In addition, fields like "Created/CreatedBy", and "Modified/ModifiedBy" are always included but not shown here. Find a list of reserved and internal field names in this topic: Data Import Guidelines
• For defining Custom Fields, you can Import or infer fields from file or manually define fields yourself. Details are found in the topic for creating fields in sample types.
• If you infer from a file that contains the built-in fields, they will not be shown as they will always be created for you.

• Note that you can create fields of the same data types as you can for sample types and assays, with the exception that you do not include fields of type "Sample". Associations of samples with sources are made from the sample definition to it's source, not the other way around.

• Click Finish Creating Source Type when finished.

Source Naming Patterns

When you create a Source Type, you decide how unique names for all the sources will be generated. You can provide them yourself or have them automatically generated with a naming pattern, similar to how samples are named.

The default pattern is the word 'Source' followed by an incrementing number:

Source-${genId}

Add Parent Source Alias

Sources may have parent sources of the same or other types. For example, you might have source types for both "Studies" and "Subjects", in which all "Subjects" have a parent "Study". Just as how parent aliases can be defined for Sample Types, you can include a Parent Source Alias for your Source Type, giving you a column name to include when uploading parents of the selected source type.

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

Add Sources

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

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

• Add Manually to create sources from grid or
• Import from file to import sources from file.

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

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

These sources are now available for associating with samples.

Update or Merge Sources from File

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

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

The Update Options selection can be either:

• Only update existing sources: (Default) Update only. Any new sources will cause the import to fail.
• Create new sources too: Merge. Both existing and new sources can be included.

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

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 in the system. If the Sample Type you are adding has any source aliases, source columns for them will be added by default.

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

• Use a Source Alias in a Sample Type
• Manage Sources
• Tutorial: Track Sample Sources
• Create Sources
• Create Samples from Grid

• View All Source Types
• Manage a Source Type
• Source Type Details
• Manage a Single Source
• View Lineage, Samples, Assays, and Jobs
• Samples Created from this Source
• Edit Sources
• Edit a Single Source
• Edit Multiple Sources
• Update from File
• Edit Source Parents
• Delete Sources
• Delete a Single Source
• Delete Multiple Sources
• Move Sources (Premium Feature)

View all Source Types

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

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

Manage a Source Type

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

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

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

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

Source Type Details

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

Manage a Single Source

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

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

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

View Lineage, Samples, Assays, and Jobs

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

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

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

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

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

Samples Created from this Source

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

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

• Create Samples:
• Select the Sample Type you want to create, then the number of new samples per parent.
• Menu sections for Assay/Picklist/Jobs/Storage/Reports:
• See details here

Edit Sources

Edit Single Source

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

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

Edit Multiple Sources

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

• Edit > Edit in Grid: Edit values directly in a grid. There are tabs for both Source Data and Lineage Details. Learn more about the grid editor here.
• Edit > Edit in Bulk: Assign the same value to one or more fields in the batch of selected rows. Learn more about the bulk editor here.

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

Update from File

• Only update existing sources (update)
• Create new sources too (merge)

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

Edit Source Parents

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

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

Delete Sources

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

Delete a Single Source

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

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

Delete Multiple Sources

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

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

Deletion of sources cannot be undone.