# Patient Merge and De-merge ## Overview When two patient records exist for the same person, a system administrator can **merge** them into a single record. The merge re-assigns all bills, encounters, investigations, and reports from the secondary (duplicate) record to the primary (surviving) record. The secondary record is then deactivated. Every merge is fully reversible via the **Unmerge** function, which restores both records to their exact pre-merge state using a stored JSON snapshot. The tools are located under **Administration → Manage Metadata → Patient Data Management**. --- ## Key Concepts | Term | Meaning | |---|---| | **Primary patient** | The surviving record — keeps its ID; all history is consolidated here | | **Secondary patient** | The duplicate — deactivated after merge; demographics preserved for unmerge | | **Merge snapshot** | A JSON copy of both patients' full demographics taken before any change | | **Affected record** | Any bill, encounter, investigation, or report re-pointed from secondary to primary | | **Unmerge** | Full reversal of a merge — restores the secondary patient and re-points all affected records back | --- ## Who Can Merge and Unmerge Users must hold the **Merge Patients** (`MergePatients`) privilege. Grant it via **Administration → Manage Users** in the relevant role's System Administration privilege group. --- ## Merge Methods ### 1. Manual Merge Use when you have already identified two specific duplicate patients. 1. Open **Administration → Manage Metadata → Patient Data Management** tab → **Patient Data Management** → **Manual Merge** tab 2. Search for and select the **Primary Patient** (the record to keep) 3. Search for and select the **Secondary Patient** (the duplicate to deactivate) 4. Review the side-by-side demographics preview 5. Optionally enter a **Merge Reason** 6. Click **Merge** and confirm the dialog The system immediately: - Saves a JSON snapshot of both patient and person records - Re-points all v1-scope records (see table below) from secondary to primary - Fills any null fields on the primary from the secondary (never overwrites existing primary data) - Sets the secondary patient to **inactive** with a note recording the merge ### 2. Deterministic Scan Automatically finds patient pairs that share an identical **NIC**, **PHN**, or **MRN**. These are near-certain duplicates — data entry error or system import caused two records to be created for the same person. 1. Open **Patient Data Management → Deterministic Scan** 2. Set a **Max results** cap (default 50, maximum 500) 3. Click **Scan by NIC**, **Scan by PHN**, **Scan by MRN**, or **Scan All** 4. The results table shows each duplicate pair with the matching field highlighted 5. For each pair: - Select which patient is the **Primary** (default: the older record by creation date) - Click **Merge** to merge, or **Dismiss** to skip this pair for now Dismiss hides a pair from the current scan session only — it does not prevent it appearing in a future scan. ### 3. Probabilistic Scan Surfaces likely duplicates using fuzzy matching on name, date of birth, and phone number. Suitable for finding duplicates created by spelling variations or transposed digits. 1. Open **Patient Data Management → Probabilistic Scan** 2. Set **Max candidate pairs** (default 100, maximum 1000) and **Name similarity threshold** (default 0.92) 3. Click **Run Scan** 4. The results table shows each suggested pair with a **match score** and breakdown: | Component | Method | Weight | |---|---|---| | Full name | Jaro-Winkler similarity | 40% | | Date of birth | Exact/near-exact day match | 35% | | Phone / mobile | Last 7–9 digits match across all phone/mobile combinations | 25% | 5. For each pair, review the score breakdown, select the primary, and click **Merge** or **Dismiss** > Pairs that have already been merged (in any direction, regardless of merge status) are excluded from scan results. --- ## What Is Re-pointed During a Merge ### Version 1 scope (current release) | Entity | Field moved | |---|---| | Bills | `patient` | | Patient Encounters | `patient` | | Patient Investigations | `patient` | | Patient Reports | `patient` | ### Future scope (planned, not yet implemented) The following will be included in a future release: - Bill Items, Bill Fees - Lab: Patient Samples, Sample Components, Report Groups, Report Item Values, Lab Test History - Inward: Patient Rooms, Transfer Requests, Reservations - Clinical: Prescriptions, Prescription Templates, Clinical Finding Values, Item Usages - Finance: Patient Deposits, Deposit History - Administration: Patient Insurance, Patient Flags, Patient Items - Family: Family Members, Family records - Communications: Tokens, Appointments, SMS, Emails, Notifications, Uploads, Form Values - Credit: Encounter Credit Company links - Channelling: Patient Session Instance Activities --- ## Demographics — Merge Rules | Situation | Outcome | |---|---| | Primary field has a value | Primary field is kept; secondary value discarded | | Primary field is null, secondary has a value | Secondary value is copied to the primary | | Both fields are null | Remains null | The primary patient's record is never overwritten. The merge only fills gaps. --- ## Multi-level Merges Multiple merges involving the same patient are fully supported. Each merge is stored as an independent record. For example: - Patient C merged into Patient B → one merge record - Patient B then merged into Patient A → a second, separate merge record Unmerging the B→A merge only undoes that specific merge. The C→B merge remains active independently and can be unmerged separately if needed. --- ## Merge History **Administration → Manage Metadata → Patient Data Management** tab → **Patient Data Management** → **Merge History** tab shows all past merge events. ### Filters - Date range (from / to) - Status: All / Active / Reversed - Merged by (user) ### Report columns | Column | Description | |---|---| | Merge Date | When the merge was performed | | Merged By | Staff member who performed the merge | | Primary Patient | Surviving patient — name and MRN | | Secondary Patient | Deactivated patient — name and MRN | | Merge Type | DETERMINISTIC / PROBABILISTIC / MANUAL | | Reason | Free-text reason entered at merge time | | Affected Records | Number of bills/encounters/records re-pointed | | Status | ACTIVE (green) / REVERSED (grey) | | Actions | Unmerge button (ACTIVE merges only) | --- ## Unmerge (Reversing a Merge) If a merge was performed in error, it can be fully reversed. 1. Open **Patient Data Management → Merge History** 2. Locate the merge to reverse (status must be **ACTIVE**) 3. Click **Unmerge** 4. Read the confirmation dialog carefully — it shows the secondary patient name and number of records that will be restored 5. Click **Confirm** The system: - Restores each affected record's `patient` reference back to the secondary patient - Restores the secondary patient's demographics from the pre-merge JSON snapshot - Re-activates the secondary patient (clears `retired` flag) - Sets the merge record status to **REVERSED** ### Important notes on unmerge - **Post-merge records are not moved back.** Any bill, encounter, or investigation created *after* the merge date — and therefore pointing to the primary — remains with the primary patient. Only the records that were explicitly re-pointed during the merge are reversed. - **A reversed merge appears in the history with REVERSED status** — it is never deleted from the audit trail. - **Multi-level merges must be reversed independently** — unmerging B→A does not automatically unmerge C→B. --- ## Merge Type Labels | Type | Meaning | |---|---| | MANUAL | Administrator searched for and selected both patients manually | | DETERMINISTIC | Merge was triggered from the Deterministic Scan (exact NIC/PHN/MRN match) | | PROBABILISTIC | Merge was triggered from the Probabilistic Scan (fuzzy match suggestion) | --- ## Related Articles - [Patient Data Management](https://github.com/hmislk/hmis/wiki/Patient-Data-Management) — admin hub overview - [Preventing Duplicate Patient Records](https://github.com/hmislk/hmis/wiki/Preventing-Duplicate-Patient-Records) — how to avoid creating duplicates - [Inactive Patients](https://github.com/hmislk/hmis/wiki/Inactive-Patients) — viewing and reactivating deactivated patient records - [Patient Registration Source](https://github.com/hmislk/hmis/wiki/Patient-Registration-Source) — identity trust level (relevant when choosing which patient is primary) - [Data Administration](https://github.com/hmislk/hmis/wiki/Admin-Data-Administration) — full data administration hub