Release Notes

• Release Notes 25.3 (March 2025)

Getting Started

• Try it Now: Data Grids
• Explore key feature areas:
• Explore Longitudinal Studies: HIV Disease Progression
• Explore Assay Data Analysis: T Cell Culture - Media Comparison
• Contact Us for a Custom Demo or Trial: The best way to get started is to let us know your research goals and team needs. Request a customized demo to see how we can help.

LabKey SDMS Documentation

• LabKey Server SDMS
• Data Basics
• Studies
• Panorama: Targeted Mass Spectrometry
• Development

LabKey Sample Manager Documentation

• Release Notes: Sample Manager
• Sample Manager Help and Documentation
• Sample Manager
• Electronic Lab Notebooks (ELN)

LabKey LIMS Documentation

• Release Notes: LabKey LIMS
• LabKey LIMS Highlights

Biologics LIMS Documentation

• Release Notes: Biologics LIMS
• Introduction to LabKey Biologics
• Biologics LIMS

Premium Resources

• Premium Resources: Premium documentation, example code, and best practices.

More Resources

• LabKey's YouTube Channel
• Upcoming Features
• Documentation Archive

Upcoming Features

Releases we are currently working on:

• Release Notes 25.7 (July 2025)

Recent Documentation Updates

Here's what we're working on for the release of LabKey Server version 25.7 (July 2025).

• LabKey Server SDMS
• Distribution Changes and Upgrade Notes
• Client APIs and Development Notes
• Other LabKey Products:
• Sample Manager Release Notes
• LabKey LIMS Release Notes
• Biologics LIMS Release Notes

LabKey Server SDMS

Premium Edition Feature Updates

• Time-based one-time password (TOTP) two-factor authentication (2FA) can now be configured to remember trusted devices and reduce the frequency of prompts to users. (docs)
• SAML Authentication now supports passwordless-login when enabled on the SAML IdP. (docs) Also available in 25.3.10.
• Parameters can be included in the SAML IdP SSO URL if required. (docs) Also available in 25.3.6.
• A new validator will identify external images referenced from Electronic Lab Notebooks. (docs)
• A custom utility that will scan for strict CSP violations in wikis, participant views, and study descriptions is now available to LabKey Cloud and Premium Edition subscribers. (docs) Also available in 25.3.9.
• Extended metrics reporting is available to support some clients. Your account manager will work with you to set this up if needed.
• Premium Resource for EHR (Electronic Health Records): Documentation of validation trigger levels has been added to assist developers. (docs)
• Sample Manager Feature Updates
• LabKey LIMS Feature Updates
• Biologics LIMS Feature Updates

Community Edition Updates

• A new simpler method for installing the Community Edition is now available, making it easier than ever to get started. (learn more)
• LabKey SQL now supports precision and scale for NUMERIC values, as well as @format annotations. (docs)
• Administrators can view content security policy reports via a new link from the admin console.
• The "Site Administrators" and "Site Developers" groups are no longer created by default or used for assigning permissions. (docs)
• Permissions for users may need to be adjusted if they previously relied on these groups. In particular, report permissions that were previously automatically granted to site administrators must now be assigned directly. (docs)
• By default, the "assigned-to" list for an issue tracker is now the "Site Users" group, where it was previously the "Site Administrators" group. (docs)

Distribution Changes and Upgrade Notes

• A strong Content Security Policy (CSP) is highly recommended for all servers. (docs)
• Our recommended strong CSP blocks all inline script and prevents browsers from accessing unvetted external resources. This means the browser blocks all cross-site script (XSS) injection and cross-origin resource sharing attacks.
• All LabKey Cloud deployments and on-premise distributions are configured with a strong CSP in enforce mode as of version 25.7.
• To use this default, administrators of on-premise distributions should remove any custom settings from their application.properties file.
• If any customizations you require are not supported by the new ability to substitute allowed external hosts, please contact us so that we can best support you.
• Validators, examples, and instructions are provided to assist you in clearing any reports that may be raised by your server so that your users can still access all their content. (docs)
• LabKey Server embeds a copy of Tomcat 10. It no longer uses or depends on a separately installed copy of Tomcat. (installation docs)
• LabKey Cloud subscribers are installed, upgraded, and maintained by LabKey.
• If you are installing LabKey Community Edition for the first time, a new easy method is provided that will meet the needs of new users. (learn more)
• Users with on-premise installations who have already upgraded to use embedded Tomcat should follow these upgrade instructions. (upgrade on linux | upgrade on windows)
• Users with on-premise installations that have not already migrated their server to use embedded Tomcat will need to follow an additional set of steps covered in the documentation archives. (migration docs)
• Tomcat v10.1.42 included changes to the defaults for max-part-count, max-part-header-size, and max-connections. LabKey requires adjustments to these defaults to support the application and provide ample concurrent requests for LabKey Server scenarios. These properties and their defaults can be overridden in the application.properties file if needed. (docs)

Deprecated Features

• The "Advanced import options" of choosing objects during import of folder archives, as well as having those imports applied to multiple folders simultaneously, have both been deprecated.
• Support for object-level discussions has been deprecated.
• Support for additional date, time, and datetime parsing patterns has been removed.
• "Assay Progress Reports" in studies have been removed.
• Support for Ancillary Studies has been removed.
• The Publish Study feature provides a more extensive mechanism for creating child studies. (docs)
• Generating a schema export from the query browser is no longer available.
• Support for study protocol design tools has been removed.
• Support for OpenEMPI has been removed.
• Support for SQL Server 2016 has been removed. (supported versions)

Client APIs and Development Notes

• The behavior of lookups with values that look like numbers has been improved. We will attempt to resolve by alternate key (if allowLookupByAlternateKey is true) and then by primary key.
• When lookup validation for a field is not selected, and allowLookupByAlternateKey is true, missing lookup values will result in an error. A deprecated feature flag is provided to restore the previous behavior of resolving to null if desired.
• Our documentation example of an assay transformation script in R has been updated to show how to enable proper encoding of strings. Use the quote=TRUE and qmethod="double" parameters for the write.table. Your code may require similar updates. (docs)
• An example of using the lineage API from Python has been added. (docs)
• API Resources

Sample Manager

The Sample Manager Release Notes list features by monthly version and product edition.

LabKey LIMS

The LabKey LIMS Release Notes list features in addition to those in the Professional Edition of LabKey Sample Manager.

Biologics LIMS

The Biologics LIMS Release Notes list features in addition to those in LabKey LIMS.

Previous Release Notes: Version 25.3

• Try LabKey Now
• Learn more about Sample Manager
• Learn more about Biologics LIMS
• Learn even more, then contact us for a custom demo or trial

• Contact Us

Topics

• LabKey Server SDMS
• Navigate the Server
• Visualizations
• R Reports
• My Account
• Tutorials

More LabKey Solutions

• LabKey Premium Editions
• LabKey Cloud for Life Sciences
• Custom Development

• Securely share your data with colleagues through interactive grid views
• Collaboratively build and explore interactive visualizations
• Drill down into de-identified data for study participants
• Combine related datasets using data integration tools

Begin the Data Grid Tutorial

LabKey Server Trial

LabKey Server Trial instances contain a core subset of features, and sample content to help get you started. Upload your own data, try tutorials, and even create a custom site tailored to your research and share it with colleagues. Your trial lasts 30 days and we're ready to help you with next steps toward incorporating LabKey Server into your research projects.

Start here: Explore LabKey Server with a trial in LabKey Cloud

Sample Manager Trial

Try the core features of LabKey Sample Manager using our example data and adding your own. Your trial lasts 30 days and we're ready to help you with next steps.

Start here: Get Started with Sample Manager

Biologics LIMS Trial

Try the core features of LabKey Biologics LIMS using our example data and tutorial walkthroughs. Your trial lasts 30 days and we're ready to help you with next steps toward incorporating LabKey Biologics into your work.

Start here: Explore LabKey Biologics with a Trial

To get started using LabKey Server and understanding the core functionality, contact us about your research needs and goals. Upon request we will set up a LabKey Cloud-based trial of LabKey Server for you.

You'll receive an email with details about getting started and logging in.

Trial server instances contain a subset of features, and some basic content to get you started. Upload your own data, try tutorials, and even create a custom site tailored to your research and share it with colleagues. Your trial lasts 30 days and we're ready to help you with next steps toward incorporating LabKey Server into your research projects.

Tours & Tutorials

Step by step introductions to key functionality of LabKey Server.

Welcome to LabKey Server!

• Navigation and User Interface
• Security Model
• Tools for Working Together
• Tools for Data Analysis
• Tools for Research Studies
• What's Next?

Navigation and User Interface

• Projects and Folders
• Tabs
• Web Parts
• Header Menus

Projects and Folders

The project and folder hierarchy is like a directory tree and forms the basic organizing structure inside LabKey Server. Everything you create or configure in LabKey Server is located in some folder. Projects are the top level folders, with all the same behavior, plus some additional configuration options; they typically represent a separate team or research effort.

The Home project is a special project. On your Trial server, it contains the main welcome banner. To return to the home project at any time, click the LabKey logo in the upper left corner.

The project menu is on the left end of the menu bar and includes the display name of the current project.

Hover over the project menu to see the available projects, and folders within them. Click any project or folder name to navigate there.

Any project or folder with subfolders will show / buttons for expanding and contracting the list shown. If you are in a subfolder, there will be a clickable 'breadcrumb' trail at the top of the menu for quickly moving up the hierarchy. The menu will scroll when there are enough items, with the current location visible and expanded by default.

The project menu always displays the name of the current project, even when you are in a folder or subfolder. A link with the Folder Name is shown near the top of page views like the following, offering easy one click return to the main page of the folder.

For more about projects, folders, and navigation, see Project and Folder Basics.

Tabs

Using tabs within a folder can give you new "pages" of user interface to help organize content. For an example of tabs in action, see the Research Study within the Example Project.

When your browser window is too narrow to display tabs arrayed across the screen, they will be collapsed into a pulldown menu showing the current tab name and a (chevron). Click the name of the tab on this menu to navigate to it.

For more about adding and customizing tabs, see Use Tabs.

Web Parts

Web parts are user interface panels that can be shown on any folder page or tab. Each web part provides some type of interaction for users with underlying data or other content.

There is a main "wide" column on the left and narrower column on the right. Each column supports a different set of web parts. By combining and reordering these web parts, an administrator can tailor the layout to the needs of the users.

For a hands-on example to try right now, explore the Collaboration Workspace project on your Trial Server.

To learn more, see Add Web Parts and Manage Web Parts. For a list of the types of web parts available in a full installation of LabKey Server, see the Web Part Inventory.

Header Menus

In the upper right, icon menus offer:

• : Click to open a site-wide search box.
• : Shown only to Admins: Administrative options available to users granted such access. See below.
• username: Login and security options; help links to documentation.

Admin Menu

The "first user" of this trial site will always be an administrator and have access to the menu. If that user adds others, they may or may not have the same menu of options available, depending on permissions granted to them.

• Site >: Settings that pertain to the entire site.
• Admin Console: In this Trial edition of LabKey Server, some fields are not configurable and may be shown as read-only. See Admin Console for details about options available in the full installation of LabKey.
• Site Users, Groups, Permissions: Site-level security settings.
• Create Project: Creates a new project (top-level folder) on the server.
• Folder >: Settings for the current folder.
• Permissions: Security configuration for the current folder.
• Management: General configuration for the current folder.
• Project Users and Settings: General configuration for the current project.
• Page Admin Mode: Used to change page layout and add or remove UI elements.
• Manage Views, Lists, Assays: Configuration for common data containers.
• Manage Hosted Server Account: Return to the site from which you launched this trial server.
• Go To Module >: Home pages for the currently enabled modules.

Security Model

LabKey Server has a group and role-based security model. Whether an individual is authorized to see a resource or perform an action is checked dynamically based on the groups they belong to and roles (permissions) granted to them. Learn more here: Security. Try a walkthrough using your Trial Server here: Exploring LabKey Security

Tools for Working Together

Collaborating with teams within a single lab or around the world is made easier when you share resources and information in an online workspace.

• Message Boards: Post announcements and carry on threaded discussions. Learn more here.

• Issue Trackers: Track issues, bugs, or other workflow tasks (like assay requests) by customizing an issue tracker. LabKey uses issue trackers to manage development issues and client requests. Learn more here.

• Wikis: Documents written in HTML, Markdown, Wiki syntax, or plain text; they can include images, links, and live content from data tables. You're reading a Wiki page right now. Learn more here.

• File Repositories: Upload and selectively share files and spreadsheets of data; connect with custom import methods. You can see an example here. Learn more here.

Tools for Data Analysis

Biomedical research data comes in many forms, shapes, and sizes. LabKey integrates directly with many types of instruments and software systems and with customization can support any type of tabular data.

• Uploading Data: From dragging and dropping single spreadsheets to connecting a data pipeline to an outside location for incoming data, your options are as varied as your data. Learn about the options here: Import Data.

• LabKey Data Grids: LabKey data grids show a configurable view of the underlying database table. To learn more, try a quick online tour of data grids.

• Interpreting Instrument Data: Using assay designs and pipeline protocols, you can direct LabKey Server to correctly interpret complex instrument data during import. Learn more here: Assay Data.

• Statistics and Queries: Add summary statistics to your data grids and write SQL queries within the UI. Learn more here: Column Summary Statistics and SQL Queries.

• Visualizations: Create easy charts and plots backed by live data. Learn more here: Visualizations.

• Reporting: Generate reports and query snapshots of your data. Use R, JavaScript, and LabKey plotting APIs to present your data in many ways. Learn more here: Reports and Charts.

Tools for Research Studies

Study folders organize research data about participants over time. There are many different ways to configure and use LabKey studies. Learn more here: Studies.

• Study Schedules and Navigation: Dashboards for seeing at a glance what work is completed and what is scheduled helps coordinators manage research data collection. Learn more here: Study Navigation.

