Premium Resource - Specimen functionality is a legacy feature available with Premium Editions of LabKey Server. For new installations, we recommend using Sample Manager instead. Learn more or contact LabKey.

An Advanced (External) Specimen Repository can be configured to support specimen request and tracking. The role of Specimen Coordinator can be granted to a user who will configure and manage the request system, but does not have full administrator permissions.

The Tutorial: Specimen Request System includes a walk-through of the role of the Specimen Coordinator. This topic provides additional detail about the Specimen Request Settings options available.


A specimen request goes through a number of states from start to finish. For example:

  • New Request
  • Processing
  • Completed
The Specimen Coordinator defines and uses these statuses to track request workflow, and Specimen Requesters can view the current state of processing for their request. The Coordinator can also choose whether to allow users to build up specimen requests over multiple searches. This is a convenient option, but requires the administrator to watch for abandoned unsubmitted requests. An initial status of Not Yet Submitted can be helpful with this option.

Each request will begin with step number 1, but will not necessarily pass through the other states in strict order or necessarily completing each one. For example, a given request would end up as either Complete or Rejected but not one before the other. You could also define a custom status like Pending Confirmation of Location that would only apply to first requests from that location but never to repeat requests.

For each status, two additional flags may be set:

  • Final State - this flag indicates that no further processing will take place.
  • Lock Specimens - this flag will prevent other requests from being made for the same items while the request is in this state.
Note that if new specimen data is imported using the merge option, in-use statuses are not replaced.


The specimen request system makes use of the locations defined in your study. Learn about managing locations and their types in this topic: Manage Locations.


Actors are individuals or groups who can be involved in a specimen request. Examples include:

  • Specimen requesters, such as lab technicians or principal investigators
  • Reviewers of requests, such as oversight boards or leadership groups
  • Those responsible for storing and shipping specimens, such as repository owners
If a person or group may be involved in processing a specimen request, an Actor should be defined to represent them in the specimen repository tracking system.
  • Study-affiliated Actors (such as an oversight board for that particular study) are defined as One Per Study and you can specify the email address(es) associated with that actor.
  • Site-affiliated actors, who may participate in multiple studies, are defined as Multiple per study and you define the site affiliation for each actor.
  • From the Specimen Data tab, click Settings.
  • Click Manage Actors and Groups.
  • Define the Actors required and declare their affiliations. For each enter:
    • Actor Name
    • Actor Type: Choose either "Multiple Per Study (Location Affiliated)" or "One Per Study".
  • Click Save after each addition.
  • Click Update Members and add email addresses for each study-affiliated actor.
  • Click Done when finished.

During the request handling process, members of the actor receive email notifications as defined and sent by the specimen administrator.

Note that if new repository data is imported using the merge option, in-use actors are not replaced, but their group memberships are replaced.

Request Requirements

You can configure default requirements for new specimen requests. General requirements are those events that must happen once per specimen request, regardless of the details/locations of the specimens.

In addition, default requirements can be tied to various specimen-specific locations, such as originating location, providing location, and requesting location. Location-specific requirements are often related to legal and shipment notifications.

Request Form

You can customize the information collected from users when they generate a new specimen request. The only required part of the standard form is a drop-down list from which the user selects the destination site; this list appears first on the form and cannot be removed or customized.

Manage New Request Form allows you to specify a number of inputs, such as assay plan, shipping information, etc, each with:

  • Title
  • Help Text - The instructive caption such as "Please enter your shipping address"
  • Multiline - Check to allow multiple lines of input
  • Required - Whether the given information must be provided to submit the request
  • Remember by Site - If checked, the input will be pre-populated with the previous value entered for the destination location. This is useful for things like the shipping address.
Depending on the type of specimen being managed, you may wish to add additional input fields such as requested preparation method or format. For example, if the specimen is a block of tissue you might support requests of individual slides from slices that were treated with paraffin prior to freezing.

Reorder or delete input fields using the arrows and X links to the left of each field.


Next configure the options for content and process for email notifications sent during the request approval process:

  • Reply-to Address: The address that will receive replies and error messages, so it should be a monitored address. Can be fixed or set to reply to the administrator who generates each notification.
  • Edit Email Template: The subject line and body of the email can be controlled using a configurable template. Administrative permissions are required to edit the email template.
  • Subject Suffix: The subject line will always begin with the name of the study, followed by whatever value is specified as the subject suffix.
  • Send Notification of New Requests - if checked, specify who to notify.
  • Always Send CC: If specified, mail addresses listed for this property will receive a copy of every email notification. Security issues should be kept in mind when adding users to this list.
  • Default Email Recipients: Specify which actors will receive notification email, provided the coordinator does not explicitly override. Possible values: All / None / Notify Actors Involved.
  • Include Requested Specimens Table: In each notification email, a table of requested specimens can be included in the email body, or as an attachment, or not at all. Possible values: In the email body / As Excel attachment / As text attachment / Never. For information about customizing the data shown, see Email Specimen Lists.

Requestability Rules

Whether a given specimen is requestable is determined by running a series of configurable rules during import. Different types of specimen and request workflows may require different sets of rules. For example, if the specimen is divided into a limited number of vials, the "Locked in request" rule would prevent multiple requests for the same item. However, if the specimen aliquot is a block of tissue, and it is possible to generate multiple slides from the same block, that rule would not apply. A common specimen aliquot is a vial, so that terminology is used in the tools even if you have customized the aliquot field names.

  • Each specimen with requestability set via these queries is annotated so that users and administrators can determine why the aliquot is or is not requestable.
  • Administrators can specify the order in which the queries are run in order to resolve potential conflicts.
  • Rules are run in order, so the last rule applied to a given aliquot will determine it's final state.
  • Rules are run exclusively during import, so changing them will not affect the requestability of aliquots currently stored in the system until the next specimen import.
  • Click Settings in the right column on the home page of your study.
  • Under the Specimen Request Settings heading, click Manage Requestability Rules.
  • The Active Rules interface allow you to view, delete and reorder existing rules, or configure new ones:
  • From the Add Rule dropdown, you can also configure a Custom Query by specifying a Schema
  • When you are finished editing rules, click Save.

Available Rule Types

  • Administrator Override: Marks vials available or unavailable based on the 'requestable' column in the specimen data feed.
  • At Repository Check: Marks vials unavailable if they are not currently held by a repository. The current lab location of a vial can be found in the specimen details; whether that location is a repository can be found via Manage > Manage Locations.
  • Locked In Request Check: Marks vials unavailable if they are part of an active specimen request.
  • Locked While Processing Check: Marks vials unavailable if they are being processed.
  • Custom Query: Marks vials available or unavailable based on the results of an administrator-defined query.

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all