EHR Migration Planning Workbook: Scope, Mapping, Validation, Cutover, and Reconciliation

An EHR migration can finish technically and still fail operationally.

The extraction may complete. The target system may report successful imports. Record counts may even look reasonable. Yet clinicians can still find an allergy under the wrong status, medications detached from prescribing context, laboratory results associated with the wrong encounter, duplicate patients, inaccessible scanned documents, or billing records that no longer reconcile.

That is why EHR migration should not be managed as a simple extract-transform-load exercise.

It needs a controlled migration framework that defines what must move, how every important data element will be interpreted, how migration accuracy will be proven, how production cutover will occur, and how the organization will demonstrate that the destination system is trustworthy after go-live.

An EHR Migration Planning Workbook provides that framework.

What Is an EHR Migration Planning Workbook?

An EHR migration planning workbook is a governed collection of migration specifications, controls, ownership decisions, acceptance criteria, and reconciliation evidence used throughout an EHR transition.

It should function as the shared technical reference between source-system owners, destination EHR teams, conversion engineers, interface developers, clinical informaticists, revenue-cycle teams, compliance stakeholders, and project leadership.

A practical workbook should include at least five connected components:

The workbook is important because EHR migration is not simply a database-copying problem. 

Clinical meaning, record relationships, historical context, billing continuity, security, and operational workflows all need to survive the transition.

1. Define the Migration Scope Before Designing the ETL

The first workbook tab should be the Data Scope Register.

Do not begin with: Which database tables can we export?

Begin with: Which information must remain clinically, operationally, financially, legally, and analytically usable after the transition?

Typical migration domains include patient demographics and identifiers, encounters, diagnoses, problems, allergies, medications, immunizations, laboratory results, diagnostic reports, orders, procedures, clinical notes, care plans, referrals, scanned documents, appointments, providers, locations, insurance information, claims, balances, payment information, consent-related data, and relevant provenance or audit metadata.

For each domain, assign a migration disposition:

Structured migration | Document migration | Searchable archive | Temporary legacy access | Approved exclusion

This prevents two common failures: attempting to force every historical object into the new production model, or migrating only a narrow clinical dataset while leaving important operational or historical information inaccessible.

Do Not Treat USCDI as the Entire Migration Scope

USCDI is a standardized set of health data classes and elements intended to support interoperable health information exchange. It can help identify important standardized clinical information, but it does not define everything that an organization may need to migrate.

A migration may need considerably more information, including specialty-specific data, historical documents, billing records, custom forms, scheduling information, local identifiers, interface metadata, and other source-system content.

Understand What ONC EHI Export Does and Does Not Provide

For certified health IT subject to 45 CFR §170.315(b)(10), ASTP/ONC requires electronic, computable exports of EHI and documentation describing the export structure and syntax. ONC does not require a single universal export standard; its guidance explicitly allows formats such as C-CDA, CSV with an accompanying data dictionary, FHIR, or another computable representation.

This means:

Never assume FHIR is automatically the migration source format.

Start with the actual source-system export contract, data dictionary, vendor documentation, APIs, database schema, document repositories, and any additional systems identified during discovery.

Equally important, ONC EHI Export should not be treated as the complete EHR migration specification. The certified product’s export capability may be one source of migration data, while a full transition may also depend on proprietary extracts, third-party billing systems, document stores, interface engines, archives, imaging platforms, or other connected applications.

2. Turn the Mapping Workbook Into a Data Contract

The mapping workbook should describe meaning, not merely column names. A useful mapping specification includes:

A mapping such as:

source.sex_code → target.gender

may appear technically straightforward while hiding substantial semantic differences involving allowable values, historical definitions, unknown states, target-system constraints, or locally defined codes.

The mapping workbook therefore needs to document transformation rules for:

