Skip to main content

Updating Data

Medplum offers three FHIR operations that can be used to update data:

  • update: Replaces the entire resource
  • upsert: Replaces the entire resource and creates a new one if the specified resource is not found
  • patch: Updates only the specific element(s) that are requested.

Update Operation​

The update operation is performed by sending a PUT request, which will create an entirely new version of your resource, rewriting every element. When sending an update request you must include the resourceType and the id of the resource you are updating, as well as the updated resource itself in the body of the request.

Medplum provides the updateResource method on the MedplumClient which implements the update operation. The function takes the updated resource as an argument.

The below example updates a Patient resource.

Example: Updating a Resource

const updatedPatient = await medplum.updateResource({
  resourceType: 'Patient',
  id: 'homer-simpson',
  name: [{ family: 'Simpson', given: ['Homer'] }],
});

Upsert Operation​

The upsert operation also sends a PUT request, updating your entire resource. However, instead of taking the id, it allows you to use a search query with FHIR search parameters to find the resource you want to update.

  • If the search query resolves to a single resource, that resource will be updated.
  • If it does not find a matching resource, one will be created from the given data.
  • If multiple matches are found, an error will be returned. In this case, more specific search criteria are required to unambiguously identify the resource to be updated or created.

Medplum provides the upsertResource method on the MedplumClient, which implements the upsert operation. The function takes a resource and a FHIR search query to find the resource to be updated.

The below operation searches for a patient to add a name to, and creates it if it cannot be found.

Example: Upserting a Resource
await medplum.upsertResource(
  { resourceType: 'Patient', id: 'homer-simpson', name: [{ family: 'Simpson', given: ['Homer'] }] },
  'Patient?family="Simpson"&given="Homer"'
);

Patch Operation​

The patch operation is performed by sending an HTTP PATCH request, which updates only the specified elements in your resource. When sending a patch operation, you must include the resourceType and the id of the resource, as well as the patch body, containing the operation, path, and value.

Medplum provides the patchResource method on the MedplumClient which implements the patch operation. The function takes the resourceType, id, and an array of PatchOperations. A PatchOperation details the updates that will be made to your resource, and has three required fields: op, path, and value. The op is the actual operation that will be performed, the path is the path to the element on the resource that is being updated, and the value is the new value for the element at the given path.

The PatchOperation below sends an add operation to the name of the Patient with our newly created name. The add operation can be used even if the patient already has a name, as it will replace any value it finds at the given path.

Example: Patching a Resource
const patchedPatient = await medplum.patchResource('Patient', 'homer-simpson', [
  { op: 'test', path: '/meta/versionId', value: patient.meta?.versionId },
  { op: 'add', path: '/name', value: [{ family: 'Simpson', given: ['Homer'] }] },
]);
Preventing Race Conditions

In the TypeScript patch example, a second PatchOperation is included:

{ op: 'test', path: '/meta/versionId', value: patient.meta?.versionId }

This is a test to prevent race conditions. This will cause the patch to fail if the resource on the server has a different versionId than the one you are sending. It is strongly recommended to include this test on all patch operations.