• Participant and Date Alignment: By aligning all of your data based on the participant and date information, you can integrate and compare otherwise disparate test results. Explore the breadth of data for a single study subject, or view trends across cohorts of similar subjects. Learn more here: Study User Guide.

• Publishing and Sharing: Select who should see which parts of your study data and analysis. Choose how to publish results, including many options for obscuring and protecting PHI (protected health information) and aggregating results. Learn more here: Study Administrator Guide and Publish a Study: Protected Health Information / PHI.

What's Next?

Explore the example content on your Trial Server using one of these walkthroughs.

• Exploring LabKey Collaboration
• Exploring Laboratory Data
• Exploring LabKey Studies

• LabKey Server Documentation

• Tour
• Try It Now
• What Else Can I Do?
• More Tutorials

Tour

The "Collaboration Workspace" folder in the "Example Project" shows three web parts on its main dashboard. Web parts are user interface panels and can be customized in many ways.

• 1. Learn About LabKey Collaboration Folders: a panel of descriptive information (not part of a default Collaboration folder).
• 2. Messages: show conversations or announcements in a messages web part
• 3. Task Tracker: LabKey's issue tracker tools can be tailored to a variety of uses.

To help show some of the collaborative options, this project also includes a few sample users with different roles. You can see a message from the "team lead" and there is also a task called "Get Started" listed as a "Todo".

Try It Now

• Messages
• Task Tracker

Messages

A message board is a basic tool for communication; LabKey Message Boards can be customized to many use cases: from announcements to developer support and discussion.

• Notice the first message, "Hello World".
• Click View Message or Respond below it.
• Click Respond.
• Enter any text you like in the Body field. If you also change the Title, your response will have a new title but the main message thread will retain the existing title.
• Notice that you can select other options for how your body text is rendered. Options: Plain Text, HTML, Markdown, or Wiki syntax.
• Notice you could attach a file if you like.
• Click Submit.

• You are now viewing the message thread. Notice links to edit or delete. Since you an administrator on this server, you can edit messages others wrote, which would not be true for most users.
• You may have also received an email when you posted your response. By default, you are subscribed to any messages you create or comment on. Click unsubscribe to see how you would reset your preferences if you don't want to receive these emails.
• Click the Collaboration Workspace link near the top of the page to return to the main folder dashboard. These links are shown any time you are viewing a page within a folder.
• Notice that on the main folder dashboard, the message board does not show the text of your reply, but just the note "(1 response)".

• Click New to create a new message.
• You will see the same input fields as when replying; enter some text and click Submit.
• When you return to the main folder dashboard, you will see your new message.

• An administrator can control many display aspects of message boards, including the level of detail, order of messages, and even what "Messages" are called.
• The (triangle) menu in the upper right corner includes several options for customizing.

• New: Create a new message.
• View List: See the message board in list format.
• Admin: Change things like display order, what messages are called, security, and what options users have when adding messages.
• Email: Control when and how email notifications are sent about messages on this board.
• Customize: Select whether this web part shows the "full" information about the message, as shown in our example, or just a simple preview.

More details about using message boards can be found in this topic: Use Message Boards.

Task Tracker

LabKey provides flexible tools for tracking tasks with multiple steps done by various team members. Generically referred to as "issue trackers" the example project includes a simple "Task Tracker".

The basic life cycle of any task or issue moves through three states:

• Open: someone decides something needs to be done; various steps and reassignments can happen, including prioritization and reassignments
• Resolved: someone does the thing
• Closed: the orginal requestor confirms the solution is correct

• Navigate to the Collaboration Workspace.
• Scroll down to the Task Tracker and click the title of the task, Get Started to open the detail view.
• The status, assignment, priority, and other information are shown here. You can see that the team leader opened this task and added the first step: assign this task to yourself.

• Click Update. Used when you are not "resolving" the issue, merely changing assignment or adding extra information.

• Select your username from the Assigned To pulldown.
• You could also change other information and provide an optional comment about your update.
• Click Save.
• Note: You may receive an email when you do this. Email preferences are configurable. Learn more here.
• The task is now assigned to you. You can see the sequence of changes growing below the current issue properties.

• Click Collaboration Workspace to return to the main page.
• Notice the task is assigned to you now.

• Click New Task to create a new task.
• Enter your choice of title, notice that the default status "Open" cannot be changed, but you can change the priority, and enter other information. Note that setting the priority field is required.
• Assign the task to the "lab technician" user.
• Click Save to open the new issue.
• When you return to the task list on the Collaboration Workspace page, you will see it listed as issue 2.

To show how the resolution process works, use the fact that you are an administrator and can use impersonation to take on another user's identity. Learn more here.

• Select (Your Username) > Impersonate > User.
• Choose "lab_technician" and click Impersonate. You are now seeing the page as the lab technician would. For example, you no longer have access to administrator options on the messages web part.
• Click the title of the new task you assigned to the lab technician to open it.
• Click Resolve.
• Notice that by default, the resolved task will be assigned to the original user who opened it - in this case you!
• The default value for the Resolution field is "Fixed", but you can select other options if appropriate.
• Enter a comment saying you've completed the task, then click Save.
• Click Stop Impersonating.
• Open the task again and close it as yourself.
• Enter a few more tasks to have more data for viewing.
• When finished, return to the Collaboration Workspace main page.

The Task Tracker grid offers many options.

• Search the contents by ID number or search term using the search box.
• Sort and filter the list of tasks using the header menu for any column. Learn more here.
• Create custom grid views (ways to view tasks), such as "All assigned to me" or "All priority 1 issues for the current milestone". Use (Grid Views) > Customize Grid and add filters and sorts here. Learn more here.
• You could also customize the grid to expose other columns if helpful, such as the name of the user who originally opened the issue. Learn more here.

Learn about creating your own issue tracker in this topic: Tutorial: Issue Tracking.

What Else Can I Do?

• Add New Web Parts
• Add a Wiki
• Add a List
• Add a File Repository

Add New Web Parts

Web parts are panels of user interface that display content to your users. As an administrator, you can customize what is shown on the page by using page admin mode. To add a new web part to any folder page:

• Select > Page Admin Mode. Note that if you do not see this option, make sure you are logged in as an administrator and not impersonating another user.

• Notice that <Select Web Part> pulldown menus appear at the bottom of the page. There is a wider "main" column on the left and a narrow column on the right; each column supports a different set of web parts.
• Note: If both pulldown menus are stacked on the right, make your browser slightly wider to show them on separate sides.

• Select the type of web part you want to create on the desired side. For example, to create a main panel wiki like the welcome panel shown in the Collaboration Workspace folder, select Wiki on the left.
• Click Add.
• The new web part will be added at the bottom of the column. While you are in Page Admin Mode, you can reposition it on the page using the (triangle) menu in the web part header. Move up or down as desired.

• Click Exit Admin Mode in the upper right.

If you later decide to remove a web part from a page, the underlying content is not deleted. The web part only represents the user interface.

For more about web part types and functionality, see Add Web Parts.

Add a Wiki

Wiki documents provide an easy way to display content. They can contain any text or visual information and be formatted in HTML, Markdown, Wiki syntax, or plain text by using "Wiki" format but not including formatting syntax. To create our first wiki, we use a wiki web part.

• Add a Wiki web part on the left side of the page. If you followed the instructions above, you already did so.
• Click Create a new wiki page. Note that if a page named "default" already exists in the folder, the new web part will display it. In this case, create a new one by selecting New from the (triangle) menu in the header of the web part.

• The Name must be unique in the folder.
• The Title is displayed at the top of the page.
• Choosing a Parent page lets you organize many wikis into a hierarchy. The table of contents on the right of the page you are reading now shows many examples.
• Enter the Body of the wiki. To change what formatting is used, use the Convert to... button in the upper right. A short guide to the formatting you select is shown at the bottom of the edit page.
• Notice that you can attach files and elect whether to show them listed at the bottom of the wiki page.
• Click Save & Close.
• Scroll down to see your new wiki web part.

• To reopen for editing, click the (pencil) icon.

More details about creating and using wikis can be found in this topic: Wikis.

Add a List

A list is a simple table of data. For example, you might store a list of labs you work with.

• Select > Manage Lists.
• You will see a number of preexisting lists related to the task tracker.
• Click Create New List.
• Name: Enter a short name (such as "labs"). It must be unique in the folder.
• Review the list properties available; for this first example, leave them unchanged.

• Click the Fields section header to open it.
• Click Manually Define Fields.
• In the Name box of the first field, enter "LabName" (no spaces) to create a key column for our list. Leave the data type "Text".
• After doing this, you can set the Key Field Name in the blue panel. Select LabName from the dropdown (the field you just added).

• Use the icon to expand the field and see the options available. Even more can be found by clicking Advanced Settings.
• Click Add Field and enter the name of each additional column you want in your list. In this example, we have added an address and contact person, both text fields. Notice the "Primary Key" field is specifed in the field details for LabName; it cannot be deleted and you cannot change its data type.

• Click Save to create the "labs" list. You will see it in the grid of "Available Lists".

To populate this new empty list:

• Click the list name ("labs") in the grid. There is no data to show.
• Select (Insert data) > Insert new row.
• Enter any values you like.
• Click Submit.
• Repeat the process to add a few more rows.

• Click the Collaboration Workspace link to return to the main folder page.
• Add a List - Single web part on the left side of the page.
• Give it the title you like, and select the new list you just created.
• Click Submit.

Now your collaboration workspace shows quick contact information on the front page.

Learn more about creating and using lists here and in the List Tutorial.

Learn more about editing fields and their properties here: Field Editor

Add a File Repository

• Add a Files web part on the left side of the page.
• Drag and drop files and folders into the window to upload them.

• Each file can then be downloaded by other users of the collaboration workspace.

See the Tutorial: File Repository for a walkthrough of using file repositories.

More Tutorials

Other tutorials using "Collaboration" folders that you can run on your LabKey Trial Server:

• Tutorial: File Repository
• Tutorial: Lists
• Tutorial: Security

Explore More on your LabKey Trial Server

• Exploring Laboratory Data
• Exploring LabKey Studies
• Exploring LabKey Security

• Tour
• Try It Now
• What Else Can I Do?
• More Tutorials

Tour

The "Laboratory Data" folder is an Assay folder. You'll see four web parts in our example:

• 1. Learn About LabKey Assay Folders: a panel of descriptive information (not part of a default Assay folder).
• 2. Assay List: a list of assays defined in the folder. Here we have "Blood Test Data."
• 3. Blood Test Data Results: A query web part showing a grid of data.
• 4. Files: a file repository where you can browse files in this container or upload new ones.

The folder includes a simple assay design created from the "Standard Assay Type" representing some blood test results. A single run (spreadsheet) of data has been imported using it. Continue below to try out the assay tools.

Try It Now

This section helps you try some key features of working with laboratory data.

• Assay List: Browse and use assay designs for data and metadata
• Understand Assay Designs: Review how assay designs are defined and customized
• Blood Test Data Results: Reviewing and analyzing data in grids
• Files: Uploading and importing files

Assay List

Using an Assay List web part, you can browse existing assay designs and as an administrator, add new ones. An assay design tells the server how to interpret uploaded data. Click the name of the design in this web part to see the run(s) that have been uploaded.

• Click the name Blood Test Data in the Assay List to see the "Runs" imported using it.

• In this case, a single run (spreadsheet) "BloodTest_Run1.xls" has been imported. Click the Assay ID (in this case the file name) to see the results.

This example shows blood data for 3 participants over a few different dates. White blood counts (WBC), mean corpuscular volume (MCV), and hemoglobin (HGB) levels have been collected in an Excel spreadsheet.

To see the upload process, we can simulate importing the existing run. We will cancel the import before any reimporting actually happens.

• Click Re-Import Run above the grid.
• The first page shows:
• Assay Properties: These are fixed properties, like the assay design name, that are read only for all imports using this design.
• Batch Properties: These properties will apply to a set of files uploaded together. For example, here they include specifying how the data is identified (the Participant/Visit setting) and selecting a target study to use if any data is to be copied. Select /Example Project/Research Study (Research Study).

• Click Next.
• On the next page, notice the batch properties are now read only.
• Below them are Run Properties to specify; these could be entered differently for each run in the assay, such as the "Assay ID". If not provided, the name of the file is used, as in our example.
• Here you also provide the data from the assay run, either by uploading a data file (or reusing the one we already uploaded) or entering your own new data.
• Click Show Expected Data Fields. You will see the list of fields expected to be in the spreadsheet. When you design the assay, you specify the name, type, and other properties of expected columns.

• Click Download Spreadsheet Template to generate a blank template spreadsheet. It will be named "data_<datetimestamp>.xls". You could open and populate it in Excel, then upload it to this server as a new run. Save this template file and use it when you get to the Files section below.

• Since we are just reviewing the process right now, click Cancel after reviewing this page.

Understand Assay Designs

Next, review what the assay design itself looks like. You need to be an administrator to perform this step.

• From the Blood Test Data Runs page, select Manage Assay Design > Edit assay design to open it.

The sections correspond to how a user will set properties as they import a run. Click each section heading to open it.

• Assay Properties: Values that do not vary per run or batch.
• Batch Fields: Values set once for each batch of runs.
• Run Fields: Values set per run; in this case none are defined, but as you saw when importing the file, some built in things like "Assay ID" are defined per run.
• Results Fields: This is the heart of the assay design and where you would identify what columns (fields) are expected in the spreadsheet, what their data type is and whether they are required.

• Click the for a row to see or set other properties of each column. With this panel open, click Advanced Settings for even more settings and properties, including things like whether a value can be used as a "measure" in reporting, as shown here for the WBC field. Learn more about using the field editor in this topic: Field Editor.

• Review the contents of this page, but make no changes and click Cancel.
• Return to the main folder page by clicking the Laboratory Data link near the top of the page.

Blood Test Data Results

