Merge pull request #312082 from evachen96/20260219_evachbulkupdatemeta

20260219 evachbulkupdatemeta

Author: prmerger-automator[bot]

articles/healthcare-apis/fhir/fhir-bulk-update.md

@@ -42,7 +42,7 @@ To execute a bulk update, the application or user must be assigned one of the fo
 
 ## Request
 
-You can use FHIR search parameters in the request. The bulk update operation supports standard search filters, for example: address:contains=Meadow, or Patient.birthdate=1987-02-20. You can also use _include, _revinclude, and _not-referenced to extend search criteria.
+You can use FHIR search parameters in the request. The bulk update operation supports standard search filters, for example: address:contains=Meadow, or Patient.birthdate=1987-02-20. You can also use _include, _revinclude, and _not-referenced to extend search criteria, and _meta-history to configure versioning behavior for metadata-only updates. 
 
 ### Request examples
 
@@ -61,6 +61,10 @@ You can use FHIR search parameters in the request. The bulk update operation sup
 
  `PATCH {FHIR-SERVICE-HOST}/DiagnosticReport/$bulk-update?_lastUpdated=lt2021-12-12&_include=DiagnosticReport:based-on:ServiceRequest&_include:iterate=ServiceRequest:encounter`
 
+4. Metadata-only updates with `_meta-history` query parameter: When the FHIR server versioning policy is set to either `versioned` or `version-update`, the `_meta-history` parameter allows you to control whether metadata-only changes to a resource create a new historical version of the resource or not. By default, any change to a resource, including metadata-only changes, creates a new version and saves the previous version as a historical record. When you set the `_meta-history` parameter to false, metadata-only changes do not create a new version, and the previous version is not saved as a historical record. This feature is useful for scenarios where frequent metadata updates are made, and you want to avoid cluttering the resource history with numerous versions that only differ in metadata. For more information and examples, see [FHIR versioning policy and history management](fhir-versioning-policy-and-history-management.md#metadata-only-updates-and-versioning).  
+
+ `PATCH https://{FHIR-SERVICE-HOST}/$bulk-update?_meta-history=false`  
+
 When using bulk update with FHIR search parameters, consider using the same query in a FHIR search first, so that you can verify the data that you plan to update.
 
 The following is an example request body.

articles/healthcare-apis/fhir/fhir-versioning-policy-and-history-management.md

@@ -12,7 +12,7 @@ ms.custom: sfi-image-nochange
 
 # Versioning policy and history management
 
-The versioning policy in the Azure Health Data Services FHIR® service is a configuration which determines how history is stored for every resource type, with the option for resource specific configuration. This policy is directly related to the concept of managing history for FHIR resources.
+The versioning policy in the Azure Health Data Services FHIR® service is a configuration that determines how history is stored for every resource type, with the option for resource specific configuration. This policy is directly related to the concept of managing history for FHIR resources.
 
 ## History in FHIR
 
@@ -71,9 +71,9 @@ Changing the versioning policy, either at a system level or resource level, won'
 > The query parameter _summary=count and _count=0 can be added to _history endpoint to get a count of all versioned resources. This count includes soft deleted resources.
 
 ## Metadata-only updates and versioning
-If the versioning policy is set to either `versioned` or `version-update`, metadata-only updates (changes to FHIR resources that only affect the metadata) increment the resource version, create a new version, and save the old version as a historical record. If you are making metadata-only changes using PUT or PATCH updates, you can use the query parameter _meta-history for PUT and PATCH updates to configure whether or not the old version is saved as a historical record.
+If the versioning policy is set to either `versioned` or `version-update`, metadata-only updates (changes to FHIR resources that only affect the metadata) increment the resource version, create a new version, and save the old version as a historical record. If you're making metadata-only changes using PUT, PATCH, or `$bulk-update`, you can use the query parameter `_meta-history` to configure whether or not the old version is saved as a historical record.
 - `_meta-history=true` is set by default. By default, the resource version is incremented, a new version is created, and the old version is saved as a historical record. The lastUpdated timestamp is updated to reflect the change.
-- `_meta-history=false` The `_meta-history` parameter can be configured to `false`. This means that the resource version is incremented, a new version is created, but the old version is not saved as a historical record. The lastUpdated timestamp is also still updated to reflect the change. This configuration can be used to help reduce data storage when making metadata-only updates.  
+- `_meta-history=false` The `_meta-history` parameter can be configured to `false`. This means that the resource version is incremented, a new version is created, but the old version isn't saved as a historical record. The lastUpdated timestamp is also still updated to reflect the change. This configuration can be used to help reduce data storage when making metadata-only updates.  
 
 
 ### Example of `_meta-history=false` with PUT
@@ -92,7 +92,7 @@ To demonstrate the use of the `_meta-history` parameter with PUT, follow this ex
     ]
 }
 ```
-2. Create a new version of the resource with `PUT <fhir server>/Patient/test-patient`. This will have version 2.
+2. Create a new version of the resource with `PUT <fhir server>/Patient/test-patient`. This has version 2.
 ```
 {
     "id": "test-patient",
@@ -127,11 +127,11 @@ To demonstrate the use of the `_meta-history` parameter with PUT, follow this ex
     ]
 }
 ```
-5. This will increment resource version and create a new version 3, but the old version 2 will not be saved as a historical record. To see this, run: `GET <fhir server>/Patient/test-patient/_history`. Two versions should be returned, versions 1 and 3. Please note that `_meta-history=false` query parameter only affects metadata-only changes made using PUT or PATCH. Using the query parameter to make metadata updates along with other non-metadata field value changes will increment the resource version and save the old version as a historical record.
+5. This increments resource version and create a new version 3, but the old version 2 won't be saved as a historical record. To see this, run: `GET <fhir server>/Patient/test-patient/_history`. Two versions should be returned, versions 1 and 3. Please note that `_meta-history=false` query parameter only affects metadata-only changes made using PUT or PATCH. Using the query parameter to make metadata updates along with other non-metadata field value changes will increment the resource version and save the old version as a historical record.
 
 
-### Example of `_meta-history=false` with PATCH
-To demonstrate the use of the `_meta-history` parameter with PATCH, follow this example:
+### Example of `_meta-history=false` with PATCH or `$bulk-update`
+To demonstrate the use of the `_meta-history` parameter with PATCH or `$bulk-update`, follow this example:
 
 1. Create a resource:  
 `PUT <fhir server>/Patient/test-patient`
@@ -169,7 +169,7 @@ To demonstrate the use of the `_meta-history` parameter with PATCH, follow this
 }
 ```
 3. Run: `GET <fhir server>/Patient/test-patient/_history`. Two versions should be returned, versions 1 and 2.
