openevidence-migration-deep-dive

OpenEvidence Migration Deep Dive

Table of Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Execute complex migrations including legacy CDS system transitions, EHR integrations (Epic/Cerner), and multi-site deployments for OpenEvidence clinical AI.

Prerequisites

• Access to both source and target systems
• Downtime window approved (if required)
• Rollback plan documented
• Clinical staff communication plan

Migration Scenarios

Scenario	Complexity	Downtime	Duration
Legacy CDS to OpenEvidence	High	4-8 hours	2-4 weeks
Add EHR Integration	Medium	None	1-2 weeks
Multi-site Expansion	Medium	None	1-2 weeks
API Version Upgrade	Low	None	1-3 days

Instructions

Step 1: Assess Legacy System

Audit current usage (daily queries, peak rate, unique users), map features, identify integrations (EHR, SSO, audit), and determine data migration scope (saved searches, preferences, audit logs -- required for HIPAA).

Step 2: Implement Parallel Running

Create ParallelRunner that queries OpenEvidence as primary, optionally queries legacy for comparison (configurable ratio). Log comparison metrics (response time, confidence, citation count) without PHI. Auto-fallback to legacy on OpenEvidence failure.

Step 3: Migrate Data

Run migration jobs for users (with role mapping), user preferences, and audit logs (HIPAA required). Use upsert for idempotency, batch processing for audit logs (10k per batch), and progress tracking.

Step 4: Integrate with EHR (Epic/Cerner)

Configure SMART on FHIR with appropriate scopes. Implement CDS Hooks endpoints for patient-view and medication-prescribe. Extract conditions and medications from FHIR prefetch data for OpenEvidence queries.

Step 5: Configure Multi-Site

Define per-site configuration: siteId, region, OpenEvidence orgId, EHR system, feature flags, and quotas. Support different tiers per site.

Step 6: Execute Cutover

Follow migration checklist: pre-migration (approvals, backups, test env), during (parallel run, data migration, EHR testing), post (decommission legacy, train staff, document lessons).

Output

• Legacy system assessment and feature mapping
• Parallel running with comparison metrics
• Data migration scripts (users, preferences, audit logs)
• EHR integration (SMART on FHIR, CDS Hooks)
• Multi-site configuration
• Migration checklist

Error Handling

Migration Issue	Detection	Resolution
Data corruption	Validation checks	Restore from backup
SSO failure	Auth errors	Verify IdP configuration
EHR integration fails	CDS Hook errors	Check FHIR endpoints
Performance regression	Metrics comparison	Optimize or rollback

Examples

CDS Hook Discovery

{
  "services": [
    { "id": "openevidence-clinical-decision-support", "hook": "patient-view" },
    { "id": "openevidence-drug-interaction", "hook": "medication-prescribe" }
  ]
}

See detailed implementation for advanced patterns.

Resources

• SMART on FHIR
• CDS Hooks
• Epic App Orchard