The assay results are displayed in a web part on the main page. Click the Laboratory Data link if you navigated away, then scroll down. Explore some general features of LabKey data grids using this web part:

Column Header Menus: Each column header has a menu of options to apply to the grid based on the values in that column.

Sort:

• Click the header of the WBC column and select Sort Descending.
• Notice the (sort) icon that appears in the column header.

Filter:

• Click the header of the Participant ID column and select Filter... to open a popup.
• Use the checkboxes to "Choose Values". For this example, uncheck the box for "202".
• The "Choose Values is only available when there are a limited number of distinct values.
• Switching to the "Choose Filters" tab in this popup would let you use filter expressions instead.

• Click OK to apply the filter.
• Notice the (filter) icon shown in the column header. There is also a new entry in the filter panel above the grid - you can clear this filter by clicking the for the "Participant <> 202" filter.

Summary Statistics:

• Click the header of the MCV column and select Summary Statistics... to open a popup.
• Select the statistics you would like to show (the values are previewed in the popup.)
• Premium Feature: Many summary statistics shown are only available with premium editions of LabKey Server. Learn more here.
• In this case, Mean and Standard Deviation might be the most interesting. Click Apply.

• Notice the new row at the bottom of the grid showing the statistics we selected for this column.

The view of the grid now includes a sort, a filter, and a summary statistic.

Notice the message "This grid view has been modified" was added when you added the summary statistic. The grid you are now seeing is not the original default. You have not changed anything about the underlying imported data table, merely how you see it in this grid.

Saving: To save this changed grid view, making it persistent and sharable with others, follow these steps:

• Click Save next to the grid modification message.

• Select Named and give the new grid a name (such as "Grid with Statistics").
• Check the box for "Make this grid view available to all users."
• Click Save.
• Notice that the grid now has Grid With Statistics shown above it.
• To switch between grid views, use the (Grid Views) menu in the grid header. Switch between "default" and "Grid With Statistics" to see the difference.

• Return to the "default" view before proceeding with this walkthrough.

Visualizations and Reports:

There is not enough data in this small spreadsheet to make meaningful visualizations or reports, but you can see how the options work:

• Column Visualizations: Each column header menu has a set of visualizations available that can be displayed directly in the grid view. Options vary based on the data type. For example, from the "WBC" column header menu, choose Box and Whisker.

• Quick Charts: Choose Quick Chart from the header menu of any column to see a quick best guess visualization of the data from that column. The default is typically a box and whisker plot.

• While similar to the column chart above, this chart creates a stand alone chart that is named and saved separately from the grid view.
• It also opens in the "Chart Wizard", described next, which offers many customization options.
• Note that a chart like this is backed by the "live" data in the source table. If you change the underlying data (either by editing or by adding additional rows to the table) the chart will also update automatically.

• Plot Editor: More types of charts and many more configuration options are available using the common plot editor, the "Chart Wizard".
• If you are already viewing a plot, you can change the plot type immediately by clicking Edit and then Chart Type.
• If you navigated elsewhere, you can open the plot editor by returning to the grid view and selecting (Charts) > Create Chart above the grid.
• Select the type of chart you want using the options along the left edge.

Learn more about creating and customizing each chart type in the documentation. You can experiment with this small data set or use the more complex data when Exploring LabKey Studies.

• Bar Charts
• Box Plots
• Line Plots
• Pie Charts
• Scatter Plots

Files

The Files web part lists the single assay run as well as the log file from when it was uploaded.

To explore the abilities of the file browser, we'll create some new assay data to import. You can also click here to download ours if you want your data to match our screenshots without creating your own: data_run2.xls

• Open the template you downloaded earlier. It is an Excel file named "data_<datetimestamp>.xls"
• Enter some values. Some participant ID values to use are 101, 202, 303, 404, 505, and 606, though any integer values will be accepted. You can ignore the VisitID column and enter any dates you like. The WBC and MCV columns are integers, HGB is a double. The more rows of data you enter, the more "new" results you will have available to "analyze."
• Save the spreadsheet with the name "data_run2.xls" if you want to match our instructions.
• Click here to download ours if you want your data to match our screenshots: data_run2.xls

• Return to the Example Project > Laboratory Data folder.
• Drag and drop the "data_run2.xls" file into the Files web part to upload it.

• Select it using the checkbox and click Import Data.
• Scroll down to find the "Import Text or Excel Assay" category.
• Select Use Blood Test Data - the assay design we predefined. Notice you also have the option to create a new "Standard" assay design instead if you wanted to change the way it is imported.
• Click Import.

• You will see the Assay Properties and be able to enter Batch Properties; select "Example Project/Research Study" as the Target Study.
• Click Next.
• On the Run Properties and Data File page, notice your "data_run2.xls" file listed as the Run Data. You don't need to make any changes on this page.
• Click Save and Finish.
• Now you will see the runs grid, with your new run added to our original sample.

• Click the file name to see the data you created.
• Notice the (Grid Views) menu includes the custom grid view "Grid with Statistics" we created earlier - select it.
• Notice the grid also shows a filter "Run = 2" (the specific run number may vary) because you clicked the run name to view only results from that run. Click the for the filter to delete it.
• You now see the combined results from both runs.

• If you saved any visualizations earlier using the original spreadsheet of data, view them now from the (Charts/Reports) menu, and notice they have been updated to include your additional data.

What Else Can I Do?

• Define a New Assay for a data spreadsheet of your own.
• Understand Link to Study, which was done already for our sample spreadsheet

Define a New Assay

LabKey can help you create a new assay design from a spreadsheet of your own. Choose something with a few columns of different types, or simply add a few more columns to the "data_run2.xls" spreadsheet you used earlier. If you have existing instrument data that is in tabular format, you can also use that to complete this walkthrough.

Here we use the name "mydata.xls" to represent your own spreadsheet of data.

• Navigate to the main page of the Laboratory Data folder.
• Drag and drop your "mydata.xls" file to the Files web part.
• Select the file and click Import Data.

• In the popup, choose "Create New Standard Assay Design" and click Import.
• Give your new assay design a Name, such as "MyData".
• Notice the default Location is the current project. Select instead the "Current Folder (Laboratory Data)".
• The Columns for Assay Data section shows the columns imported from your spreadsheet and the data types the server has inferred from the contents of the first few rows of your spreadsheet.
• If you see a column here that you do not want to import, simply uncheck it. If you want to edit column properties, you can do that using the (triangle) button next to the column name.

• You can change the inferred data types as necessary. For example, if you have a column that happens to contain whole number values, the server will infer it is of type "Integer". If you want it to be "Number (Double)" instead, select that type after clicking the (caret) button next to the type. If a column happens to be empty in the first few rows, the server will guess "Text (String)" but you can change that as well.
• Column Mapping below these inferrals is where you would map things like Participant ID and Date information. For instance, if you have a column called "When" that contains the date information, you can tell the server that here. It is not required that you provide mappings at all.

• When you are satisfied with how the server will interpret your spreadsheet, scroll back up and click Begin Import.
• You will be simultaneously creating the assay design (for this and future uses) and importing this single run. Enter batch properties if needed, then click Next.
• Enter run properties if needed, including an Assay ID if you want to use a name other than your file name.
• Click Show Expected Data Fields to review how your data will be structured. Notice that if you didn't provide mappings, new columns will be created for Specimen, Participant, Visit ID, and Date.
• Click Save and Finish.

• You now see your new run in a grid, and the new assay design has been created.

• Click the filename (in the Assay ID column) to see your data.
• Click column headers to sort, filter, or create quick visualizations.
• Select Manage Assay Design > Edit assay design to review the assay design.
• Click Laboratory Data to return to the main folder page.
• Notice your new assay design is listed in the Assay List.

• You can now upload and import additional spreadsheets with the same structure using it. When you import .xls files in the future, your own assay design will be one of the options for importing it.

Understand Link to Study

You may have noticed the Linked to Research Study column in the Blood Test Data Results web part. The sample assay design includes linking data automatically to the Example Project/Research Study folder on your Trial Server.

"Linking" data to a study does not copy or move the data. What is created is a dynamic link so that the assay data can be integrated with other data in the study about the same participants. When data changes in the original container, the "linked" set in the study is also updated.

Click the View Link to Study History link in the Blood Test Data Results web part.

You will see at least one link event from the original import when our sample data was loaded and linked during the startup of your server (shown as being created by the "team lead"). If you followed the above steps and uploaded a second "data_run2.xls" spreadsheet, that will also be listed, created and linked by you.

• Click View Results to see the result rows.
• Click one of the links in the Linked to Research Study column. You see what appears to be the same grid of data, but notice by checking the project menu or looking at the URL that you are now in the "Research Study" folder. You will also see the tabs present in a study folder.

• Click the Clinical and Assay Data tab.
• Under Assay Data you will see the "Blood Test Data" linked dataset. In the topic Exploring LabKey Studies we will explore how that data can now be connected to other participant information.

• Using the project menu, return to the Laboratory Data folder.

More Tutorials

Other tutorials using "Assay" folders that you can run on your LabKey Trial Server:

• Tutorial: Import Experimental / Assay Data
• Tutorial: Lab Workflow Folder

Explore More on your LabKey Trial Server

• Exploring LabKey Collaboration
• Exploring LabKey Studies
• Exploring LabKey Security

• Tour
• Try It Now
• What Else Can I Do?
• More Tutorials

Tour

The "Research Study" folder contains a simple fictional study. There are 5 tabs in the default LabKey study folder; the main landing page is the Overview tab where you will see three web parts:

• 1. Learn About LabKey Study Folders: a panel of descriptive information (not part of a default Study folder)
• 2. Study Data Tools: commonly used tools and settings.
• 3. Study Overview: displays study properties and quick links to study navigation and management options.

A study has five tabs by default. Each encapsulates functions within the study making it easier to find what you need. Click the tab name to navigate to it. Returning to the Research Study folder returns you to the Overview tab.

Participants: View and filter the participant list by cohort; search for information about individuals.

Clinical and Assay Data: Review data and visualizations available; create new joined grids, charts, charts and reports.

The Data Views web part lists several datasets, joined views, and reports and charts.

• Hover over a name to see a preview and some metadata about it.
• Click a name or use the (Details) link to open an item.
• The Access column indicates whether special permissions have been set for an item. Remember that only users granted "Read" access to this folder can see any content here, so seeing "public" means only that it is shared with all folder users. Other options are "private" (only visible to the creator) and custom (shared with specific individuals). See Configure Permissions for Reports & Views for more information.

• Demographic datasets contain a single row per participant for the entire study.
• Clinical datasets can contain many rows per participant, but only one per participant and date combination.
• Assay datasets, typically results from instrument tests, can contain many rows per participant and date.

Try It Now

This example study includes a simplified research scenario. Let's explore some key feature areas on each tab:

• Change Study Properties
• Track Overall Progress
• View Participant Data: Get the picture for a specific study subject.
• Integrate Data Aligned by Participant and Date: Aggregate cross-study information to see broader trends.
• Customize Visualizations and Reports
• Manage Your Study

Display Study Properties

The Study Overview web part shows properties and introductory information about your study.

• Click the Overview tab.
• Click the (pencil) icon on the Study Overview web part.
• Review and change study properties:

• Label: By default, the folder name, here "Research Study," is used. You can edit to make it more descriptive, such as "HIV Study".
• Investigator: Enter your own name to personalize this example.
• Grant/Species: If you enter the grant name and/or species under study, they will be displayed. These fields also enable searches across many study folders to locate related research. Enter a grant name to see how it is shown.
• Description/Render Type: Our example shows some simple HTML formatted text. You can include as much or as little information here as you like. Select a different Render Type to use Markdown, Wiki syntax, or just plain text.
• Protocol Documents: Attach documents if you like - links to download will be included in the web part.
• Timepoint Type: Studies can use several methods of tracking time; this decision is fixed at the time of study creation and cannot be modified here. See Visits and Dates to learn more.
• Start/End Date: See and change the timeframe of your study if necessary. Note that participants can also have individual start dates. Changing the start date for a study in progress should be done with caution.
• Subject Noun: By default, study subjects are called "participants" but you can change that here to "subject," "mouse," "yeast," or whatever noun you choose. Try changing these nouns to "Subject" and "Subjects".
• Subject Column Name: Enter the name of the column in your datasets that contains IDs for your study subjects. You do not need to change this field to match the subject nouns you use.
• When finished, click Submit and see how this information is displayed. Notice the "Participants" tab name is changed.

• Reopen the editor and change the subject noun back to "Participant[s]" to restore the original tab and tool names for this walkthrough.

Track Overall Progress

• Return to the Overview tab if you navigated away.
• Click the Study Navigator link or the small graphic in the Study Overview web part.
• The Study Navigator shows you at a glance how much data is available in your study and when it was collected.
• Rows represent datasets, columns represent timepoints.

• Use the Participant's current cohort dropdown to see collection by cohort.
• Use the checkboxes to switch between seeing counts of participants or rows or both.
• Click the number at the intersection of any row and column to see the data. For example, Lab Results in month two look like this:

View Participant Data

Within a study you can dive deep for all the information about a single participant of interest.

• Click the Participants tab.
• If you know the participant ID, you can use the search box to find their information.
• The Participant List can be quickly filtered using the checkboxes on the left.
• Use the Filter box to narrow the list if you know part of the participant ID.
• Hover over a label to see the group member IDs shown in bold. Click a label to select only that filter option in that category. Here we see there are 8 participants enrolled receiving ARV treatment.

• Click any participant ID to see all the study data about that participant.
• The details of any dataset can be expanded/collapsed using the and icons.

• Click the Search For link above the report to search the entire site for other information about that participant. In this case, you will also see results from the "Laboratory Data" folder in this project.

Integrate Data Aligned by Participant and Date

Study datasets can be combined to give a broad picture of trends within groups over time.

• Click the Clinical and Assay Data tab.
• There are three primary datasets here: Demographics, Physical Exam, and Lab Results.
• Click "Joined View: Physical Exam and Demographics" to open an integrated custom grid.

