FAQs

General

How can I access LabKey at University of Basel?

LabKey is accessible from the University of Basel network, including via VPN. A unibas account is required. sciCORE provides three LabKey instances:

1. sciCORE DEV LabKey server — A testing environment for exploring and validating configurations before migrating data.
2. sciCORE Main LabKey server — The primary production server for research data.
3. sciCORE Collab LabKey server — Designed for collaborations with users who do not have a UniBas email.

Can I use LabKey without a unibas account?

Yes, LabKey access can be provided to external users who are not affiliated with University of Basel. To request access, please open a ticket with sciCORE.

I am a researcher/MS student at University of Basel, am I allowed access to LabKey?

Access to LabKey is managed by the Principal Investigator (PI) of the research project. Please contact your PI to request access.

Is LabKey free of charge for users with a unibas account?

Currently, LabKey is provided free of charge to university researchers and partner institutions.

Where can I find a complete user guide for LabKey?

A complete user guide is available here.

Is my data protected?

Yes, data security is a priority. LabKey follows best practices in data protection, ensuring controlled access, regular backups, and secure storage.

Who should I contact in case I face server issues?

For server-related issues, please open a ticket by sending an email to scicore-admin@unibas.ch. A sciCORE team member will assist you.

How can I request new features?

• To request new features in LabKey, please open a ticket with sciCORE.
• Please note that the availability of requested features depends on the priorities of the LabKey team.

Where can I get further documentation about LabKey?

Further training material and resources can be found through the following links:

• LabKey Documentation Home
• LabKey YouTube channel
• sciCORE LabKey Community Forum

---

LabKey API

What is an API Key?

An API key is a long, randomly generated token that provides an alternative authentication credential for use with APIs. API keys have security benefits over passwords:

• they are used to authenticate to a sever, avoiding the use and storage of a LabKey password on the client machine.
• they are tied to a specific server.
• they can be configured to expire.
• they can be revoked.

But since a valid API key provides complete access to your data and actions, it should be kept secret. More details can be found in the LabKey API Keys documentation.

How can I generate an API Key?

To generate an API key, please follow the steps below:

Step 1: Select the menu 👤 –> External Tool Access on the top right-hand side of the page.

Step 2: Click the button Generate API Key.

Step 3: To grab the key, click the button Copy to Clipboard. The button will read Copied! when the copy has completed.

Step 4: Finalize by clicking the button Done.

Please note that 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. Therefore, make sure to copy and save the key in a secure place immediately after it is generated.

Where can I get more information on the API usage?

The following resources provide code samples and documentation for working with the LabKey APIs in various programming languages:

• LabKey Python API.
• Rlabkey Package Documentation.
• JavaScript API Examples.
• sciCORE LabKey Scripts Gitlab repository.

---

SQL Queries

How can I create a query from one or several lists?

Step 1: Select the menu Go To Module → Query on the top right-hand side of the page.

Step 2: In the Query Schema Browser, select the list to be included in the query.

Step 3: Click the Create New Query button.

• Step 4: Enter a name for the new query and click Create And Edit Source.

• Step 5: Edit the SQL statements.

• Step 6: View SQL results by clicking Execute Query.

• Step 7: Save the query using Save & Finish or Save.

How can I edit an existing query?

Step 1: Select the menu “ → Go To Module → Query” on the top right-hand side of the page.

Step 2: In the Query Schema Browser, select the query to edit.

Step 3: Click EDIT SOURCE.

Step 4: Edit the SQL statements.

Step 5: View SQL results by clicking Execute Query.

Step 6: Save the query using Save & Finish or Save.

How can I create a view from a query or “Query Report”?

Step 1: Select Manage Views on the top right-hand side of the page.

Step 2: From the Add Report menu, select Query Report.

Step 3: Enter a name for the new view.

Step 4: Select schema, query, and default view from the dropdowns.

Step 5: Confirm by clicking Save.

Step 6: The new view will appear under Manage Views.

How can I delete a “Query Report”?

Step 1: Select Manage Views on the top right-hand side of the page.

Step 2: Select views to delete and click Delete Selected.

Step 3: Confirm by clicking OK.

---

Sample Manager

What is a classical LabKey view in Sample Manager?

