Moving from Medplum to Ovok: a step-by-step migration guide
How to move a Medplum project to Ovok: export with Bulk FHIR, load in transaction Bundles, then move files, access policies, Bots and users.
Ovok runs Medplum's open-source FHIR server behind its own API gateway, so a Medplum project moves to Ovok without changing its data model. Your Patients, Observations, Questionnaires and AccessPolicies stay standard FHIR R4. What changes is the layer around them: credentials, sign-in, file uploads and the client SDK. This guide walks through a migration step by step, from the export in Medplum to the cut-over, with the limits worth knowing before you start.
Key takeaways
- Export from Medplum with the Bulk FHIR API (
$export), which returns NDJSON files. - Load into Ovok through the FHIR API in
transactionBundles, in dependency order, keeping each old id as an identifier. - Turn on the
transaction-bundlesproject feature first. Without it, a transaction Bundle is accepted but runs as a batch. - Move files through Ovok's document upload, and recreate AccessPolicies, Subscriptions and Bots in the new project.
- Passwords cannot move between systems. Plan to invite your users to set a new one.
What moves, what changes, what stays behind
Moves as it is. FHIR R4 resources, references between them, AccessPolicy resources, Subscriptions and Bots. Ovok documents Bots as a project feature, with $deploy, $execute and Subscription triggers; check that your Bot's runtime is supported before you rely on it.
Changes. Credentials come from the Ovok Console. Patients and practitioners sign in through Ovok's tenant sign-in. Files go through Ovok's document upload. Your apps move to the @ovok/core SDK.
Stays behind. User passwords, and anything you built on Medplum's admin app rather than on the FHIR API.
Step 1: Create the Ovok project and credentials
Sign up for the free Developer sandbox to rehearse, and run the real migration in the environment of your paid plan.
In the Console, open Applications and create a client. For a server-to-server migration script, use an Admin client. Your script gets a token with POST /oauth2/token and grant_type=client_credentials, the same OAuth flow you know from Medplum.
Then switch on the project features you need, with PATCH /v1/projects/me/features. The call replaces the whole list, so send every feature you want on. For a migration you want at least transaction-bundles, and websocket-subscriptions if your apps use them.
Step 2: Export from Medplum
Medplum supports the Bulk FHIR API 2.0.0. Two options:
- Whole project.
GET /fhir/R4/$exportexports every resource in the project. - A group of patients. Create a Group with the patients as members, then
GET /fhir/R4/Group/<id>/$export?_outputFormat=ndjson.
The export runs in the background. You poll the status URL Medplum returns, then download the NDJSON files it lists. The client you export with needs read access to AsyncJob, or it cannot poll the status.
Step 3: Load into Ovok
Load the NDJSON files through the FHIR API at /fhir/R4.
- Go in dependency order. Organizations and Practitioners first, then Patients, then the resources that point at them: Encounters, Observations, QuestionnaireResponses, CarePlans and so on.
- Keep the old id. Resources you create get new ids. Add each resource's Medplum id as an
identifierwith a system you own, and keep a map from old id to new id. The map rewrites references; the identifier makes the load traceable and safe to re-run. - Use transaction Bundles. With `transaction-bundles` on, a Bundle is applied completely or not at all. Inside one Bundle, entries can reference each other with
urn:uuidfull URLs. - Stay inside the limits. A transaction may hold at most 50 update (
PUT) entries. Conditional creates, updates or deletes are refused in a Bundle with more than 8 entries, so keep conditional writes out of large Bundles. - Mind the request budget. Each Bundle counts as one request, so loading in Bundles is far cheaper than one call per resource. Plans have request caps and per-client rate limits; a
429tells you to slow down.
Step 4: Move files
Files stored as Binary resources or attachments need their own step. Download each file with your Medplum credentials, then upload it to Ovok through its document upload: POST /document returns a short-lived upload form for the file, and the guide shows how your resources refer to it. Check that each content type is on Ovok's allowed list, and pace uploads, since upload credentials are rate limited.
Step 5: Recreate access rules
AccessPolicy resources work the same way on Ovok, through /fhir/R4/AccessPolicy (see creating an access policy). Load your policies, then attach them to memberships as you invite users. Set the project's default patient and practitioner policies too.
One warning: on Ovok, a membership without any policy has full access to the project. Make sure every user and client ends up with the policy you intend.
Step 6: Real-time updates and server-side logic
- Subscriptions. Load your Subscription resources. For WebSocket subscriptions, turn on the `websocket-subscriptions` feature; clients connect to the API host's subscription socket with a binding token.
rest-hookSubscriptions are signed, so your receiver can verify each call. - Bots. Deploy your Bots to the new project and re-link the Subscriptions that trigger them. Test each one before the cut-over.
- Many clinics? On Ovok, a project is a tenant with its own tenant code, and a clinic customer can be its own sub-project. If you modelled clinics as separate Medplum projects, map each to an Ovok sub-project.
Step 7: Move your users
There is no way to move passwords between two systems, and you shouldn't want one. Recreate each Patient and Practitioner, then invite users to set a new password, or let them register or use social sign-in where your project allows it. Tell your users before the cut-over, so the invitation email is expected.
Step 8: Point your apps at Ovok
Move your apps from the Medplum client to Ovok's SDKs: @ovok/core for web and React, the React Native SDK for mobile, and the Java, Python and Flutter SDKs for other stacks. Sign-in moves to Ovok's tenant sign-in, with PKCE, optional MFA and a tenant code. FHIR reads, writes and searches keep the same resources and search parameters.
Step 9: Verify and cut over
- Count. Compare resource counts per type between the export and Ovok.
- Spot-check. Open a sample of patients end to end, including references, attachments and history you care about.
- Test access. Sign in as a patient and a practitioner, and confirm each sees exactly what their policy allows.
- Freeze and delta. Stop writes in Medplum, export what changed since the first load, load it, and switch your apps over.
- Keep the export. Keep the Medplum export until you are sure you no longer need it.
Common pitfalls
- Sending a transaction Bundle before
transaction-bundlesis on: it is accepted, but runs as a batch, so a failure leaves a partial write. - Loading Observations before the Patients they reference: create referenced resources first, or in the same Bundle.
- Large Bundles with conditional entries: they are refused above 8 entries.
- Forgetting a policy on a membership: on Ovok, no policy means full access.
- Leaving users to discover the new sign-in: send invitations before the cut-over.
FAQ
Can I keep my resource ids?
Plan for new ids. Store each Medplum id as an identifier, rewrite references with your id map, and you keep full traceability.
Is there a bulk import, like $import?
Load through the FHIR API in transaction Bundles, as described above. That path is documented and supports atomic writes.
Can my users keep their passwords?
No. Passwords can't be moved between systems. Invite users to set a new password, or let them use social sign-in where your project allows it.
Can I get my data out of Ovok later?
Yes. Your data stays standard FHIR R4, and Ovok documents exporting your data with the same Bulk FHIR $export operation.
How long does a migration take?
It depends on your data volume, files and number of apps. Rehearse the whole run in the free sandbox first; the rehearsal tells you how long the real one will take.
Conclusion
A Medplum project moves to Ovok with its data model intact: export with Bulk FHIR, load in transaction Bundles, then move files, policies, subscriptions, Bots and users. Start by rehearsing in the free Developer sandbox, read why we built Ovok on Medplum, and see Ovok and Medplum compared.
Medplum is a trademark of its owner. Facts about Medplum come from its public documentation as of 20 November 2026.