Medplum migration from legacy EHR and FHIR data

What a Medplum data migration involves

Every Medplum data migration follows the same five stages whichever source you start from: extract data from the source, map it to FHIR R4 resources, load it into Medplum, validate the result against clinical and business rules, and cut over so that the new platform becomes the system of record. The four paths this page covers differ mainly in how hard the extract and map stages are. Legacy EHR exports are often proprietary and incomplete, an HL7 v2 feed carries events rather than a clean record, another FHIR server may already be close to R4, and moving from hosted Medplum to self-hosted Medplum is mostly an infrastructure and data-movement exercise.

Migrations are usually triggered by a platform change, the retirement of an existing EHR, a new interface requirement from a partner or payer, or a decision to move off the hosted plan onto infrastructure you control. Whatever the trigger, start by inventorying every source, its owner, its data volume and the clinical content it holds. Confirm with your vendor whether the export format and any retention obligations are documented, because those answers set the extract effort before any mapping begins.

On in-house versus partner: a team with strong FHIR and HL7 skills and a small, well-understood dataset can often run the migration itself. Large or multi-source clinical data usually benefits from a partner for the mapping specification, the validation rules and the reconciliation reports, since errors in code systems, patient matching or dates are costly to find after cutover. Ask any partner to show how it will prove that every source record was either loaded or deliberately excluded.

DeployOpen prepares systems, controls and evidence for compliance assessments, but it does not issue audit reports, attestations or certifications. Migration validation records can support your HIPAA or other assessments, and the independent auditor or certification body makes the final judgment. Agree in writing which evidence the migration will produce, who signs off on it and how it will be retained.

What the work includes

Each package ends in a document or artifact you keep after the engagement. Scope is agreed in writing before work starts, so the list below shows what a fixed-scope migration typically covers rather than a fixed count of activities.

Source assessment and data inventory

We catalog every source system, interface and data domain that feeds the migration, including the legacy EHR, any HL7 v2 feeds, and any existing FHIR server. The deliverable is a data inventory listing volumes, owners, retention rules and known quality issues. Ask which records are in scope for history and which are archived only.

FHIR R4 mapping specification

The specification maps each legacy field to a FHIR R4 resource and element, and records the terminology and code system mapping, identifier systems, patient matching rules and how references are resolved. Clinical staff should review the crosswalk for codes that have no direct equivalent. The client receives the mapping specification as a versioned document.

Extraction and transformation pipelines

We build repeatable pipelines that extract source data, apply the mapping rules and produce FHIR resources in a staged form. Pipelines are run more than once during testing, so they must be idempotent and logged. The client receives the pipeline code, its configuration and run logs from the test loads.

Loading into Medplum

Transformed resources are loaded into your Medplum server through the FHIR API, Bots or the HL7 server, depending on the data type and volume. The loading method is confirmed against the Medplum version you run, since APIs and limits change between releases. The client receives the load scripts and a record of which method was used for each resource type.

Validation and reconciliation reports

Reconciliation compares record counts, patient matches and sampled clinical content between the source and Medplum after each load. Resources that fail FHIR validation or matching are listed with a reason, not silently dropped. The client receives reconciliation reports for each test and dress rehearsal load.

Cutover runbook and rollback plan

The runbook sets out the freeze window, final extract, delta load, go/no-go checks, and the owner of each step. The rollback plan defines the point of no return and how the legacy system stays available if the cutover fails. Ask how long your source system must remain read-only and who approves each decision.

Handover documentation

Handover covers the architecture of the pipelines, operating procedures for re-running loads, known data exceptions and the support boundary after go-live. Your team should be able to rerun a load without DeployOpen present. The client receives the documentation set and a walkthrough recording or session.

What drives cost and duration

This table lists the factors that most change the effort of a Medplum migration, why each one matters and what to do about it, so you can check a written scope against your own source systems.

