User guides

• 1: Discover and map data
• 2: Data import workflow
• 3: Organize and publish datasets
• 4: Import phylogenies into the backbone
• 5: Define Traits and record Measurements
• 6: Curate shared libraries
• 7: Trait governance and curation
• 8: Vouchers, labels, and requests
• 9: Tutorials

1 - Discover and map data

Who can use it

Visitors can search public content. Authenticated users can also see records released to their access level or made available through projects, datasets, or biocollections. The same filters may therefore return different results to users with different permissions.

Choose a tool

• Use record lists to search one object type and follow its relationships.
• Use Data Explorer to combine filters across related data records.
• Use Map Explorer to inspect spatial distributions and open Location and Individual details.
• Use the GET API or OpenDataBio-R for reproducible queries and analysis.

Start with the smallest useful set of filters. Check whether Taxon and Location filters include descendants, and use Project or Dataset filters when provenance or data policy matters. Inspect representative records before exporting.

Maps and exports

Map Explorer displays Locations, Individuals, plots, and transects. Large results use vector tiles and simplified geometries for navigation; use the official record or export geometry for analysis.

Small exports may be returned directly; large exports run as UserJobs. Follow the job progress and log, review warnings, then keep the README and field metadata with the downloaded data. A query export is a result at one moment; cite a dataset version when fixed, published content is required.

Exports may include OpenDataBio and Darwin Core fields. Botanical installations may also offer the BRAHMS/INPA profile for Individual- or Voucher-based exchange. Select the base record explicitly and review its metadata: the profile does not turn incomplete records into complete curatorial data.

Continue with Getting data with R.

2 - Data import workflow

A reliable import is iterative: prepare one dependency, search existing shared records, send a small batch, recover generated IDs, reconcile them with the source table, and validate the result before importing dependent objects.

Prepare and order dependencies

Define the destination Project and Dataset, confirm permissions, preserve an immutable source copy, and add a unique local key such as source_row_id. Normalize encoding, dates, missing values, decimals, and column names. Search shared People, References, Taxons, Locations, and Traits before creating them, and check the POST API. Keep both the source key and ODB ID or UUID.

Validate coordinates first

POST locations-validation accepts decimal latitude and longitude and reports registered Locations containing each point. Use it before creating Individuals or automatic point Locations to find swapped axes, wrong signs, unexpected administrative areas or protected areas, duplicates, and unsuitable precision. It reports relationships with existing Locations; it does not decide whether a coordinate is scientifically correct.

The UserJob cycle

1. Submit representative pilot rows and save the UserJob ID.
2. Follow status, progress, and logs; do not resubmit while processing.
3. Review every row’s status, ID, recognition fields, errors, and warnings.
4. Join results back to source_row_id; never rely on position after sorting.
5. GET created or reused records and compare essential fields and relationships.
6. Correct and resubmit only pending rows, preserving every job ID.
7. Use validated IDs in the next dependency stage.

A successful job may still contain warnings or reused records. A useful working table keeps source_row_id, odb_status, odb_id, odb_uuid, odb_error, and odb_warning. An import is complete only when every row is documented, warnings reviewed, IDs reconciled, server records checked, counts and permissions verified, and source files and UserJob results preserved.

Continue with the R import tutorials.

3 - Organize and publish datasets

Roles

• Visitors and viewers read or download content allowed by policy.
• Collaborators work with authorized records but do not manage membership, policy, or publication.
• Dataset administrators manage access, participants, metadata, and versions.
• Super administrators can maintain any dataset, but scientific stewardship and publication decisions belong to the responsible team.

Dataset versus dataset version

A dataset is a managed collection that may keep changing. It organizes records and participants and controls access. Page visibility does not by itself publish every record or grant a reuse license.

A dataset version is a fixed distribution snapshot with its own UUID, date, and files. Use the dataset page for ongoing work and the version UUID for links, citations, and reproducible analyses.

Before publication, review title, description, project, participants, access, license, use policy, download agreement, ordered authors and roles, references, record scope, filters, taxonomic-list sharing, related datasets, and metadata.

To publish, define version, date, scope, and filters; review authorship, license, policy, citation, and metadata; generate and follow the UserJob; open the UUID page; download the main and media files; and check the README, field definitions, counts, sample records, agreement, and access as a non-administrator.

Version files are persistent and must be included in backups. Correct the managed dataset and publish a new version instead of silently replacing files from an already cited version. Usage logs support reporting but do not change permissions or prove how data were used.

4 - Import phylogenies into the backbone

Import compares source-tree terminals and relationships with existing Taxons. Labels must be reconciled with local taxonomic concepts. Importing a tree does not incorporate it automatically; it creates a proposal for review.

