External Organisation Catalogue
Epic summary
The External Organisation Catalogue stores organisations that interact with a MedCES tenant but do not belong inside its organisational LTREE.
Examples include the National Medical Commission, a health-sciences university, a state counselling authority, a government department, or an affiliated hospital. Creating an organisation records its identity only; a separate relationship explains how it applies to an institute or programme.
Before you start
The platform must already contain the standard organisation types and jurisdictions. If the organisation is being imported from another system, the source system and its code format must also be known.
Actors and access
| Access source | Access in this epic |
|---|---|
| Platform Admin | Maintains technical identity, duplicate resolution, and platform-wide mappings |
| Institute member with Academic Registrar role | Proposes regulators, universities, and issuing authorities needed by an institute |
| Tenant member with Governance Registrar role | Requests a missing organisation and views approved records |
| Auditor role | Reviews identity sources, merges, and history |
Screen structure and data captured
The workspace contains Organisation Details, Classification, Identifiers, Contacts, Source Evidence, Mappings, and History.
| Field | Required | Meaning and validation |
|---|---|---|
| Legal name | Yes | Official current name |
| Display name | Yes | Familiar name used in selectors |
| Organisation type | Yes | Regulator, university, counselling authority, government body, hospital, or another governed type |
| Jurisdiction | Yes | National, state, university, or other defined jurisdiction |
| Parent external organisation | No | Administrative grouping only; does not enter the tenant LTREE |
| Official identifiers | Conditional | Code, registration number, government identifier, or source-system ID |
| Effective dates | Yes | Period in which this identity/name is valid |
| Address and contacts | No | Official correspondence information |
| Source evidence | Yes | Website, notification, order, or verified source document |
| Status | Yes | Draft, Under Review, Published, Superseded, or Archived |
Use case 1: Register an external organisation
As a Platform Admin
I want to register a verified external organisation
So that tenants select one shared identity instead of recreating it.
Acceptance criteria
- The administrator records the legal name, type, jurisdiction, effective dates, and source evidence.
- Duplicate detection compares official identifiers, normalised names, and known aliases.
- A draft organisation cannot be used in a published tenant relationship.
- Publication records the reviewer and source version.
Negative cases and alternate flows
- Probable duplicate: Require review of the existing record before creating another.
- Unverified body: Keep the record in Draft and prevent operational selection.
- Name change: Create an effective-dated identity version and preserve the former name as an alias.
Use case 2: Maintain identifiers and aliases
As a Platform Admin
I want to maintain official identifiers and historical names
So that imports and users resolve the correct organisation.
Acceptance criteria
- Identifier uniqueness is enforced by identifier scheme and issuer.
- Aliases retain language, validity, and source.
- Import mappings identify the source system and external code.
- An identifier already used by another active organisation cannot be reassigned without a controlled merge.
Use case 3: Merge duplicate organisations
As a Platform Admin
I want to merge a proven duplicate into the canonical organisation
So that existing relationships remain valid without duplicated reporting.
Acceptance criteria
- The screen previews relationships, packages, mappings, and documents referencing both records.
- The canonical record is explicitly selected.
- Conflicting identifiers or overlapping versions block automatic merge.
- References are redirected through an audited migration; the duplicate remains as a redirect/tombstone.
Business rules
- External organisations never receive a tenant LTREE path.
- Organisation type describes identity; the role it performs for a tenant is recorded as a relationship.
- One organisation may be both affiliating and examining through separate relationships.
- Archiving prevents new use but does not remove existing relationships or source history.
Technical design
Conceptual schema
| Record | Important fields |
|---|---|
org.external_organisation | id, legal_name, display_name, organisation_type_id, jurisdiction_id, valid_from, valid_to, status |
org.external_organisation_identifier | organisation_id, scheme, value, issuer, is_primary, valid_from, valid_to |
org.external_organisation_alias | organisation_id, alias, language, valid_from, valid_to |
integration.external_organisation_mapping | source_system, external_code, organisation_id, mapping_status |
org.external_organisation_redirect | retired_organisation_id, canonical_organisation_id, merge_event_id |
Process-layer responsibilities
- Normalise names and identifiers for duplicate detection without discarding the entered official form.
- Validate identifier uniqueness and effective-date overlap.
- Resolve redirects so downstream consumers always receive the canonical identity.
- Run impact analysis before merge or archival.
- Prevent external organisations from participating in tenant descendant-access queries.
Success outcome
Every external authority or organisation has one verified reusable identity, while its tenant-specific role remains explicit and separately governed.