Driver	Why it matters	How to reduce it
Source systems and feed types	Each EHR, HL7 v2 feed, FHIR server or flat file needs its own extraction, mapping and error handling, and HL7 v2 message variation adds mapping work.	Inventory every source and feed before scoping, retire unused feeds, and group sources that share a message pattern.
Data volume and history depth	Post-load validation and reindexing time grow with record counts, and deciding how many years of history to load changes the work more than the record count alone.	Agree a history cutoff with clinical and records owners and load older data later or as read-only archives if the scope allows.
Resource types and profiles	Each FHIR resource type you map, and each profile or extension your implementation guide requires, adds mapping rules and test cases.	Limit the first release to resource types that clinical workflows need and document profiles before mapping starts.
Code system and terminology mismatches	Local codes that have no clean LOINC, SNOMED CT, RxNorm or ICD-10-CM equivalent need manual crosswalks and clinical sign-off.	Build a code inventory early, agree a crosswalk owner and decide how unmapped local codes are carried forward.
Patient matching and duplicate records	Duplicate patients and weak identifiers cause merge decisions that need human review and can delay cutover.	Profile identifiers and demographics before load, set matching thresholds in writing and budget for a review queue.
Unstructured and document data	Scanned documents, PDFs and free-text notes need extraction, classification or attachment handling that structured mapping does not cover.	Decide which documents move as Binary or DocumentReference resources and which stay in the archive, and limit extraction to agreed types.
Interface uptime during cutover	Feeds that must stay live during the switch require parallel running, replay of queued messages and a tested rollback path.	Agree the acceptable interruption window with clinical operations and rehearse cutover at least once in a non-production environment.
Number of environments	Each environment needs its own load, validation and configuration runs, and production-like test data must be prepared and protected.	Keep the environment count to what testing requires and automate loads so each environment is rebuilt the same way.
Compliance evidence requirements	Assessors may expect mapping specifications, reconciliation reports, access records and sign-offs, which take time to collect and keep current.	Define the evidence list with your compliance lead before work starts and generate reconciliation and audit output as the migration runs.
Hosted Medplum or another source system	Moving from Medplum's hosted cloud to self-hosting involves export, access and version alignment, while another FHIR server may need a different export method and version.	Confirm the source platform, version and export options in writing, and check which Medplum server version the target will run.

Project phases and outputs

The sequence moves clinical data from a source system into a self-hosted Medplum environment in controlled stages, with each phase closing on a written output the client keeps.

Inventory sources and data scope
DeployOpen works with your clinical, IT and data owners to list each source system, feed and export, along with the resource types, volumes, code sets and known data quality issues. The output is a source inventory and data scope document that the client signs off before any mapping work begins.
Specify and sign off mappings
Source fields are mapped to FHIR R4 resources, profiles, value sets and extensions, with transformation rules, default values and handling for unmapped or ambiguous data. The client receives a mapping specification and a sign-off record from the named data owners, which defines what counts as a correct load.
Build extract and load pipelines
Extract, transform and load code is built against a non-production Medplum environment in infrastructure the client controls, with idempotent loads, error queues and logging. The output is versioned pipeline code, a runbook for the load process and a non-production environment the client can inspect.
Run trial loads with reconciliation
Repeated trial loads are run against copies of the source data, and record counts, identifiers and sampled clinical content are reconciled between source and target. Each run produces a reconciliation report listing discrepancies, their causes and the fixes applied, so the client can see how the load behaves over time.
Validate with clinical and data owners
Clinical and data owners review sampled records in the loaded environment against the mapping specification and their own acceptance criteria. The output is a validation log with signed acceptance or a list of open defects that must close before cutover.
Rehearse cutover and set rollback
A full cutover rehearsal runs the production sequence end to end, including freeze, final extract, load, verification and reopening of access, and times each step against the runbook. The rehearsal report and a documented rollback decision point, with the criteria that trigger rollback, are standard outputs before production cutover.
Cut over and monitor after go-live
The production cutover follows the rehearsed runbook, with the data owners present for the go or no-go decision at the rollback point. After go-live, load logs, error rates and access reports are monitored for an agreed period, and the client receives a closure report with the final reconciliation and open items. A data migration run in a self-hosted Medplum environment must be planned alongside the platform version in use, so the team confirms the migration path before the build begins.

What teams keep in-house and what they outsource

This table lists each migration task, the skill it needs and whether the client usually keeps the decision in-house, so readers can see where a partner adds capacity and where clinical and governance ownership must stay with the organization.

Migration task	Skill required	Usually kept in-house?
Source system knowledge	Understanding of the legacy EHR's data model, interface feeds, custom fields and historical data quirks, usually held by long-serving administrators and vendor contacts	Yes, the client provides access and the people who know the source system; a partner documents what it finds
Clinical data ownership and sign-off	Clinical judgment on which records, codes and histories are valid, retained or retired	Yes, clinical owners make and sign these decisions; a partner cannot approve clinical data
FHIR R4 mapping design	Resource modeling, extensions, profiles and reference integrity across Patient, Encounter, Observation and related resources	Shared, with the partner drafting mappings and the client's clinical and data owners approving them
HL7 v2 segment parsing and interface testing	Working knowledge of HL7 v2 message structures, segment and field variation across senders, and acknowledgment handling	Often outsourced, though the client keeps the sample messages and approves test outcomes
Terminology mapping	Mapping local codes to standard terminologies such as LOINC, SNOMED CT and RxNorm, with ownership of crosswalk decisions	Shared, with clinical terminology decisions kept by the client and the partner building the crosswalk tables
Pipeline build	Engineering for repeatable extract, transform and load jobs against Medplum's FHIR API, with logging and restartability	Often outsourced, with the client's engineers reviewing code and running it in their environment
Validation and reconciliation	Record counts, resource-level comparisons and sampling against source data, plus documented exception handling	Shared, with the partner producing reconciliation reports and the client deciding which exceptions are acceptable
Security and access controls during migration	Least-privilege service accounts, network restrictions, encryption and audit logging for the migration window	Shared, with the client approving access policy and the partner configuring and documenting it
Cutover execution	Freeze planning, final delta load, switch of interfaces and rollback rehearsal	Shared, with the client's operations and clinical leads approving the go or no-go decision
Post-go-live support	Monitoring of interface errors, data defects and correction loads after cutover	Often retained by the client, or covered by a support arrangement that the client scopes in writing

