nowdatabase/documentation/functionality/species_merge.md

Species Merge

The Species Merge tool replaces all obsolete species ids with a selected accepted species id, while preserving occurrence data, synonyms, and update logs. This flow is Admin-only and uses the same reference-selection and save procedures as other DetailView updates.

UI Flow Summary

1. Select an Obsolete taxonomy and an Accepted taxonomy.
2. Review the Selected taxonomies table (side-by-side values on the same row).
3. Choose whether to copy selected parameters from obsolete to accepted.
4. Decide whether to append the obsolete species name to locality-species source_name values.
5. Resolve occurrence conflicts (only shown when obsolete values exist and differ from accepted).
6. Decide whether to add the obsolete species as a synonym (optional comment).
7. Proceed to Reference selection (staging view) and save.

After a successful merge, the UI navigates to the accepted species detail page.

Selected Taxonomies Table

• Displayed as a single table with columns: Field, Obsolete taxonomy, Accepted taxonomy.
• Field names are bold and rows are striped for quick comparison.

Copy Selected Parameters

The copy list is intentionally tight:

• Shows only fields where the obsolete value is non-empty and differs from the accepted value.
• Taxonomic fields are excluded (see list below).
• Additional excluded fields: class_name, used_morph, used_now, used_gene, sp_status.

When the admin selects the obsolete value for a field, the accepted species is updated with that value during merge.

Taxonomic Fields Excluded

• order_name
• family_name
• genus_name
• species_name
• subclass_or_superorder_name
• suborder_or_superfamily_name
• subfamily_name
• unique_identifier

Occurrence Conflict Resolution

Occurrence conflicts are listed per locality only when:

• the obsolete value exists, and
• the obsolete value is different from the accepted value.

Selections are applied during merge to update accepted occurrence rows and migrate obsolete rows.

References and Save

The merge flow uses the same staging/reference selection flow as other entity edits:

• References are required.
• Save triggers the merge and logs updates in the update log tables.

API Endpoints

Backend endpoints are defined in backend/src/routes/speciesMerge.ts and implemented in backend/src/services/speciesMerge.ts:

• GET /admin/species-merge/summary?obsoleteId=<id>&acceptedId=<id>
• POST /admin/species-merge

Payload and response shapes are defined in frontend/src/shared/types under SpeciesMergeRequest, SpeciesMergeSummary, and SpeciesMergeResponse.