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

Query-based Specimen Import is available in the Professional and Enterprise Editions of LabKey Server. Learn more or contact LabKey.

Specimen data can be automatically loaded from an external source by configuring a query-based specimen import connection as described in this topic. In some organizations, specimen data is maintained in an external database. Scheduled reload into as many studies as require the data can be performed using a query customized to perform all necessary actions, ensuring that researchers have up-to-date data and minimizing maintenance overhead.

Set Up

To use query-based specimen import, you must have installed the Professional module and enabled it in every study folder where you want the importer to work. Learn more in this topic:

If you have different studies with different query requirements, each container can be configured to use a different query.

Query Design

The query to import your external specimen data can be defined in any schema, but a typical scenario would involve first defining an external schema. Be sure that it publishes the table containing your specimen data.

For example, you might define an external schema named "MyRepository" exposing the table that included all the information required, optionally including primary, additive, and derivative types.

Next, you would write a query in the LabKey study folder to apply any necessary filters, adjust columns, remap column names, etc. Linked schemas may be used to write the specific queries that pull exactly the subset of information required for each study folder. In this example, the query is named "SpecimenSummary" but you can use any name you like.

To further customize on a per folder basis, you could use custom views, but in the following, we show using the default view of the query.

Query Column Names

The columns in your query must align with the field names expected by the specimen tables to be imported correctly. Find the expected specimen column names and details in this topic:

In particular, if you include columns for primary, derivative, and additive type data, these columns must be named 'primary_type' or 'PrimaryType', 'derivative_type' or 'DerivativeType', or 'additive_type' or 'AdditiveType' respectively. During the import process, the information in these files will be used to generate the various .tsv files within the archive that is constructed and imported.

Update Lookup Tables

When you provide new values for primary, additive, and derivative types via the column naming above, these will be added to the appropriate lookup tables.

Query ColumnMaps to Lookup Table

Note that you cannot update the list of labs during a query-based specimen import. To update the labs list, use a specimen archive containing only the necessary .tsv files. Learn more here: Specimen Archive File Reference

Configure Connection

  • Navigate to the study folder where the Professional module is enabled.
  • Click the Manage tab. Under the heading Specimen Repository Settings, click Configure Specimen Import.
  • Check the Enable reload box if you want to enable automated reloading of this query for this folder.
  • In the Configure Connection panel, enter the schema, query, and view that includes the specimen data needed.

Reload Specimens

Once you have configured a query-based specimen importer and enabled reloading, you have the option to click Reload Now from the configuration page (see above) to immediately reload the specimens from the external source.

In addition, when reloading is enabled, it will be performed automatically on the same schedule as other daily system maintenance tasks.

Use the System Maintenance dashboard from the admin console if you want to disable or reschedule the daily reload, or run the task immediately.

  • Select (Admin) > Site > Admin Console.
  • Under Configuration click System Maintenance.
  • Learn about the options here in this topic:

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all