What usually goes wrong

These six patterns cover the most common risks in moving clinical data onto Medplum. Each card names the prevention step to build into the plan before loading begins.

Mapping that loads but misstates meaning

A load can succeed while a source code, unit, or status lands in the wrong FHIR R4 element or a different terminology. Code system drift between the legacy EHR and the target shows up as valid-looking data with changed meaning. Check mapped values against clinician-reviewed samples and confirm code system versions on both sides before go-live.

Duplicate patients from weak matching

Patients often exist in the legacy EHR, an HL7 v2 feed, and a partner FHIR server under different identifiers. Matching on name and date of birth alone creates duplicates that split clinical history across records. Agree match rules, confidence thresholds, and a manual review queue with the data owners, and run the match against a sample before any bulk load.

References break when resources load out of order

FHIR resources point at each other, so an Observation or Encounter that references a Patient not yet loaded fails or ends up dangling. Load in dependency order, with Patients and Organizations first, then clinical resources, and record every failed reference for replay. Count unresolved references after each batch to confirm integrity.

PHI copied into non-production without controls

Test and staging copies of migration data often inherit production access rules, which leaves real patient records in environments with looser logging and wider developer access. Mask or synthesize data for development, restrict who can reach the staging copy, and document access, retention, and deletion for each copy within your HIPAA compliance program.

Cutover without a tested rollback

A cutover plan that only describes the forward move leaves the team stuck if validation fails after clinicians start writing to Medplum. Rehearse the full cutover and the reverse path on a copy of production data, define who decides to roll back and when the data freeze begins, and confirm how writes made during the freeze are reconciled.

Skipping Medplum minor versions on self-hosting

Self-hosted Medplum must move through each minor version in sequence. The upgrade guide documents startup failures when minor versions are skipped, for example from v3.1.2 straight to v4.3.4. Post-deploy data migrations can run for hours or days on large datasets, so plan the upgrade path and schedule it before the migration window and test it on a copy first.

How the work changes by starting point

A legacy EHR export usually arrives as flat files or a vendor-specific extract, so the first phase is understanding what the export contains before any mapping starts.

Inventory the export: list each table or file, its record counts and what the vendor's data dictionary says each field means.
Map to FHIR R4: decide which resources each source entity becomes, and document the code system translations for problems, medications and results.
Validate in staging: load de-identified or test extracts first and check resource conformance, references and duplicate patients before any production load.
Reconcile counts: compare source and target totals per resource type and keep the reconciliation report as migration evidence.

Confirm with the EHR vendor which export formats, attachments and audit history are included, and whether the export license permits this use. For compliance, treat staging copies as PHI, and confirm the business associate agreement covers the vendor's export and your transfer path.

What you need to provide

Access and people come first. Before mapping starts, the client needs to provide read access or export rights to each legacy source (the EHR, the HL7 v2 interface engine, or the source FHIR server) and a named technical contact for each one. Name a clinical owner who can sign off mappings for each domain, such as medications, problems, allergies and encounters. Without those sign-offs, the mapping workbook stalls and the load cannot be validated against clinical expectations.

The client also supplies a data inventory: record counts by resource type, data volumes, the history depth to be migrated, and any archived or purged data that must stay out of scope. Sample extracts, HL7 v2 message samples and the sending system's interface specifications are needed early, along with local terminology and code lists (local lab codes, custom observation codes, value sets) so that mappings to FHIR R4 can be tested against real content rather than assumptions.

Provide a non-production Medplum environment before loading begins, and confirm the hosting arrangement in writing. If the environment runs on infrastructure the client controls, the client must have a signed business associate agreement with that hosting provider. Medplum's hosted plans list a standard BAA, and the client should confirm the terms that apply to its own deployment. Decide which identity provider migration staff will use, which roles they hold, and how their access is removed after cutover.

Set the cutover window and downtime tolerance in writing, including the latest acceptable point for a final delta load. Name one decision maker with authority to call go or no-go, and agree the criteria in advance. The client remains responsible for its own HIPAA program, including risk analysis, workforce training and policies that cover the migrated data. DeployOpen prepares technical evidence, such as load reconciliation reports and configuration records, to support the client's review, but does not issue attestations or certifications. Independent auditors do that work.