This grid includes columns from two datasets. To see how it was created:

• Select (Grid Views) > Customize Grid.
• Scroll down on the Available Fields side to Datasets and click the to expand it. Listed are the two other datasets.
• Expand the "Demographics" node by clicking the .

• Scroll down and notice the checked fields like Country and Group Assignment which appear in our joined view.
• Scroll down on the Selected Fields side to see these fields shown.
• You can use checkboxes to add more fields to what is shown in the grid, drag and drop to rearrange columns in your view, and use the and icons for selected fields to edit display titles or delete them from the view.
• Click View Data when finished to see your changes.

• Notice the message indicating you have unsaved changes. Click Revert to discard them.

Customize Visualizations and Reports

In Exploring Laboratory Data we show you how to create charts and plots based on single columns or tables. With the integration of diverse data in a study, you can easily create visualization and reports across many tables, backed by live data. Our example study includes a few examples.

• On the Clinical and Assay Data tab, click Bar Chart: Blood Pressure by Cohort and Treatment.
• Here we see plotted a measure from the "Physical Exam" dataset (Systolic Blood Pressure) against cohort and treatment group data from the "Demographics" dataset.

• Click Edit in the upper right to open the plot for editing.
• Click Chart Type to open the chart wizard.

• Columns on the right can be dragged and dropped into the plot attribute boxes in the middle.
• Select a different plot type using the options to the left. The plot editor will make a best effort to retain plot attribute column selections, though not all attributes apply to each chart type.
• Click Box.
• Notice that the X and Y axis selections are preserved.
• Drag the column "Study: Cohort" to the "Color" box.
• Drag the column "Gender" to the "Shape" box.

• Click Apply to see the new box plot. At present, only the outliers make use of the color and shape selections.

• Click Chart Layout.
• Give the plot a new title, like "Systolic - Box Plot"
• Change Show Points to All.
• Check the box to Jitter Points; otherwise points will be shown in a single column.
• Scroll down to see the controls for plot line and fill colors.
• Choose a different Color Palette from which the point colors will be selected. Shown here, "Dark".

• Click Apply to see the revised box plot.

• Click Save As to save this as a new visualization and preserve the original bar chart.
• Give the new report a name and click Save in the popup.

Manage Your Study

On the Manage tab, you can control many aspects of your study. For example, click Manage Cohorts to review how cohorts were assigned and what the other options are:

• Assignment Mode: Cohorts can be simple (fixed) or advanced, meaning they can change during the study.
• Assignment Type: You can manually assign participants to cohorts, or have assignments made automatically based on a dataset.
• Automatic Participant/Cohort Assignment: Choose the dataset and column to use for assigning cohorts.

What Else Can I Do?

• Manage Dataset Security
• Learn about Protecting PHI
• Publish the Study

Manage Dataset Security

Access to read and edit information in folders is generally controlled by the LabKey role based security model. Within a study, you gain the additional option of dataset level security.

• On the Manage tab, click Manage Security.
• Review the Study Security Type: Datasets can be read-only or editable, under either type of security:
• Basic security: folder permissions determine access to all datasets
• Custom security: folder permissions can be set by dataset for each group with folder access
• Change the type to Custom security with editable datasets. Notice the warning message that this can change who can view and modify data.
• Click Update Type.
• When you change to using 'custom' security, two additional web parts are added to the page:
• Study Security: Use radio buttons to grant access to groups. Click Update after changing. In the screenshot below, we're changing the "Study Team" and "Example Team Members" groups to "Per Dataset" permissions.

• Per Dataset Permissions: Once any group is given per-dataset permissions using the radio buttons, you will have the option to individually set permission levels for each group for each dataset.
• Click Save when finished, or to revert to the configuration before this step, set all for "Example Team Members" to read, and set all for "Study Team" to edit.

Learn About Protecting PHI

When displaying or exporting data, Protected Health Information (PHI) that could be used to identify an individual can be protected in several ways.

Alternate Participant IDs and Aliases

If you want to share data without revealing participant IDs, you can use a system of alternates or aliases so that you can still show a consistent ID for any set of data, but it is not the actual participant ID.

Mark Data as PHI

There are four levels to consider regarding protection of PHI, based on how much information a user will be authorized to see. For PHI protection to be enforced, you must BOTH mark data as PHI and implement viewing and export restrictions on your project. Data in columns can be marked as:

• Restricted: The most sensitive information not shared with unauthorized users, even those authorized for Full PHI.
• Full PHI: Only shared when users have permission to see all PHI. The user can see everything except restricted information.
• Limited PHI: Some information that is less sensitive can be visible here.
• Not PHI: All readers can see this information.

To mark a column's PHI level:

• On the Clinical and Assay Data tab, open the dataset of interest. Here we use the Demographics dataset.
• Above the grid, click Manage.

• Click Edit Definition.

• Click the Fields section to open it.
• Find the field of interest, here "Status of Infection."
• Click the to expand it.
• Click Advanced Settings.
• In the popup, you will see the current/default PHI Level: "Not PHI".
• Make another selection from the dropdown to change; in this example, we choose "Full PHI".

• Click Apply.
• Adjust PHI levels for as many fields as necessary.
• Scroll down and click Save.
• Click View Data to return to the dataset.

Publish the Study

Publishing a LabKey study allows you to select all or part of your results and create a new published version.

• Click the Manage tab.
• Click Publish Study (at the bottom).
• The Publish Study Wizard will guide you through selecting what to publish.
• By default, the new study will be called "New Study" and placed in a subdirectory of the current study folder.
• Select the participants, datasets, timepoints, and other objects to include. On the Datasets step, you can elect to have the study refresh data if you like, either manually or nightly.
• The last page of the publish wizard offers Publish Options including obscuring information that could identify individuals and opting for the level of PHI you want to publish.
• Click Finish at the end of the wizard to create the new study folder with the selected information.

Explore the new study, now available on the projects menu.

More Tutorials

Other tutorials using "Study" folders that you can run on your LabKey Trial Server:

• Tutorial: Longitudinal Studies
• Tutorial: Set Up a New Study

Explore More on your LabKey Trial Server

• Exploring LabKey Collaboration
• Exploring Laboratory Data
• Exploring LabKey Security

• Tour
• Try It Now
• What Else Can I Do?
• Learn More

Tour

Our Example Project contains three subfolders, intended for different groups of users:

• Collaboration Workspace: The entire team communicates here and shares project-wide information.
• Laboratory Data: A lab team performs tests and uploads data here, perhaps performing basic quality control.
• Research Study: A team of researchers is exploring a hypothesis about HIV.

Project Groups

Groups at the project level allow you to subdivide your project team into functional subgroups and grant permissions on resources to the group as a whole in each folder and subfolder. While it is possible to assign permissions individually to each user, it can become unwieldy to maintain in a larger system.

• Navigate to the Example Project. You can be in any subfolder.
• Select > Folder > Permissions.
• Click the tab Project Groups.

• There are 5 predefined project groups. See at a glance how many members are in each.
• Click the name to see the membership. Click Example Team Members and see the list of all our example users.

• Click Done in the popup.
• Click the Lab Team to see that the two members are the team lead and the lab technician.
• Click the Study Team to see that the two members are the team lead and the study researcher.

Next we'll review how these groups are assigned different permissions within the project's subfolders.

Permission Roles

Permission roles grant different types of access to a resource. Read, Edit, and Admin are typical examples; there are many more permission roles available in LabKey Server. Learn more here.

• If you navigated away after the previous section, select > Folder > Permissions.
• Click the Permissions tab.
• In the left column list of folders, you will see the entire project hierarchy. The folder you are viewing is shown in bold. Click Example Project to see the permissions in the project itself.

• The "Admin Team" is both project and folder administrator, and the "Example Team Members" group are Editors in the project container.

• Click Collaboration Workspace and notice that the "Example Team Members" are editors here, too.
• Click Laboratory Data. In this folder, the "Lab Team" group has editor permissions, and the "Example Team Members" group only has reader permission.
• Note that when users are members of multiple groups, like in the case of our sample "lab_technician@local.test", they hold the sum of permissions granted through the groups they belong to. This lab_technician has read access with example team membership, but also editor access because of lab team membership, so that user will be able to edit contents here.
• To see the user membership of any group, click the group name in the permissions UI.
• To see all permissions granted to a given user, click the Permissions link in the group membership popup.

• This example lab technician can edit content in the example project, the collaboration workspace folder, and the laboratory data folder. They can read but not edit content in the research study folder.

• Close any popups, then click Cancel to exit the permissions editing UI.

Try It Now

• Impersonate a User
• Impersonate a Group
• Audit Logging

Impersonation

Using impersonation, an admin can see what another user would be able to see and do on the server.

• Navigate to the Example Project/Research Study folder using the project menu.
• Notice that as yourself, the application admin on this server, you can see a (pencil) icon in the header of the Study Overview web part. You would click it to edit study properties. You also see the Manage tab.
• Select (User) > Impersonate > User.

• Select "lab_technician@local.test" from the dropdown and click Impersonate.
• Now you are seeing the content as the lab technician would: with permission to read but not edit, as we saw when reviewing permissions above.
• Notice the (pencil) icon and Manage tabs are no longer visible. You also no longer have some of the original options on the menu in the header.
• Click Stop Impersonating to return to your own "identity".

Impersonate a Group

Impersonation of a group can help you better understand permissions and access. In particular, when configuring access and deciding what groups should include which users, group impersonation can be very helpful.

• Navigate to the Example Project/Research Study folder, if you navigated away.
• Select (User) > Impersonate > Group.
• Choose the "Study Team" and click Impersonate.
• Hover over the project menu and notice that the only folder in "Example Project" that members of the "Study Team" can read is this "Research Study" folder.

• Click Stop Impersonating.
• To see an error, select (User) > Impersonate > Group, choose the "Lab Team" and click Impersonate. This group does not have access to this folder, so the error "User does not have permission to perform this operation" is shown.
• Click Stop Impersonating.

Impersonate a Role

You can also directly impersonate roles like "Reader" and "Submitter" to see what access those roles provide.

To learn more about impersonation, see Test Security Settings by Impersonation.

Audit Logging

Actions on LabKey Server are extensively logged for audit and security review purposes. Impersonation is among the events logged. Before you complete this step, be sure you have stopped impersonating.

• Select > Site > Admin Console.
• Under Management, click Audit Log.
• Using the pulldown, select User Events.

• You will see the impersonation events you just performed. Notice that for impersonations of individual users, these are paired events - both the action taken by the user to impersonate, and the action performed "on" the user who was impersonated.
• Explore other audit logs to see other kinds of events tracked by the server.

What Else Can I Do?

The Security Tutorial walks you through more security features. You can create a new project for tutorials on your trial server, then run the security tutorial there.

• Tutorial: Security

Learn More

• Security
• Compliance

Explore More on your LabKey Trial Server

• Exploring LabKey Collaboration
• Exploring Laboratory Data
• Exploring LabKey Studies

• Create a Project
• Add Some Content
• Share With Others
• What Else Can I Do?

Create a Project

To open the project creation wizard you can:

• Click the "Create" button on the Trial Server home page.
• OR: Select > Site > Create Project.
• OR: Click the "Create Project" icon at the bottom of the project menu as shown:

The project creation wizard includes three steps.

1. Give the project a Name and choose the folder type.
2. Configure users and permissions (or accept the defaults and change them later).
3. Choose optional project settings (or configure them later).

• Select > Site > Create Project.
• Step 1: Create Project:
• Enter the Name: "Tutorials". Project names must be unique on the server.
• Leave the box checked to use this as the display title. If you unchecked it, you could enter a different display title.
• Folder Type: Leave the default selection of "Collaboration". Other folder types available on your server are listed; hover to learn more about any type. Click Folder Help for the list of folder types available in a full LabKey installation.

• Click Next.

• Step 2: Users / Permissions: Choose the initial security configuration. As the admin, you can also change it later.
• The default option "My User Only" lets you set up the project before inviting additional users.
• The other option "Copy From Existing Project" is a helpful shortcut when creating new projects to match an existing one.
• Leave "My User Only" selected and click Next.

• Step 3: Project Settings:
• On a LabKey Trial Server, you cannot Choose File Location, so this option is grayed out.
• Advanced Settings are listed here for convenience, but you do not need to set anything here.
• Simply click Finish to create your new project.

• You'll now see the landing page of your new project and can start adding content.

Add Some Content

Let's customize the landing page and make it easier to use.

• In the Wiki web part, click Create a new wiki page to display in this web part.
• Leave the Name as "default"
• Enter the Title "Welcome"
• In the body field, enter: "Feel free to make a new subfolder and run a tutorial in it."
• Click Save & Close.

• Customize the page layout:
• Select > Page Admin Mode.
• In the web part header menu for your new "Welcome" wiki, select (triangle) > Move Up.
• In the web part header menu for both "Messages" and "Pages", select (triangle) > Remove From Page.

• Click Exit Admin Mode.

You can now use this project as the base for tutorials.

Subfolders Web Part

Most LabKey tutorials begin with creation of a new subfolder of a specific type, which you can add by clicking Create New Subfolder here. There are no subfolders to display yet, but once you add a few, this web part will look something like this, giving you a one click way to return to a tutorial folder later.

Tutorials for your LabKey Trial Server

Try one of these:

• Tutorial: Security
• Tutorial: File Repository
• Tutorial: Import Experimental / Assay Data
• Tutorial: Longitudinal Studies

Share With Others

Now that you have created a new project and learned more about LabKey Server, consider sharing with a colleague. To invite someone to explore the Trial Server you created, simply add them as a new user:

What Else Can I Do?

Change the Color Scheme

The color scheme, or theme, is a good way to customize the look of a given project. To see what the other themes look like, see Web Site Theme.

To change what your Tutorials project looks like:

You can also change the theme for the site as a whole by selecting > Site > Site Console. Click Settings, then under Configuration, choose Look and Feel Settings. The same options are available for the Theme setting.

