You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/healthcare-apis/dicom/update-files.md
+42-7Lines changed: 42 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
2
title: Update files in the DICOM service in Azure Health Data Services
3
3
description: Learn how to use the bulk update API in Azure Health Data Services to modify DICOM attributes for multiple files in the DICOM service. This article explains the benefits, requirements, and steps of the bulk update operation.
4
-
author: varunbms
4
+
author: Expekesheth
5
5
ms.service: azure-health-data-services
6
6
ms.subservice: dicom-service
7
7
ms.topic: how-to
8
8
ms.date: 07/23/2025
9
-
ms.author: buchvarun
9
+
ms.author: kesheth
10
10
---
11
11
12
12
# Update DICOM files
@@ -21,7 +21,7 @@ There are a few limitations when you use the bulk update operation:
21
21
- A maximum of 50 studies can be updated in a single operation.
22
22
- Only one bulk update operation can be performed at a time for a given study.
23
23
- For updates involving UID changes, only one study can be updated in a single operation.
24
-
-Only Study Instance UIDand Series Instance UID can be updated as part of UID update. SOP Instance UID cannot be updated for an instance.
24
+
- Study Instance UID, Series Instance UID, and SOP Instance UID can be updated.SOP Instance UID updates require `seriesInstanceUid`. Missing this results in HTTP 400 (Bad Request).
25
25
- UID update operation would fail when the target UIDs (`studyInstanceUID`, `seriesInstanceUid` and `sopInstanceUId`) already exists.
26
26
- You can't delete only the latest version of a study, or revert back to the original version.
27
27
- You can't update any field from non-null to a null value.
@@ -101,6 +101,19 @@ For updating the UIDs, new UIDs have to be provided in the change dataset as fol
101
101
}
102
102
}
103
103
```
104
+
3. Use the request below to update the 'SOPInstanceUid' for a specific instance within a series. Note that a single instance is updated at a time, and both the 'studyInstanceUid' and 'seriesInstanceUid' must be provided along with the current 'sopInstanceUid' and the new value in the changeDataset.
105
+
106
+
{
107
+
"studyInstanceUid": "1.2.3.4",
108
+
"seriesInstanceUid": "5.6.7.8",
109
+
"sopInstanceUid": "9.10.11.12",
110
+
"changeDataset": {
111
+
"00080018": {
112
+
"vr": "UI",
113
+
"Value": ["9.10.11.13"]
114
+
}
115
+
}
116
+
}
104
117
105
118
#### Responses
106
119
When a bulk update operation starts successfully, the API returns a `202` status code. The body of the response contains a reference to the operation.
@@ -178,22 +191,44 @@ GET {dicom-service-url}/{version}/operations/{operationId}
178
191
| 404 (Not Found) || Operation not found |
179
192
180
193
## Retrieving study versions
181
-
The [Retrieve (WADO-RS)](dicom-services-conformance-statement-v2.md#retrieve-wado-rs) transaction allows you to retrieve both the original and latest version of a study, series, or instance. By default, the latest version of a study, series, or instance is returned. The original version is returned by setting the `msdicom-request-original` header to `true`. For bulk updates involving UID update, the original and latest version can be retrieved using the newer UIDs only. An example request follows.
194
+
The [Retrieve (WADO-RS)](dicom-services-conformance-statement-v2.md#retrieve-wado-rs) transaction allows you to retrieve both the original and latest version of a study, series, or instance. By default, the latest version of a study, series, or instance is returned.
195
+
* To retrieve the original version, set the `msdicom-request-original` header to `true`.
196
+
* For bulk updates involving UID update, including Study, Series, or SOP Instance UID updates, the original and latest version can be retrieved using the newer UIDs only.
197
+
* When SOP Instance UID filtering was used in a bulk update, you can retrieve specific instances by providing the updated SOP Instance UID.
198
+
199
+
Example request for retrieving a specific instance after a bulk update:
182
200
183
201
```http
184
202
GET {dicom-service-url}/{version}/studies/{study}/series/{series}/instances/{instance}
For bulk updates involving UID update, the original and latest version can be retrieved using the newer UIDs only.
207
+
This ensures precise retrieval even after hierarchy or UID changes in bulk updates.
191
208
192
209
## Delete
193
210
The [delete](dicom-services-conformance-statement-v2.md#delete) method deletes both the original and latest version of a study, series, or instance.
194
211
195
212
## Change feed
196
-
The [change feed](change-feed-overview.md) records update actions in the same manner as create and delete actions. For UID updates, change feed entries for the older UIDs will not be updated. The update action would be present only for the new UIDs.
213
+
The [change feed](change-feed-overview.md) records update actions in the same manner as create and delete actions.
214
+
* For UID updates, including Study, Series, or SOP Instance UID, change feed entries for the older UIDs are not updated.
215
+
* Update actions are recorded only for the new UIDs.
216
+
* When SOP Instance UID filtering is applied, the change feed reflects updates only for the targeted instances.
217
+
218
+
## Summary of DICOM UID Update Behavior by Hierarchy Level
219
+
This table outlines how bulk updates behave at different levels of the DICOM hierarchy—Study, Series, and Instance—highlighting when updates are allowed, whether a SOP Instance UID filter is required, how instances are moved, and the resulting impact on the UID hierarchy.
| Update patient demographic attributes only | ✅ | ✅ | ✅ |Not required | No movement | Attributes updated in place; original UID hierarchy preserved. |
225
+
| Update Study Instance UID | ✅ | ❌ | ❌ | ❌ | Study → New Study | All instances in study get new Study UID; series and instance UIDs remain unless explicitly changed. |
226
+
| Update Series Instance UID | ✅ | ✅ | ❌ | Not required | Series → New Series | All instances in series get new Series UID; Study UID remains unless updated; SOP Instance UID unchanged. |
227
+
| Update SOP Instance UID | ❌ | ❌ | ✅ | Required | Instance → New Instance | Only the filtered SOP Instance(s) are updated; new SOP Instance UID assigned; Study/Series UID preserved. |
228
+
| Update Study & Series UIDs | ✅ | ✅ | ❌ | Not required | Study → New Study → Series → New Series | Hierarchy updated; all instances in series adopt new UIDs. |
229
+
| Update Study, Series, and SOP Instance UIDs | ✅ | ✅ | ✅ | Required | Study → New Study → Series → New Series → Instance → New Instance | Complete hierarchy updated with filtered SOP instance selection where applicable. |
230
+
| Filter specific SOP Instance(s) without UID change| ❌ | ❌ | ✅ | Required | Instance → No movement | Only selected SOP instances updated in place; other instances untouched. |
231
+
197
232
198
233
## Supported DICOM modules
199
234
Any attributes in the [Patient Identification Module](https://dicom.nema.org/dicom/2013/output/chtml/part03/sect_C.2.html#table_C.2-2) and [Patient Demographic Module](https://dicom.nema.org/dicom/2013/output/chtml/part03/sect_C.2.html#table_C.2-3) that aren't sequences can be updated using the bulk update operation. Supported attributes are called out in the tables.
0 commit comments