Adoption Strategy | Medplum

On this page

When migrating existing provider/patient apps to Medplum, a phased approach allows for a smoother transition, minimizes risk, and provides opportunities for validation at each step. This section outlines the recommended phases for migration, along with their rationales and best practices.

It's important to note that these phases don't necessarily need to be completed in strict sequence for your entire dataset. Instead, consider applying this phased approach to each data element type described individually as described in our migration sequence guide. This approach allows for faster user feedback and more manageable chunks of work.

The recommended phases are:

1. Write-only / Dual write
2. Backfill data
3. Read from Medplum
4. Front-End write to Medplum
5. Deprecate old store

Let's explore each phase in detail.

Write-only / Dual Write [​](/content/docs/migration/adoption-strategy#write-only "Direct link to Write-only / Dual Write"/index.html)

When write/update operations come into your existing services, have your existing services write to both Medplum and your existing store.

Rationale [​](/content/docs/migration/adoption-strategy#rationale "Direct link to Rationale"/index.html)

• This is purely a backend change and doesn't affect users, minimizing disruption.
• Generally requires less infrastructure work, as you can modify existing API gateways rather than standing up new pipeline infrastructure.
• Allows you to start populating Medplum with new data immediately.

Best Practices [​](/content/docs/migration/adoption-strategy#best-practices "Direct link to Best Practices"/index.html)

• Implement error handling and logging to catch any discrepancies between writes to the old system and Medplum.
• Start with less critical data types to minimize risk.

Backfill Data [​](/content/docs/migration/adoption-strategy#backfill "Direct link to Backfill Data"/index.html)

Migrate older data from the existing data store to Medplum.

Rationale [​](/content/docs/migration/adoption-strategy#rationale-1 "Direct link to Rationale"/index.html)

• Ensures historical data is available in Medplum.
• Allows for data validation and reconciliation before switching reads to Medplum.

Best Practices [​](/content/docs/migration/adoption-strategy#best-practices-1 "Direct link to Best Practices"/index.html)

• Set up regular sync infrastructure. This could be as simple as running a script on your local machine or in a serverless function. Many Medplum users also use tools like Apache Airflow to orchestrate their ETL.
• Implement idempotent operations to allow for safe re-runs of the backfill process.
• Start with a small subset of data to validate your migration scripts before running on the entire dataset.
• Implement data validation checks to ensure the integrity of migrated data.

Read from Medplum in the Client [​](/content/docs/migration/adoption-strategy#read-from-medplum "Direct link to Read from Medplum in the Client"/index.html)

Update your UX to read from Medplum's API rather than your existing API.

Rationale [​](/content/docs/migration/adoption-strategy#rationale-2 "Direct link to Rationale"/index.html)

• This is the first user-facing change and can be used for data verification and user acceptance testing.
• Allows you to start benefiting from Medplum's capabilities while still maintaining write operations through your existing system.

Best Practices [​](/content/docs/migration/adoption-strategy#best-practices-2 "Direct link to Best Practices"/index.html)

• Implement feature flags to easily switch between old and new data sources.
• Start with read-only views or reports before moving to more critical user interactions.
• Monitor performance and user feedback closely during this phase.

Front-End Write to Medplum [​](/content/docs/migration/adoption-strategy#front-end-write "Direct link to Front-End Write to Medplum"/index.html)

Update your UX to write directly to Medplum rather than through your existing services.

Rationale [​](/content/docs/migration/adoption-strategy#rationale-3 "Direct link to Rationale"/index.html)

• Completes the transition to Medplum for both read and write operations.
• Allows you to take full advantage of Medplum's features and performance benefits.

Best Practices [​](/content/docs/migration/adoption-strategy#best-practices-3 "Direct link to Best Practices"/index.html)

• Implement this change gradually, starting with less critical write operations.
• Ensure your error handling and user feedback mechanisms are robust.
• Consider maintaining dual writes (to both old system and Medplum) for a period to allow for easy rollback if needed.
• Provide additional user support during this transition.

Deprecate Old System [​](/content/docs/migration/adoption-strategy#deprecate "Direct link to Deprecate Old System"/index.html)

Phase out the old data store once you're confident in the Medplum implementation.

Rationale [​](/content/docs/migration/adoption-strategy#rationale-4 "Direct link to Rationale"/index.html)

• Reduces maintenance overhead and potential for data inconsistencies.
• Completes the migration process.

Best Practices [​](/content/docs/migration/adoption-strategy#best-practices-4 "Direct link to Best Practices"/index.html)

• Ensure all historical data has been successfully migrated and validated.
• Maintain read-only access to the old store for a period to allow for data verification if needed.
• Update all documentation and operational procedures to reflect the new system.
• Provide training to all relevant staff on the new procedures and systems.

Conclusion [​](/content/docs/migration/adoption-strategy#conclusion "Direct link to Conclusion"/index.html)

It's crucial to understand that these phases don't need to be implemented in strict sequence for your entire system. Instead, consider applying this phased approach in parallel to each data element type individually.

By proceeding through these phases for each data element type, you can ensure a smoother transition, minimize risk, and get user feedback earlier in the process.

The key to a successful migration is flexibility, thorough planning, and constant communication with all stakeholders throughout the process.