64. Checklist Version Workflow¶

Related standard: Catalogue of Life Data Package (ColDP)

64.1 Overview¶

BIMS publishes taxonomy as versioned, citable checklists — one release per biological module (TaxonGroup). Each published version is an immutable snapshot of all validated taxa in that module at the time of publishing. Changelog entries (additions, updates, deletions) are derived automatically by diffing the new snapshot against the previous version, so no manual tagging is required.

Published versions can be exported as a ColDP ZIP package for submission to ChecklistBank or for external citation.

64.2 Prerequisites¶

To become a taxon group expert for a module, an admin must add you to that group's expert list via Taxa Management (/taxa-management).

64.3 Accessing the Checklist Page¶

Navigate to /checklist/ in your BIMS instance.

64.4 Page Layout¶

The page is split into two areas:

Left sidebar - Filters - Module dropdown - select the biological module (TaxonGroup) whose versions you want to view. - Status dropdown (visible to publishers only) - filter between All, Published, and Draft. - + Add Version button (visible to superusers only).

Main area - Version table

64.5 Viewing Version Details¶

Click any version string in the table to open the version detail panel. It shows all metadata fields: module, status, taxa count, changelog summary, DOI, previous version UUID, internal notes, and audit timestamps.

64.6 Creating a New Draft Version¶

Only superusers can create draft versions.

64.6.1 Step 1 - Open the Add Version modal¶

Click the + Add Version button in the left sidebar.

64.6.2 Step 2 - Fill in the version form¶

64.6.3 Step 3 - Save as draft or publish immediately¶

• Save as draft - the version is created with Draft status. You can publish it later from the table.
• Save and publish - the draft is created and immediately queued for publishing. You will be asked to confirm before proceeding.

64.7 Publishing a Draft Version¶

Publishing can be triggered two ways:

1. At creation - click Save and publish in the Add Version modal.
2. From the table - click the Publish button on any existing draft row.

Both routes require you to confirm. After confirmation:

• The version status changes to Publishing (orange badge with spinner) immediately.
• A blue banner appears above the table: "Publishing version — building taxa snapshot, this may take a moment…"
• The page polls every 3 seconds and reloads the table automatically when publishing completes.

64.7.1 What happens during publishing¶

1. All validated taxa belonging to the module and its child groups are collected.
2. Each taxon is diffed against the previous version's snapshot to determine its change_type.
3. A snapshot row is written for every taxon (one INSERT, never modified later).
4. Taxa count, additions count, updates count, and deletions count are recorded on the version.
5. The version status changes to Published and published_at is stamped.

64.8 Updating a DOI on a Published Version¶

After a version is published, its DOI can be updated without re-publishing the version. This is useful when a DOI is reserved before publishing but only registered (activated) with the DOI provider afterward, or when a DOI needs to be corrected.

64.8.1 Who can update a DOI¶

64.8.2 Steps¶

1. Locate the published version in the checklist table.
2. Click the version string to open the version detail panel.
3. Click the Edit DOI button (pencil icon) next to the DOI field.
4. Enter or paste the new DOI value (e.g. https://doi.org/10.XXXX/YYYY).
5. Click Save. The DOI is updated immediately on the version record and will be reflected in any subsequent ColDP ZIP exports.

Note: Updating a DOI does not alter the immutable taxa snapshot or changelog counts. It only updates the metadata field on the ChecklistVersion record.

64.9 Understanding the Changelog¶

The Changes column shows how this version differs from its previous_version:

A dash (—) means no previous version was set, or all counts are zero.

64.9.1 Tracked fields for change detection¶

scientific_name, rank, authorship, taxonomic_status, parent, basionym, kingdom, phylum, class, order, family, genus, vernacular_names, distributions, reference_id.

64.10 Downloading a Checklist Export¶

Each published version has a download dropdown in the Actions column. Click the download icon to open the menu and choose one of the four export formats.

64.10.1 Available formats¶

64.10.2 ColDP ZIP contents¶

64.10.3 Receiving the file¶

When the export task completes you will receive an email with a download link. Large modules may take a few minutes. You can also re-open the download dialog from the same dropdown and use the link in the status popup once it appears.

64.11 Removing a Published Version¶

Authorized users (superuser or assigned taxon group expert) can remove a published version by clicking the Remove button in the Actions column and confirming.

Removal runs in the background and: - Deletes all snapshot rows for that version. - Clears checklist_version_uuid and last_checklist_published_uuid on affected Taxonomy rows. - Deletes any associated ColDP ZIP download files. - Deletes the ChecklistVersion record.

Warning: Removal is permanent and cannot be undone.

64.12 Version Chain¶

Each version points to its predecessor via previous_version, forming an auditable chain per module:

v2023.1 ──► v2024.1 ──► v2024.2 ──► v2025.1
  │              │            │
  │              │            └── 3 additions, 1 update
  │              └── 5 additions, 2 updates
  └── initial release (all taxa are additions)

Setting previous_version = None (first release) marks every taxon as an addition.

64.13 Version UUIDs on Taxonomy Records¶

After publishing, BIMS stamps two version UUIDs on each Taxonomy record:

These UUIDs appear in the Taxonomy REST API and in generated PDF headers:

Module:               Freshwater Invertebrates
Version:              2025.1
Version UUID:         a1b2c3d4-0000-0000-0000-000000000000
Previous version:     d4e5f6e7-0000-0000-0000-000000000000
DOI:                  https://doi.org/10.XXXX/YYYY
Changes this ver:     5 additions, 2 updates
Generated:            2025-04-01

64.14 API Endpoints¶

64.14.1 List endpoint filters¶

64.15 Per-Module Visibility (checklist_enabled)¶

Each TaxonGroup has a checklist_enabled boolean (default False). Only modules with checklist_enabled = True are listed in the public /api/checklist-version/ endpoint and included in external ColDP feeds. The checklist management page itself uses the module category filter, so all taxon groups appear regardless of this flag.

64.16 Troubleshooting¶

Publish button is not visible on a draft row You are not a superuser and are not listed as an expert for that taxon group. Ask an admin to grant you expert access via Taxa Management.

Status stays "Publishing" for a long time The Celery background worker may be overloaded or stopped. Contact your system administrator to check the worker queue. The is_publishing flag will remain set until the task completes or fails. If the task fails, the flag is automatically cleared so the Publish button reappears.

Changes column shows a dash for a published version Either previous_version was not set (all taxa are additions but the +N count equals the total so no special formatting is needed) or all counts are zero. Check the version detail panel for the raw counts.

ColDP ZIP download never completes The export task runs via Celery. If the download dialog stays open indefinitely, contact your system administrator to check the worker. You can close and re-click the download icon to reuse the same in-progress download request.

"Version already exists for this module" error The version string you entered is already in use for this module. Choose a different string, e.g. increment the minor version or append a suffix.