OpenEvidence Migration Deep Dive

Overview

Execute complex migrations including EHR integration, legacy system transitions, and multi-site deployments for OpenEvidence clinical AI.

Prerequisites

Understanding of source and target systems
Access to both environments during migration
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

Scenario 1: Legacy CDS to OpenEvidence Migration

Step 1: Assessment and Planning

// src/migration/assessment.ts

interface LegacySystemAssessment {
  systemName: string;
  queryVolume: {
    dailyQueries: number;
    peakQueriesPerMinute: number;
    uniqueUsers: number;
  };
  features: {
    clinicalQuery: boolean;
    drugInfo: boolean;
    guidelines: boolean;
    deepResearch: boolean;
  };
  integrations: {
    ehr: string[];
    sso: string[];
    audit: string[];
  };
  dataToMigrate: {
    savedSearches: boolean;
    userPreferences: boolean;
    auditLogs: boolean;
  };
}

async function assessLegacySystem(): Promise<LegacySystemAssessment> {
  // Analyze legacy system usage
  const queryLogs = await legacyDb.queryLogs.aggregate({
    _count: { daily: true },
    _max: { queriesPerMinute: true },
  });

  const users = await legacyDb.users.count();

  return {
    systemName: 'LegacyCDS',
    queryVolume: {
      dailyQueries: queryLogs._count.daily,
      peakQueriesPerMinute: queryLogs._max.queriesPerMinute,
      uniqueUsers: users,
    },
    features: {
      clinicalQuery: true,
      drugInfo: true,
      guidelines: true,
      deepResearch: false, // OpenEvidence advantage
    },
    integrations: {
      ehr: ['Epic', 'Cerner'],
      sso: ['ADFS'],
      audit: ['Splunk'],
    },
    dataToMigrate: {
      savedSearches: true,
      userPreferences: true,
      auditLogs: true, // Required for HIPAA
    },
  };
}

Step 2: Parallel Running Period

// src/migration/parallel-runner.ts

interface ParallelConfig {
  legacyClient: LegacyClient;
  openEvidenceClient: OpenEvidenceClient;
  comparisonRatio: number; // 0-1, how many queries to compare
  autoFallback: boolean;
}

export class ParallelRunner {
  constructor(private config: ParallelConfig) {}

  async query(question: string, context: any): Promise<{
    result: any;
    source: 'legacy' | 'openevidence';
    comparison?: ComparisonResult;
  }> {
    const shouldCompare = Math.random() < this.config.comparisonRatio;

    // Always query OpenEvidence (new system)
    const oePromise = this.config.openEvidenceClient.query({
      question,
      context,
    });

    // Optionally query legacy for comparison
    let legacyPromise: Promise<any> | null = null;
    if (shouldCompare) {
      legacyPromise = this.config.legacyClient.query(question);
    }

    try {
      const oeResult = await oePromise;

      // Log comparison if available
      if (legacyPromise) {
        const legacyResult = await legacyPromise.catch(() => null);
        if (legacyResult) {
          await this.logComparison(question, oeResult, legacyResult);
        }
      }

      return {
        result: oeResult,
        source: 'openevidence',
      };
    } catch (error) {
      if (this.config.autoFallback && legacyPromise) {
        // Fallback to legacy if OpenEvidence fails
        console.warn('[Migration] OpenEvidence failed, falling back to legacy');
        const legacyResult = await legacyPromise;
        return {
          result: legacyResult,
          source: 'legacy',
        };
      }
      throw error;
    }
  }

  private async logComparison(
    question: string,
    oeResult: any,
    legacyResult: any
  ): Promise<void> {
    const comparison: ComparisonResult = {
      timestamp: new Date(),
      questionHash: hashQuestion(question), // Don't log PHI
      openEvidence: {
        responseTime: oeResult.responseTime,
        confidence: oeResult.confidence,
        citationCount: oeResult.citations.length,
      },
      legacy: {
        responseTime: legacyResult.responseTime,
        sourceCount: legacyResult.sources?.length || 0,
      },
    };

    await db.migrationComparisons.create({ data: comparison });
  }
}

Step 3: Data Migration

// src/migration/data-migration.ts

interface MigrationJob {
  id: string;
  type: 'users' | 'preferences' | 'audit_logs';
  status: 'pending' | 'running' | 'completed' | 'failed';
  progress: number;
  errors: string[];
}

export class DataMigrator {
  async migrateUsers(): Promise<MigrationJob> {
    const job = await this.createJob('users');

    try {
      const legacyUsers = await legacyDb.users.findMany();
      let processed = 0;

      for (const user of legacyUsers) {
        try {
          await db.users.upsert({
            where: { email: user.email },
            create: {
              email: user.email,
              firstName: user.firstName,
              lastName: user.lastName,
              role: this.mapRole(user.role),
              migratedFrom: 'legacy',
              migratedAt: new Date(),
            },
            update: {
              migratedFrom: 'legacy',
              migratedAt: new Date(),
            },
          });
        } catch (error: any) {
          job.errors.push(`User ${user.email}: ${error.message}`);
        }

        processed++;
        job.progress = (processed / legacyUsers.length) * 100;
        await this.updateJob(job);
      }

      job.status = 'completed';
      await this.updateJob(job);
      return job;
    } catch (error: any) {
      job.status = 'failed';
      job.errors.push(error.message);
      await this.updateJob(job);
      throw error;
    }
  }

