updateEpisodeOfCare

Instructions

Implementation Reference

• src/tools/episodeOfCareUtils.ts:166-277 (handler)

  Core handler function that updates an EpisodeOfCare resource by reading the existing resource, applying partial updates to fields like status, type, period, managingOrganization, and careManager, then calling Medplum's updateResource.

  export async function updateEpisodeOfCare(
    episodeOfCareId: string,
    updates: UpdateEpisodeOfCareArgs,
    client?: MedplumClient,
  ): Promise<EpisodeOfCare | OperationOutcome> {
    const medplumClient = client || medplum;
    await ensureAuthenticated();
    try {
      if (!episodeOfCareId) {
        throw new Error('EpisodeOfCare ID is required for update.');
      }
      if (Object.keys(updates).length === 0) {
        throw new Error('No updates provided for EpisodeOfCare.');
      }
  
      // Fetch the existing resource
      const existingEpisode = await medplumClient.readResource('EpisodeOfCare', episodeOfCareId);
      if (!existingEpisode) {
        // This case should ideally be handled by readResource throwing a not-found error
        // which would be caught and returned as OperationOutcome or null by getEpisodeOfCareById logic
        // For robustness, if it somehow returns null here:
        return {
          resourceType: 'OperationOutcome',
          issue: [
            {
              severity: 'error',
              code: 'not-found',
              diagnostics: `EpisodeOfCare with ID "${episodeOfCareId}" not found for update.`,
            },
          ],
        };
      }
      
      // Construct the updated resource. Be careful with deep merges or partial updates.
      // A common strategy for utilities is to merge top-level fields or replace arrays.
      const resourceToUpdate: EpisodeOfCare = {
        ...existingEpisode,
        resourceType: 'EpisodeOfCare', // Ensure resourceType is maintained
        id: episodeOfCareId, // Ensure ID is maintained
      };
  
      if (updates.status) resourceToUpdate.status = updates.status;
      if (updates.type) resourceToUpdate.type = updates.type; // Replace array
      if (updates.managingOrganizationId) {
        resourceToUpdate.managingOrganization = { reference: `Organization/${updates.managingOrganizationId}` };
      } else if (updates.hasOwnProperty('managingOrganizationId') && updates.managingOrganizationId === null) {
          delete resourceToUpdate.managingOrganization; // Allow unsetting
      }
  
      if (updates.careManagerId) {
        resourceToUpdate.careManager = { reference: `Practitioner/${updates.careManagerId}` };
      } else if (updates.hasOwnProperty('careManagerId') && updates.careManagerId === null) {
          delete resourceToUpdate.careManager; // Allow unsetting
      }
  
      // Handle period update
      let periodUpdated = false;
      const currentPeriod = resourceToUpdate.period || {};
      const newPeriod: Period = { ...currentPeriod };
      if (updates.hasOwnProperty('periodStart')) {
        newPeriod.start = updates.periodStart; // Allow null/undefined to clear
        periodUpdated = true;
      }
      if (updates.hasOwnProperty('periodEnd')) {
        newPeriod.end = updates.periodEnd; // Allow null/undefined to clear
        periodUpdated = true;
      }
      if(periodUpdated){
          if(newPeriod.start || newPeriod.end){
              resourceToUpdate.period = newPeriod;
          } else {
              delete resourceToUpdate.period;
          }
      }
  
      // Remove undefined top-level fields from the merged object that might have been introduced by spread
      Object.keys(resourceToUpdate).forEach(
          (key) => (resourceToUpdate as any)[key] === undefined && delete (resourceToUpdate as any)[key]
      );
  
      const result = (await medplumClient.updateResource(resourceToUpdate)) as EpisodeOfCare;
      console.log('EpisodeOfCare updated successfully:', result.id);
      return result;
    } catch (error: any) {
       if (error.outcome && error.outcome.issue && error.outcome.issue[0]?.code === 'not-found') {
        return {
          resourceType: 'OperationOutcome',
          issue: [
            {
              severity: 'error',
              code: 'not-found',
              diagnostics: `EpisodeOfCare with ID "${episodeOfCareId}" not found for update.`,
            },
          ],
        };
      }
      const outcome: OperationOutcome = {
        resourceType: 'OperationOutcome',
        issue: [
          {
            severity: 'error',
            code: 'exception',
            diagnostics: `Error updating EpisodeOfCare: ${error.message || 'Unknown error'}`,
          },
        ],
      };
      if (error.outcome) {
        return error.outcome as OperationOutcome;
      }
      return outcome;
    }
  }

• src/tools/episodeOfCareUtils.ts:39-47 (helper)

  TypeScript interface defining the input arguments accepted by the updateEpisodeOfCare handler function.

  export interface UpdateEpisodeOfCareArgs {
    status?: EpisodeOfCareStatus;
    type?: CodeableConcept[];
    periodStart?: string;
    periodEnd?: string;
    managingOrganizationId?: string;
    careManagerId?: string;
    // Consider how to handle diagnosis updates - potentially replacing all, or adding/removing specific ones.
  }

• src/tools/toolSchemas.ts:619-639 (schema)

  JSON schema defining the input parameters and validation for the updateEpisodeOfCare tool.

    name: 'updateEpisodeOfCare',
    description: 'Updates an existing EpisodeOfCare. Requires the EpisodeOfCare ID and the fields to update.',
    input_schema: {
      type: 'object',
      properties: {
        episodeOfCareId: { type: 'string', description: 'The unique ID of the EpisodeOfCare to update.' },
        status: { 
          type: 'string', 
          description: "New status for the episode of care. Optional.",
          enum: ['planned', 'waitlist', 'active', 'onhold', 'finished', 'cancelled', 'entered-in-error']
        },
        type: { /* Same as in createEpisodeOfCare, optional */ type: 'array', items: { '$ref': '#/definitions/episodeOfCareTypeItem' }, description: "Optional. New list of types for the episode of care. This will replace the existing types." },
        periodStart: { type: 'string', format: 'date-time', description: "Optional. New start date/time (ISO8601)." },
        periodEnd: { type: 'string', format: 'date-time', description: "Optional. New end date/time (ISO8601)." },
        managingOrganizationId: { type: 'string', description: "Optional. New ID of the managing organization. Provide an empty string or null (if supported by LLM) to remove." },
        careManagerId: { type: 'string', description: "Optional. New ID of the care manager. Provide an empty string or null to remove." }
        // Diagnosis updates are complex and typically handled differently, so not included in simple updates.
      },
      required: ['episodeOfCareId'] // At least one update field is implicitly required
    }
  },

• src/index.ts:752-769 (registration)

  MCP server tool registration including name, description, and input schema for updateEpisodeOfCare.

    name: "updateEpisodeOfCare",
    description: "Updates an existing episode of care. Requires the episode ID and fields to update.",
    inputSchema: {
      type: "object",
      properties: {
        episodeOfCareId: {
          type: "string",
          description: "The unique ID of the episode of care to update.",
        },
        status: {
          type: "string",
          description: "New status for the episode of care.",
          enum: ["planned", "waitlist", "active", "onhold", "finished", "cancelled", "entered-in-error"],
        },
      },
      required: ["episodeOfCareId"],
    },
  },

• src/index.ts:981-981 (registration)

  Mapping of tool name to handler function in the toolMapping object used by the MCP server request handler.

  updateEpisodeOfCare,

• src/index.ts:58-60 (registration)

  Import of the updateEpisodeOfCare handler function from episodeOfCareUtils.

    updateEpisodeOfCare,
    searchEpisodesOfCare,
  } from './tools/episodeOfCareUtils.js';