When using Sample Manager with LabKey Server, you can view your sample data in the classical LabKey interface. Follow the steps below to switch to the classical view:

Step 1: Click the grid icon (2x2 boxes) next to the steering wheel.

Step 2: Select LabKey Server.

Step 3: Click your SampleManager folder.

How can I add a new Project Group and add members inside Sample Manager?

To add a new Project Group and assign members, either switch to the classical LabKey view or navigate to the Project home. Then, follow the steps outlined under User Administration in the following documentation: User Administration Guide

How can I view all Boxes with storage locations in Sample Manager?

Step 1: Switch to the classic LabKey view:

Step 2: Click the grid icon (2x2 boxes) next to the steering wheel.

Step 3: Select LabKey Server.

Step 4: Click your SampleManager folder.

Step 5: Navigate to the Query module.

Step 6: Click the steering wheel icon.

Step 7: Select Go to Module → Query.

Step 8: Under Schemas in LabKey, select Inventory > Box.

Step 9: Click View Data to see all boxes with their storage locations.

How can I show more sample details when hovering over a sample in the storage box view?

You can display more sample details by configuring Identifying Fields—custom attributes set for sample or source types in Sample Manager. By default, only the SampleID or SourceID is shown, but administrators can add up to three additional fields to enhance visibility. When configured, Identifying Fields enhance workflows by:

• Selection: Extra details appear in dropdowns, aiding differentiation.
• Storage: Displayed during storage operations; hover reveals details for accurate handling.

For a step-by-step setup guide, please visit this link

Can Identifying Fields be modified after setup?

Yes, administrators can edit/remove Identifying Fields via the “Edit Identifying Fields” option, using a similar interface to grid view customization.

Read more

What is Check Out, Check In, and Remove in Sample Manager?

• Check Out: Temporarily removes a sample from storage (e.g., for an assay), reserving its location and optionally recording a reason for checking out.
• Check In: Returns the sample to storage, updating the stored amount and, by default, incrementing the freeze‑thaw count (which can be adjusted). You may also add an optional reason for checking in.
• Remove: Takes the sample out of storage without deleting it from Sample Manager. The storage location and freeze‑thaw count are cleared, but metadata remains intact. You can update sample status and remaining amount at removal, and add a reason. Note that “Remove” does not delete the sample record—it simply marks it as Not in Storage, preserving all associated data.

For full details on each action and your role-based permissions, see the official documentation: LabKey Sample Manager: Check Out, Check In, and Remove

Is it possible to allow users to organize and partition sensitive data in Sample Manager while maintaining a shared storage environment?

Yes, Folders allow users to organize and partition sensitive data within the application while maintaining a shared storage environment. This structure supports lab-wide consistency by sharing data structures and resources like reagent lists, enabling individual teams to work with their own secured data.

For more information, please see LabKey documentation on Folder Organization.

Is it possible to print labels for my samples using LabKey Sample Manager?

Yes, to print labels for your samples in LabKey Sample Manager, ensure that your system administrator has configured the integration with BarTender, a label printing software. This one-time setup is necessary to enable label printing functionality. For assistance with this configuration, please contact the sciCORE LabKey Team at scicore-admin@unibas.ch

Once the label printing functionality is enabled, please refer to the LabKey documentation on printing labels with BarTender for detailed instructions on how to print labels for your samples.

How can I customize the columns or data shown in the sample grid view?

Administrators can define Default views for all users, but any user can create and save their own personalized views for each Sample Type.

You can tailor how your data is displayed by:

• Showing, hiding, or rearranging columns
• Rename the label of a column
• Adding filters
• Applying sorting rules

You can quickly customize a grid view directly using the column header menus, or open the grid view customizer by selecting Views > Customize Grid View to make many changes at once.

After modifying a grid, a banner will appear indicating that the view has been edited, with the option to Save your changes. Saved views let you switch between multiple configured views depending on what’s useful to you.

For detailed information, see LabKey documentation.

How can I change the order of fields shown in Sample Details within the Storage View as shown in the screenshot below?

The order of fields in the Sample Details panel is determined by the order of the Fields in Sample Type Design.

To update the field order:

• Navigate to the relevant Sample Type
• Got to Manage → Edit Sample Type Design

