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).

  1. Configure a REST Adapter trigger connection and FHIR Adapter invoke connection.
  2. 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.


    The REST trigger Summary page shows fields for Description, Endpoint Summary, REST Service URI, Method, and Query Params. The contents of these fields are described above this image. Below this are the Previous and Close buttons.

  3. Drag the FHIR Adapter into the integration canvas.
  4. 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 ...).
  5. 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:


    The Configure Interaction page is shown. Fields are shown for FHIR Schema Source, FHIR Resource, FHIR Interaction, and Configure Response. Below this is the Operations section, which includes a table with columns for Operation and Resource Element. At the bottom are buttons for Close, Previous, and Next.

  6. Open and configure the mapper to pass the ID of the Patient resource to patch.
  7. 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.


      The mapper shows the Sources, Mapping canvas, and Targets section. Source elements are mapped to target elements. The From Index target element is set with a literal value shown in the Expression Builder at the bottom.

      A view of key parts of the existing JSON FHIR Patient 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"
          }
       }
    }
.....
.....
  8. Save and activate the integration.
  9. Select Actions icon, and then Run.
  10. 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. If female is instead specified, patch operations stop and the instance run fails with a value did not match error.
    • Add a new name of Bob to the FHIR resource.


      The Request section shows tabs for URI parameters (which is selected), Headers, Body, cURL, and Integration properties. A table shows three parameters and their values.

      The operation to move the address of Austin above Chicago in the FHIR resource was specified as literal strings in the mapper. Therefore, nothing needs to be specified here.

  11. 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.


    The Activity stream is shown. The instance ID is shown. The tracing level is set to Debug. The key milestones are shown. All have run successfully. An invoke connection is expanded to show the Payload with the patch syntax.

    A review of the JSON-based Patient resource shows that the name of Bob was added, the gender of male was tested successfully, and Austin was moved (reordered) to the first array in the index above Chicago.
    {
    "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.

  1. Drag the FHIR Adapter invoke connection into the integration canvas.
  2. On the Basic Info page, enter a name and optional description, and select Perform Actions on a FHIR Resource (Create, Read, Update, and more ...).
  3. 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


    The Configure Interaction page is shown. Fields are shown for FHIR Schema Source, FHIR Resource, FHIR Interaction, and Configure Response. Below this is the Operations section, which includes a table with columns for Operation and Resource Element. Add and Remove buttons also appear.

  4. Open and configure the mapper to pass the ID of the Patient resource to patch.
  5. 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.

  6. Select Path, then right-click and select Create target node to explicitly specify the path in the Expression Builder.


    The mapper shows the Sources, Mapping canvas, and Targets section. Source elements are mapped to target elements. The Path target element is set with a literal value shown in the Expression Builder at the bottom.

    You must now select the corresponding data type of that element.

  7. Right-click Value and select Extended Data Types, then Period. This adds a Period extends Value element.


    The Add FHIR Path Param target element is expanded to show the Path, Value, and Period extends Value elements.

  8. Expand Period extends Value to set literal string values for child elements such as Start and End.


    The mapper shows the Sources, Mapping canvas, and Targets section. Source elements are mapped to target elements. The Start target element is set with a literal value shown in the Expression Builder at the bottom.

  9. 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.

  10. Right-click From Path and To Path and select Create target node to set paths as literal values for each.


    The From Path target element is set with a literal value shown in the Expression Builder at the bottom.


    The To Path target element is set with a literal value shown in the Expression Builder at the bottom.

  11. Expand Test FHIR Path Param.
  12. Select Path, then right-click and select Create target node to explicitly specify the path in the Expression Builder.


    The mapper shows the Sources, Mapping canvas, and Targets section. Source elements are mapped to target elements. The Path element is set with a literal value shown in the Expression Builder at the bottom.

    You must now select the corresponding data type of that element.

  13. Right-click Value below Path and select Extended Data Types, then Address. This adds the Address extends Value element.
  14. Expand Address extends Value to set literal string values for child elements such as City.
  15. Right-click City and select Create target node to set a literal value in the Expression Builder.


    The mapper shows the Sources, Mapping canvas, and Targets section. Source elements are mapped to target elements. The City target element is set with a literal value shown in the Expression Builder at the bottom.

  16. Set literal values for additional elements, as needed.