Import FreezerPro Data: /Documentation

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.

Premium Feature — Available in the Professional and Enterprise Editions of LabKey Server. Also available as an Add-on to the Starter Edition. Learn more or contact LabKey.

FreezerPro is a web-based tool widely used for managing frozen specimens. LabKey Server can import FreezerPro data into the specimen management system allowing for integration of the FreezerPro inventory information with other data within a LabKey study. LabKey Server supports automated reloading of data directly from a FreezerPro installation using the FreezerPro API. A data reload may be triggered manually or configured to run on a regular schedule with other system maintenance tasks if desired. The reloaded data may be filtered and columns can be remapped to LabKey columns during the reload process.

Enable FreezerPro
Connect to the FreezerPro Server
Select Specimen Types and Map Fields
Filtering FreezerPro Data
Manual Configuration Via XML
Manual Triggering of Reload
Scheduling Automatic Reload

FreezerPro Enterprise or Elite editions are required for integration with LabKey Server. (FreezerPro Basic and Standard editions do not expose an API, which LabKey Server uses to communicate with FreezerPro.)

Individual vials in a FreezerPro archive are identified by the barcode used; vials are grouped using the unique SpecimenID field which is also included. The Specimen Repository features like reports, quality control, request management and tracking are supported as if the data had come from a standard LabKey Server specimen archive. Not all fields are mapped directly to specimen archive fields - fields which are not recognized will be ignored unless a custom field is added to LabKey Server. See below for adding custom fields.

The following steps show you how to enable, configure, and import FreezerPro data into your LabKey Server folder.

Enable FreezerPro

To add FreezerPro functionality to your project or folder, enable the FreezerPro module in that project or folder.

Begin with a folder of type Study. (Only study folders support FreezerPro.)
Select (Admin) > Folder > Management.
Click the Folder Type tab.
Select the checkbox on the right to enable the FreezerPro module.
Click Update Folder.

Connect to the FreezerPro Server

Navigate to the study folder where the FreezerPro module is enabled.
Click the Manage tab. Under the heading Specimen Repository Settings, click Configure Specimen Import.

If the Professional module is also enabled in your folder, you will next see a page to select between two external importer options. Only one can be active at once.
Click the Active bubble to enable FreezerPro, then click the Configure link for that row.

On the Connection tab, enter the following:

FreezerPro Server Base URL. This is the URL where you log in to FreezerPro, plus the suffix "/api".
Check the Change Password box to enable entry of username and password.
Enter the User Name and Password you want to use to connect to the remote FreezerPro server.

Click Test Connection to confirm the ability to connect using these entries. A popup message will confirm a successful connection or indicate a possible problem to resolve before proceeding.

Select Specimen Types and Map Fields

After adding the credentials and server information, configure which sample types you want to import and the field mappings between FreezerPro and LabKey Server.

Click the Specimen Fields tab.
Click the pencil icon to open the field configuration panel.
A list of available sample types is shown. Select the sample types you want to import and click Next.

A list of destination LabKey fields is shown next to a list of source FreezerPro fields. Select which FreezerPro fields you want to match to the corresponding LabKey fields. (Note that the list of available field options is filtered based on the field type. For example, a LabKey date field only shows FreezerPro date fields as mapping options.)
If no LabKey field shown is appropriate for a FreezerPro field of interest, click the arrow button to open the Add Custom LabKey Field panel.

Enter the name, label, and select the appropriate type.
Click Add to add the field to the list.
Assign a mapping to your new field.

Click Apply when finished. Custom fields are validated to ensure that the field name doesn't have spaces and doesn't already exist in the current folder, but will not be added to the specimen tables until you click Save on the specimen fields tab.

A summary of selected sample types and field mappings is shown.
An "Exclamation Point" icon is shown next to any mapped FreezerPro fields that are no longer available from the FreezerPro server. Mouse over the icon for the warning message: "This field is no longer available from the configured FreezerPro server for the selected sample type. Please adjust the specimen mapping."
Once the types and mappings are configured as desired, click Save. Custom fields will now be added to the study.SpecimenEvent and study.Vial table in the current folder.)