Preserve the source file, register its reference or DOI, check terminal labels and homonyms, create or validate missing Taxons through the normal taxonomic workflow, and document the target clade and intended interpretation. After import, review unmatched terminals, ambiguous matches, taxonomic conflicts, and relationships incompatible with the current backbone.

Backbone incorporation affects an installation-wide shared library and requires super-administrator review and approval. While experimental, this documentation does not promise general publication, sharing, analysis, versioning, or export of phylogenies; visible interface features may only support import review.

5 - Define Traits and record Measurements

Traits are shared variable definitions; Measurements are their values recorded for Locations, Taxons, Individuals, Vouchers, or Media. Define the Trait before collection, because changing its meaning after others use it can invalidate data. For ownership, curator permissions, duplicate consolidation, statuses, and translation tools, see Trait governance and curation.

Before creating a Trait

Search name, export_name, unit, and definition; select the measured object; describe method, instrument, position, precision, and protocol; reuse a unit with the same meaning; cite the protocol when applicable; and define validation rules. Similar names and units do not guarantee equivalent methods. The unique export_name should be stable, short, and contain no spaces or accents.

Choose the type

• Quantitative real: decimal measurements, normally with unit and range.
• Quantitative integer: counts and other integers.
• Categorical: one unordered category.
• Categorical multiple: several simultaneous categories.
• Ordinal: one category whose rank represents order.
• Text: observations that should not be categories.
• Color: a validated hexadecimal color.
• Link: a Taxon or Voucher, optionally with an associated count.
• Spectral: a value vector with a defined expected length.
• GenBank: a molecular accession linked to an Individual or Voucher.

Categories need stable meanings, descriptions when necessary, and consistent translations. Rank is part of an ordinal Trait’s definition. Do not encode a genuinely quantitative measurement as numbered categories.

Record and review Measurements

Every Measurement identifies its Trait, measured object, responsible Person, date, and access-controlling Dataset. Add a Reference for values extracted from publications. Before a bulk import, create one Measurement in the interface, test validation and object type, submit pilot rows, review the UserJob, reconcile returned IDs, and GET the result to verify value, date, Person, and object.

See importing Traits with R and importing Measurements with R.

Use forms

Web forms arrange Traits and required fields. A Form Task applies the protocol to target objects and tracks what remains unmeasured. Mobile forms supply OpenDataBio Collect with protocols, Taxons, objects, geolocation, photographs, and offline measurement fields. Define Dataset, Traits, units, and categories first; assign users; test a few objects; synchronize; and review Measurements, coordinates, Media, and logs before full deployment.

Changes after use

The creator can edit a valid Trait while it is unused or used only in Datasets where the creator is an administrator. Trait curators can maintain the public library globally. Categories already used in Measurements require a curator to redefine or reorder them. Coordinate cross-user corrections through the governance workflow instead of silently changing a shared concept.

6 - Curate shared libraries

Taxons, People, Bibliographic References, Locations, Traits, and vernacular names are installation-wide libraries. Search before creating, and remember that a global correction may affect many Datasets.

External Taxon validation

Full users may validate a Project, Dataset, or taxonomic root. Work on a small scope, inspect the UserJob, separate safe results from conflicts and missing Taxons, and choose a source appropriate to the group. Review Index Fungorum for fungi, Tropicos and IPNI for plants, and use GBIF as a broad source without assuming it resolves every conflict. Accept parent changes only when the local hierarchy should change. Apply permitted changes and submit suggestions for the others. Conflicts between sources require curatorial judgment.

Duplicate-Taxon merging is restricted to super administrators. Compare authorship, publication, validity, accepted name, parent, external keys, and descendant use. Homonyms and distinct concepts are not duplicates.

Shared Locations

Countries, administrative units, protected areas, Indigenous lands, environmental layers, plots, and transects are shared. Search name, hierarchy, type, and geometry first. Do not duplicate a country or municipality merely for another spelling or language. Coordinate new countries and large administrative imports with super administrators because they affect parent detection and coordinate validation.

For protected or environmental layers, record source, date, geometry version, and correct type; use WGS84; validate polygons; and check overlaps and existing versions. For plots and transects, use distinctive names and verify parent, geometry, orientation, dimensions, subplots, search width, datum, and units.

Some imports automatically create point Locations from Individual coordinates. Check whether that mechanism fits before creating points in bulk. Full users may edit Locations only while they have no linked Individuals, Vouchers, Measurements, or Media. Once used, only a super administrator may alter them; deletion also requires no descendants or related data.

Duplicate People and References

Search name variants, abbreviation, institution, email, and ORCID before creating a Person. Super administrators may merge duplicates and redirect collection, authorship, identification, measurement, expertise, and unpublished name relationships. Confirm the same real person, select the most complete primary record, inspect User links and conflicting roles, then review all relationships. Never merge homonyms.

Search DOI and BibTeX key before creating a Bibliographic Reference. If either already exists, compare and correct the existing record when it represents the same publication; do not change a key just to force a duplicate.