• terminology and code systems
• date and timezone normalization
• status conversion
• unit conversion
• null and unknown values
• patient and provider identifiers
• encounter relationships
• one-to-many transformations
• many-to-one consolidations
• duplicate handling
• deleted or entered-in-error records
• document metadata
• source provenance

Unresolved mappings should remain visible as controlled exceptions. They should never disappear silently inside transformation logic.

Use FHIR Mapping Resources Where They Actually Fit

When FHIR is part of the migration architecture, ConceptMap can help represent relationships between source and target concepts.

HL7 explicitly states that ConceptMap mappings are directional and context-dependent. 

A reverse mapping cannot automatically be assumed, and a source concept can map to multiple targets depending on context. FHIR R4 also distinguishes equivalence relationships such as equivalent, wider, narrower, inexact, and unmatched.

That matters when converting local terminology into standards such as SNOMED CT, LOINC, RxNorm, or target-specific value sets.

FHIR StructureMap addresses a different problem. It defines transformation rules between structures and can contain enough detail to support automated instance conversion. HL7 also makes clear that these mappings are unidirectional.

Neither resource removes the need for clinical and operational mapping decisions. 

Standards can express transformations; they cannot determine whether a transformation is appropriate for a particular organization’s workflow.

3. Define Validation Before Running the First Migration

Do not wait until conversion is complete to decide how the data will be tested. The Validation Matrix should be designed alongside the mapping specification. A strong validation model covers multiple layers.

Completeness Validation

Confirm that every eligible source population has an accounted-for outcome.

But avoid relying on a simplistic equation such as:

Source rows = Target rows

That works only when source and destination representations are genuinely one-to-one.

Real migrations may include duplicate consolidation, normalization, one-to-many resource creation, many-to-one transformation, or target-model restructuring.

Instead, reconcile the logical population:

Eligible source population → transformed population → accepted target representation + quarantined exceptions + approved exclusions ± documented consolidation or expansion

Referential Integrity Validation

Verify that clinical relationships remain intact.

For example:

Result → Order → Encounter → Patient

Or:

Medication → Prescriber → Patient

A laboratory result can be technically loaded and still be unusable if the patient, encounter, ordering provider, or specimen relationship has been lost.

Taction similarly identifies completeness, field accuracy, referential integrity, reconciliation, and clinical validation as distinct migration controls rather than treating import success as sufficient validation.

Field-Level and Transformation Validation

Validate high-risk elements against approved mapping rules, including identifiers, terminology, units, timestamps, statuses, medication instructions, allergy reactions, diagnosis codes, provider attribution, document dates, and null handling.

Clinical Validation

Clinical reviewers or clinical informatics specialists should inspect representative migrated patient records. 

Technical validation can show that a diagnosis reached the target database. Clinical validation answers the more important question: Does the migrated chart still communicate the same clinical meaning?

Operational and Revenue-Cycle Validation

Migration testing should extend beyond the chart.

Test workflows such as:

registration → encounter → documentation → charge → claim

Also validate scheduling, referrals, lab review, medication workflows, reporting, interfaces, patient access, eligibility processes, and downstream analytics where those workflows depend on migrated information.

Migration guidance from Light-it similarly emphasizes semantic continuity, workflow integrity, billing validation, and post-go-live usability rather than limiting testing to technical data transfer.

4. Protect Migration Environments as Production-Sensitive Systems

Migration staging environments often contain large volumes of historical ePHI.

For HIPAA-regulated covered entities and business associates, environments that create, receive, maintain, or transmit ePHI remain subject to applicable HIPAA Security Rule safeguards. HHS requires administrative, physical, and technical safeguards designed to protect the confidentiality, integrity, and availability of ePHI.

Migration controls should therefore address appropriate authorization, least-necessary operational access, secure transmission, logging, temporary storage, backup, environment segregation, exception files, and secure disposal or retention of intermediate migration artifacts.

Encryption alone is not sufficient. HHS specifically notes that encryption does not by itself address integrity, availability, risk analysis, contingency planning, or the other safeguards required by the Security Rule. 

