Support linked mapping-only sources for CIEL SNOMED-CT and ICD-11 mappings

User story

As a CIEL terminologist and release maintainer, I want CIEL's SNOMED-CT and ICD-11 mappings stored in separate mapping-only sources that still behave as part of CIEL, so we meet licensing constraints without losing the concept view, API results, bundles, or OpenMRS-compatible exports we rely on today.

Use case

A curator adds a SNOMED-CT SAME-AS mapping to CIEL concept 1234 in CIEL Lab. The mapping is stored in /orgs/CIEL/sources/map-SNOMED-CT/, but OCL Web, the OCL API (includeMappings, /concepts/1234/mappings/, $cascade) and the next CIEL release export still show it together with the concept's other mappings, and the OpenMRS dump still contains it.

Requirements

• Move CIEL mappings whose target is /orgs/IHTSDO/sources/SNOMED-CT/ or /orgs/WHO/sources/ICD-11-WHO/ out of /orgs/CIEL/sources/CIEL/ into dedicated mapping-only sources.
  • SNOMED-CT → /orgs/CIEL/sources/map-SNOMED-CT/.
  • ICD-11 → a mapping source following the same convention (name to be confirmed).
  • Mapping-only sources contain mappings only; from_concept_url keeps pointing at CIEL concepts.
• Add a CIEL source configuration (oclapi2) that declares linked mapping sources per target source, e.g. /orgs/IHTSDO/sources/SNOMED-CT/ → /orgs/CIEL/sources/map-SNOMED-CT/.
• Reads (oclapi2): with the configuration in place, CIEL concept responses return linked mappings as they do today.
  • Concept detail with includeMappings / includeInverseMappings.
  • /concepts/{id}/mappings/.
  • Concept search indexing of mapped codes.
  • Linked mappings are returned only when the caller has view access to the linked mapping source.
• Writes (oclapi2): inline mappings sent in a CIEL concept create/update whose target matches a configured target source are persisted in the linked mapping source, not in CIEL.
• Bundles (oclapi2): $cascade and collection reference cascade on a CIEL source version include mappings from the linked mapping sources.
• Versioning: a CIEL source version must be resolvable to the matching versions of its linked mapping sources, so a released version is reproducible.
• Exports: keep a way to produce the OpenMRS-compatible outputs we produce today.
  • OpenMRS SQL dump (CIEL Lab release) contains the same SNOMED-CT and ICD-11 concept_reference_map rows as before the split.
  • OCL export / subscription consumed by openmrs-module-openconceptlab (single subscription URL) still delivers CIEL concepts with their linked mappings for authorized consumers.
  • A CIEL-only export without the linked mappings remains possible.
• CIEL Lab (ciel-lab-v2) treats CIEL plus its linked mapping sources as one logical source.
  • Configuration for linked mapping sources next to OCL_CIEL_SOURCE_URI.
  • HEAD mirror, staged changes and QA include linked mappings.
  • A mapping write to a linked mapping source re-syncs the from-concept in the HEAD mirror.
  • Release creates the linked mapping source versions together with the CIEL version and builds the SQL dump from the combined content.
• Migration preserves mapping identity and history.
  • Preserve external_id (used as OpenMRS concept_reference_map.uuid), map type, retired state and extras.
  • Existing released CIEL versions remain unchanged.
• Decide and document before implementation:
  • Exact licensing constraint: who may view/export SNOMED-CT and ICD-11 mappings (public access of the mapping sources and of combined exports).
  • Where the configuration lives on the Source model (new field vs. existing attribute) and its API contract.
  • How CIEL and mapping source versions are paired (same version id vs. recorded pairing).
  • Delivery shape for OpenMRS: combined source export, collection composing CIEL + mapping sources, or CIEL Lab merge.
  • Whether mapping ids (mnemonics) are kept or reassigned in the new sources.

Acceptance criteria

• Given CIEL has a linked mapping source for SNOMED-CT, when a user with access requests a CIEL concept with includeMappings=true, then its SNOMED-CT mappings stored in map-SNOMED-CT are returned with the same fields as today.
• Given a user without view access to map-SNOMED-CT, when they request the same concept, then SNOMED-CT mappings are not returned and no error is raised.
• Given a CIEL concept update containing a new SNOMED-CT mapping, when it is saved, then the mapping is created in map-SNOMED-CT and no SNOMED-CT mapping is created in /orgs/CIEL/sources/CIEL/.
• Given a CIEL source version with paired mapping source versions, when $cascade runs on a CIEL concept, then the bundle includes its linked SNOMED-CT and ICD-11 mappings.
• Given the split is applied, when CIEL Lab builds the OpenMRS SQL dump for a release, then SNOMED-CT and ICD-11 concept_reference_map rows match a pre-split dump of the same content, including uuids.
• Given an OpenMRS instance subscribed to the CIEL delivery URL, when it imports the next release, then SNOMED-CT and ICD-11 mappings are imported as before.
• Given the migration ran, then no SNOMED-CT or ICD-11 mappings remain in /orgs/CIEL/sources/CIEL/ HEAD and previously released CIEL versions are unchanged.
• Given a mapping is saved in a linked mapping source through CIEL Lab, then the HEAD mirror and staged changes show it on the from-concept.
• Open decisions above are answered and recorded before implementation starts.

More details (collapsible)