Vernacular names

Record language and use citations for source, context, and regional variation. The same spelling in different languages or regions does not necessarily express the same use. Full users may create names; ordinary users may edit only their own, and deletion is blocked by citations owned by others. Search name and language, inspect linked objects, and prefer adding a relationship or citation to creating a duplicate.

7 - Trait governance and curation

Traits form a public, installation-wide library. Dataset permissions control the Measurements that use a Trait; they do not turn the Trait definition into a private Dataset resource. Trait governance therefore protects both scientific meaning and every Dataset that reuses the definition.

Installation and upgrade

For a new installation, choose interface and user-content locales during setup; assisted translation remains disabled unless the administrator explicitly configures a provider. After an upgrade, run database migrations, php artisan locales:audit, clear configuration caches and restart queue workers. The migration initializes existing Traits as valid, records the first super administrator as creator when available, and creates the governance and duplicate-review tables; no separate Trait backfill is required.

After installation, a super administrator may assign Trait curator on a full user’s profile. Curators can then review the shared library. Configure optional translation, Tropicos and e-mail services as described in Administrator configuration.

Trait lifecycle

Every Trait has a creator and a status:

• valid: an active definition that may be selected for new Measurements;
• duplicate: an alias consolidated into another Trait, identified by canonical_trait_id;
• deprecated: retained for provenance but not recommended for new use.

Deleting an unused Trait owned by the current user permanently removes it when it has no protected usage or dependencies. This also applies to normal batch deletion. Other eligible deletions archive the Trait with a soft delete, keeping its relations and history available for restoration.

When duplicate Traits are consolidated, Measurements, forms, references, tags, object types, and compatible categories are reconciled with the retained Trait. The old Trait remains as a duplicate alias. A Measurement import that refers to that alias is redirected to the canonical Trait.

Who can do what

In the Trait model-index, normal deletion automatically purges an isolated Trait owned by the acting user. For records owned by someone else, curators and administrators must explicitly select Permanently delete eligible Traits; without that option the deletion remains recoverable. Every selected record is checked independently, and protected Traits are rejected.

The Trait model-index separates Active Traits, Merged duplicate Traits, Deprecated Traits, and soft-deleted Archived Traits. Merged aliases are visibly marked and link to the canonical Trait. Measurement totals shown in the Trait list count all linked Measurements because the Trait library is public; opening that total still applies Dataset access rules, so a user may see fewer Measurement records than the public aggregate.

Full users may select Archived Traits in the Trait model-index and open an archived definition. This read-only access explains an import collision with a reserved export_name; the import result also reports the archived Trait id. It does not grant restoration or curation rights. In the archived view, curators and administrators may restore selected records or permanently delete eligible ones. A creator may permanently delete their own isolated legacy archived Trait from its detail page. Registered users continue to see active Traits only.

A Project or Dataset administrator does not automatically become a Trait curator. Dataset administration is nevertheless relevant to the creator rule: the creator may correct a used Trait directly only when they administer every Dataset containing its Measurements. Once other Datasets depend on the definition, the correction must be handled by a Trait curator.

Changing or adding a category can change the meaning of existing categorical Measurements. Categories already used by Measurements may only be redefined or reordered by a Trait curator.

Review possible duplicate Traits

Full users can open Measurements → Review possible duplicate traits, search for one Trait by export name, name, or description, and compare it with the suggested records. The comparison uses multilingual names and descriptions and requires the same Trait type. Numeric Traits may still be reported when their units differ: units can be converted, and therefore should not suppress a scientific duplicate warning.

A full user cannot consolidate records. They submit a suggestion and can later see whether it is pending, confirmed, or rejected. Curators review those suggestions in the same tool.

Trait curators may also select Scan the complete trait database. The scan runs as a background UserJob and groups connected similarity matches instead of showing only isolated pairs. Load the result after the job finishes, then review the name, description, type, unit, and Measurement count shown for every member. Large result sets are paginated, and their full state is kept in a short-lived server cache so the browser does not resend every group on each decision.

For each member of a group, the curator chooses:

• No decision: leave it for later;
• Record to retain: the canonical definition;
• Merge: consolidate this Trait into the retained record;
• Delete permanently: remove an isolated Trait without merging it, when the current user is authorized and the Trait has no protected usage or dependency;
• Not a duplicate: record that this pair represents different concepts.

Save decisions persists non-duplicate judgments while leaving merge and delete choices available for execution. Mark all as not duplicates changes every member to that judgment, saves all pairwise decisions, and disables execution because no operational action remains. Execute decisions first inspects structural compatibility and authorization, then submits selected merges and permanent deletions as a UserJob. Detection is intentionally broader than execution: for example, Traits with different units can be detected as possible duplicates, while an unsafe merge may be rejected until the unit/value implications are resolved.