  async migrateAuditLogs(): Promise<MigrationJob> {
    // HIPAA requires preserving audit logs
    const job = await this.createJob('audit_logs');

    const batchSize = 10000;
    let offset = 0;
    let hasMore = true;

    while (hasMore) {
      const logs = await legacyDb.auditLogs.findMany({
        skip: offset,
        take: batchSize,
      });

      if (logs.length === 0) {
        hasMore = false;
        continue;
      }

      // Transform and insert
      const transformed = logs.map(log => ({
        timestamp: log.timestamp,
        userId: log.userId,
        action: this.mapAction(log.action),
        resourceType: 'legacy_query',
        resourceId: log.queryId,
        ipAddress: log.ipAddress,
        migratedFrom: 'legacy',
      }));

      await db.auditLogs.createMany({ data: transformed });

      offset += batchSize;
      job.progress = Math.min(99, job.progress + 10);
      await this.updateJob(job);
    }

    job.status = 'completed';
    job.progress = 100;
    await this.updateJob(job);
    return job;
  }

  private mapRole(legacyRole: string): ClinicalRole {
    const mapping: Record<string, ClinicalRole> = {
      'doctor': ClinicalRole.Physician,
      'nurse': ClinicalRole.Nurse,
      'pharmacist': ClinicalRole.Pharmacist,
      'admin': ClinicalRole.Admin,
    };
    return mapping[legacyRole] || ClinicalRole.Nurse;
  }

  private mapAction(legacyAction: string): string {
    const mapping: Record<string, string> = {
      'search': 'clinical_query',
      'view': 'view_result',
      'export': 'export',
    };
    return mapping[legacyAction] || legacyAction;
  }
}

Scenario 2: EHR Integration (Epic)

Step 1: SMART on FHIR Configuration

// src/integrations/epic/smart-config.ts

interface SMARTConfig {
  clientId: string;
  clientSecret: string;
  redirectUri: string;
  scope: string[];
  epicEndpoints: {
    authorize: string;
    token: string;
    fhir: string;
  };
}

export const epicConfig: SMARTConfig = {
  clientId: process.env.EPIC_CLIENT_ID!,
  clientSecret: process.env.EPIC_CLIENT_SECRET!,
  redirectUri: `${process.env.APP_URL}/auth/epic/callback`,
  scope: [
    'openid',
    'fhirUser',
    'launch/patient',
    'patient/Patient.read',
    'patient/MedicationRequest.read',
    'patient/Condition.read',
  ],
  epicEndpoints: {
    authorize: 'https://fhir.epic.com/interconnect-fhir-oauth/oauth2/authorize',
    token: 'https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token',
    fhir: 'https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4',
  },
};

Step 2: CDS Hooks Integration

// src/integrations/epic/cds-hooks.ts
import { Router } from 'express';
import { ClinicalEvidenceService } from '../../services/clinical';

const router = Router();

// CDS Hooks Discovery Endpoint
router.get('/cds-services', (req, res) => {
  res.json({
    services: [
      {
        id: 'openevidence-clinical-decision-support',
        hook: 'patient-view',
        title: 'OpenEvidence Clinical Decision Support',
        description: 'AI-powered clinical evidence at the point of care',
        prefetch: {
          patient: 'Patient/{{context.patientId}}',
          conditions: 'Condition?patient={{context.patientId}}',
          medications: 'MedicationRequest?patient={{context.patientId}}&status=active',
        },
      },
      {
        id: 'openevidence-drug-interaction',
        hook: 'medication-prescribe',
        title: 'OpenEvidence Drug Interaction Check',
        description: 'Check for drug interactions using AI clinical evidence',
        prefetch: {
          patient: 'Patient/{{context.patientId}}',
          medications: 'MedicationRequest?patient={{context.patientId}}&status=active',
        },
      },
    ],
  });
});

// CDS Hooks Service Endpoint
router.post('/cds-services/:serviceId', async (req, res) => {
  const { serviceId } = req.params;
  const { hook, context, prefetch } = req.body;

  try {
    let cards: any[] = [];

    switch (serviceId) {
      case 'openevidence-clinical-decision-support':
        cards = await handlePatientView(context, prefetch);
        break;
      case 'openevidence-drug-interaction':
        cards = await handleMedicationPrescribe(context, prefetch);
        break;
    }

    res.json({ cards });
  } catch (error) {
    console.error('[CDS Hooks] Error:', error);
    res.json({ cards: [] });
  }
});

