Genomes Management — User Guide

Form Bio's Genomes Management feature keeps your reference genomes and their annotations in sync with Benchling, then makes them available in IGV and the Workflow Launcher.

The short version of how it works:

• Benchling is the source of truth. Bioinformaticians create and edit reference genomes and annotation versions directly in Benchling. There are no genome create/edit/delete forms on the platform.
• Form Bio pulls on demand. When someone clicks Sync from Benchling, the platform reads the current genome and annotation records out of Benchling, validates them, and stores them so they can be used elsewhere on the platform.
• The sync is one-way. Form Bio reads from Benchling. It never writes changes back. To change a genome, you change it in Benchling and sync again.

This guide covers what data is pulled, how to run and review a sync, and how to make sure a genome is usable in IGV and the Workflow Launcher.

⚠️ Important: the legacy genome publishing API is being retired

Before Genomes Management, genomes were published to the platform through an admin publishing API (the POST /admin/genomes/publish endpoint) and a self-service create/edit/delete write path. As soon as this feature is rolled out, that API and write path are no longer supported.

What this means:

• Benchling becomes the only way to add, edit, or remove genomes. The admin publishing endpoint and the platform's genome create/edit/delete forms are retired — there is no replacement endpoint, by design.
• Any scripts or integrations that call the old genome publishing/admin API will stop working. If you have automation that publishes genomes that way, move that work into Benchling and rely on Sync from Benchling instead.
• Genome metadata changes now flow one direction only: edit in Benchling → Sync from Benchling → available on the platform.

If you maintained genomes through the old API, the rest of this guide is the new workflow that replaces it.

Part 1 — Syncing Genome & Annotation Data from Benchling

1.1 What gets pulled (and what doesn't)

A sync reads two Benchling entity types: GEN-Reference Genome (the genome itself) and GEN-Annotation Version (one or more annotation versions linked to a genome).

Genome fields pulled from Benchling:

Annotation fields pulled from Benchling (per GEN-Annotation Version):

The genome's Current Annotation Version link determines which version is marked as the active ("designated") one. Changing that link in Benchling and re-syncing is how you change which annotation version consumers use.

📸 Screenshot: A GEN-Reference Genome entity in Benchling with its fields visible (Common Name, FASTA URL, Chromosome Order, Current Annotation Version link, etc.).

📸 Screenshot: A linked GEN-Annotation Version entity showing its GTF URL

What is not pulled:

• Anything not modeled in those two entity types. If a piece of metadata isn't a field on GEN-Reference Genome or GEN-Annotation Version, it won't appear on the platform.
• Scientific accuracy, naming, and formatting. The sync does not check whether values are scientifically correct or follow a naming convention — that is managed in Benchling.
• Records that fail validation. A genome missing a required field (see below) is not published; the platform keeps the last good values and flags the genome with an error.
• Genomes for non-Colossal organizations. Synced genomes are made available to the Colossal organizations only.

One-way sync. Edits you make on the platform are never written back to Benchling. Always make genome changes in Benchling, then sync.

What blocks a sync vs. what's only a warning

Validation runs per genome at sync time. One genome failing never affects the others — each is processed independently.

Errors — the genome will not publish:

• Missing Genome ID
• Missing or unreachable FASTA URL
• Missing Common Name
• Missing Tax ID

Warnings — the genome publishes, but is flagged:

• Missing Index / Alias / Cytoband URL
• Missing Chromosome Order (the genome will have no gene search in IGV)
• A linked Current Annotation Version whose GTF path is missing

1.2 How to sync data from Benchling

1. Open the Genomes page from the project navigation menu.
2. Click Sync from Benchling.
3. The sync runs immediately (the button shows Syncing…). When it finishes, a summary appears, for example:

Synced 12 genomes. 2 warnings. 1 error. 3 archived (no longer in Benchling).

📸 Screenshot: The Genomes page header showing the Sync from Benchling and View Syncs buttons. A second shot of the result summary snackbar after a sync completes is helpful here too.

The sync is on-demand — it only runs when you click the button. It reads every genome currently in Benchling, updates the platform to match, and archives any genome that used to exist but is no longer returned by Benchling (archived genomes stop appearing in IGV and the Workflow Launcher).

1.3 How to see what was synced

You can review sync results in two places.

A) The Genomes table — the current state of every genome after the most recent sync. Useful columns:

📸 Screenshot: The Genomes table displaying ok rows, and one error row so readers can see the Status colors, and the GCS Files columns.

📸 Screenshot: *Note you may need to scroll to the right to see the number and link to Annotations

B) Sync history — click View Syncs to see every sync run, then open a run to view its Sync Detail page:

• A summary block with Run By, Started, Finished, and per-genome counts: Added, Updated, Deleted, Unchanged.
• An operations table listing each genome that was added, updated, or deleted, with the specific Changed Fields and any per-genome message. (Unchanged genomes are omitted from the table.)

📸 Screenshot: The Genome Syncs history list (Run By / Started / Finished / Status / Added / Updated / Deleted / Error), and a Sync Detail page — the summary block (Run By / Started / Finished / Added / Updated / Deleted / Unchanged) with the operations table below it (showing an added, an updated with Changed Fields, and a deleted / Archived row).

Coming soon: annotation-level sync reporting. A future update adds per-annotation counts (Added / Updated / Deleted / Unchanged / Errors) and a Skipped warning that surfaces annotations dropped because they weren't linked to a parent genome in Benchling. Today, sync counts cover genomes; per-genome annotation totals are visible in the Annotations column of the Genomes table.

Part 2 — Using Genome & Annotation Data in IGV and the Workflow Launcher

Once a genome has synced successfully, it becomes selectable in IGV and the Workflow Launcher. No extra step is needed beyond a clean sync.

2.1 In IGV

1. Open IGV from the project navigation.
2. Under Select a Reference Genome, use the dropdown. Genomes are grouped as Public, Private, and From File, and you can search by common name.
3. Select your genome to load it. (You can also click Open Genome File to load your own FASTA from the project instead of a synced genome.)

📸 Screenshot: The IGV Select a Reference Genome dropdown open, showing the Public / Private / From File groupings and the search box.

If you select a genome and see:

Reference sequence data for this genome is not yet available for IGV viewing. Please check back after the next genome metadata sync.

…the genome's sequence data hasn't been fully synced yet. Run Sync from Benchling (or wait for the next sync) and confirm the genome's GCS Files column reads Verified.

2.2 In the Workflow Launcher

When a workflow asks for a reference genome, you'll see a genome selection field that uses the same searchable dropdown as IGV.

• Only genomes that have at least one annotation version appear here. A genome with 0 annotations is intentionally excluded, because workflows need annotation data to run.
• The current annotation version a workflow uses is the one designated in Benchling via the genome's Current Annotation Version link. To change which annotation version workflows use, update that link in Benchling and re-sync.

📸 Screenshot: The Workflow Launcher Reference Genome step, showing the Genome field and the Reference genome annotation version field.

📸 Screenshot: A second shot with the Genome dropdown open (showing the grouped, annotation-backed genomes).

2.3 Checklist — making sure a genome works in IGV and the Launcher

If a genome isn't showing up or won't load, check these in order. Most fixes are made in Benchling, followed by a re-sync.

Rule of thumb: a green ok status, Verified GCS files, and at least one annotation version means the genome is ready for both IGV and the Workflow Launcher.