13.26.1Bulk Resource Modification

Smile CDR includes two operations which can be used to modify large numbers of FHIR resources in a batch operation. These operations use the FHIR Asynchronous Interaction Request Pattern.

13.26.2Security Implications

The operations described here are powerful and potentially destructive operations that can modify large amounts of data. They are intended to be used to correct data issues, upgrade data, etc., typically as a one-time and well-planned action.

Each operation here requires a specific dedicated permission to be granted to the initiating user, and for the given operation to be specifically enabled on the FHIR Storage module. It is highly recommended that the operations be enabled and the appropriate permissions granted only temporarily when the operation is required to minimize the risk of unintended data modification.

It is also highly recommended to test the operations in a development environment before using them in production, and to take appropriate system backups.

13.26.3Bulk Patch ($hapi.fhir.bulk-patch)

The Bulk Patch operation takes one or more FHIR search URLs, fetches the resources matched by those URLs, and applies a change to the newest version of each returned resource. If a resource is modified by the operation, a new version of the resource will be stored.

In order to use this operation, the Bulk Modify Patch Operation setting must be enabled and the user must have appropriate permissions.

13.26.3.1Request

To initiate a Bulk Patch operation, send a POST request to the http://base-url/$hapi.fhir.bulk-patch endpoint. An HTTP Prefer request header must be included indicating asynchronous processing. The request body must contain a Parameters resource. See Request Parameters for a list of parameters to include. An example request is shown below.

13.26.3.2Request Parameters

13.26.3.3Example Request

POST /$hapi.fhir.bulk-patch
Prefer: respond-async
Content-Type: application/fhir+json

(.. Parameters Resource in Request Body ..)

An example request payload with a simple FHIRPath Patch document is shown below.

{
  "resType": "Parameters",
  "parameter": [ {
    "name": "patch",
    "resource": {
      "resType": "Parameters",
      "parameter": [ {
        "name": "operation",
        "part": [ {
          "name": "type",
          "valueCode": "replace"
        }, {
          "name": "path",
          "valueString": "Patient.active"
        }, {
          "name": "value",
          "valueCode": "true"
        } ]
      } ]
    }
  }, {
    "name": "url",
    "valueString": "Patient?"
  } ]
}

13.26.3.4Response

The server will respond with an HTTP 202 Accepted response code. The response will include a Content-Location header with a URL that can be polled to determine the status of the operation.

An example response is shown below.

202 Accepted
Content-Location: http://example.org/$hapi.fhir.bulk-patch-status?_jobId=33b280a7-1715-4d38-a7d4-6f5d1c705551
Content-Type: application/fhir+json;charset=utf-8

{
	"resourceType":"OperationOutcome",
	"issue":[
		{
			"severity":"information",
			"code":"informational",
			"diagnostics":"$hapi.fhir.bulk-patch job has been accepted. Poll for status at the following URL: http://localhost:8000/$hapi.fhir.bulk-patch.poll-for-status?_jobId=33b280a7-1715-4d38-a7d4-6f5d1c705551"
		}
	]
}

13.26.4Bulk Patch with History Rewrite ($hapi.fhir.bulk-patch-rewrite-history)

The Bulk Patch with History Rewrite operation takes one or more FHIR search URLs, fetches the resources matched by those URLs, and applies a change to all versions of each returned resource. Each version is modified by rewriting the history for the resource. This means that existing resource versions are directly modified without creating a new version. This is a potentially destructive operation and should be used with extreme caution.

In order to use this operation, both the History Rewrite and Bulk Modify Patch with History Rewrite Operation settings must be enabled and the user must have appropriate permissions.

13.26.4.1Request

To initiate a Bulk Patch operation, send a POST request to the http://base-url/$hapi.fhir.bulk-patch-rewrite-history endpoint. An HTTP Prefer request header must be included indicating asynchronous processing. The request body must contain a Parameters resource. See Request Parameters for a list of parameters to include.

13.26.4.2Request Parameters

13.26.4.3Example Request

POST /$hapi.fhir.bulk-patch-rewrite-history
Prefer: respond-async
Content-Type: application/fhir+json

(.. Parameters Resource in Request Body ..)

13.26.5Common Bulk Modification Request Parameters

The following table outlines request parameters which are common for all Bulk Modification operations.

13.26.6Polling for Status

When initiating a bulk resource modification operation, the server will respond with an HTTP 202 Accepted response code. The response will include a Content-Location header with a URL that can be polled to determine the status of the operation.

While the operation is in progress, the server will respond with an HTTP 202 Accepted response code. When the operation is complete (whether it has completed successfully or has failed or been canceled), the server will respond with an HTTP 200 OK response code. The response body will contain a FHIR Bundle resource with the results of the operation.

In the case of a successful operation completion, the Bundle will contain an OperationOutcome resource where OperationOutcome.issue.diagnostics contains a brief report outlining the results of the job. A sample report is shown below:

Bulk Patch Report
-------------------------------------------------
Start Time                : 2025-08-19 14:24:03.404
Duration                  : 158ms
Total Resources Changed   : 2 (2/sec)
Total Resources Unchanged : 1 (1/sec)
Total Failed Changes      : 0 (0/sec)
Total Retried Chunks      : 0
Total Retried Resources   : 0
-------------------------------------------------
ResourceType[Patient]
    Changed   : 2
    Unchanged : 1
-------------------------------------------------