-4. Use PATCH to make a metadata-only update with `_meta-history=false` query parameter. The example uses PATCH to update only the Patient.meta.tag.system value. More information about PATCH [here](rest-api-capabilities.md#patch-and-conditional-patch).
+4. Use PATCH or `$bulk-update`to make a metadata-only update with `_meta-history=false` query parameter. The example demonstrates using PATCH or `$bulk-update` to update only the Patient.meta.tag.system value. More information about PATCH [here](rest-api-capabilities.md#patch-and-conditional-patch) and `$bulk-update` [here](fhir-bulk-update.md).
 
 Using PATCH with FHIRPath patch:  
 `PATCH <fhir server>/Patient/test-patient?_meta-history=false`  
@@ -192,6 +192,30 @@ Using PATCH with FHIRPath patch:
   ]
 }
 ```
+If you wanted to bulk update multiple resources, you could use `$bulk-update`. The following example shows how to use `$bulk-update` to update the same metadata field for all Patient resources with `_meta-history=false`:
+
+`PATCH <fhir server>/Patient/$bulk-update?_meta-history=false`
+`Accept: application/fhir+json`  
+`Content-type: application/fhir+json`
+`Prefer: respond-async`
+
+``` 
+
+{
+  "resourceType": "Parameters",
+  "parameter": [
+    {
+      "name": "operation",
+      "part": [
+        { "name": "type",  "valueCode": "upsert" },
+        { "name": "path",  "valueString": "Patient.meta.tag[0].system" },
+        { "name": "value", "valueUri": "test2" }
+      ]
+    }
+  ]
+}
+```
+
 
 Using PATCH with JSON Patch:
 `PATCH <fhir server>/Patient/test-patient?_meta-history=false`  
@@ -207,6 +231,8 @@ Using PATCH with JSON Patch:
 ```
 5. This will increment resource version and create a new version 3, but the old version 2 will not be saved as a historical record. To see this, run: `GET <fhir server>/Patient/test-patient/_history`. Two versions should be returned, versions 1 and 3. Please note that `_meta-history=false` query parameter only affects metadata-only changes made using PUT or PATCH. Using the query parameter to make metadata updates along with other non-metadata field value changes will increment the resource version and save the old version as a historical record.
 
+
+
 ## Next steps
 
 In this article, you learned how to purge the history for resources in the FHIR service. For more information about how to disable history and some concepts about history management, see

articles/healthcare-apis/fhir/rest-api-capabilities.md

@@ -182,7 +182,7 @@ Content-Type: `application/json`
 ```
 
 #### Patch with `_meta-history` parameter
-The FHIR service supports the `_meta-history` query parameter with both `PUT` and `PATCH` operations. This parameter allows you to control whether metadata-only changes to a resource create a new historical version of the resource or not. By default, any change to a resource, including metadata-only changes, creates a new version and saves the previous version as a historical record. When you set the `_meta-history` parameter to `false`, metadata-only changes do not create a new version, and the previous version is not saved as a historical record. This feature is useful for scenarios where frequent metadata updates are made, and you want to avoid cluttering the resource history with numerous versions that only differ in metadata. For more information and examples, see [FHIR versioning policy and history management](fhir-versioning-policy-and-history-management.md#metadata-only-updates-and-versioning).
+The FHIR service supports the `_meta-history` query parameter with both `PUT` and `PATCH` operations.  When the FHIR server versioning policy is set to either `versioned` or `version-update`, the `_meta-history` parameter allows you to control whether metadata-only changes to a resource create a new historical version of the resource or not. By default, any change to a resource, including metadata-only changes, creates a new version and saves the previous version as a historical record. When you set the `_meta-history` parameter to `false`, metadata-only changes do not create a new version, and the previous version is not saved as a historical record. This feature is useful for scenarios where frequent metadata updates are made, and you want to avoid cluttering the resource history with numerous versions that only differ in metadata. For more information and examples, see [FHIR versioning policy and history management](fhir-versioning-policy-and-history-management.md#metadata-only-updates-and-versioning).
 
 `PATCH <fhir server>/Patient/test-patient?_meta-history=false`