Update Specific Fields of a FHIR Resource with the Patch Interaction
You can update specific fields of a FHIR resource with the patch interaction. This section provides use cases that describe how to patch both top-level elements and more granular, child-level elements in a FHIR resource.
A FHIR resource (for example, Patient) consists of an entire schema tree that includes top-level elements and child-level elements.
You can patch top-level elements. For example, a top-level name element can be comprised of child-level elements such as first name, last name, and others. You can only patch name in its entirety because you get the entire schema tree.
If you need to patch any child-level element in the entire schema tree, you must use the FHIR Patch Param resource element.
Patch Top-Level Elements of the FHIR Resource
This use case provides a design-time to runtime overview of how to configure patch interaction operations to test the specific gender in a resource, add a name to a resource, and move an address in a resource. You then run the integration to view the results in the activity stream. This use case specifically describes how to patch top-level elements of a FHIR resource (for example, adding a top-level name to a resource, instead of adding a child-level first name, last name, and family name to a resource).
- Configure a REST Adapter trigger connection and FHIR Adapter invoke connection.
- Drag the REST Adapter into
the integration canvas and specify the configuration
details. When complete, the following details are
defined:
- REST service URL of /startFhirOutboundPatchDemo.
- HTTP method of GET.
- Three defined query parameters: patient-id, gender, and name.
- Drag the FHIR Adapter into the integration canvas.
- On the Basic Info page, enter a name (for this
example,
PatchInvoke
) and optional description, and select Perform Actions on a FHIR Resource (Create, Read, Update, and more ...). - On the Configure Interaction page, specify the
following:
Element Description FHIR Schema Source Standard Schema Definition Note: Only Standard Schema Definition is supported for the patch interaction.
FHIR Resource Patient FHIR Interaction patch Configure Response representation Operations Select the following three patch operations and resource elements to perform on the Patient FHIR resource. - Operation one:
- Operation: test
- Resource Element: gender
- Operation two:
- Operation: add
- Resource Element: name
- Operation three:
- Operation: move
- Resource Element: address
The Configure Interaction page looks as follows:
- Operation one:
- Open and configure the mapper to pass the ID of the Patient resource to patch.
- Configure the operations you defined on the
Configure Interaction page:
- Map the source
Name to the target
Name.
This mapping is to add the name of a patient. Note that Add Name appears under an Index element because it is an array in the Patient resource. You add a new name to a specific index in that array, which prevents the name from being added to the end of the array. If you don't specify the index, the name is added to the end of the array.
- Map the source
Gender to the target
Gender.
This mapping is simply to test that the specific patient gender matches with what is specified at runtime. Test Gender does not appear under an Index because it is not an array in the Patient resource.
- Define the address to move as
literal strings in the Expression Builder.
Note that Move Address also appears under an Index because it is an array in the Patient resource. You must specify the indexes from which and to which to move the address. When you perform a move operation, you are always moving (reordering) elements of arrays.
A view of key parts of the existing JSON FHIRPatient
resource prior to patching shows one current name (John
), the gender (male
), and two addresses.{ "resourceType": "Patient", "name": [ { "use": "official", "family": "Doe", "given": [ "John" ] } ], "telecon": [ { "system": "phone", "value": "999 888 7777" } ], "birthdate": "1980-01-01", "id": "bf7321c0-aa0a-465a-abe0-5a0f35da709a", "gender": "male", "meta": { "versionId": "54", "lastUpdated": "2025-02-12T08:27:08.776973414+00:00" }, "address": [ { "city": "Chicago" }, { "city": "Austin" } } } ..... .....
- Map the source
Name to the target
Name.
- Save and activate the integration.
- Select
, and then Run.
- Specify the following parameter values to patch the
Patient FHIR resource.
- Add the ID of the Patient resource.
- Test that the gender specified
matches with
male
in the FHIR resource. If it does, patching continues. Iffemale
is instead specified, patch operations stop and the instance run fails with avalue did not match
error. - Add a new name of
Bob
to the FHIR resource.
The operation to move the address of
Austin
aboveChicago
in the FHIR resource was specified as literal strings in the mapper. Therefore, nothing needs to be specified here.
- When processing completes, expand invoke
PatchInvoke in the activity stream. The
JSON patch payload is visible and consists of the three
operations to test the gender, add the name, and move the
address.
A review of the JSON-basedPatient
resource shows that the name ofBob
was added, the gender ofmale
was tested successfully, andAustin
was moved (reordered) to the first array in the index aboveChicago
.{ "resourceType": "Patient", "name": [ { "use": "official", "family": "Doe", "given": [ "John" ] } "given": [ "Bob" ] } ], "telecon": [ { "system": "phone", "value": "999 888 7777" } ], "birthdate": "1980-01-01", "id": "bf7321c0-aa0a-465a-abe0-5a0f35da709a", "gender": "male", "meta": { "versionId": "54", "lastUpdated": "2025-02-12T08:27:08.776973414+00:00" }, "address": [ { "city": "Austin" }, { "city": "Chicago" } } } ..... .....
Patch Child-Level Elements of the FHIR Resource
This use case provides a design-time overview of how to configure patch interaction operations for child-level elements in the selected FHIR resource.
You may have scenarios in which you need to perform more granular, child-level element patching in the FHIR resource. For example, you need to patch the first and last names (child-level elements) of a patient, instead of just the name (top-level element). To patch child-level elements, you select the FHIR Path Param resource element on the Configure Interaction page during FHIR Adapter configuration. The FHIR Path Param resource element works with paths, instead of indexes. The FHIR Path Param resource element enables you to literally specify the path to any FHIR resource, child-level element in the mapper. The steps to patch child-level elements in the mapper are slightly more detailed than with patching top-level elements. The following steps provide an overview of child-level patching.
- Drag the FHIR Adapter invoke connection into the integration canvas.
- On the Basic Info page, enter a name and optional description, and select Perform Actions on a FHIR Resource (Create, Read, Update, and more ...).
- On the Configure Interaction page, specify the
following:
Element Description FHIR Schema Source Standard Schema Definition FHIR Resource Patient FHIR Interaction patch Configure Response representation Operations Select the following patch operations and resource elements to perform on the Patient FHIR resource. The FHIR Path Param resource element lets you literally specify the path to a child-level element to patch in the FHIR resource. This action provides a more fine-grained approach to patching and does not restrict you to patching only top-level elements. - Operation one:
- Operation: add
- Resource Element: FHIR Path Param
- Operation two:
- Operation: test
- Resource Element: FHIR Path Param
- Operation three:
- Operation: move
- Resource Element: FHIR Path Param
- Operation one:
- Open and configure the mapper to pass the ID of the Patient resource to patch.
- Expand Add FHIR Path Param.
Note that Add FHIR Path Param (for patching child-level elements) appears under the Path element. This differs from the first use case described in Patch Top-Level Elements of the FHIR Resource in which Add Name (for patching top-level elements) appears under the Index element. The Path element requires you to perform a different set of mapper tasks.
- Select Path, then
right-click and select Create target
node to explicitly specify the path in
the Expression Builder.
You must now select the corresponding data type of that element.
- Right-click Value and select
Extended Data Types, then
Period. This adds a
Period extends Value
element.
- Expand Period extends Value
to set literal string values for child elements such as
Start and
End.
- Expand Move FHIR Path
Param.
The From Path and To Path nodes are displayed. Unlike Add FHIR Path Param, Move FHIR Path Param does not appear under a Path. Move FHIR Path Param also does not require the selection of a data type.
- Right-click From Path and
To Path and select
Create target node to set
paths as literal values for each.
- Expand Test FHIR Path Param.
- Select Path, then right-click and select
Create target node to
explicitly specify the path in the Expression Builder.
You must now select the corresponding data type of that element.
- Right-click Value below Path and select Extended Data Types, then Address. This adds the Address extends Value element.
- Expand Address extends Value to set literal string values for child elements such as City.
- Right-click City and select
Create target node to set a
literal value in the Expression Builder.
- Set literal values for additional elements, as needed.