Where a FHIR architecture is used, Provenance can represent how resources were imported or transformed, while AuditEvent is designed to record events for purposes such as maintaining a security log.

5. Rehearse the Cutover Before Production Go-Live

Production cutover should never be the first time the full migration workflow is executed at realistic scale.

Perform repeated migration rehearsals using production-representative data volumes. Capture:

• extraction duration
• transformation duration
• loading duration
• reconciliation duration
• failure and quarantine counts
• unresolved defects
• delta volumes
• dependency timing
• interface activation timing

Dry runs reveal mapping defects, performance bottlenecks, operational dependencies, and unrealistic downtime assumptions before production cutover. Taction specifically recommends repeated rehearsals to establish timing and expose defects before go-live.

A production runbook can follow a sequence such as:

Legacy change control → baseline migration → final delta extraction → transformation and load → reconciliation → clinical verification → interface activation → go/no-go decision → production release → hypercare

Each runbook step should identify an owner, predecessor, evidence of completion, escalation path, and rollback decision point.

Whether the organization uses a phased transition or a big-bang cutover depends on operational structure, vendor constraints, coexistence capabilities, facility scope, migration architecture, downtime tolerance, and clinical risk. Neither method should be presented as universally correct.

6. Make Reconciliation the Evidence for Go-Live

The Reconciliation Ledger should account for each migration wave and each important domain.

Track:

Do not compare only aggregate row counts. Also reconcile distinct patients, identifier collisions, duplicate patients, orphaned relationships, unmapped terminology, documents, high-risk clinical domains, migrated financial balances, interface exceptions, and quarantined records.

Use Hashes and Checksums Only Where They Prove Something Useful

Checksums and deterministic hashes are useful for verifying files, attachments, unchanged binary objects, or normalized representations expected to remain identical.

They are not universally appropriate for semantically transformed records.

A legacy relational row transformed into several FHIR resources will not have the same binary representation as its source.

Use:

Control totals + field comparisons + deterministic hashes where representation should remain equivalent + domain-specific semantic reconciliation

That provides stronger evidence than treating every migration object as if it were a byte-for-byte copy.

7. Define Acceptance Criteria Before Go-Live Pressure Begins

Migration acceptance criteria should be agreed upon before the production cutover.

Define thresholds for:

• unresolved critical defects
• patient identity discrepancies
• missing clinical information
• orphaned relationships
• mapping exceptions
• financial variance
• inaccessible documents
• failed interfaces
• performance issues
• security defects

Higher-risk clinical domains should have stricter acceptance criteria than low-value historical artifacts.

The final go/no-go decision should therefore depend on documented reconciliation, clinical approval, operational readiness, interface readiness, security controls, critical defect status, and rollback feasibility, not simply whether the migration job completed successfully.

EHR Migration Is Complete When the New System Can Be Trusted

The real objective of EHR migration is not transferring data.

It is restoring confidence in the destination environment.

Clinicians must be able to find the information required for care. Revenue-cycle teams must be able to continue financial workflows. Interfaces must preserve patient and encounter context. Compliance teams need evidence showing how sensitive information was handled. IT teams need traceability explaining what was extracted, transformed, consolidated, rejected, archived, and reconciled.

That is what an EHR Migration Planning Workbook provides:

Traceability from the first scope decision through final production reconciliation and stabilization.

Planning an EHR Migration?

CapMinds supports healthcare organizations with EHR migration assessment, data mapping and conversion, HL7/FHIR interoperability, migration testing, validation, reconciliation, cutover planning, clinical and revenue-cycle workflow testing, and post-go-live stabilization.

Whether you are replacing a legacy EHR, consolidating multiple platforms, moving to a modern architecture, or migrating complex clinical and financial data, we can help identify migration risks before they become production problems.

Book a Free EHR Migration Assessment