Admin Guide

This guide is for administrators managing proposals, guest access, and data exports.

Admin Access

Admin privileges are controlled via the ADMIN_USERS environment variable:

ADMIN_USERS=username1,username2,username3

Once configured, admin users will see:

  • Admin and Guest Codes links in the top navigation
  • "Admin" badge next to their username
  • Access to proposal management, guest code management, and export tools

KE-WP Proposal Management

Viewing Proposals

Navigate to Admin to access the KE-WP proposals dashboard with:

  • Filterable table of all proposals
  • Status indicators (Pending / Approved / Rejected)
  • User contact information and provenance details
  • Proposed changes detailed view

Reviewing Proposals

  1. Click View Details to see full proposal information
  2. Review the proposed changes:
    • New mapping submission (proposal-first workflow)
    • Delete mapping request
    • Confidence level change
    • Connection type modification
  3. Check user rationale and contact information

Approving Proposals

  1. Click Approve button
  2. Changes are immediately applied to the mapping (or a new mapping is created)
  3. Provenance fields (approved_by, approved_at) are recorded
  4. Proposal status updated to "Approved"

Rejecting Proposals

  1. Click Reject button
  2. Optionally add admin notes explaining the rejection
  3. Proposal status updated to "Rejected"
  4. Original mapping remains unchanged

Bulk Approval

All three proposal queues support approving many proposals at once. Tick the checkboxes on the rows you want, review the selection in the side panel, and confirm.

The whole batch is applied in a single database transaction: if any one proposal in the selection fails, the entire batch is rolled back and nothing is applied. This is deliberate — a partially-applied batch would leave the queue in a state that is hard to reason about. Each approval is written to the audit log individually, so bulk approval is just as traceable as approving one at a time.

Tip: bulk approve is most useful after a curation workshop, when a single trusted curator has submitted a run of mappings. Spot-check a sample rather than approving a large batch unseen — approval is what publishes a mapping to the public API.

KE-GO Proposal Management

GO mapping proposals are managed separately. Access via the GO Proposals link on the admin page, or navigate directly to /admin/go-proposals.

The workflow is the same as KE-WP proposals: review, approve (creates/updates GO mapping), or reject with notes.

KE-Reactome Proposal Management

KE-Reactome proposals live at /admin/reactome-proposals, accessible from the admin page. The workflow mirrors KE-WP and KE-GO: review the proposal payload, approve (creates / updates the Reactome mapping) or reject with notes.

Note: the curator-side Reactome tab shows an "under development" notice while suggestion thresholds are being calibrated. The proposal pipeline itself is fully functional.

Proposal types across the three queues

A queue contains more than new submissions. Deletion and revision proposals are badged in the table so they can be told apart from new pairs at a glance — worth noticing before bulk-approving, since approving a deletion proposal removes a published mapping.

ResourceNew pairDeletionChange confidenceChange connection type
KE-WPyesyesyesyes
KE-GOyesyesyesyes
KE-Reactomeyesyes——

The Reactome gaps are deliberate, not missing features: Reactome confidence is fixed when the proposal is created, and Reactome mappings carry no connection type, so the proposal modal hides both revision blocks for that resource.

KE Description Coverage

At /admin/ke-descriptions you can see which Key Events have usable descriptions in AOP-Wiki and toggle individual KEs out of description-based matching.

This matters because suggestion quality depends on the KE text the embedding is computed from. When a KE's AOP-Wiki description is empty, boilerplate, or describes the assay rather than the biology, including it makes suggestions worse than using the title alone. Toggling that KE off falls back to title-only matching for it.

Guest Code Management

Workshop participants can log in with temporary access codes instead of GitHub OAuth. Manage codes at Guest Codes in the navigation or /admin/guest-codes.

Creating Guest Codes

  1. Click Create Code
  2. The system generates a unique access code
  3. Share the code with workshop participants

Revoking Guest Codes

Click Revoke next to any active code to disable it immediately. Revoked codes cannot be used to log in.

Exports & Zenodo

The Exports & Zenodo dashboard at /admin/exports shows the current live mapping counts beside the counts recorded in the last Zenodo deposit, so you can see at a glance how much curation has accumulated since the last release. It offers two actions:

  • Regenerate Exports — rebuilds the cached GMT and Turtle files that the /exports/… routes and the Downloads page serve. Safe to run any time; it only touches the on-disk cache.
  • Publish to Zenodo — mints a new version of the dataset under the existing concept DOI. This is public and permanent, so the button asks for confirmation first and disables itself while the request is in flight.
Publishing is irreversible. A Zenodo version cannot be withdrawn once published, only superseded by a further version. Check the live-versus-deposited counts on the dashboard first, and prefer releasing after a batch of curation has landed rather than after every individual mapping.

If the button is disabled with a warning, no Zenodo API token is configured on the container. The token is read from a Docker secret at /run/secrets/zenodo_api_token, or failing that from the ZENODO_API_TOKEN environment variable. The full install and rotation procedure is in docs/RELEASES.md; the equivalent command-line path is scripts/publish_zenodo.py, which also offers --dry-run to assemble a deposit without sending it.

Database Management

The application uses SQLite with automatic migrations on startup. The database is stored in the data/ directory.

Tables

TablePurpose
mappingsKE-WP mapping entries with UUID and provenance
proposalsChange proposals for KE-WP mappings
ke_go_mappingsKE-GO BP mapping entries with UUID and provenance
ke_go_proposalsChange proposals for KE-GO mappings
ke_reactome_mappingsKE-Reactome mapping entries with UUID and provenance
ke_reactome_proposalsChange proposals for KE-Reactome mappings
sparql_cacheCached SPARQL query responses (24-hour expiry)
Important: All admin actions are logged with timestamps and usernames for accountability. Audit trails are maintained in the database via provenance columns.

User Management

User access is managed through:

  • GitHub OAuth sign-in. Identities are stored with a provider prefix (e.g. github:alice) so the database is forward-compatible with additional providers (ORCID, LS Login, SURFconext) when their credentials are provisioned.
  • Guest access codes for workshop participants (admin-managed at /admin/guest-codes)
  • Environment variable whitelist (ADMIN_USERS) for admin privileges; supports the same provider prefixes