The LabKey Biologics application supports collaboration across multiple projects by using LabKey containers to hold and selectively share data across projects. This topic covers considerations for designing your system.

• Options for Sharing Biologics Data
• Manage Multiple Biologics Projects
• Create New Project
• Work within Projects
• Cross-Project Actions
• Restricted Visibility of Inaccessible Data
• ID/Name Settings
• Force Usage of Naming Patterns for Consistency
• Apply Naming Prefix
• Naming Pattern Elements/Tokens
• Shared Data Structures (Sample Types Registry Source Types, Assays, Storage Systems)

Options for Sharing Biologics Data

Biologics runs in the context of a LabKey project or folder, collectively known as containers. Each container can have unique permissions assignments and data, supporting a secure and isolated workspace. If desired, many resources, including assay designs and sample type definitions, can also be shared across multiple containers. Further, within a LabKey project of type "Biologics", an administrator can add LabKey subfolders which selectively share data across other subfolders, known in the Biologics application as Projects

The Biologics administrator should determine the configuration that best represents the organization.

Example Scenarios:

1. You might have two groups doing distinct work with no need to share data or compare results. These two groups could each use a separate Biologics project or folder and keep all resources within it. Permissions are assigned uniquely within the container.

2. If two groups needed to use the same assay designs or sample types, but would not otherwise share or compare the actual data, those definitions could be placed in the Shared project, with all collection and analysis in separate folders for the two groups as in option 1. Note that in this scenario, samples created of those shared types would have the same naming pattern and if you used a container-specific prefix, it would not be applied to the samples of the shared type.

3. If multiple groups need to share and compare data, and also keep clear which data came from which group originally, you could apply a container prefix in each group's folder so that all data would be consistently identified. In this scenario, each container would need its own sample type definitions so that the naming patterns would propagate the prefix into the created samples.

4. For more integrated sharing, configure Biologics in a top level LabKey container, then add one or more sub-containers also of folder type "Biologics". These sub-containers are called Projects within Biologics. Bioregistry and Sample definitions can be shared among the Projects and permissions controlled independently. Learn about this option in the next section.

5. Freezers can be shared among folders with different permissions. Users will only be able to see details for the stored samples to which they have been granted access. Learn more about shared freezer access in this topic: Shared Storage

Manage Multiple Biologics Projects

When using Biologics in a top-level LabKey Server container, administrators have the option to manage multiple Biologics Projects directly from within the admin interface. Note that this is not supported when the top level Biologics container is a folder or subfolder in LabKey Server.

To manage Projects, select > Projects.

Create New Project

To create a new Project, click Create a Project and provide the container name, selecting whether to also use the container name as the label (and if not, providing a label). You can also use checkboxes to control which data types and storage systems are visible to users in the project. Note that hiding data types in this way does not delete any data, and lineage relationships are maintained, it just simplifies the interface for users of the project. Learn more in the Sample Manager documentation here:

• Select Data in Project: You can only hide custom Registry Source Types (listed under "Parent Types")
• Select Project Storage

You can also select whether to enforce using naming patterns for consistency and apply a naming prefix in the new project.

Work within Projects

When in use, you'll see Projects listed on the left side of the main menu. Select the desired Project, then click the item of interest on the menu. Users will see the contents of the application 'scoped' to the selected Project. Selecting the top-level container (aka the "home" Project, named "BiologicsMultiVerse" in this example) will show all data the user can access across all Projects to which they have been granted "Read" permissions.

To navigate, click the name of the desired project, then the page of interest from the main menu. When you hover over a project name, you'll see quick links to key pages for that project:

• Dashboard
• Administration

See below for notes about cross-project actions on samples, media, etc.

Cross-Project Actions

When multiple Biologics Projects (subfolders) are in use, these notes apply to how some cross-project actions are handled:

• Registry Sources and Media:
• Creating entities, either in a grid or via file import, allows parents and related entities to be chosen from the current project or projects above it in the hierarchy. You cannot select parents from a "child" project of the current one.
• Editing entities in a grid or in bulk is only allowed for entities in the current project. To do editing, you must be in the project the entity belongs to and will see an error if you attempt to edit in the wrong location
• Deleting entities is only allowed for entities in the current project.
• Deriving samples from a Registry Source allows parent objects from only the current project or a project above it.
• Moving Registry Sources and some Media between Projects is detailed in this topic: Move Entities Between Projects
• Samples:
• Individual sample creation in a grid allows parent types from the current project and projects above it.
• Grid edit, sample derivation and deletion: Only works for entities in the current project.
• File import only allows sample parent type and parent selection from the current project, as for grid editing.
• Editing parent details for an individual sample only works when adding parents from the current project.
• Derived or Aliquoted samples end up in the project where they are derived/aliquoted.
• Moving Samples between Projects is detailed in this topic: Move Samples Between Projects
• Assay:
• Imported assay data can reference samples in the current project or any 'higher' (parent) project, but cannot reference samples in sibling or 'lower' (child) project.
• Imported assay data can also reference samples defined in the Shared project.
• Moving Assay Runs between Projects is detailed in this topic: Move Assay Runs Between Projects
• Storage:
• Learn about shared freezers in this topic: Shared Storage
• Workflow:
• Creation of workflow jobs using samples from different projects is possible both from any project.
• The job that is created will belong to the project in which it was created, regardless of the samples included.
• Additional samples from all visible projects can be added to existing jobs.
• Picklists:
• Creation of picklists using samples from different projects is possible from any project.
• The picklist that is created will belong to the project in which it is created, regardless of the samples included.
• The picklist will be visible in only the project in which it was created.
• Additional samples from all visible projects can be added to existing picklists in the current project.
• Notebooks:
• Notebooks can reference entities from all projects visible in the current context.
• Notebooks created from a parent project are also visible from any child project, and vice versa.
• Notebooks created in any project can be submitted for review, or accessed for review, from any project.
• Moving Notebooks between Projects is detailed in this topic: Move Notebooks Between Projects

