Skip to content

Sample Tracker Guide

Welcome to Sample Tracker, a metadata tracking system designed to support a wide range of use cases—from basic to complex—across multi-organization and lab-based projects.

Sample Tracker helps you trigger and track automated data processing (pipelines), downstream analysis, and visualization workflows. This guide introduces the core concepts you’ll use in Sample Tracker, including Sample Trackers, Collections, and Fields.

Benefits of Sample Tracker’s design

  • Flexible design: Define Sample Trackers, Collections, and Fields using a schema approach inspired by MongoDB-style document storage. This makes it easy for metadata to evolve as your project grows.
  • Web APIs: Sample Tracker provides secure, token-based Web APIs so metadata (and processed outputs) can be accessed programmatically in support of FAIR data practices.
  • Sharing and permissions: Each Sample Tracker, collection, field, and record supports dynamic permission controls, enabling owners to grant or restrict access for specific groups or users.
  • Standardize metadata across datasets and runs: Use consistent fields and values so datasets and runs are comparable and easier to manage.
  • Use metadata on the Run page: When configuring a run, you can open the selected dataset’s Sample Tracker metadata to populate samplesheet information before starting the pipeline.

Core concepts

  • Sample Tracker: A workspace that groups related collections, fields, and permissions for a team, lab, or initiative.
  • Collection: A table-like view of records (documents). Each row is a record. Collections are where you insert, update, and delete metadata.
  • Field: A metadata attribute stored on a record (for example: name, file1, sample_id, condition, replicate, library_type).

sample-tracker-all-trackers

Working with collections

At the top of the Sample Tracker dashboard, use the Select Collection dropdown to choose the collection you want to view. Collections are where you insert, update, and manage your metadata records. You can also use the filter controls next to the dropdown to narrow what’s shown.

all-collections

In the collection table view, you’ll typically see action buttons such as:

  • Add: Opens Add File Modal, a spreadsheet-style editor for creating one or many records.

  • Optional: enable Import from spreadsheet to Download Template, then upload a .csv, .tsv, .xls, or .xlsx file.

  • Click Create to insert the rows you changed.
  • Edit: Bulk-edit selected records in a spreadsheet-style editor, then click Update.
  • Delete: Remove one or more records.
  • Permissions: Bulk-update row-level read/write permissions for the selected records.
  • Download: Export the current collection as an Excel file (.xlsx).

sample-tracker-biosample-collection

Collection configuration guide

To open collection configuration:

  1. Go to Sample Trackers
  2. Open a Sample Tracker (URL looks like /sample-trackers/:id)
  3. Click Configuration
  4. Open the All Collections tab

collection configuration

Creating a collection

  1. Click New Collection (top right). A drawer titled New Collection opens.

  2. Fill in the fields below:

  3. Name (required): Internal name. It will be normalized (lowercased; spaces become _) and must be unique within the Sample Tracker.

  4. Label (required): Display name shown in the UI. Must also be unique within the Sample Tracker.
  5. Data Delete Protected: If enabled, protects the collection’s data from deletion (UI toggle; enforced server-side).

  6. Admin Permissions: Who can view/edit the collection configuration:

    • Click + Add Admin Permission
    • Choose type (user / group), then set Read and optionally Write

  7. Data Permissions: Who can view/edit the items/rows stored in this collection:

    • Click + Add Data Permission
    • Same permission structure as above

  8. Click Save.

Info

When you create a collection, Via Foundry automatically creates an ID field (name: id, label: ID). It is Required, Unique, and marked as the collection’s Identifier, with a naming pattern like P-${AUTOINCREMENT} (the prefix is the first letter of the collection name).

Editing a collection

  • In the collections table, open the row Options menu and choose Edit Collection.
  • Update any fields (Name/Label, Data Delete Protected, Admin/Data permissions), then click Save.

Deleting a collection

  • In the collections table, open the row Options menu and choose Delete Collection.
  • Confirm in the Delete Collection dialog.

Field configuration guide

A field defines a property on each record in a collection (similar to a column). Fields can be used for validation, uniqueness, and for building references between collections.

To manage fields:

  1. Go to Sample Tracker → Configuration → Fields
  2. Choose the target collection from the Select Collection dropdown
  3. Use Add Field or Add Reference Field

collection configuration

Adding a field

  1. Select a collection.
  2. Click Add Field (drawer titled New Field).

  3. Fill in:

    • Name (required): Internal key. It will be normalized (lowercased; non-alphanumeric characters become _) and must be unique within the collection.
    • Label (required): Display label shown in forms/tables. Must be unique within the collection.
    • Type (required): One of: String, Number, Boolean, Array, Date, Mixed, mongoose.Schema.ObjectId
    • Unique: Enforces uniqueness.
    • Identifier: Marks the collection’s primary identifier field. Only one field should be set as the Identifier. By default, the auto-created id field is the Identifier. If you want to use a different identifier, first create another Unique field, then switch the Identifier to that field.
    • Required: If enabled, the field must be provided.
    • Naming Pattern: Optional pattern used for generated values (commonly used by the auto-created id field).
    • Default: Optional default value.
    • Description: Optional help text.

  4. (Optional) Toggle Show Advanced Fields for extra configuration:

    • Descriptive: Marks the field as descriptive metadata (useful for display/search; typically not used as an identifier).
    • Hidden: Hides the field from default UI views/forms.
    • Deprecated: Indicates the field should not be used for new records (kept for backwards compatibility).
    • Lowercase: Automatically normalizes string values to lowercase on save.
    • Uppercase: Automatically normalizes string values to uppercase on save.
    • Unit: Optional unit label for numeric values (for example: ng/µL, bp).
    • Grouped: Groups related fields together in the UI for easier form/table organization.
    • Barcode Pattern: Validation pattern for barcode values.
    • Barcode Prefix: Required starting prefix for barcode values.
    • Ontology: Must be a valid JSON object (entered as text).
    • Checkvalid: Stored as-is (advanced validation configuration).
    • Ref: Reference target (used for reference fields).
    • Enum: Must be a valid JSON array (entered as text).
    • Min / Max, Min Length / Max Length

  5. (Optional) Permissions: Click + Add Permission to set per-field read/write access (user/group).

  6. Click Save.

Adding a reference field (parent/child relationship)

Use a reference field when one collection needs to point to a record in another collection.

  1. Select the child collection (the collection that will store the reference).
  2. Click Add Reference Field.

  3. In Create Reference Field:

    • Choose the collection you want to reference (the parent)
    • Provide a Label

  4. Confirm. Via Foundry creates a field with:

    • Type: mongoose.Schema.ObjectId
    • Name: ${SelectedCollection}_id
    • Ref: ${sampleTrackerId}_${SelectedCollection}

Editing and deleting fields

  • In the fields table, use the row Options menu:

    • Edit Field to update field settings
    • Delete Field to remove it (confirm in Delete Field)

Info

The Fields tab shows a warning if no Identifier field is set or if multiple Identifier fields are set. Keep exactly one Identifier (usually the auto-created id).