• Expand the Fields section
• Untick any default fields you don’t want displayed
• Drag and drop custom fields into your preferred order

How do I set up a dropdown column that only lets users select from a fixed list and prevents them from typing their own values?

To configure a column with a fixed list of values:

Step 1: Got to Manage → Edit Sample Type Design

Step 2: Expand the Fields section, then click the “>” icon next to the column to open its field properties.

Step 3: Set the Data Type to Text Choice.

Step 4: All distinct values from the current dataset in that column will be listed automatically.

Step 5: To add more values, click Add Values and enter them manually.

Step 6: To remove a value: - First, ensure it’s no longer used in the dataset for this Sample Type. - Then return to the field properties and delete it from the dropdown list.

For details on text choices, see LabKey documentation.

Can LabKey APIs be used to interact with data in Sample Manager?

Yes, LabKey provides robust APIs—including Python, R, and JavaScript libraries—that allow programmatic interaction with data in Sample Manager. These APIs can be used to create, update, query, and manage sample types, metadata, and associated data across projects. Example scripts demonstrating these capabilities can be found in the sciCORE LabKey Scripts Gitlab repository.

---

Lists

How can I create a list?

Lists can be created manually or via data import (Excel, TSV, CSV).

Step 1: Prepare file: First line = column names

Recommended to use only letters, numbers, and underscores for column names, starting with a letter or underscore.

Step 2: Create list:

• Go to Project/Folder.
• Click Manage Lists in the Lists web part or “⚙︎” → Manage Lists.
• Click Create New List.

Step 3: Define list properties:

• Enter a unique name.
• Provide an optional description.

Step 4: Define fields:

• Import file to auto-detect columns and data types or define columns manually.

• Adjust/remove columns, set data types.
  Some changes, like Integer to Double, or String to Integer aren’t allowed after creation. Therefore, it is recommended to set the data type at this point.

• Choose a Key Field: Select a primary key that uniquely identifies each record.
  Options: use an integer or text field from your data, or generate an auto-incrementing integer key.
  Auto-increment keys prevent updating the list via file import.

Step 5: Import data (optional): Tick “Import data from file upon creation”.

Step 6: Save to complete.

How can I edit a row?

Click edit icon in left-most column, then edit the values.

How can I add a row?

• Add single row: Click “+” → Insert new row.

  

• Add rows via file: Click “+” → Import bulk data. Match columns, upload file. Only columns matching the list’s names (case-insensitive) will be imported. To ensure compatibility, click Download Template, fill it, and upload.

  

How can I update existing data?

Click + → Import bulk data, select Update rows, optionally allow new rows. For lists with an auto-incrementing integer key, updates and merges are not available. Only columns matching the list’s names (case-insensitive) will be updated. New columns need to be defined prior to the update (How can I add a column).

How can I add a column?

• Click Design → Fields → add new field.

• Customize grid to include new column.

  

How can I remove a row?

Select rows to be deleted and click the Bin icon.

How can I remove a column?

Click Design, expand Fields and click X on the right of the column.

Note: Deleting a field including its data is permanent and cannot be undone. If you only want to hide it from the grid view, but keep the data check (How can I customize the appearance of a list?)

How can I customize the appearance of a list?

Navigate to Grid views → Customize Grid.

• To Show/Hide/Organize Columns:

  Select which columns to display. Enable Show Hidden Fields to reveal hidden columns. Drag and drop to arrange selected columns in the desired order.

• To define Filtered View:

  Go to the Filter tab. Add custom filters for specific column.

Click Save. Give a name or keep as Default view. Saved views let you switch between multiple configured views depending on your needs.

Why do I only see some rows of the list?

• Check above the header row to see if a filter is applied. If so, clear it by clicking the X.

• Click the Grid views icon and check if Apply Grid Filter is selected. If it is, go to Customize Grid, open the Filter tab, and remove the filter.

How do I prevent users from entering free text in a field? / How can I define a fixed list of allowed values for a column?

• Click Design at the top of the list.
• Expand Fields box, click “>” icon to open field properties of the column.
• Select Text Choice as the Data Type.
• All distinct values of the column appear.
• Add additional values via Add Values.
• To remove a value, first clear it from the list, then go back to the field properties of the column and remove it from the Drop-down values list.

For details, see LabKey documentation.