Restricted Visibility of Inaccessible Data

When a user has access to a subset of projects, there can be situations where this user will be restricted from seeing data from other projects, including identifiers such as Sample IDs that might contain restricted details. In detail pages, listing pages, and grids, entities a user does not have access to will show "unavailable" in the display instead of a name or rowid.

As an example, if a notebook contains references to any data a user cannot access, they will not be able to access that notebook. It will not be included on the "All Notebooks" listing and if they happen to directly access it, such as through a saved URL, they will see only a banner message reading "You cannot view notebook [notebook title] because it contains references to data you don't have permission to view. The references may be in active or archived entries."

As another example, when a storage unit contains samples you cannot view, you'll see the space occupied by a lock icon and a hover message will explain "This location is occupied by a restricted sample."

In timelines, the names of entities the user does not have access to, such as the parent of an entity they can access, will be redacted from the timeline events.

ID/Name Settings

Select > Application Settings and scroll down to the ID/Name Settings section to control several options related to naming of entities in the application.

Force Usage of Naming Patterns for Consistency

To maintain consistent naming, particularly when using container-specific naming prefixes, you may want to restrict users from entering their own names for entities. This requires that every type of entity have a naming pattern that can be used to generate unique names for them.

When users are not permitted to create their own IDs/Names, the ID/Name field will be hidden during creation and update of rows, and when accessing the design of a new or existing Sample Type or Registry Source Type.

Additionally:

• Attempting to import new data will fail if an ID/Name is encountered.
• Attempting to update existing rows during file import will also fail if an unrecognized/new ID/Name is encountered.

To disallow User-defined IDs/Names:

• Select > Application Settings.
• Scroll down to ID/Name Settings.
• Uncheck the box Allow users to create/import their own IDs/Names.
• Note that to complete this change, all entities in the system must have a valid naming pattern. You will see a warning if any need to be added.

Apply Naming Prefix

You can apply a container-specific naming prefix that will be added to naming patterns to assist integration of data from multiple locations while maintaining a clear association with the original source of that data.

This prefix is typically short, 2-3 characters long, but will not be limited. Prefixes must be unique site-wide, and should be recognizable to your users. Before setting one, make sure you understand what will happen to the naming patterns and names of existing entities in your project.

• The prefix will be applied to names created with naming patterns for all Sample Types and Registry Source Types in the container.
• New samples and entities created after the addition of the prefix will have names that include the prefix.
• Existing samples and entities created prior to the addition of the prefix will not be renamed and thus will not have the prefix (or might have a different previously-applied prefix).
• Sample aliquots are typically created and named including the name of the sample they are aliquoted from. This could mean that after the prefix is applied, new aliquots may or may not include the prefix, depending on whether the originating sample was created before or after the prefix was applied. Learn more about aliquot naming here: Aliquot Naming Patterns.

To set a container prefix:

• Select > Application Settings.
• Scroll down to the ID/Name Settings section.
• Enter the prefix to use. You will see a preview of what a name generated with the Naming Pattern with the prefix applied might look like using a representative example, Blood-${GenId}:

• Click Apply Prefix to apply it.
• This action will change the Naming Pattern for all new and existing Sample Types and Registry Source Types. No existing IDs/Names will be affected. Are you sure you want to apply the prefix?
• Click Yes, Save and Apply Prefix to continue.

Naming Pattern Elements/Tokens

The sampleCount and rootSampleCount tokens are used in Naming Patterns across the application. In this section, you'll see the existing value (based on how many samples and/or aliquots have already been created). To modify one of these counters, enter a value higher than the value shown and click the corresponding Apply New... button.

Learn more about these naming pattern tokens in this topic:

• Incrementing Sample Counters

Shared Data Structures (Sample Types, Registry Source Types, Assays, and Storage)

Sample Types, Registry Source Types, Assays, and Storage Systems are defined in the home project and available in subprojects, provided an administrator has not 'hidden' them. Administrators can edit these shared data structures from the home project or any subproject, but the changes will be made at the home project level, applying to all subprojects.

In addition, any Sample Types, Registry Source Types, and Assay definitions defined in the /Shared project will be available for use in LabKey Biologics. You will see them listed on the menu and dashboards alongside local definitions.

From within the Biologics application, users editing (or deleting) a shared definition will see a banner indicating that changes will affect other folders. The same message is applied when editing a data structure from a subproject within the Biologics application.

Note that when you are viewing a grid for any Registry Source Type, the container filter defaults to "Current". You can change the container filter using the grid customizer if you want to show all Registry Sources in "CurrentPlusProjectAndShared" or similar.

Related Topics

• Sample Naming Patterns
• Aliquot Naming Patterns
• Shared Storage