Update DICOM files

The bulk update operation lets you 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.

Beyond the efficiency gains, the bulk update capability preserves a record of the changes in the change feed and persists the original, unmodified instances for future retrieval.

Limitations

There are a few limitations when you use the bulk update operation:

  • A maximum of 50 studies can be updated in a single operation.
  • Only one bulk update operation can be performed at a time.
  • You can't delete only the latest version of a study, or revert back to the original version.
  • You can't update any field from non-null to a null value.

Use the bulk update operation

Bulk update is an asynchronous, long-running operation available at a study's endpoint. The request payload includes one or more studies to update, the set of attributes to update, and the new values for those attributes.

Update instances in multiple studies

The bulk update endpoint starts a long-running operation that updates all instances in each study with the specified attributes.

POST {dicom-service-url}/{version}/studies/$bulkUpdate
POST {dicom-service-url}/{version}/partitions/{PartitionName}/studies/$bulkUpdate

Request header

Name Required Type Description
Content-Type False string application/json is supported

Request body

The request body contains the specification for studies to update. Both the studyInstanceUids and changeDataset are required.

{
    "studyInstanceUids": ["1.113654.3.13.1026"],
    "changeDataset": { 
        "00100010": { 
            "vr": "PN", 
            "Value": 
            [
                { 
                    "Alphabetic": "New Patient Name 1" 
                }
            ] 
        } 
    }
}

Responses

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.

HTTP/1.1 202 Accepted
Content-Type: application/json
{
    "id": "1323c079a1b64efcb8943ef7707b5438",
    "href": "../v1/operations/1323c079a1b64efcb8943ef7707b5438"
}

If the operation fails to start successfully, the response includes information about the failure in the errors list, including UIDs of one or more failing instances.

{
    "operationId": "1323c079a1b64efcb8943ef7707b5438",
    "type": "update",
    "createdTime": "2023-05-08T05:01:30.1441374Z",
    "lastUpdatedTime": "2023-05-08T05:01:42.9067335Z",
    "status": "failed",
    "percentComplete": 100,
    "results": {
        "studyUpdated": 0,
        "studyFailed": 1,
        "instanceUpdated": 0,
        "errors": [
            "Failed to update instances for study 1.113654.3.13.1026"
        ]
    }
}
Name Type Description
202 (Accepted) Operation Reference A long-running operation was started to update DICOM attributes
400 (Bad Request) Request body has invalid data

Operation Status

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.

GET {dicom-service-url}/{version}/operations/{operationId}

URI Parameters

Name In Required Type Description
operationId path True string The operation ID

Responses

{
    "operationId": "1323c079a1b64efcb8943ef7707b5438",
    "type": "update",
    "createdTime": "2023-05-08T05:01:30.1441374Z",
    "lastUpdatedTime": "2023-05-08T05:01:42.9067335Z",
    "status": "completed",
    "percentComplete": 100,
    "results": {
        "studyUpdated": 1,
        "instanceUpdated": 16,
        // Errors will go here
    }
}
Name Type Description
200 (OK) Operation The operation with the specified ID is complete.
202 (Accepted) Operation The operation with the specified ID is running.
404 (Not Found) Operation not found

Retrieving study versions

The 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. An example request follows.

GET {dicom-service-url}/{version}/studies/{study}/series/{series}/instances/{instance}
Accept: multipart/related; type="application/dicom"; transfer-syntax=*
msdicom-request-original: true
Content-Type: application/dicom

Delete

The delete method deletes both the original and latest version of a study, series, or instance.

Change feed

The change feed records update actions in the same manner as create and delete actions.

Supported DICOM modules

Any attributes in the Patient Identification Module and Patient Demographic Module that aren't sequences can be updated using the bulk update operation. Supported attributes are called out in the tables.

Attributes automatically changed in bulk updates

When you perform a bulk update, the DICOM service updates the requested attributes and two additional metadata fields automatically. Following is the information that is updated automatically.

Tag Attribute name Description Value
(0002,0012) Implementation Class UID Uniquely identifies the implementation that wrote this file and its content. 1.3.6.1.4.1.311.129
(0002,0013) Implementation Version Name Identifies a version for an Implementation Class UID (0002,0012) Assembly version of the DICOM service (for example, 0.1.4785)

The UID 1.3.6.1.4.1.311.129 is a registered under Microsoft OID arc in IANA.

Patient identification module attributes

Attribute Name Tag Description
Patient's Name (0010,0010) Patient's full name
Patient ID (0010,0020) Primary hospital identification number or code for the patient
Other Patient IDs (0010,1000) Other identification numbers or codes used to identify the patient
Type of Patient ID (0010,0022) The type of identifier in this item; Enumerated Values: TEXT RFID BARCODE. Note that the identifier is coded as a string, not as a binary value, regardless of the type.
Other Patient Names (0010,1001) Other names used to identify the patient
Patient's Birth Name (0010,1005) Patient's birth name
Patient's Mother's Birth Name (0010,1060) Birth name of patient's mother
Medical Record Locator (0010,1090) An identifier used to find the patient's existing medical record (for example, film jacket).

Patient demographic module attributes

Attribute Name Tag Description
Patient's Age (0010,1010) Age of the Patient
Occupation (0010,2180) Occupation of the Patient
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 patient's name when other patients are present.
Patient's Birth Date (0010,0030) Date of birth of the named patient
Patient's Birth Time (0010,0032) Time of birth of the named patient
Patient's Sex (0010,0040) Sex of the named patient
Quality Control Subject (0010,0200) Indicates whether or not the subject is a quality control phantom.
Patient's Size (0010,1020) Patient's height or length in meters
Patient's Weight (0010,1030) Weight of the patient in kilograms
Patient's Address (0010,1040) Legal address of the named patient
Military Rank (0010,1080) Military rank of patient
Branch of Service (0010,1081) Branch of the military; The country or regional allegiance might also be included (for example, U.S. Army).
Country of Residence (0010,2150) Country where a patient currently resides
Region of Residence (0010,2152) Region within patient's country of residence
Patient's Telephone Numbers (0010,2154) Telephone numbers at which the patient can be reached
Ethnic Group (0010,2160) Ethnic group or race of patient
Patient's Religious Preference (0010,21F0) The religious preference of the patient
Patient Comments (0010,4000) User-defined comments about the patient
Responsible Person (0010,2297) Name of a person with medical decision making authority for the patient.
Responsible Person Role (0010,2298) Relationship of Responsible Person to the patient
Responsible Organization (0010,2299) Name of an organization with medical decision making authority for the patient
Patient Species Description (0010,2201) The species of the patient
Patient Breed Description (0010,2292) The breed of the patient; See Section C.7.1.1.1.1.
Breed Registration Number (0010,2295) Identification number of a veterinary patient within the registry
Issuer of Patient ID (0010,0021) Identifier of the Assigning Authority (system, organization, agency, or department) that issued the Patient ID

General study module

Attribute Name Tag Description
Referring Physician's Name (0008,0090) Name of the patient's referring physician
Accession Number (0008,0050) A RIS generated number that identifies the order for the Study
Study Description (0008,1030) Institution-generated description or classification of the Study (component) performed

Nota

DICOM® is the registered trademark of the National Electrical Manufacturers Association for its Standards publications relating to digital communications of medical information.