async function handlePatientView(context: any, prefetch: any): Promise<any[]> {
  // Extract relevant conditions
  const conditions = prefetch.conditions?.entry?.map(
    (e: any) => e.resource.code?.text
  ).filter(Boolean) || [];

  if (conditions.length === 0) {
    return [];
  }

  // Query OpenEvidence for relevant clinical information
  const evidence = await clinicalService.queryClinicalEvidence(
    `What are the latest treatment guidelines for ${conditions.join(', ')}?`,
    {
      specialty: 'internal-medicine',
      urgency: 'routine',
    },
    { userId: 'epic-cds', userRole: 'integration' }
  );

  return [{
    uuid: crypto.randomUUID(),
    summary: 'Clinical Evidence Available',
    detail: evidence.summary,
    indicator: 'info',
    source: {
      label: 'OpenEvidence',
      url: 'https://openevidence.com',
      icon: 'https://openevidence.com/icon.png',
    },
    links: [{
      label: 'View Full Evidence',
      url: `${process.env.APP_URL}/evidence?q=${encodeURIComponent(conditions.join(','))}`,
      type: 'absolute',
    }],
  }];
}

async function handleMedicationPrescribe(context: any, prefetch: any): Promise<any[]> {
  const newMedication = context.draftOrders?.[0]?.resource?.medicationCodeableConcept?.text;
  const currentMedications = prefetch.medications?.entry?.map(
    (e: any) => e.resource.medicationCodeableConcept?.text
  ).filter(Boolean) || [];

  if (!newMedication || currentMedications.length === 0) {
    return [];
  }

  // Check for drug interactions
  const interaction = await clinicalService.checkDrugInteraction(
    [newMedication, ...currentMedications],
    { userId: 'epic-cds', userRole: 'integration' }
  );

  if (!interaction.hasInteraction) {
    return [];
  }

  return [{
    uuid: crypto.randomUUID(),
    summary: `Drug Interaction Alert: ${newMedication}`,
    detail: interaction.details,
    indicator: interaction.severity === 'major' ? 'critical' : 'warning',
    source: {
      label: 'OpenEvidence',
      url: 'https://openevidence.com',
    },
    suggestions: interaction.severity === 'major' ? [{
      label: 'Review Alternatives',
      uuid: crypto.randomUUID(),
      isRecommended: true,
    }] : [],
  }];
}

export default router;

Scenario 3: Multi-Site Expansion

Step 1: Site Configuration

// src/config/multi-site.ts

interface SiteConfig {
  siteId: string;
  siteName: string;
  region: string;
  openEvidenceOrgId: string;
  ehrSystem: 'epic' | 'cerner' | 'meditech' | 'none';
  features: {
    deepConsult: boolean;
    webhooks: boolean;
  };
  quotas: {
    dailyQueries: number;
    monthlyDeepConsults: number;
  };
}

const SITE_CONFIGS: Record<string, SiteConfig> = {
  'main-hospital': {
    siteId: 'main-hospital',
    siteName: 'Main Hospital',
    region: 'us-central',
    openEvidenceOrgId: 'org_main_***',
    ehrSystem: 'epic',
    features: { deepConsult: true, webhooks: true },
    quotas: { dailyQueries: 10000, monthlyDeepConsults: 500 },
  },
  'clinic-network': {
    siteId: 'clinic-network',
    siteName: 'Clinic Network',
    region: 'us-east',
    openEvidenceOrgId: 'org_clinic_***',
    ehrSystem: 'cerner',
    features: { deepConsult: false, webhooks: true },
    quotas: { dailyQueries: 5000, monthlyDeepConsults: 0 },
  },
  'urgent-care': {
    siteId: 'urgent-care',
    siteName: 'Urgent Care Centers',
    region: 'us-west',
    openEvidenceOrgId: 'org_uc_***',
    ehrSystem: 'none',
    features: { deepConsult: false, webhooks: false },
    quotas: { dailyQueries: 2000, monthlyDeepConsults: 0 },
  },
};

export function getSiteConfig(siteId: string): SiteConfig {
  const config = SITE_CONFIGS[siteId];
  if (!config) {
    throw new Error(`Unknown site: ${siteId}`);
  }
  return config;
}

Migration Checklist

Pre-Migration

[ ] Stakeholder approval obtained
[ ] Clinical staff notified
[ ] Downtime window scheduled (if needed)
[ ] Rollback plan documented
[ ] Data backup completed
[ ] Test environment validated

During Migration

[ ] Parallel running period completed
[ ] Comparison metrics reviewed
[ ] User data migrated
[ ] Audit logs migrated (HIPAA)
[ ] EHR integration tested
[ ] SSO integration tested

Post-Migration

[ ] Legacy system decommissioned
[ ] All users transitioned
[ ] Performance baseline established
[ ] Clinical staff trained
[ ] Support documentation updated
[ ] Lessons learned documented

Output

Legacy system assessment
Parallel running configuration
Data migration scripts
EHR integration (SMART on FHIR, CDS Hooks)
Multi-site configuration

Error Handling

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

Resources

Next Steps

Congratulations! You have completed the OpenEvidence skill pack. For ongoing support, contact support@openevidence.com or visit https://openevidence.com.