What's Next?

You can create more new projects and folders on your LabKey Trial Server to mock up how it might work for your specific solution. Many features available in a full LabKey installation are not shown in the trial version; you can learn more in our documentation.

Feel free to contact us and we can help you determine if LabKey is the right fit for your research.

Related Topics

• Explore LabKey Server with a trial in LabKey Cloud
• Features in LabKey Server Premium Editions

Learn the Basics

Try these step by step topics to get started.

• Introduction to LabKey Server
• Exploring LabKey Collaboration
• Exploring Laboratory Data
• Exploring LabKey Studies
• Exploring LabKey Security
• Exploring Project Creation

Explore More...

Premium Features

Your 30 day trial includes several premium features. See them in action prior to subscribing:

• Quality Control Trend Reporting
• Extract Transform Load (ETL)
• Compliance Features
• File Watcher

Data Analysis Options

Try built-in data analysis options, including:

• Tutorial: NAb Assay
• Tutorial: ELISA Assay
• Flow Cytometry
• Proteomics
• Panorama: Targeted Mass Spectrometry

Development with LabKey Server

• Using R with LabKey
• Using LabKey SQL
• JavaScript API

LabKey provides a customizable framework for longitudinal study data. A study tracks information about subjects over time. You can explore a read-only example here:

• Example Longitudinal Study
• Learn about solutions for longitudinal studies

• Plan Your Study Framework
• Create Your Study
• Upload Your Data

Plan Your Study Framework

You may already have data you plan to upload. If not, we will provide example files to get you started.

Identify your Study Subjects

The subjects being studied, "participants" by default, can be humans, animals, trees, cells, or anything else you want to track.

Look at a dataset you plan to use. How are subjects under study identified. What column holds identifying information?

Decide How To Track Time

Time Based: Some studies track time using dates. The date of each data collection is entered and the study is configured to break these into month-long timepoints, labeled as "Month 1", "Month 2" etc.

Visit Based: You can also track time in a visit-by-visit manner. If the elapsed time between events is not relevant but you have a fixed sequence of visit events, a visit-based study may be appropriate. Visits are identified by sequence numbers.

Continuous: A continuous study is used when there is no strong concept of visits or fixed buckets of time. Data is entered and tracked by date without using timepoints.

Security

Identify your security requirements and how you plan to use the data in your study. Who will need access to what data. Will you want to be able to assign access 'per dataset' or is folder level security sufficient?

When you select your Security Mode, use basic if folder-level is sufficient and "custom" otherwise. Decide if you want datasets to be editable by any non-admins after import. Learn more about study security in this topic: Manage Study Security

Create Your Study

• Once your trial server has been created, you will receive an email notification with a direct link to it.
• Click the Create Project button on the home page.
• Enter Name "Tutorials", leave the default folder type and click Next, then Next and then Finish to create the new project with all the default settings.
• In the new project, click Create New Subfolder.
• Enter the Name you want. In our example, it is named "My New Study".
• Select the folder type Study and click Next.
• Click Finish to create the folder.
• Click Create Study.

• Under Look and Feel Properties:
• Study Label: Notice your folder name has the word "Study" added; you can edit to remove redundancy here if you like.
• Subject Noun (Singular and Plural): If you want to use a word other than "Participant/Participants" in the user interface, enter other nouns here.
• Subject Column Name: Look at the heading in your dataset for the column containing identifiers. Edit this field to match that column.

• Under Visit/Timepoint Tracking:
• Select the type of time tracking you will use. Dates, Assigned Visits, or Continuous.
• If needed for your selection, enter Start Date and/or Default Timepoint Duration.

• Under Security:
• Select whether to use basic or custom security and whether to make datasets editable or read-only.
• To maximize the configurability of this study, choose Custom security with editable datasets.

• Click Create Study.
• You will now be on the Manage tab of your own new study. This tab exists in the read-only exploration study we provided, but you cannot see it there. It is visible only to administrators.

Upload Your Data

Add Demographic Data

Begin with your demographic dataset. Every study is required to have one, and it contains one row per study participant (or subject). It does not have to be named "Demographics.xls", and you do not have to name your dataset "Demographics"; that is just the convention used in LabKey examples and tutorials.

You can now click the Participants/Subjects tab in your study and see the list gleaned from your spreadsheet. Each participant has a built in participant report that will contain (so far) their demographic data.

Add More Datasets

Repeat the above process for the other data from your study, except under Data Row Uniqueness, non-demographic datasets will use the default Participants and Visits. For example, you might have some sort of Lab Results for a set of subjects. Each row in a dataset like this will have one row per participant and visit/date combination. This enables studying results over time.

Once you have uploaded all your data, click the Clinical and Assay Data tab to see the list of datasets.

Join your Data

With only two datasets, one demographic, you can begin to integrate your data.

Learn more about creating joined grids in this topic: Customize Grid Views

Related Topics

• Tutorial: Set Up a New Study
• Study Administrator Guide

Trial instances contain some example data to help you explore using LabKey Biologics for your own research data. Your trial lasts 30 days and we're ready to help you understand how LabKey Biologics can work for you.

Biologics Tours

Documentation

• Biologics LIMS

Tutorials provide a "hands on" introduction to the core features of LabKey Server, giving step-by-step instructions for building solutions to common problems. They are listed roughly from simple to more complex, and you can pick and choose only those that interest you.

In order to run any tutorial, you will need:

• An account on a running LabKey Server.
• A project where you can create a new folder. If you don't have one, contact us about setting up a free trial .
• Familiarity with some basics of navigating and using LabKey Server.

If you are using a free trial of LabKey Server, this video will show you around:

This icon indicates whether the tutorial can be completed on a trial server.

New User Tutorials

Title Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Description Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Works on Cloud Trial Server? Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Data Grid Tutorial Take a quick tour of data grids and visualizations. No trial server necessary.   Tutorial: Security Learn how to organize and secure your data using LabKey Server. Tutorial: File Repository Manage, search, and share file resources. Get Started with Collaboration Tools Learn to use messages, wikis, and issue trackers. Tutorial: Lists Work with data tables.

Study Tutorials

Title Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Description Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Works on Cloud Trial Server? Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Tutorial: Longitudinal Studies Analyze longitudinal study data. Tutorial: Set Up a New Study Design a new longitudinal study.

Assay Tutorials

Title Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Description Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Works on Cloud Trial Server? Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Tutorial: Import Experimental / Assay Data Import, manage, and analyze assay data. Tutorial: NAb Assay Work with NAb experiment data from 96-well or 384-well plates Tutorial: ELISA Assay Import and analyze ELISA experiment data. Tutorial: ELISpot Assay Tutorial Import and analyze ELISpot experiment data. Discovery Proteomics Tutorial Storage and analysis for high-throughput proteomics and tandem mass spec experiments. Tutorial: Import a Flow Workspace Learn about using LabKey for management, analysis, and high-throughput processing of flow data. Tutorial: Set Flow Background Learn about setting metadata and using backgrounds with flow data. Luminex Assay Tutorial Level I Manage, quality control, analyze, share, integrate and export Luminex immunoassay results.   Luminex Assay Tutorial Level II Use advanced features for quality control and analysis.

Developer Tutorials

Title Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Description Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Works on Cloud Trial Server? Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart LabKey SQL Tutorial   Tutorial: Create Applications with the JavaScript API   Python APIs Use Python to query and update data on the server.   Tutorial: Use URLs to Pass Data and Filter Grids   Tutorial: Visualizations in JavaScript   Adding a Report to a Data Grid with JavaScript     Tutorial: Extract-Transform-Load (ETL) Create and use a simple ETL.   Tutorial: Hello World Module     Tutorial: File Based Module Resources     Tutorial: Hello World Java Tutorial

Biologics Tutorials

Title Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Works on Cloud Trial Server? Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Works on a Biologics Trial Server? Sort Ascending Sort Descending Clear Sort Filter... Clear Filter Remove Column Summary Statistics... Bar Chart Pie Chart Quick Chart Biologics Tutorial: Navigate and Search the Registry   Biologics Tutorial: Add Sequences to the Registry   Biologics Tutorial: Register Samples and Experiments   Biologics Tutorial: Work with Recipes and Batches   Biologics Tutorial: Create a New Biologics Project

LabKey Trial Server

To run the LabKey Tutorials, you need three things:

1. An account on a running LabKey Server instance. After contacting us about your specific research needs and goals, we may set up a LabKey Trial Server for you:

• Contact us about getting started with LabKey Server

• LabKey Server trial in LabKey Cloud

Finished

Congratulations, you can now begin running tutorials in this workspace on your trial server.

I'm Ready for the Tutorial List

To run any LabKey Tutorial you need:

1. An account on a running LabKey Server instance.
2. A tutorial workspace project on that server where you are an administrator and can create new folders.
3. A basic familiarity with navigation, folder creation, and utilities like web parts.

• Existing Installations
• Full Local Installation

Existing Installations

1. & 2. If your organization is already using LabKey Server, contact your administrator about obtaining access as an administrator to a project or folder to use. For example, they might create and assign you a "Tutorials-username" project or subfolder. They will provide you the account information for signing in, and the URL of the location to use.

3. Learn the navigation and UI basics in this topic:

• Navigation and UI Basics

Full Local Installation

1. If none of the above are suitable, you may need to complete a full manual installation of LabKey Server. Detailed instructions are provided here:

• Install LabKey

3. Learn the navigation and UI basics in this topic:

• Navigation and UI Basics

Finished

Congratulations, you can now log in, navigate to your workspace, and begin running tutorials.

Learn More

I'm Ready for the Tutorial List

Welcome to LabKey Server!

This topic helps you get started using LabKey Server, understanding the basics of navigation and the user interface.

• Projects and Folders
• Tabs
• Web Parts
• Header Menus and URLs
• Security Model

Projects and Folders

The project and folder hierarchy is like a directory tree and forms the basic organizing structure inside LabKey Server. Everything you create or configure in LabKey Server is located in some folder. Projects are the top level folders, with all the same behavior, plus some additional configuration options; they typically represent a separate team or research effort.

The Home project is a special project. It is the default landing page when users log in and cannot be deleted. You can customize the content here to suit your needs. To return to the home project at any time, click the LabKey logo in the upper left corner.

The project menu is on the left end of the menu bar and includes the display name of the current project.

Hover over the project menu to see the available projects, and folders within them. Click any project or folder name to navigate there.

Any project or folder with subfolders will show / buttons for expanding and contracting the list shown. If you are in a subfolder, there will be a clickable 'breadcrumb' trail at the top of the menu for quickly moving up the hierarchy. The menu will scroll when there are enough items, with the current location visible and expanded by default.

The project menu always displays the name of the current project, even when you are in a folder or subfolder. A link with the Folder Name is shown near the top of page views like the following, offering easy one click return to the main page of the folder.

For more about projects, folders, and navigation, see Project and Folder Basics.

Tabs

Using tabs within a folder can give you new "pages" of user interface to help organize content. LabKey study folders use tabs as shown here:

When your browser window is too narrow to display tabs arrayed across the screen, they will be collapsed into a pulldown menu showing the current tab name and a (chevron). Click the name of the tab on this menu to navigate to it.

For more about adding and customizing tabs, see Use Tabs.

Web Parts

Web parts are user interface panels that can be shown on any folder page or tab. Each web part provides some type of interaction for users with underlying data or other content.

There is a main "wide" column on the left and narrower column on the right. Each column supports a different set of web parts. By combining and reordering these web parts, an administrator can tailor the layout to the needs of the users.

To learn more, see Add Web Parts and Manage Web Parts. For a list of the types of web parts available in a full installation of LabKey Server, see the Web Part Inventory.

Header Menus and URLs

In the upper right, icon menus offer:

• (Search): Click to open a site-wide search box
• (Admin/Settings): Shown only to Admins: Administrative options available to users granted such access. See Admin Console for details about options available.
• (User): Login and security options; help links to documentation and support options.

Watch the URL at the top of the page as you navigate LabKey Server and explore features on your server. Many elements are encoded in the URL and programmatic access via building URLs is possible with APIs. Learn more here: LabKey URLs.

Security Model

LabKey Server has a group and role-based security model. Whether an individual is authorized to see a resource or perform an action is checked dynamically based on the groups they belong to and roles (permissions) granted to them. Learn more here: Security.

What's Next?

• Set Up for Tutorials: Non-Trial
• Tutorials

LabKey Server Editions

• Community Edition: Free to download and use forever. Best suited for technical enthusiasts and evaluators in non-mission-critical environments. LabKey provides documentation and you can request help using the support menu link on this page.
• Premium Editions: Paid subscriptions that provide additional functionality and resources to help teams optimize workflows, manage complex projects, and explore multi-dimensional data. Premium Editions also include professional support services for the long-term success of your informatics solutions.

Topics

• Training
• Premium Resource: Training Materials
• LabKey Support Portals
• Premium Resources
• Biologics LIMS
• LabKey LIMS
• Sample Manager

User and Administrator Training

LabKey's user and administrator training course, LabKey Fundamentals, is included with Premium Editions of LabKey Server. It provides an introduction to the following topics:

• LabKey Server Basics: Explains the basic anatomy/architecture of the server and its moving parts. It outlines the basic structures of folders and data containers, and the modules that process requests and craft responses. Best practices for configuring folders is included. The role of Administrators is also described.
• Security: Describes LabKey Server's role-based security model--and how to use it to protect your data resources. General folder-level security is described, as well as special security topics, such as dataset-level security and Protected Health Information (PHI) features. Practical security information is provided, such as how to set up user accounts, assigning groups and roles, best practices, and testing security configurations using impersonation.
• Collaboration: Explains how to use the Wiki, Issues, and Messages modules. Branding and controlling the look-and-feel of your server are also covered.
• Data Storage: Files and Database: Explains the two basic ways that LabKey Server can hold data: (1) as files and (2) as records in a database. Topics include: full-text search, converting tabular data files into database tables, special features of the LabKey database (such as 'lookups'), the role of SQL queries, adding other databases as external data sources.
• Instrument Data: Explains how LabKey Server models and captures instrument-derived data, including how to create a new assay "design" from scratch, or how to use a prepared assay design. Special assay topics are covered, such as transform scripts, creating new assay design templates ("types") from simple configuration files, and how to replace the default assay user interface.
• Clinical/Research Study Data Management: Explains how to integrate heterogeneous data, such as instrument, clinical, and demographic data, especially in the context of longitudinal/cohort studies.
• Reports: Explains the various ways to craft reports on your data, including R reports, JavaScript reports, and built-in visualizations, such as Time Charts, Box Plots, and Scatter Plots.
• Samples: Explains how to manage sample data and link it to assay and clinical data.
• Advanced Topics: A high-level overview of how to extend LabKey Server. The Starter Edition includes support for users writing custom SQL, R scripts, and ETLs. The Professional Edition provides support for users extending LabKey Server with JavaScript/HTML client applications, user-created file modules.

Developer Training

LabKey's developer training is included in the Professional and Enterprise Editions of LabKey Server. It is tailored to your project's specific needs and can cover:

• Server-to-server integrations
• Client APIs
• Assay transform scripts
• Remote pipeline processing servers
• Custom LabKey-based pipelines
• Module development assistance

Related Topics

• Tutorials

• LabKey Server Editions

Introduction

• Navigate the Server
• Data Basics

Solutions

• Assay Data Integration
• Longitudinal Study Data Management
• Clinical Document Abstraction
• Panorama - Targeted Mass Spectrometry

• What is LabKey Server?
• How Does it Work?
• The Basic Workflow
• Additional Topics

What is LabKey Server?

LabKey Server's features can be grouped into three main areas:

1. Data Repository

LabKey Server lets you bring data together from multiple sources into one repository. These sources can be physically separated in different systems, such as data in Excel spreadsheets, different databases, REDCap, etc. Or the data sources can be separated "morphologically", having different shapes. For example, patient questionnaires, instrument-derived assay data, medical histories, and sample inventories all have different data shapes, with different columns names and different data types. LabKey Server can bring all of this data together to form one integrated whole that you can browse and analyze together.

2. Data Showcase

LabKey Server lets you securely present and highlight data over the web. You can present different profiles of your data to different audiences. One profile can be shown to the general public with no restrictions, while another profile can be privately shared with selected individual colleagues. LabKey Server lets you collaborate with geographically separated teams, or with your own internal team members. In short, LabKey Server lets you create different relationships between data and audiences, where some data is for general viewing, other data is for peer review, and yet other data is for group editing and development.

3. Electronic Laboratory

LabKey Server provides many options for analyzing and inquiring into data. Like a physical lab that inquires into materials and natural systems, LabKey Server makes data itself the object of inquiry. This side of LabKey Server helps you craft reports and visualizations, confirm hypotheses, and generally provide new insights into your data, insights that wouldn't be possible when the data is separated in different systems and invisible to other collaborators.

The LabKey Server Platform

LabKey Server is a software platform, as opposed to an application. Applications have fixed use cases targeted on a relatively narrow set of problems. As a platform, LabKey Server is different: it has no fixed use cases, instead it provides a broad range of tools that you configure to build your own solutions. In this respect, LabKey Server is more like a car parts warehouse and not like any particular car. Building solutions with LabKey Server is like building new cars using the car parts provided. To build new solutions you assemble and connect different panels and analytic tools to create data dashboards and workflows.

The following illustration shows how LabKey Server takes in different varieties of data, transforms into reports and insights, and presents them to different audiences.

How Does LabKey Server Work?

LabKey Server is a web server, and all web servers are request-response machines: they take in requests over the web (typically as URLs through a web browser) and then craft responses which are displayed to the user.

Modules

Modules are the main functionaries in the server. Modules interpret requests, craft responses, contain all of the web parts, and application logic. The responses can take many different forms:

• a web page in a browser
• an interactive grid of data
• a report or visualization of underlying data
• a file download
• a long-running calculation or algorithm

• External Schemas and Data Sources

The illustration below shows the relationships between web browsers, LabKey Server, and the underlying databases. The modules shown are not a complete set; many other modules are included in LabKey Server.

User Interface

You configure your own user interface by adding panels, aka "web parts", each with a specific purpose in mind. Some example web parts:

• The Wiki web part displays text and images to explain your research goals and provide context for your audience. (The topic you are reading right now is displayed in a Wiki web part.)
• The Files web part provides an area to upload, download, and share files will colleagues.
• The Query web part displays interactive grids of data.
• The Report web part displays the results of an R or JS based visualization.

The illustration below shows a data dashboard formed from tabs and web parts.

Folders and Projects

Folders are the "blank canvases" of LabKey Server, the workspaces where you organize dashboards and web parts. Folders are also important in terms of securing your data, since you grant access to audience members on a folder-by-folder basis. Projects are top level folders: they function like folders, but have a wider scope. Projects also form the center of configuration inside the server, since any setting made inside a project cascades into the sub-folders by default.

Security

LabKey uses "role-based" security to control who has access to data. You assign roles, or "powers", to each user who visits your server. Their role determines how much they can see and do with the data. The available roles include: Administrator (they can see and do everything), Editors, Readers, Submitters, and others. Security is very flexible in LabKey Server. Any security configuration you can imagine can be realized: whether you want only a few select individual to see your data, or if you want the whole world to see your data.

The server also has extensive audit logs built. The audit logs record:

• Who has logged in and when
• Changes to a data record
• Queries performed against the database
• Server configuration changes
• File upload and dowload events
• And many other activities

The Basic Workflow: From Data Import to Reports

To build solutions with LabKey Server, follow this basic workflow: import or synchronize your data, apply analysis tools and build reports on top of the data, and finally share your results with different audiences. Along the way you will add different web parts and modules as needed. To learn the basic steps, start with the tutorials, which provide step-by-step instructions for using the basic building blocks available in the server.

Ready to See More?

• You don't need to download or install anything to try a few basic features right now: Try it Now: Data Grids.
• Learn about navigating the server: Navigate the Server
• Learn about the user interface: Build User Interface
• Request a customized demo

• Main Header Menus
• Product Selection Menu (Premium Feature)
• Project and Folder Menu
• Navigation
• Context Sensitive Help

Main Header Menus

The project menu is on the left end of the menu bar and includes the display name of the current project.

In the upper right, icon menus offer:

• - Search: Click to open a site-wide search box
• - Product Selection: (Premium Feature) Click to switch between products available on your server.
• - Admin/Settings: Administrative options available to users granted such access.
• - User: Login and security options; context-sensitive help.

Product Selection Menu (Premium Feature)

LabKey offers several products, all of which may be integrated on a single Premium Edition of LabKey Server. When more than one application is installed on your server, you can use the menu to switch between them in a given container.

Learn more in this topic: Product Selection Menu

Project and Folder Menu

Hover over the project menu to see the available projects and folders within them. Note that only locations in which you have at least "Read" access are shown. If you have access to a subfolder, but not to the parent, the name of the parent folder or project will still be included on the menu for reference.

Any project or folder with subfolders will show and buttons for expanding and contracting the list shown. The menu will scroll when there are enough items, and the current location will be visible and expanded by default.

• - Permalink URL: Click for a permalink to the current location.
• Administrators have additional options shown in the bottom row of this menu.

Navigation

Click the name of any project or folder in the menu to navigate to that location. When you are in a folder or subfolder, you will see a "breadcrumb" path at the top of the projects menu, making it easy to step back up one or more levels. Note that if you have access to a subfolder, but not to one or more of its parent folders, the parent folder(s) will be still be displayed in the menu (and on the breadcrumb path) but those locations will not be clickable links.

Notice that from within a folder or subfolder, the project menu still displays the name of the project. A link with the Folder Name is shown next to the title offering easy one click return to the main page of the folder.

Context Sensitive Help

Click the icon in the upper right to open the user menu. Options for help include:

• Support: Options for asking questions or learning more about whichever LabKey product you are using.
• LabKey Documentation: Navigates directly to the relevant documentation for the product you are using. In some cases, you'll see specific documentation to the feature area you are viewing when you click.

Related Topics

• Project and Folder Basics - Administrator options for projects and folders
• Product Selection Menu
• Add Custom Menus

Topics

• LabKey Data Structures
• Preparing Data for Import
• Field Editor
• Data Grids
• Reports and Charts
• Visualizations
• Lists
• R Reports
• Premium RStudio Integration
• SQL Queries
• Linked Schemas and Tables
• Controlling Data Scope
• Data Quality Control
• Search

A scatter plot visualization of the same data:

Related Topics

• External Schemas and Data Sources
• System Integration: Instruments and Software

LabKey Server offers a wide variety of ways to store and organize data. Different data structure types offer specific features, which make them more or less suited for specific scenarios. You can think of these data structures as "table types", each designed to capture a different kind of research data.

This topic reviews the data structures available within LabKey Server, and offers guidance for choosing the appropriate structure for storing your data.

• Where Should My Data Go?
• Universal Table Features
• Lists
• Assays
• Datasets
• Custom Queries
• Sample Types
• DataClasses
• Domains
• Domain (Data Structure) Names
• File Import Column Names (aka Parent/Source aliases)
• Field Names with Special Characters
• Vocabulary Domain
• External Schemas
• Linked Schemas

Where Should My Data Go?

The primary deciding factors when selecting a data structure will be the nature of the data being stored and how it will be used. Information about lab samples should likely be stored as a sample type. Information about participants/subjects/animals over time should be stored as datasets in a study folder. Less structured data may import into LabKey Server faster than highly constrained data, but integration may be more difficult. If you do not require extensive data integration or specialized tools, a more lightweight data structure, such as a list, may suit your needs.

The types of LabKey Server data structures appropriate for your work depend on the research scenarios you wish to support. As a few examples:

• Management of Simple Tabular Data. Lists are a quick, flexible way to manage ordinary tables of data, such as lists of reagents.
• Integration of Data by Time and Participant for Analysis. Study datasets support the collection, storage, integration, and analysis of information about participants or subjects over time.
• Analysis of Complex Instrument Data. Assays help you to describe complex data received from instruments, generate standardized forms for data collection, and query, analyze and visualize collected data.

Universal Table Features

Most LabKey data structures support the following features:

• Interactive, Online Grids
• Data Validation
• Visualizations
• SQL Queries
• Lookup Fields

Lists

Lists are the simplest and least constrained data type. They are generic, in the sense that the server does not make any assumptions about the kind of data they contain. Lists are not entirely freeform; they are still tabular data and have primary keys, but they do not require participant IDs or time/visit information. There are many ways to visualize and integrate list data, but some specific applications will require additional constraints.

Lists data can be imported in bulk as part of a TSV, or as part of a folder, study, or list archive. Lists also allow row-level insert/update/delete.

Lists are scoped to a single folder, and its child workbooks (if any).

Assays

Assays capture data from individual experiment runs, which usually correspond to an output file from some sort of instrument. Assays have an inherent batch-run-results hierarchy. They are more structured than lists, and support a variety of specialized structures to fit specific applications. Participant IDs and time information are required.

Specific assay types are available, which correspond to particular instruments and offer defaults specific to use of the given assay instrument. Results schema can range from a single, fixed table to many interrelated tables. All assay types allow administrators to configure fields at the run and batch level. Some assay types allow further customization at other levels. For instance, the Luminex assay type allows admins to customize fields at the analyte level and the results level. There is also a general purpose assay type, which allows administrators to completely customize the set of result fields.

Usually assay data is imported from a single data file at a time, into a corresponding run. Some assay types allow for API import as well, or have customized multi-file import pathways. Assays result data may also be integrated into a study by aligning participant and time information, or by sample id.

Assay designs are scoped to the container in which they are defined. To share assay designs among folders or subfolders, define them in the parent folder or project, or to make them available site-wide, define them in the Shared project. Run and result data can be stored in any folder in which the design is in scope.

Datasets

Clinical Datasets are designed to capture the variable characteristics of an organism over time, like blood pressure, mood, weight, and cholesterol levels. Anything you measure at multiple points in time will fit well in a Clinical Dataset.

Datasets are always part of a study. They have two required fields:

• ParticipantId (this name may vary) - Holds the unique identifier for the study subject.
• Date or Visit (the name may vary) - Either a calendar date or a number.

• Demographic: Zero or one row for each subject. For example, each participant has only one enrollment date.
• “Standard”/"Clinical": Can have multiple rows per subject, but zero or one row for each subject/timepoint combination. For example, each participant has exactly one weight measurement at each visit.
• “Extra key”/"Assay": can have multiple rows for each subject/timepoint combination, but have an additional field providing uniqueness of the subject/timepoint/arbitrary field combination. For example, many tests might be run each a blood sample collected for each participant at each visit.

A dataset can be backed by assay data that has been copied to the study. Behind the scenes, this consists of a dataset with rows that contain the primary key (typically the participant ID) of the assay result data, which is looked up dynamically.

Non-assay datasets can be imported in bulk (as part of a TSV paste or a study import), and can also be configurable to allow row-level inserts/updates/deletes.

Datasets are typically scoped to a single study in a single folder. In some contexts, however, shared datasets can be defined at the project level and have rows associated with any of its subfolders.

Datasets have their own study security configuration, where groups are granted access to datasets separately from their permission to the folder itself. Permission to the folder is a necessary prerequisite for dataset access (i.e., have the Reader role for the folder), but is not necessarily sufficient.

A special type of dataset, the query snapshot, can be used to extract data from some other sources available in the server, and create a dataset from it. In some cases, the snapshot is automatically refreshed after edits have been made to the source of the data. Snapshots are persisted in a physical table in the database (they are not dynamically generated on demand), and as such they can help alleviate performance issues in some cases.

Custom Queries