A non-duplicate decision is pair-specific, not a judgment about the whole group. Future scans ignore that pair. If a relevant name, description, type, unit, category, range, parent, or other conceptual field changes, related decisions are invalidated so the pair can be evaluated again.

Missing content translations

Traits, Trait categories, Trait units, Tags, Projects, and Media contain user-authored translatable content. When a translation provider is configured, the navigation displays Missing translations.

Google-assisted translation saves repetitive multilingual work but is never a scientific authority: previews and bulk results must be reviewed. It is optional and unavailable while USER_TRANSLATION_PROVIDER is empty.

The validation action starts a UserJob that checks every enabled content locale and reports missing fields that the current user is authorized to update. A missing field without source text is reported but cannot be generated. The correction action rechecks the record, authorization, source, target, character limit, and whether another user has already supplied the text before calling the provider and saving a result. Always inspect the UserJob results and review the generated scientific terminology.

Forms can also generate missing fields while a record is being edited. The translation API provides a preview endpoint and a separate save endpoint, so a client can review generated content before persistence.

Trait POST and PUT do not machine-translate missing locales. They store only translations explicitly submitted by the client; a partial PUT preserves translations in omitted locales. This separation prevents an import from silently publishing unreviewed terminology.

The same similarity check used by the form also protects API POST and PUT. A row with possible duplicates is rejected with candidate identifiers. After review, a genuinely distinct concept may be resubmitted with confirm_similar_trait=true; this explicit acknowledgement is per row and must not be applied blindly to an entire import.

See also Traits and Measurements and Import Traits with R.

8 - Vouchers, labels, and requests

Batch identification and Vouchers

Before identifying Individuals in a batch, review the selection, Taxon, identifiers, date, modifier, reference, and notes. Follow the UserJob and inspect Identification History, which preserves previous determinations.

A Voucher represents physical material from an Individual deposited in a Biocollection. Check its source Individual, collection and catalog number, collectors and date, nomenclatural type, references, and media. Vouchers inherit the Individual’s identification and Location. Attach a Measurement or Medium to the Voucher only when it describes that physical sample.

Generate labels

Select a small test set, object and sheet format, dimensions, margins, and content. Preview and print one sheet at 100%, verify codes, names, collection numbers, and identifiers, and only then generate the full batch. A saved preset stores print configuration, not a frozen copy of the selected records. Public presets may be reused or duplicated, but only their owner may change them.

Biocollection requests

Requests are available when at least one Biocollection is managed by the installation. They support two distinct cases: depositing material already represented by Individuals, and requesting material already deposited in a collection. This is separate from requesting access to a Dataset.

Deposit material and register Vouchers

Use this workflow after registering collection data as Individuals:

1. review each Individual’s Location, collectors, date, and identification;
2. select the Individuals and destination Biocollection;
3. request Voucher registration and follow the UserJob that creates the request;
4. a collection administrator or collaborator reviews the items and may record corrections or apply the requested identification update;
5. when accepted, the collection selects the new Vouchers’ Dataset and first catalog number; OpenDataBio creates one sequentially numbered Voucher per Individual;
6. review which items were registered or denied.

Only administrators and collaborators of the Individual’s Dataset may include it. The interface also requires these Individuals to belong to a Dataset open to the public or to registered users so collection staff can evaluate them.

Registration changes editing responsibility in a managed collection:

• only collection members may edit its Voucher;
• only users belonging to all managed collections linked to an Individual may edit that Individual, including its identification and Location;
• the installation super administrator retains administrative access;
• Measurements and Media do not pass to collection control and continue to follow their own Dataset permissions.

The depositor retains authorship and access defined by the Datasets, but cannot continue editing the collection-curated record unless also on collection staff.

Request a material loan

Use this workflow for Vouchers already held by a managed Biocollection:

1. find and select the Vouchers;
2. provide institution, contact, purpose, and intended conditions;
3. follow each Voucher’s status separately;
4. collection staff check the items and record the loan or denial;
5. staff record return, or donation when that is the agreed outcome.

Implemented states distinguish requested, checked, lent, denied, returned, and donated items. They document processing in OpenDataBio; packing, shipping, deadlines, and institutional agreements remain the collection’s responsibility.

The requester creates and tracks the request. Collection administrators and collaborators may annotate and process it; for multiple collections, the user must belong to all of them. Editing administrative request data requires being an administrator of every involved collection, except for a super administrator. Status and history belong to each item, so one request can have mixed outcomes.

9 - Tutorials

The tutorials apply the concepts and user guides through reproducible workflows with the OpenDataBio-R package.

• Get and review data with R
• Prepare and import data with R
• Import Traits with R
• Import Measurements with R
• Overview, recommended sequence, and planned improvements

Before importing, also read the Data import workflow, which explains dependencies, validation, and reconciliation of UserJob results.