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
+95-7Lines changed: 95 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,29 @@ 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
+
{
108
+
"studyInstanceUids": ["1.2.3.4"],
109
+
"seriesInstanceUid": "5.6.7.8",
110
+
"sopInstanceUid": "9.10.11.12",
111
+
"changeDataset": {
112
+
"0020000D": {
113
+
"vr": "UI",
114
+
"Value": ["1.2.3.5"]
115
+
},
116
+
"0020000E": {
117
+
"vr": "UI",
118
+
"Value": ["5.6.7.9"]
119
+
},
120
+
"00080018": {
121
+
"vr": "UI",
122
+
"Value": ["9.10.11.13"]
123
+
}
124
+
}
125
+
}
126
+
```
104
127
105
128
#### Responses
106
129
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 +201,43 @@ GET {dicom-service-url}/{version}/operations/{operationId}
178
201
| 404 (Not Found) || Operation not found |
179
202
180
203
## 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.
204
+
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.
205
+
* To retrieve the original version, set the `msdicom-request-original` header to `true`.
206
+
* 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.
207
+
* When SOP Instance UID filtering was used in a bulk update, you can retrieve specific instances by providing the updated SOP Instance UID.
208
+
209
+
Example request for retrieving a specific instance after a bulk update:
182
210
183
211
```http
184
212
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.
217
+
This ensures precise retrieval even after hierarchy or UID changes in bulk updates.
191
218
192
219
## Delete
193
220
The [delete](dicom-services-conformance-statement-v2.md#delete) method deletes both the original and latest version of a study, series, or instance.
194
221
195
222
## 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.
223
+
The [change feed](change-feed-overview.md) records update actions in the same manner as create and delete actions.
224
+
* For UID updates, including Study, Series, or SOP Instance UID, change feed entries for the older UIDs are not updated.
225
+
* Update actions are recorded only for the new UIDs.
226
+
* When SOP Instance UID filtering is applied, the change feed reflects updates only for the targeted instances.
227
+
228
+
## Summary of DICOM UID Update Behavior by Hierarchy Level
229
+
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. |
234
+
| Update Study Instance UID | ✅ | ❌ | ❌ | ❌ | Study → New Study | All instances in study get new Study UID; series and instance UIDs remain unless explicitly changed. |
235
+
| 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. |
236
+
| 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. |
237
+
| Update Study & Series UIDs | ✅ | ✅ | ❌ | Not required | Study → New Study → Series → New Series | Hierarchy updated; all instances in series adopt new UIDs. |
238
+
| 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. |
239
+
| Filter specific SOP Instance(s) without UID change| ❌ | ❌ | ✅ | Required | Instance → No movement | Only selected SOP instances updated in place; other instances untouched. |
240
+
197
241
198
242
## Supported DICOM modules
199
243
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.
@@ -259,4 +303,48 @@ The UID `1.3.6.1.4.1.311.129` is a registered under [Microsoft OID arc](https://
259
303
| Accession Number | (0008,0050) | A RIS generated number that identifies the order for the Study |
260
304
| Study Description | (0008,1030) | Institution-generated description or classification of the Study (component) performed |
| Instance Number | (0020,0013)| A number that identifies the instance |
337
+
| Acquisition Date | (0008,0022)| The date the acquisition of data that resulted in this image started |
338
+
| Acquisition Time | (0008,0032)| The time the acquisition of data that resulted in this image started |
339
+
| Image Laterality | (0020,0062)| Laterality of (possibly paired) body part examined in the image; Enumerated Values: R (right), L (left), U (unpaired), B (both) |
340
+
| Measurement Laterality | (0024,0113)| The laterality of the measurement |
![prmerger-automator[bot]](https://avatars.githubusercontent.com/u/22479449?v=4&size=40){kind=avatar}
0 commit comments