|
| 1 | +--- |
| 2 | +title: Update DICOM files in the DICOM service |
| 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: mmitrik |
| 5 | +ms.service: healthcare-apis |
| 6 | +ms.subservice: dicom |
| 7 | +ms.topic: how-to |
| 8 | +ms.date: 10/27/2023 |
| 9 | +ms.author: mmitrik |
| 10 | +--- |
| 11 | + |
| 12 | +# Update DICOM files |
| 13 | + |
| 14 | +The bulk update operation allows you to make changes to imaging metadata for multiple files stored in the DICOM® service. For example, bulk update enables you to modify DICOM attributes for one or more studies in a single, asynchronous operation. You can use this API to perform updates to patient demographic changes and avoid the costs of repeating time-consuming uploads. |
| 15 | + |
| 16 | +Beyond the efficiency gains, the bulk update capability preserves a record of the changes in the [change feed](dicom-change-feed-overview.md) and persists the original, unmodified instances for future retrieval. |
| 17 | + |
| 18 | +## Use the bulk update operation |
| 19 | +Bulk update is an asynchronous, long-running operation available at the studies endpoint. The request payload includes one or more studies to update, the set of attributes to update, and the new values for those attributes. |
| 20 | + |
| 21 | +### Update instances in multiple studies |
| 22 | +The bulk update endpoint starts a long-running operation that updates all instances in each study with the specified attributes. |
| 23 | + |
| 24 | +```http |
| 25 | +POST {dicom-service-url}/{version}/studies/$bulkUpdate |
| 26 | +``` |
| 27 | + |
| 28 | +```http |
| 29 | +POST {dicom-service-url}/{version}/partitions/{PartitionName}/studies/$bulkUpdate |
| 30 | +``` |
| 31 | + |
| 32 | +#### Request header |
| 33 | + |
| 34 | +| Name | Required | Type | Description | |
| 35 | +| ------------ | --------- | ------ | ------------------------------- | |
| 36 | +| Content-Type | False | string | `application/json` is supported | |
| 37 | + |
| 38 | +#### Request body |
| 39 | + |
| 40 | +The request body contains the specification for studies to update. Both the `studyInstanceUids` and `changeDataset` are required. |
| 41 | + |
| 42 | +```json |
| 43 | +{ |
| 44 | + "studyInstanceUids": ["1.113654.3.13.1026"], |
| 45 | + "changeDataset": { |
| 46 | + "00100010": { |
| 47 | + "vr": "PN", |
| 48 | + "Value": |
| 49 | + [ |
| 50 | + { |
| 51 | + "Alphabetic": "New Patient Name 1" |
| 52 | + } |
| 53 | + ] |
| 54 | + } |
| 55 | + } |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +#### Responses |
| 60 | +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. |
| 61 | + |
| 62 | +```http |
| 63 | +HTTP/1.1 202 Accepted |
| 64 | +Content-Type: application/json |
| 65 | +{ |
| 66 | + "id": "1323c079a1b64efcb8943ef7707b5438", |
| 67 | + "href": "../v1/operations/1323c079a1b64efcb8943ef7707b5438" |
| 68 | +} |
| 69 | +``` |
| 70 | + |
| 71 | +If the operation fails to start successfully, the response will include information about the failure in the errors list, including UIDs of the failing instance(s). |
| 72 | + |
| 73 | +```http |
| 74 | +{ |
| 75 | + "operationId": "1323c079a1b64efcb8943ef7707b5438", |
| 76 | + "type": "update", |
| 77 | + "createdTime": "2023-05-08T05:01:30.1441374Z", |
| 78 | + "lastUpdatedTime": "2023-05-08T05:01:42.9067335Z", |
| 79 | + "status": "failed", |
| 80 | + "percentComplete": 100, |
| 81 | + "results": { |
| 82 | + "studyUpdated": 0, |
| 83 | + "studyFailed": 1, |
| 84 | + "instanceUpdated": 0, |
| 85 | + "errors": [ |
| 86 | + "Failed to update instances for study 1.113654.3.13.1026" |
| 87 | + ] |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +| Name | Type | Description | |
| 93 | +| ----------------- | ------------------- | ------------------------------------------------------------ | |
| 94 | +| 202 (Accepted) | Operation Reference | A long-running operation has been started to update DICOM attributes | |
| 95 | +| 400 (Bad Request) | | Request body has invalid data | |
| 96 | + |
| 97 | +### Operation Status |
| 98 | +The `href` URL can be polled for the current status of the update operation until completion. A return code of `200` indicates the operation completed successfully. |
| 99 | + |
| 100 | +```http |
| 101 | +GET {dicom-service-url}/{version}/operations/{operationId} |
| 102 | +``` |
| 103 | + |
| 104 | +#### URI Parameters |
| 105 | + |
| 106 | +| Name | In | Required | Type | Description | |
| 107 | +| ----------- | ---- | -------- | ------ | ---------------- | |
| 108 | +| operationId | path | True | string | The operation ID | |
| 109 | + |
| 110 | +#### Responses |
| 111 | + |
| 112 | +```json |
| 113 | +{ |
| 114 | + "operationId": "1323c079a1b64efcb8943ef7707b5438", |
| 115 | + "type": "update", |
| 116 | + "createdTime": "2023-05-08T05:01:30.1441374Z", |
| 117 | + "lastUpdatedTime": "2023-05-08T05:01:42.9067335Z", |
| 118 | + "status": "completed", |
| 119 | + "percentComplete": 100, |
| 120 | + "results": { |
| 121 | + "studyUpdated": 1, |
| 122 | + "instanceUpdated": 16, |
| 123 | + // Errors will go here |
| 124 | + } |
| 125 | +} |
| 126 | +``` |
| 127 | + |
| 128 | +| Name | Type | Description | |
| 129 | +| --------------- | --------- | -------------------------------------------- | |
| 130 | +| 200 (OK) | Operation | The operation with the specified ID has completed | |
| 131 | +| 202 (Accepted) | Operation | The operation with the specified ID is running | |
| 132 | +| 404 (Not Found) | | Operation not found | |
| 133 | + |
| 134 | +## Retrieving study versions |
| 135 | +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. The latest version of a study, series, or instance is always returned by default. The original version is returned by setting the `msdicom-request-original` header to `true`. Here's an example request: |
| 136 | + |
| 137 | +```http |
| 138 | +GET {dicom-service-url}/{version}/studies/{study}/series/{series}/instances/{instance} |
| 139 | +Accept: multipart/related; type="application/dicom"; transfer-syntax=* |
| 140 | +msdicom-request-original: true |
| 141 | +Content-Type: application/dicom |
| 142 | + ``` |
| 143 | + |
| 144 | +## Delete |
| 145 | +The [delete](dicom-services-conformance-statement-v2.md#delete) method deletes both the original and latest version of a study, series, or instance. |
| 146 | + |
| 147 | +## Change feed |
| 148 | +The [change feed](dicom-change-feed-overview.md) records update actions in the same manner as create and delete actions. |
| 149 | + |
| 150 | +## Supported DICOM modules |
| 151 | +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. |
| 152 | + |
| 153 | +#### Patient identification module attributes |
| 154 | +| Attribute Name | Tag | Description | |
| 155 | +| ---------------- | --------------| --------------------- | |
| 156 | +| Patient's Name | (0010,0010) | Patient's full name | |
| 157 | +| Patient ID | (0010,0020) | Primary hospital identification number or code for the patient. | |
| 158 | +| Other Patient IDs| (0010,1000) | Other identification numbers or codes used to identify the patient. |
| 159 | +| Type of Patient ID| (0010,0022) | The type of identifier in this item. Enumerated Values: TEXT RFID BARCODE Note The identifier is coded as a string regardless of the type, not as a binary value. |
| 160 | +| Other Patient Names| (0010,1001) | Other names used to identify the patient. |
| 161 | +| Patient's Birth Name| (0010,1005) | Patient's birth name. |
| 162 | +| Patient's Mother's Birth Name| (0010,1060) | Birth name of patient's mother. |
| 163 | +| Medical Record Locator | (0010,1090)| An identifier used to find the patient's existing medical record (for example, film jacket). |
| 164 | + |
| 165 | +#### Patient demographic module attributes |
| 166 | +| Attribute Name | Tag | Description | |
| 167 | +| ---------------- | --------------| --------------------- | |
| 168 | +| Patient's Age | (0010,1010) | Age of the Patient. | |
| 169 | +| Occupation | (0010,2180) | Occupation of the Patient. | |
| 170 | +| Confidentiality Constraint on Patient Data Description | (0040,3001) | Special indication to the modality operator about confidentiality of patient information (for example, that they shouldn't use the patients name where other patients are present). | |
| 171 | +| Patient's Birth Date | (0010,0030) | Date of birth of the named patient | |
| 172 | +| Patient's Birth Time | (0010,0032) | Time of birth of the named patient | |
| 173 | +| Patient's Sex | (0010,0040) | Sex of the named patient. | |
| 174 | +| Quality Control Subject |(0010,0200) | Indicates whether or not the subject is a quality control phantom. | |
| 175 | +| Patient's Size | (0010,1020) | Patient's height or length in meters | |
| 176 | +| Patient's Weight | (0010,1030) | Weight of the patient in kilograms | |
| 177 | +| Patient's Address | (0010,1040) | Legal address of the named patient | |
| 178 | +| Military Rank | (0010,1080) | Military rank of patient | |
| 179 | +| Branch of Service | (0010,1081) | Branch of the military. The country allegiance may also be included (for example, U.S. Army). | |
| 180 | +| Country of Residence | (0010,2150) | Country in which patient currently resides | |
| 181 | +| Region of Residence | (0010,2152) | Region within patient's country of residence | |
| 182 | +| Patient's Telephone Numbers | (0010,2154) | Telephone numbers at which the patient can be reached | |
| 183 | +| Ethnic Group | (0010,2160) | Ethnic group or race of patient | |
| 184 | +| Patient's Religious Preference | (0010,21F0) | The religious preference of the patient | |
| 185 | +| Patient Comments | (0010,4000) | User-defined comments about the patient | |
| 186 | +| Responsible Person | (0010,2297) | Name of person with medical decision making authority for the patient. | |
| 187 | +| Responsible Person Role | (0010,2298) | Relationship of Responsible Person to the patient. | |
| 188 | +| Responsible Organization | (0010,2299) | Name of organization with medical decision making authority for the patient. | |
| 189 | +| Patient Species Description | (0010,2201) | The species of the patient. | |
| 190 | +| Patient Breed Description | (0010,2292) | The breed of the patient. See Section C.7.1.1.1.1. | |
| 191 | +| Breed Registration Number | (0010,2295) | Identification number of a veterinary patient within the registry. | |
| 192 | +| Issuer of Patient ID | (0010,0021) | Identifier of the Assigning Authority (system, organization, agency, or department) that issued the Patient ID. ``` |
| 193 | + |
| 194 | +#### General study module |
| 195 | +| Attribute Name | Tag | Description | |
| 196 | +| ---------------- | --------------| --------------------- | |
| 197 | +| Referring Physician's Name | (0008,0090) | Name of the patient's referring physician. | |
| 198 | +| Accession Number | (0008,0050) | A RIS generated number that identifies the order for the Study. | |
| 199 | +| Study Description | (0008,1030) | Institution-generated description or classification of the Study (component) performed. | |
| 200 | + |
| 201 | +## Limitations |
| 202 | +There are a few limitations when you use the bulk update operation: |
| 203 | + |
| 204 | +- A maximum of 50 studies can be updated in a single operation. |
| 205 | +- Only one bulk update operation can be performed at a time. |
| 206 | +- You can't delete only the latest version of a study or revert back to the original version. |
| 207 | +- You can't update any field from non-null to a null value. |
| 208 | +[!INCLUDE [DICOM trademark statements](../includes/healthcare-apis-dicom-trademark.md)] |
0 commit comments