A custom query is effectively a non-materialized view in a standard database. It consists of LabKey SQL, which is exposed as a separate, read-only query/table. Every time the data in a custom query is used, it will be re-queried from the database.

In order to run the query, the current user must have access to the underlying tables it is querying against.

Custom queries can be created through the web interface in the schema browser, or supplied as part of a module.

Sample Types

Sample types allow administrators to create multiple sets of samples in the same folder, which each have a different set of customizable fields.

Sample types are created by pasting in a TSV of data and identifying one, two, or three fields that comprise the primary key. Subsequent updates can be made via TSV pasting (with options for how to handle samples that already exist in the set), or via row-level inserts/updates/deletes.

Sample types support the notion of one or more parent sample fields. When present, this data will be used to create an experiment run that links the parent and child samples to establish a derivation/lineage history. Samples can also have "parents" of other dataclasses, such as a "Laboratory" data class indicating where the sample was collected.

One sample type per folder can be marked as the “active” set. Its set of columns will be shown in Customize Grid when doing a lookup to a sample table. Downstream assay results can be linked to the originating sample type via a "Name" field -- for details see Samples.

Sample types are resolved based on the name. The order of searching for the matching sample type is: the current folder, the current project, and then the Shared project. See Shared Project.

DataClasses

DataClasses can be used to capture complex lineage and derivation information, for example, the derivations used in bio-engineering systems. Examples include:

• Reagents
• Gene Sequences
• Proteins
• Protein Expression Systems
• Vectors (used to deliver Gene Sequences into a cell)
• Constructs (= Vectors + Gene Sequences)
• Cell Lines

Similarities with Sample Types

A DataClass is similar to a Sample Type or a List, in that it has a custom domain. DataClasses are built on top of the exp.Data table, much like Sample Types are built on the exp.Materials table. Using the analogy syntax:

SampleType : exp.Material :: DataClass : exp.Data

Rows from the various DataClass tables are automatically added to the exp.Data table, but only the Name and Description columns are represented in exp.Data. The various custom columns in the DataClass tables are not added to exp.Data. A similar behavior occurs with the various Sample Type tables and the exp.Materials table.

Also like Sample Types, every row in a DataClass table has a unique name, scoped across the current folder. Unique names can be provided (via a Name or other ID column) or generated using a naming pattern.

For more information, see Data Classes.

Domains

A domain is a collection of fields. Lists, Datasets, SampleTypes, DataClasses, and the Assay Batch, Run, and Result tables are backed by an LabKey internal datatype known as a Domain. A Domain has:

• a name
• a kind (e.g. "List" or "SampleType")
• an ordered set of fields along with their properties.

The fields and properties of a Domain can be edited interactively using the field editor or programmatically using the JavaScript LABKEY.Domain APIs.

Also see Modules: Domain Templates.

Domain/Data Structure Names

Data structures (Domains) like Sample Types, Source Types, Assay Designs, etc. must have unique names and avoid specific special characters, particularly if they are to be used in naming patterns or API calls. Names must follow these rules:

• Must not be blank
• Must start with a letter or a number character.
• Must contain only valid unicode characters. (no control characters)
• May not contain any of these characters:

  <>[]{};,`"~!@#$%^*=|?\

• May not contain 'tab', 'new line', or 'return' characters.
• May not contain space followed by dash followed by a character.
• i.e. these are allowed: "a - b" or "a-b" or "a–-b"
• these are not allowed: "a -b", "a –-b"

AliquotedFrom
~DataInputs
DataInputs
Inputs
~MaterialInputs
MaterialInputs
batchRandomId
containerPath
contextPath
sampleCount
rootSampleCount
dailySampleCount
dataRegionName
genId
monthlySampleCount
now
queryName
randomId
schemaName
schemaPath
selectionKey
weeklySampleCount
withCounter
yearlySampleCount
folderPrefix

Names are not allowed to contain the following substrings. These are used as substitution operators internally:

:passThrough
:htmlEncode
:jsString
:urlEncode
:encodeURIComponent
:encodeURI
:first
:rest
:last
:trim
:date
:dailySampleCount
:weeklySampleCount
:yearlySampleCount
:monthlySampleCount
:defaultValue
:minValue
:number
:prefix
:suffix
:join
:withCounter

File Import Column Names (aka Parent/Source aliases)

• Must not contain any of the following characters:

  /:<>$[]{};,`"~!@#$%^*=|?\

Field Names with Special Characters

While field names themselves are allowed to contain special characters, it is best practice to have "database legal" names without them and use the special characters you want to show users in the field label.

You can find a list of all the field names using the "exp.Fields" table in the query browser. View data, use the grid folder filter to set the desired scope, then filter the Special Characters column for "true".

External Schemas

External schemas allow an administrator to expose the data in a "physical" database schema through the web interface, and programmatically via APIs. They assume that some external process has created the schemas and tables, and that the server has been configured to connect to the database.

Administrators have the option of exposing the data as read-only, or as insert/update/delete. The server will auto-populate standard fields like Modified, ModifiedBy, Created, CreatedBy, and Container for all rows that it inserts or updates. The standard bulk option (TSV, etc) import options are supported.

External schemas are scoped to a single folder. If an exposed table has a "Container" column, it will be filtered to only show rows whose values match the EntityId of the folder.

The server can connect to a variety of external databases, including Oracle, MySQL, SAS, Postgres, and SQLServer. The schemas can also be housed in the standard LabKey Server database.

The server does not support cross-database joins. It can do lookups (based on single-column foreign keys learned via JDBC metadata, or on XML metadata configuration) only within a single database though, regardless of whether it’s the standard LabKey Server database or not.

Learn more in this topic:

• External Schemas and Data Sources

Linked Schemas

Linked schemas allow you to expose data in a target folder that is backed by some other data in a different source folder. These linked schemas are always read-only.

This provides a mechanism for showing different subsets of the source data in a different folder, where the user might not have permission (or need) to see everything else available in the source folder.

The linked schema configuration, set up by an administrator, can include filters such that only a portion of the data in the source schema/table is exposed in the target.

Learn more in this topic:

• Linked Schemas and Tables

Related Topics

• Data Grid Tour
• Preparing Data for Import
• Shared Project
• Vocabulary Domains

LabKey Server provides a variety of different data structures for different uses: Assay Designs for capturing instrument data, Datasets for integrating heterogeneous clinical data, Lists for general tabular data, etc. Some of these data structures place strong constraints on the nature of the data to be imported, for example Datasets make uniqueness constraints on the data; other data structures, such as Lists, make few assumptions about incoming data.

• Design Choices: Column Names and Field Types
• Choose Column Data Types
• Avoid Mixed Data Types in a Column
• Avoid Special Characters in Column Headers
• Data Column Aliasing
• Import to Unrecognized Fields
• Data Format Considerations
• Handling Backslash Characters
• Clinical Dataset Details
• Demographic Dataset Details
• Date Parsing Considerations
• Use Import Templates
• Import Options: Add, Update, and Merge Data
• Data Import Previews
• OOXML Documents Not Supported

Design Choices: Column Names and Field Types

Choose Column Data Types

When deciding how to import your data, consider the data type of columns to match your current and future needs. Considerations include:

• Available Types: Review the list at the top of this topic.
• Type Conversions are possible after data is entered, but only within certain compatibilities. See the table of available type changes here.
• Number type notes:
• Integer: A 4-byte signed integer that can hold values ranging -2,147,483,648 to +2,147,483,647.
• Decimal (Floating Point): An 8-byte double precision floating point number that can hold very large and very small values. Values can range approximately 1E-307 to 1E+308 with a precision of at least 15 digits. As with most standard floating point representations, some values cannot be converted exactly and are stored as approximations. It is often helpful to set on Decimal fields a display format that specifies a fixed or maximum number of decimal places to avoid displaying approximate values.

General Advice: Avoid Mixed Data Types in a Column

LabKey tables (Lists, Datasets, etc.) are implemented as database tables. So your data should be prepared for insertion into a database. Most importantly, each column should conform to a database data type, such as Text, Integer, Decimal, etc. Mixed data in a column will be rejected when you try to upload it.

Wrong

The following table mixes Boolean and String data in a single column.

Right

Split out the mixed data into separate columns

General Advice: Avoid Special Characters in Column Headers

Column names should avoid special characters such as !, @, #, $, etc. Column names should contain only letters, numbers, spaces, and underscores; and should begin only with a letter or underscore. We also recommend underscores instead of spaces.

Wrong

The following table has special characters in the column names.

Right

The following table removes the special characters and replaces spaces with underscores.

Data Column Aliasing

Use data column aliasing to work with non-conforming data, meaning the provided data has different columns names or different value ids for the same underlying thing. Examples include:

• A lab provides assay data which uses different participant ids than those used in your study. Using different participant ids is often desirable and intentional, as it provides a layer of PHI protection for the lab and the study.
• Learn more here: Participant Aliases
• Excel files have different column names for the same data, for example some files have the column "Immune Rating" and other have the column "Immune Score". You can define an arbitrary number of these import aliases to map to the same column in LabKey.
• Learn more here: Import Aliases
• The source files have a variety of names for the same visit id, for example, "M1", "Milestone #1", and "Visit 1".
• Learn more here: Import Visit Names / Aliases

Import to Unrecognized Fields

When importing data, if there are unrecognized fields in your spreadsheet, meaning fields that are not included in the data structure definition, they will be ignored. In some situations, such as when importing sample data, you will see a warning banner explaining that this is happening:

Data Format Considerations

Handling Backslash Characters

If you have a TSV or CSV file that contains backslashes in any text field, the upload will likely ignore the backslash and either substitute it for another value or ignore it completely. This occurs because the server treats backslashes as escape characters, for example, \n will insert a new line, \t will insert a tab, etc.

To import text fields that contain backslashes, wrap the values in quotes, either by manual edit or by changing the save settings in your editor. For example:

Test\123

"Test\123"

Clinical Dataset Details

Datasets are intended to capture measurements events on some subject, like a blood pressure measurement or a viral count at some point it time. So datasets are required to have two columns:

• a subject id
• a time point (either in the form of a date or a number)

Wrong

The following dataset has duplicate subject id / timepoint combinations.

Right

The following table removes the duplicate row.

Demographic Dataset Details

Demographic datasets have all of the constraints of clinical datasets, plus one more: a given subject identifier cannot appear twice in a demographic dataset.

Wrong

The following demographic dataset has a duplicate subject id.

Right

The following table removes the duplicate row.

Date Parsing Considerations

Whether to parse user-entered or imported date values as Month-Day-Year (as typical in the U.S.) or Day-Month-Year (as typical outside the U.S.) is set at the site level. For example, 11/7/2020 is either July 11 or November 7; a value like 11/15/2020 is only valid Month-Day-Year (US parsing).

If you attempt to import date values with the "wrong" format, they will be interpreted as strings, so you will see errors similar to ""Could not convert value '11/15/20' (String) for Timestamp field 'FieldName'."

Use Import Templates

For the most reliable method of importing data, first obtain a template for the data you are importing. Most data structures will include a Download Template button when you select any bulk import method, such as importing from a file.

Use the downloaded template as a basis for your import file. It will include all possible columns and will exclude unnecessary ones. You may not need to populate every column of the template when you import data.

Import Options: Add, Update and Merge Data

When bulk importing data (via > Import bulk data) the default Import Option is Add rows, for adding new rows only. If you include data for existing rows, the import will fail.

To update data for existing rows, select the option to Update rows. Note that update is not supported for Lists with auto-incrementing integer keys or Datasets with system-managed third keys.

If you want to merge existing data updates with new rows, select Update rows, then check the box to Allow new rows during update. Note that merge is not supported for Lists with auto-incrementing integer keys or Datasets with system-managed third keys.

Learn more about updating and merging data in these topics:

• Populate a List
• Import Data to a Dataset
• Update and Merge Data in Sample Manager, LIMS, or Biologics

Data Import Previews

In some contexts, such as creating a list definition and populating it at the same time and importing samples from file into Sample Manager or LabKey Biologics, you will see a few lines "previewing" the data you are importing.

These data previews shown in the user interface do not apply field formatting from either the source spreadsheet or the destination data structure.

In particular, when you are importing Date and DateTime fields, they are always previewed in ISO format (yyyy-MM-dd hh:mm) regardless of source or destination formatting. The Excel format setting is used to infer that this is a date column, but is not carried into the previewer or the imported data.

For example, if you are looking at a spreadsheet in Excel, you may see the value with specific date formatting applied, but this is not how Excel actually stores the date value in the field. In the image below, the same 'DrawDate' value is shown with different Excel formatting applied. Date values are a numeric offset from a built-in start date. To see the underlying value stored, you can view the cell in Excel with 'General' formatting applied (as shown in the fourth line of the image below), though note that 'General' formatted cells will not be interpreted as date fields by LabKey. LabKey uses any 'Date' formatting to determine that the field is of type 'DateTime', but then all date values are shown in ISO format in the data previewer, i.e. here "2022-03-10 00:00".

After import, display format settings on LabKey Server will be used to display the value as you intend.

OOXML Documents Not Supported

Excel files saved in the "Strict Open XML Spreadsheet" format will generate an .xlsx file, however this format is not supported by POI, the library LabKey uses for parsing .xlsx files. When you attempt to import this format into LabKey, you will see the error:

There was a problem loading the data file. Unable to open file as an Excel document. "Strict Open XML Spreadsheet" versions of .xlsx files are not supported.

As an alternative, open such files in Excel and save as the ordinary "Excel Workbook" format.

Learn more about this lack of support in this Apache issue.

Related Topics

• LabKey Data Structures
• Populate a List
• Import Data to a Dataset
• Prepare Specimen Data for Import

This topic covers using the Field Editor, the user interface for defining and editing the fields that represent columns in a grid of data. The set of fields, also known as the schema or "domain", describes the shape of data. Each field, or column, has a main field type and can also have various properties and settings to control display and behavior of the data in that column.

