Sequencing Your Migration
When migrating data to Medplum, maintain the relationships between data types. FHIR splits data across multiple Resources that contain References to each other.
The order below is a practical starting point, not a rule that applies to every migration. Walk through the references produced by your approved mappings and adjust the sequence when your data model differs. Loading a record early is not useful if doing so requires dropping the context that makes it meaningful.
Recommended Migration Order
We generally recommend starting with shared records, then loading the resources that refer to them. This sequence also prioritizes current clinical information before lower-priority history.
| Order | Data element | Common FHIR resources | Why it comes here |
|---|---|---|---|
| 1 | Organizations and locations | Organization, Location | Referenced by roles, patients, encounters, and other records |
| 2 | Providers and roles | Practitioner, PractitionerRole | Load practitioners and organizations before roles that connect them |
| 3 | Patient identity and administration | Patient, RelatedPerson, Coverage | Load Patient before RelatedPerson and Coverage records that reference it |
| 4 | Operational context | Encounter, Appointment | Load these before clinical records that preserve encounter or appointment context |
| 5 | Current clinical state | Condition, AllergyIntolerance, MedicationRequest | Gives users an immediately useful patient summary |
| 6 | Longitudinal clinical history | Observation, DiagnosticReport, Procedure | Load Observation before DiagnosticReport records that reference it in result |
| 7 | Documents and workflow history | DocumentReference, Communication, Task | These often refer to patients, encounters, authors, or clinical records loaded earlier |
Install required profiles and terminology before validating these stages.
Check the Order Against Your References
The table is a starting point. Inspect the references produced by your approved mappings before finalizing the sequence. For example, a Condition without an encounter reference can load before encounter history, while a Condition.encounter reference requires that Encounter to exist first or be created in the same transaction.
This diagram illustrates common dependencies. Arrows point from prerequisite data to records that commonly depend on it:
When a target reference does not exist yet, change the order, create the related resources together in a FHIR transaction with transaction support enabled, or use a conditional reference to a resource that already exists. Do not drop the reference merely to make the load succeed.
Next, define and approve the rules for governing data mappings.