Premium Editions of LabKey Server include the option to use the Sample Manager application within a project and integrate with LabKey Studies and other resources.
This topic covers considerations for using Sample Manager with LabKey Server.
Sample Manager in a Project
Sample Manager is designed to be contained in a
project on LabKey Server. This provides advantages in scoping permissions specific to sample management. For instance, many studies in other projects may need to be linked to sample data, but a single group doing the actual sample administration and freezer management for all studies would have elevated permissions on the Sample Manager folder instead of needing them on all studies.
Resources including Sample Types and Assay Designs that should be usable in both the Sample Manager project and other containers on the server should be placed in the
Shared project.
Using Sample Manager in a Folder
Depending on where the Sample Types, Assays, and study data you hope to integrate with are housed, you can also use Sample Manager in a folder, with two options. In both cases, you will be able to use the
product selection menu to switch between Sample Manager and the traditional LabKey Server interface.
In a folder, you can still access resources from the
Shared project, but can also share Sample Types and Assay Designs that are defined at the project level with other folders in the project, without having them shared site wide.
Folder of "Sample Manager" Type
You can create a new folder and select the "Sample Manager" folder type. The application will launch every time you navigate to this folder, as if it were at the project level.
It is not possible to "promote" a folder to the project level within LabKey Server. You may use
folder export and import to relocate data, but some adjustment of permissions will likely be required.
Enable "SampleManagement" Module
If you want to use Sample Manager resources in a folder, but do not want to auto-navigate to the application, you can create a folder of another type (such as Study) and then enable the "SampleManagement" module via
(Admin) > Folder > Management > Folder Type.
You will
not be navigated directly to the application in this folder, but can still reach it by editing the URL to replace "project-begin.view?" with "sampleManager-app.view?".
Export and Import of Sample Manager
Export Sample Manager Archive
As with other projects and folders in LabKey, you can
export folder objects and data using the folder management tools.
- Switch to the LabKey Server interface in your Sample Manager project.
- Note that if your Sample Manager application is in a folder, you will need to use the navigation menu to reach it, then manually replace "sampleManager-app.view?#/" in the URL with "project-begin.view?".
- Select (Admin) > Folder > Management and click the Export tab.
- Select the folder objects you want to export; a list is below.
- Select whether to include any PHI columns, and whether export to the pipeline root or via the browser.
- Click Export.
Sample Manager Folder Objects
When exporting a project or folder containing Sample Manager, include these folder objects for the corresponding Sample Manager resources:
- Sample Status and QC State Settings
- Definitions of sample statuses
- Assignment of statuses to samples included in the export
- Experiments, Protocols, and Runs
- Assay definitions and data
- Workflow jobs, tasks, templates, assignments, and files
- Sample Types and Data Classes
- Samples and Sample Types, including their lineage
- Sources and Source Types, including their lineage
- Inventory locations and items
- Freezer configurations
- Storage locations for samples
Note that Picklists are not included in folder exports. They are intended as transient collections of samples, and the connection to the samples of interest will not be retained in a folder archive.
Import Sample Manager Archive
You can import an archive to create a
new Sample Manager project. Importing into a working project, i.e. one where there are already samples of the same Sample Types, is not recommended. Sample IDs in the archive may collide with those in the working project, particularly when aliquots are involved.
- Create a new project of type "Sample Manager".
- Select (Admin) > Folder > Management and click the Import tab.
- Browse to select the archive you exported and click Import.
Importing an archive containing sample statuses into an empty folder will create the exported sample status types and samples will end up with the same status. Assignment of status will be done as a separate timeline event in the audit log.
If you import an archive into a non-empty folder, any existing sample status types will be retained and any new ones added. If there are any name collisions, the incoming status type will replace the existing one.
- The current/initial status of any existing samples in the non-empty target folder will be used to determine whether updates will be made to that sample. For example, if the current status of a sample is locked, then the import will fail if it attempts to add assay data or aliquots for that sample.
- After the import, i.e. after the update decision has been made based on the current status, the sample's status will be updated to match that of the incoming sample.
Shared Sample Types and Source Types
Any Sample Types and Sources defined in the
/Shared project will also be available for use in LabKey Sample Manager. You will see them listed on the menu and dashboards alongside local definitions.
From within the Sample Manager application, users editing (or deleting) a shared Sample Type or Source Type will see a banner indicating that changes could affect other folders.
Note that when you are viewing a grid of Sources, the container filter defaults to "Current". You can change the container filter using the
grid customizer if you want to show all Sources in "CurrentPlusProjectAndShared" or similar.
Sample Management Users and Permission Roles
An administrator in the Sample Manager or LabKey Biologics applications can access a grid of active users using the
Administration option on the user avatar menu. You'll see all the users with any access to the container in which the application is enabled.
Sample Manager and Biologics both use a subset of LabKey's role-based permissions. The "Reader", "Editor", "Editor without Delete", "Folder Administrator", and "Project Administrator" roles all map to the corresponding container-scoped roles. Learn more about those permissions in this topic:
Security Roles Reference In addition, "Storage Editor" and "Storage Designer" roles are added to the Sample Manager and Biologics applications and described
below.
Reader, Editor, and Editor without Delete
- When a user is granted the "Reader", "Editor", or "Editor without Delete" role, either in the LabKey Server folder permissions interface or the Sample Manager > Administration > Permissions tab, they will have that role in both interfaces.
- Assigning a user to a role in either place, or revoking that role in either place will apply to both the Sample Manager and LabKey Server resources in that container.
Permission Inheritance Note:
- If Sample Manager is defined in a folder, and that folder inherits permissions from a parent container, you will not be able to change role assignments within the application.
Administrator Roles
In the stand-alone Sample Manager or application, a single "Administrator" role is provided that maps to the site role "Application Admin". This also means that any "Application Admin" on the site will appear in Sample Manager as an Administrator. The
Sample Manager Documentation means these site-level roles when it identifies tasks available to an "Administrator".
When using Sample Manager within LabKey Server, administrator permissions work differently. Users with the "Folder Administrator" or "Project Administrator" role on the project or folder containing Sample Manager have those roles carry into the application. These roles may also be assigned from within the application (by users with sufficient permission). The difference between these two roles in Sample Manager is that a Project Administrator can add new user accounts, but a Folder Administrator cannot. Both admin roles can assign the various roles to existing users and perform other administrative tasks, with some exceptions listed below.
As in any LabKey Server Installation, "Site Admin" and "Application Admin" roles are assigned at the site level and grant administrative permission to Sample Manager, but are not shown in the Administrator listing of the application.
Most actions are available to any administrator role in Sample Manager with some exceptions including:
- The storage editor role described below must be granted in addition before an administrator can perform those functions
- Only "Site Admin" and "Application Admin" users can manage sample statuses.
Storage Roles for Freezer Management
Two roles specific to managing freezer storage of physical samples let Sample Manager and LabKey Biologics administrators independently grant users control over the physical storage details for samples.
Storage Editor: confers the ability to read, add, edit, and delete data related to items in storage, picklists, and jobs. These abilities are not included in any other role, including Administrator.
Storage Designer: confers the ability to read, add, edit, and delete data related to storage locations and storage units. These abilities are included for Administrators, but not for any lower role.
Learn more in this topic:
Storage Permission Roles
Workflow Editor Role
The
Workflow Editor role lets a user create and edit sample picklists as well as workflow jobs and tasks, though not workflow templates. Workflow editors also require the "Reader" role or higher in order to accomplish these tasks.
Administrators can also perform the tasks available to users with the Workflow Editor role.
Use Naming Prefixes
You can apply a container-specific naming prefix that will be added to naming patterns for all Sample Types and Source Types to assist integration of data from multiple locations while maintaining a clear association with the original source of that data.
When you have more than one Sample Manager project or folder, or are using both Sample Manager and
LabKey Biologics on the same LabKey Server, it can be helpful to assign unique prefixes to each container.
Learn more about using prefixes here:
Configure Freezer Location Options
Freezers can be assigned locations to make it easier for users to find them in a multi-freezer campus. When using a standalone version of LabKey Sample Manager, your Account Manager will create the necessary location options for you, but by using the LabKey Server interface, an administrator can opt to add or customize these locations directly.
Use caution to follow the configuration steps exactly to avoid interfering with internal entries in the same table that are used to manage the hierarchies
within freezers.
To add/edit freezer locations, open the
inventory.Location table as detailed below. In this table, you'll see entries of two
Type values.
- Freezer row entries are for locations within freezers, like racks and boxes.
- FreezerLocation row entries are for locations of freezers.
Enter (or edit) FreezerLocation rows to match your hierarchy. Start with the top levels so that you can select them as 'parents' of child locations. An example is below.
- Navigate to the Sample Manager folder.
- Switch to the LabKey Server interface: > LabKey Server > [Folder Name].
- Select (Admin) > Go To Module > Query.
- Open the inventory schema and Location table.
- Click View Data.
- Use > Insert New Row to add new locations.
- Name: the name of the location as you want users to see it in the UI.
- Description: Optional; will be shown to users selecting locations when provided.
- Type: Select FreezerLocation.
- Location (i.e. Parent Location): Select the Parent location, i.e. the location this one is 'inside'. For a top-level location, leave this field blank.
- Position (i.e. Sibling Order): Select the order for this location among the sibling locations. i.e. if you have a list of rooms on a given floor, where should this one be listed.
- You can ignore all other fields.
- Click Submit.
For example, to have the following selections for freezer locations, you'd enter these rows in the inventory.Location table.
Note that the entries do not need to be in order and position numbers do not need to be contiguous or zero-based series, they are used to 'rank' sibling locations.
Freezer Management API
In situations where you have a large number of freezers to define, it may be more convenient to define them programmatically instead of
using the UI. Learn more in the API documentation:
Related Topics
