Skip to content

Commit e6aae3a

Browse files
denreadenrea
authored
Merge pull request #292485 from bcarthic/bcarthic/meta
Add external metadata documentation
2 parents 1933b81 + 872efd0 commit e6aae3a

File tree

5 files changed

+123
-3
lines changed

5 files changed

+123
-3
lines changed

‎articles/healthcare-apis/dicom/dicom-extended-query-tags-overview.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,6 @@ The following VR types are supported:
6161
| AS | Age String | X | | |
6262
| CS | Code String | X | | |
6363
| DA | Date | X | X | |
64-
| DS | Decimal String | X | | |
6564
| DT | Date Time | X | X | |
6665
| FD | Floating Point Double | X | | |
6766
| FL | Floating Point Single | X | | |
@@ -423,7 +422,7 @@ The query status of extended query tag.
423422
| Enabled | string | The extended query tag is allowed to be queried |
424423

425424
> [!NOTE]
426-
> Errors during the reindex operation disables QIDO on the extended query tag. You can call the [Update Extended Query Tag](#update-extended-query-tag) API to enable it.
425+
> Errors during the reindex operation disable QIDO on the extended query tag. You can call the [Update Extended Query Tag](#update-extended-query-tag) API to enable it.
427426
428427
### Extended query tag for updating
429428

‎articles/healthcare-apis/dicom/dicom-services-conformance-statement-v2.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,10 @@ When a sequence contains an attribute that fails validation, or when there are m
108108

109109
If an attribute is padded with nulls, the attribute is indexed when searchable and is stored as is in dicom+json metadata. No validation warning is provided.
110110

111+
#### Store DICOM file with external metadata
112+
113+
The [external metadata](external-metadata.md#store-stow-rs) documentation explains the ability to store DICOM file with external metadata.
114+
111115
#### Store response status codes
112116

113117
| Code | Description |
@@ -377,6 +381,9 @@ Retrieving metadata doesn't return attributes with the following value represent
377381

378382
Retrieved metadata includes the null character when the attribute was padded with nulls and stored as is.
379383

384+
> [!NOTE]
385+
> The [external metadata](external-metadata.md#store-stow-rs) documentation explains the ability to retrieve DICOM file with external metadata.
386+
380387
### Retrieve metadata cache validation (for study, series, or instance)
381388

382389
Cache validation is supported using the `ETag` mechanism. In the response to a metadata request, ETag is returned as one of the headers. This ETag can be cached and added as an `If-None-Match` header in the later requests for the same metadata. Two types of responses are possible if the data exists.
@@ -511,6 +518,9 @@ Example query searching for instances:
511518

512519
`../instances?Modality=CT&00280011=512&includefield=00280010&limit=5&offset=0`
513520

521+
> [!NOTE]
522+
> The [external metadata](external-metadata.md#store-stow-rs) documentation explains the ability to query DICOM file with external metadata.
523+
514524
### Search response
515525

516526
The response is an array of DICOM datasets. Depending on the resource, by *default* the following attributes are returned.

‎articles/healthcare-apis/dicom/external-metadata.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
---
2+
title: Store external metadata in the DICOM service in Azure Health Data Services
3+
description: Learn how to store, retrieve, and query external metadata that aren't part of the DICOM files in the DICOM service
4+
author: kabalas
5+
ms.service: azure-health-data-services
6+
ms.subservice: dicom-service
7+
ms.topic: how-to
8+
ms.date: 12/30/2024
9+
ms.author: kabalas
10+
---
11+
12+
# External metadata
13+
14+
The external metadata feature allows users to store metadata or additional information about the DICOM files that isn't part of the DICOM file. This functionality is accomplished by using STOW-RS to store the metadata by passing the additional information in the header.
15+
16+
## Limitations
17+
18+
- External metadata is only supported in latest API version. That is, Version 2 or above
19+
- External metadata is only supported in [DICOM® service with Azure Data Lake Storage](dicom-data-lake.md)
20+
- Only tags which don't conform with standard DICOM protocol tags such as [private tags](https://dicom.nema.org/dicom/2013/output/chtml/part05/sect_7.8.html) are supported to be as external metadata.
21+
- Only study level tags are supported.
22+
- External metadata tags can't be updated or deleted.
23+
- The following VR types are supported:
24+
25+
| VR | Description | Single Value Matching | Range Matching | Fuzzy Matching |
26+
| ---- | --------------------- | --------------------- | -------------- | -------------- |
27+
| AE | Application Entity | X | | |
28+
| AS | Age String | X | | |
29+
| CS | Code String | X | | |
30+
| DA | Date | X | X | |
31+
| DT | Date Time | X | X | |
32+
| FD | Floating Point Double | X | | |
33+
| FL | Floating Point Single | X | | |
34+
| IS | Integer String | X | | |
35+
| LO | Long String | X | | |
36+
| PN | Person Name | X | | X |
37+
| SH | Short String | X | | |
38+
| SL | Signed Long | X | | |
39+
| SS | Signed Short | X | | |
40+
| TM | Time | X | X | |
41+
| UI | Unique Identifier | X | | |
42+
| UL | Unsigned Long | X | | |
43+
| US | Unsigned Short | X | | |
44+
45+
> [!NOTE]
46+
> Sequential tags, which are tags under a tag of type Sequence of Items (SQ), are currently not supported.
47+
> We don't index external metadata tags if the value is null or empty.
48+
> There's no ability to add private creator as part of external metadata tags.
49+
50+
### Store (STOW-RS)
51+
52+
The [Store (STOW-RS)](dicom-services-conformance-statement-v2.md#store-stow-rs) transaction allows storing external metadata as customer headers.
53+
In order to store external metadata as part of the store transaction, specify the tag key in the format `msdicom-meta-{VR}-{TagPath}`. An example request follows.
54+
55+
```http
56+
POST {dicom-service-url}/{version}/studies
57+
Accept: multipart/related; type="application/dicom+json";
58+
msdicom-meta-CS-001912FF: CS
59+
msdicom-meta-PN-00191100: PersonName
60+
msdicom-meta-DA-001900FF: 20241231
61+
62+
Body:
63+
{DICOM FILE}
64+
```
65+
66+
> [!NOTE]
67+
> Only study level tags are supported.
68+
> If the tag already exists, it updates the value of the existing tag for the study.
69+
> If the tag already exists with a different VR, the transaction will result in an error.
70+
71+
> Once a tag is created, its Value Representation (VR) is fixed and must comply with the standard for that specific VR. If there's an issue with one of the tags, then it fails the whole transaction.
72+
73+
### Retrieve metadata (for study, series, or instance)
74+
75+
The [Retrieve metadata (for study, series, or instance)](dicom-services-conformance-statement-v2.md#retrieve-metadata-for-study-series-or-instance) transaction allows users to retrieve the external metadata along with other metadata. The external metadata is retrieved along with other tags by setting the `msdicom-request-meta` header to `true`. An example request follows.
76+
77+
```http
78+
GET {dicom-service-url}/{version}/studies/{study}/series/{series}/instances/{instance}/metadata
79+
Accept: multipart/related; type="application/dicom"; transfer-syntax=*
80+
msdicom-request-meta: true
81+
Content-Type: application/dicom
82+
```
83+
84+
> [!NOTE]
85+
> The `json` response includes a standard private creator tag that follows the [DICOM standard](https://dicom.nema.org/dicom/2013/output/chtml/part05/sect_7.8.html).
86+
> The default value of the private creator tag will be `Microsoft`.
87+
> For e.g if the private tag is `001910FF` then the private creator tag will be `00190010`.
88+
89+
### Search (QIDO-RS)
90+
91+
The [Search (QIDO-RS)](dicom-services-conformance-statement-v2.md#search-qido-rs) transaction allows users to query external metadata similar to other tags. The external metadata can be queried by setting the `msdicom-request-meta` header to `true`. An example request follows.
92+
93+
```http
94+
GET {dicom-service-url}/{version}/studies?00191100=PersonName
95+
msdicom-request-meta: true
96+
Content-Type: application/dicom
97+
```
98+
99+
> [!NOTE]
100+
> Only study level tags are supported.
101+
> If there's an extended query tag with the same tagPath, but if the header `msdicom-request-meta` is set to `true`, then value from the external metadata is used to filter or to be included as part of response data.
102+
103+
## Other transaction
104+
105+
There are no changes to other transactions like WADO-RS, Delete, ChangeFeed, and Update.
106+
107+
[!INCLUDE [DICOM trademark statements](../includes/healthcare-apis-dicom-trademark.md)]

‎articles/healthcare-apis/dicom/index.yml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,4 +79,6 @@ landingContent:
7979
- text: Export DICOM files
8080
url: export-files.md
8181
- text: Bulk update DICOM files
82-
url: update-files.md
82+
url: update-files.md
83+
- text: External metadata
84+
url: external-metadata.md

‎articles/healthcare-apis/dicom/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,8 @@ items:
5555
href: update-files.md
5656
- name: Support for proxy URLs
5757
href: dicom-proxy-url-support.md
58+
- name: External metadata
59+
href: external-metadata.md
5860
- name: API reference
5961
expanded: true
6062
items:

0 commit comments

Comments
 (0)