The field editor is a common tool used by many different data structures in LabKey. The method for opening the field editor varies by data structure, as can the types of field available. Specific details about fields of each data type are covered in the topic: Field Types and Properties.

Topics:

• Open the Field Editor
• Default System Fields for Sample Types and Data Classes
• Create Custom Fields
• Import or Infer Fields from File
• Manually Define Fields
• Edit Fields
• Rearrange Fields
• Delete Fields
• Edit Field Properties and Options: Expand field details.
• Type Specific Formatting Options are covered in the topic: Field Types and Properties
• Name and Linking Options
• Conditional Formatting and Validation Options
• Advanced Settings
• View Fields in Summary Mode
• Export Sets of Fields (Domains)

Open the Field Editor

How you open the field editor depends on the type of data structure you are editing.

If you are learning to use the Field Editor and do not yet have a data structure to edit, you can get started by creating a simple list as shown in the walkthrough of this topic.

Default System Fields for Sample Types and Data Classes

Both Sample Types and Data Classes show Default System Fields at the top of the Fields panel. Other data types do not show this section.

• Some system fields, such as Name cannot be disabled and are always required. Checkboxes are inactive when you cannot edit them.
• Other fields, including the MaterialExpDate (Expiration Date) column for Sample Types, can be adjusted using checkboxes, similar to the Description field for Data Classes, shown below.
• Enabled: Uncheck the box in this column to disable a field. This does not prevent the field from being created, and the name is still reserved, but it will not be shown to users.
• Note that if you disable a field, the data in it is not deleted, you could later re-enable the field and recover any past data.
• Required: Check this box to make a field required.

Click the to collapse this section and move on to any Custom Fields as for any data type.

Create Custom Fields

• Open your data structure for editing.
• For Sample Types and Data Classes you will see a collapsible panel of Default System Fields. Click the to collapse it for now.
• Decide how you want to define your first custom fields:
• Import or infer fields from file: The supported formats are shown below the upload panel.
• Manually Define Fields: Click the button to open the manual field editor.

Both options are available when the set of fields is empty. Once you have defined some fields by either method, the manual editor is the only option for adding more fields.

Import or Infer Fields from File

Manually Define Fields

• After clicking Manually Define Fields, the panel will change to show the manual field editor. In some data structures, you'll see a banner about selecting a key or associating with samples, but for this walkthrough of field editing, these options are ignored.
• Depending on the type of data structure, and whether you started by importing some fields, you may see a first "blank" field ready to be defined.
• If not, click Add Field to add one.

• Give the field a Name. If you enter a field name with a space in it, or other special character, you will see a warning. It is best practice to use only letters, numbers and underscores in the actual name of a field. You can use the Label property to define how to show this field name to users.
• SQL queries, R scripts, and other code are easiest to write when field names only contain combination of letters, numbers, and underscores, and start with a letter or underscore.
• If you include a dot . in your field name, you may see unexpected behavior since that syntax is also used as a separator for describing a lookup field. Specifically, participant views will not show values for fields where the name includes a .
• Use the drop down menu to select the Data Type.
• The data types available vary based on the data structure. Learn which structures support which types here.
• Each data type can have a different collection of properties you can set.
• Once you have saved fields, you can only make limited changes to the type.
• You can use the checkbox if you want to make it required that that field have a value in every row.

• Continue to add any new fields you need - one for each column of your data.
• Learn more about field types and property settings below.
• Click Save to save and exit the editor.

Edit Fields

To edit fields, reopen the editor and make the changes you need. If you attempt to navigate away with unsaved changes you will have the opportunity to save or discard them. When you are finished making changes, click Save.

Once you have saved a field or set of fields, you can change the name and most options and other settings. However, you can only make limited changes to the type of a field. Learn about specific type changes in this section.

Rearrange Fields

To change field order, drag and drop the rows using the six-block handle on the left.

Delete Fields

To remove one field, click the on the right. It is available in both the collapsed and expanded view of each field and will turn red when you hover.

To delete one or more, use the selection checkboxes to select the fields you want to delete. You can use the box at the top of the column to select all fields, and once any are selected you will also see a Clear button. Click Delete to delete the selected fields.

You will be asked to confirm the deletion and reminded that all data in a deleted field will be deleted as well. Deleting a field cannot be undone.

Click Save when finished.

Edit Field Properties and Options

Each field has a data type and can have additional properties defined. The properties available vary based on the field type. Learn more in this topic: Field Types and Properties

To open the properties for a field, click the icon (it will become a handle for closing the panel). For example, the panel for a text field looks like:

Fields of all types have:

• Name and Linking Options
• Conditional Formatting and Validation Options
• Advanced Settings

Name and Linking Options

All types of fields allow you to set the following properties:

• Description: An optional text description. This will appear in the hover text for the field you define. XML schema name: description.
• Label: Different text to display in column headers for the field. This label may contain spaces. The default label is the Field Name with camelCasing indicating separate words. For example, the field "firstName" would by default be labelled "First Name". If you wanted to show the user "Given Name" for this field instead, you would add that string in the Label field.

• Import Aliases: Define alternate field names to be used when importing from a file to this field. This option offers additional flexibility of recognizing an arbitrary number of source data names to map to the same column of data in LabKey. Multiple aliases may be separated by spaces or commas. To define an alias that contains spaces, use double-quotes (") around it.
• URL: Use this property to change the display of the field value within a data grid into a link. Multiple formats are supported, which allow ways to easily substitute and link to other locations in LabKey. The ${ } syntax may be used to substitute another field's value into the URL. Learn more about using URL Formatting Options.
• Ontology Concept: (Premium Feature) In premium editions of LabKey Server, you can specify an ontology concept this field represents. Learn more in this topic: Concept Annotations

Conditional Formatting and Validation Options

Most field types offer conditional formatting. String-based fields offer regular expression validation. Number-based fields offer range expression validation. Learn about options supported for each type of field here.

• Conditional Formatting
• Regular Expression Validation
• Range Validators

Create Conditional Format Criteria

Conditional formats change how data is displayed depending on the value of the data. Learn more in this topic:

• Conditional Formats

• Click Add Format to open the conditional format editor popup.

• Specify one or two Filter Type and Filter Value pairs.
• Select Display Options for how to show fields that meet the formatting criteria:
• Bold
• Italic
• Strikethrough
• Text/Fill Colors: Choose from the picker (or type into the #000000 area) to specify a color to use for either or both the text and fill.

• You will see a cell of Preview Text for a quick check of how the colors will look.
• Add an additional format to the same field by clicking Add Formatting. A second panel will be added to the popup.
• When you are finished defining your conditional formats, click Apply.

Create Regular Expression Validator

• Click Add Regex to open the popup.

• Enter the Regular Expression that this field's value will be evaluated against.
• All regular expressions must be compatible with Java regular expressions as implemented in the Pattern class.
• You can test your expression using a regex interpreter, such as https://regex101.com/.
• Description: Optional description.
• Error Message: Enter the error message to be shown to the user when the value fails this validation.
• Check the box for Fail validation when pattern matches field value in order to reverse the validation: With this box unchecked (the default) the pattern must match the expression. With this box checked, the pattern may not match.
• Name: Enter a name to identify this validator.
• You can use Add Regex Validator to add a second condition. The first panel will close and show the validator name you gave. You can reopen that panel using the (pencil) icon.
• Click Apply when your regex validators for this field are complete.
• Click Save.

Create Range Expression Validator

• Click Add Range to open the popup.

• Enter the First Condition that this field's value will be evaluated against. Select a comparison operator and enter a value.
• Optionally enter a Second Condition.
• Description: Optional description.
• Error Message: Enter the error message to be shown to the user when the value fails this validation.
• Name: Enter a name to identify this validator.
• You can use Add Range Validator to add a second condition. The first panel will close and show the validator name you gave. You can reopen that panel using the (pencil) icon.
• Click Apply when your range validators for this field are complete.
• Click Save.

Advanced Settings for Fields

Open the editing panel for any field and click Advanced Settings to access even more options:

• Display Options: Use the checkboxes to control how and in which contexts this field will be available.
• Show field on default view of the grid
• Show on update form when updating a single row of data
• Show on insert form when updating a single row of data
• Show on details page for a single row

• Default Value Options: Automatically supply default values when a user is entering information. Not available for Sample Type fields or for Assay Result fields.
• Default Type: How the default value for the field is determined. Options:
• Last entered: (Default) If a default value is provided (see below), it will be entered and editable for the user's first use of the form. During subsequent uploads, the user will see their last entered value.
• Editable default: An editable default value will be entered for the user. The default value will be the same for every user for every upload.
• Fixed value: Provides a fixed default value that cannot be edited.
• Default Value: Click Set Default Values to set default values for all the fields in this section.
• Default values are scoped to the individual folder. In cases where field definitions are shared, you can manually edit the URL to set default values in the specific project or folder.
• Note that setting default values will navigate you to a new page. Save any other edits to fields before leaving the field editor.

• Miscellaneous Options:
• PHI Level: Use the drop down to set the Protected Health Information (PHI) level of data in this field. Note that setting a field as containing PHI does not automatically provide any protection of that data.
• Learn more in this topic: Protecting PHI Data
• (Premium Feature) Learn about using PHI Levels to mask data in the user interface in this topic: Compliance: Setting PHI Levels on Fields
• Exclude from "Participant Date Shifting" on export/publication: (Date fields only) If the option to shift/randomize participant date information is selected during study folder export or publishing of a study, do not shift the dates in this field. Use caution when protecting PHI to ensure you do not exempt fields you intend to shift.
• Make this field available as a measure: Check the box for fields that contain data to be used for charting and other analysis. These are typically numeric results. Learn more about using Measures and Dimensions for analysis.
• Make this field available as a dimension: (Not available for Date fields) Check the box for fields to be used as 'categories' in a chart. Dimensions define logical groupings of measures and are typically non-numerical, but may include numeric type fields. Learn more about using Measures and Dimensions for analysis.
• Make this field a recommended variable: Check the box to indicate that this is an important variable. These variables will be displayed as recommended when creating new participant reports.
• Track reason for missing data values: Check this box to enable the field to hold special values to indicate data that has failed review or was originally missing. Administrators can set custom Missing Value indicators at the site and folder levels. Learn more about using Missing Value Indicators.
• Require all values to be unique: Check this box to add a uniqueness constraint to this field. You can only set this property if the data currently in the field is unique. Supported for Lists, Datasets, Sample Types, and Data Classes.

View Fields in Summary Mode

In the upper right of the field editor, the Mode selection lets you choose:

• Detail: You can open individual field panels to edit details.
• Summary: A summary of set values is shown; limited editing is possible in this mode.

In Summary Mode, you see a grid of fields and properties, and a simplified interface. Scroll for more columns. Instead of having to expand panels to see things like whether there is a URL or formatting associated with a given field, the summary grid makes it easier to scan and search large sets of fields at once.

You can add new fields, delete selected fields, and export fields while in summary mode.

Export Sets of Fields (Domains)

Once you have defined a set of fields (domain) that you want to be able to save or reuse, you can export some or all of the fields by clicking (Export). If you have selected a subset of fields, only the selected fields will be exported. If you have not selected fields (or have selected all fields) all fields will be included in the export.

A Fields_*.fields.json file describing your fields as a set of key/value pairs will be downloaded. All properties that can be set for a field in the user interface will be included in the exported file contents. For example, the basic text field named "FirstField" we show above looks like:

[
    {
        "conditionalFormats": [],
        "defaultValueType": "FIXED_EDITABLE",
        "dimension": false,
        "excludeFromShifting": false,
        "hidden": false,
        "lookupContainer": null,
        "lookupQuery": null,
        "lookupSchema": null,
        "measure": false,
        "mvEnabled": false,
        "name": "FirstField",
        "propertyValidators": [],
        "recommendedVariable": false,
        "required": false,
        "scale": 4000,
        "shownInDetailsView": true,
        "shownInInsertView": true,
        "shownInUpdateView": true,
        "isPrimaryKey": false,
        "lockType": "NotLocked"
    }
]

You can save this file to import a matching set of fields elsewhere, or edit it offline to reimport an adjusted set of fields.

For example, you might use this process to create a dataset in which all fields were marked as measures. Instead of having to open each field's advanced properties in the user interface, you could find and replace the "measure" setting in the JSON file and then create the dataset with all fields set as measures.

Related Topics

• Field Types and Properties
• Protecting PHI Data
• Measure and Dimension Columns

This topic outlines the field formatting and properties specific to each data type.

• Field Types Available by Data Structure
• Changes Allowed by Field Type
• Validators Available by Field Type
• Type Specific Properties and Options
• Text, Multi-Line Text, and Flag Options
• Text Choice Field Options
• Boolean Options
• Integer and Decimal Options
• Date, Time, and Date Time Options
• Calculation (Premium Feature)
• File and Attachment Options
• Choose Download or View in Browser for Files and Attachments
• Inline Thumbnails for Files and Attachments
• Bulk Import into the File Field Type
• User Options
• Subject/Participant Options
• Lookup Options
• Sample Options
• Ontology Lookup Options (Premium Feature)
• Visit Date/Visit ID/Visit Label Options
• Unique ID Options (Premium Feature)
• SMILES Field (Biologics Feature)

Field Types Available by Data Structure

Fields come in different types, each intended to hold a different kind of data. Once defined, there are only limited ways you can change a field's type, based on the ability to convert existing data to the new type. To change a field type, you may need to delete and recreate it, reimporting any data.

The following table show which fields are available in which kind of table/data structure. Notice that Datasets do not support Attachment fields. For a workaround technique, see Linking Data Records to Image Files.

Changes Allowed by Field Type

Once defined, there are only limited ways you can change a field's data type, based on the ability to safely convert existing data to the new type. This table lists the changes supported (not all types are available in all data structures and contexts):

If you cannot make your desired type change using the field editor, you may need to delete and recreate the field entirely, reimporting any data.

Validators Available by Field Type

This table summarizes which formatting and validators are available for each type of field.