Filtering FreezerPro Data

You can configure filters that limit the data exported from FreezerPro via the Filters tab.

To add filters:

On the FreezerPro Configuration page, click the Filters tab.
Click Add New Filter.
Using the dropdowns, select a FreezerPro field to filter and an operator.
Using the text box, add a criteria value.
Add multiple filters as desired.
Click Save when finished.

Manual Configuration Via XML

You can manually edit the configuration XML for more complex cases, such as loading data into multiple LabKey studies, mapping columns that are not universally present in the sample types chosen, and skipping location information. Editing the XML manually will replace any configurations added through the user interface. If you later choose to go back to configuration via the user interface, the manually configured XML is translated into configurations supported by the graphical user interface, but any configurations not supported by the graphical user interface will be lost.

Some XML common elements to use:

filterString: return all rows which contain the given string anywhere in the imported row.
columnFilters: return rows which have an exact match for the specified value in the column of the given name. Multiple columnFilters rows are ANDed together.
columnMap: map data in the FreezerPro field sourceName into the LabKey field destName. The destName field must be defined on both the SpecimenEvent and Vial tables.

For a complete XML reference see the LabKey XML Reference and click the file freezerProExport.xsd.

XML Config Example

In your study, click the Manage tab, and then click Configure Freezerpro.
Select the Advanced tab.
Select "Configure manually via XML". As long as this option is selected, the configuration options on the specimen fields and filters tabs will be read-only.
Edit or add the XML metadata to provide the filtering and mapping required. For example, paste the following code block to import only records containing a keyword "validated" for the INS-4074 Study Protocol, and map FreezerPro field "Cells/Vial" to LabKey field "CellsVial", etc.

<?xml version="1.0" encoding="UTF-8"?>
<freezerProConfig xmlns="http://labkey.org/study/xml/freezerProExport">
   <filterString>validated</filterString>
   <columnFilters>
     <filter name="Study Protocol" value="INS-4074"/>
   </columnFilters>
   <columnMap>
      <column sourceName="subject_id" destName="ptid"/>
      <column sourceName="Cells/Vial" destName="CellsVial"/>
   </columnMap>
</freezerProConfig>

Click Save.

Click Test Configuration if desired to confirm an active connection.
Click Reload Now to reload applying the new filters and mapping.

Manual Triggering of Reload

This step assumes you have already configured a connection with a FreezerPro server instance. For details see above.

On the Configure FreezerPro page, click the Connection tab.
Click Test Connection to confirm the ability to connect using these entries. A popup message will confirm a successful connection or indicate a possible problem to resolve before attempting reload.
Click Reload Now to pull data from FreezerPro. You'll see the pipeline import screen, which will show COMPLETE when finished.
Return to the Specimen Data tab to view the loaded freezerpro data.

Scheduling Automatic Reload

You may also have FreezerPro data automatically reloaded on a regular schedule. Reloading is configured at the study-level and different studies may have different schedules for the day(s) on which reloading occurs, but all automatic reloading is done at the same time of day, along with other site-wide system maintenance tasks.

On the Configure Freezerpro page click the Connection tab.
Click the box for Enable Reloading.
Specify the Load on date - the date to start automatic reloading.
Set Repeat (days) for the number of days between automatic reloads. Use 1 for daily reloading, 7 for weekly pulls.

The time of day at which system maintenance occurs is set by an administrator at the site level. A typical default is to have maintenance run at 2am when users are less likely to be inconvenienced. So for instance, if you want to have reloading happen "tonight" be sure to use tomorrow's date.

To see or change when reloading occurs:

Select (Admin) > Site > Admin Console.
Under Configuration, click System Maintenance.
While FreezerPro automatic reloading is performed with these tasks on this schedule, it is not part of every installation, so does not appear as one of the options listed on the page.

If you want to confirm that the FreezerPro Upload Task will be run with the checked tasks, click Run all tasks and you will see a progress log of tasks as they start and complete.

LabKey Support

LabKey Support