Frequently asked questions

How is the cost of a Medplum migration set?

A migration is priced from a written, fixed-scope quote that follows from the agreed scope, not from a standard rate card. DeployOpen does not publish a price list. The quote is driven by the effort drivers: how many source systems feed the migration (an EHR, an HL7 v2 feed, another FHIR server, or a hosted Medplum tenant), how much data moves, how many resource types and code systems need mapping to FHIR R4, how much cleansing and deduplication the source data needs, and how many validation and cutover rounds are required. Ask for the quote to list each source, each mapping set, the validation approach and the cutover plan as separate line items, so you can see what changes the price if scope moves.

How long does a Medplum data migration take?

The duration depends on three things that are confirmed during scoping: the number of source systems, the volume of data, and the complexity of the mapping. A single clean FHIR source with a small number of resource types is far shorter than several HL7 v2 feeds with local code sets and free-text fields. Load time also depends on the target hardware and database sizing. Ask for a schedule with milestones for source analysis, mapping sign-off, test loads, validation, dress rehearsal and cutover, and ask which dates depend on your clinical and IT reviewers responding.

Can our in-house team run the migration without a partner?

Yes, if your team already has FHIR R4 modeling skills, experience with HL7 v2 message parsing, PostgreSQL bulk loading and a clinical validation process. Most of the difficulty is not the tooling. It is the mapping decisions, the handling of incomplete or conflicting records, and proving to clinical owners that the loaded data is correct. Assess that gap honestly. Many organizations keep ownership of clinical sign-off and bring in a partner for mapping, load tooling and validation evidence.

What do clinical and IT staff need to provide during a migration?

Clinical staff must define which data is in scope, confirm how legacy codes map to standard terminologies, and sign off on sample records before test loads are accepted. IT staff must provide read access to source extracts or interface logs, a non-production target environment, identity and network access for the Medplum server, and a named change owner for cutover. Agree these responsibilities and their turnaround times in the written scope, because waiting on sign-off is one of the most common causes of schedule slip.

Does using Medplum's hosted plans or the free Community option change the migration work?

The mapping, transformation and validation work is largely the same. What changes is where the data lands and who operates the target. On a hosted Medplum plan, the vendor operates the platform and the agreements for hosting sit with Medplum's pricing terms. On the free Community self-hosting option or Enterprise Self-Hosted, your infrastructure, backups, patching and upgrade sequence are part of the migration scope. Confirm which edition you will run before the quote is written, because hosting, backup and cutover tasks differ between them.

How is cutover risk controlled, and what happens after go-live?

Cutover risk is controlled by repeated test loads, reconciliation reports comparing record counts and key clinical values between source and target, a documented rollback point, and a dress rehearsal on a copy of production-like data before the final load. After go-live, the scope should cover a hypercare period, defect triage, and handover of mapping documentation and load scripts. Ongoing upgrades and support are available as a separate retainer, so ask whether post-go-live support is included in the quote or priced separately.

How DeployOpen delivers this work

DeployOpen plans, builds, validates and hands over Medplum migrations inside infrastructure you control, from a legacy EHR, an HL7 v2 feed, another FHIR server or Medplum's hosted cloud. Each engagement runs against a written scope, so mapping decisions, validation evidence and cutover steps are agreed before loading begins.

How we scope

The written scope lists each source system, data domain and interface that moves into Medplum.
Mapping from source formats to FHIR R4 resources is defined per domain, with agreed handling for unmapped fields.
Target hosting is set in scope, whether self-hosted on AWS, Kubernetes or another environment you control.
Engagements are fixed-scope, so deliverables, timelines and acceptance criteria are agreed in writing before work starts.

How we build

Mapping specifications and transformation logic are built and tested against representative sample records from your source.
Loads are staged so that bulk data, HL7 v2 feeds and FHIR resources are validated in test environments before production.
Validation checks cover resource conformance, referential integrity, record counts and clinically reviewed sample sets.
Cutover runbooks define sequencing, rollback points and the interface switch from the legacy system to Medplum.

How we hand over

You receive the mapping documentation, load scripts, validation reports and the cutover runbook as project deliverables.
Operating procedures cover reruns, reconciliation of late-arriving data and how to troubleshoot failed loads.
Knowledge transfer sessions walk your engineers through the Medplum data model and the transformation pipeline.
Retirement steps for the legacy source, including archive and access controls, are documented before decommissioning.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after cutover.
Post-migration support can cover data quality issues found in production and follow-up loads for late sources.
Medplum upgrades are planned in sequence, because self-hosted installs must move through each minor version in order.
Compliance evidence for the migration, such as validation records and access logs, is prepared for your assessors. DeployOpen does not issue audit reports or certifications.