Skip to content

Commit acafc71

Browse files
bcarthicbcarthic
authored
Add external metadata documentation
1 parent 9daff5f commit acafc71

File tree

4 files changed

+118
-2
lines changed

4 files changed

+118
-2
lines changed

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

Lines changed: 0 additions & 1 deletion
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 | | |

‎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) documentaion explains the ablity 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) documentaion explains the ablity 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) documentaion explains the ablity 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: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
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 are not 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 to store the metadata or additional information about the DICOM files that is not part of the DICOM file. For e.g, using the same (STOW-RS), you can store the metadata by passing the additional information in the header.
15+
16+
## Limiations
17+
18+
- External metadata is only supported in latest api version. i.e Version 2 or above
19+
- Only private dicom tags are supported to be as external metadata.
20+
- Only study level tags are supported.
21+
- External metadata tags cannot be updated or deleted.
22+
- The following VR types are supported:
23+
24+
| VR | Description | Single Value Matching | Range Matching | Fuzzy Matching |
25+
| ---- | --------------------- | --------------------- | -------------- | -------------- |
26+
| AE | Application Entity | X | | |
27+
| AS | Age String | X | | |
28+
| CS | Code String | X | | |
29+
| DA | Date | X | X | |
30+
| DT | Date Time | X | X | |
31+
| FD | Floating Point Double | X | | |
32+
| FL | Floating Point Single | X | | |
33+
| IS | Integer String | X | | |
34+
| LO | Long String | X | | |
35+
| PN | Person Name | X | | X |
36+
| SH | Short String | X | | |
37+
| SL | Signed Long | X | | |
38+
| SS | Signed Short | X | | |
39+
| TM | Time | X | X | |
40+
| UI | Unique Identifier | X | | |
41+
| UL | Unsigned Long | X | | |
42+
| US | Unsigned Short | X | | |
43+
44+
> [!NOTE]
45+
> Sequential tags, which are tags under a tag of type Sequence of Items (SQ), are currently not supported.
46+
> We do not index external metadata tags if the value is null or empty.
47+
> There is no ability to add private creator as part of external metadata tags.
48+
49+
### Store (STOW-RS)
50+
51+
The [Store (STOW-RS)](dicom-services-conformance-statement-v2.md#store-stow-rs) transaction allows storing external metadata as customer headers.
52+
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.
53+
54+
```http
55+
POST {dicom-service-url}/{version}/studies
56+
Accept: multipart/related; type="application/dicom+json";
57+
msdicom-meta-CS-001912FF: CS
58+
msdicom-meta-PN-00191100: PersonName
59+
msdicom-meta-DA-001900FF: 20241231
60+
61+
Body:
62+
{DICOM FILE}
63+
```
64+
65+
> [!NOTE]
66+
> Only study level tags are supported.
67+
> If the tag already exists, it will update the value of the existing tag for the study.
68+
> If the tag already exists with different VR, then it will results in an error.
69+
> All the tag values must follow the standard for their respective VR. If there is an issue with one of the tags, then it will fail the whole transaction.
70+
71+
### Retrieve metadata (for study, series, or instance)
72+
73+
The [Retrieve metadata (for study, series, or instance)](dicom-services-conformance-statement-v2.md#retrieve-metadata-for-study-series-or-instance) transaction allows 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.
74+
75+
```http
76+
GET {dicom-service-url}/{version}/studies/{study}/series/{series}/instances/{instance}/metadata
77+
Accept: multipart/related; type="application/dicom"; transfer-syntax=*
78+
msdicom-request-meta: true
79+
Content-Type: application/dicom
80+
```
81+
82+
> [!NOTE]
83+
> The `json` response will include a standard private creator tag that follows the [DICOM standard](https://dicom.nema.org/dicom/2013/output/chtml/part05/sect_7.8.html).
84+
> The default value of the private creator tag will be `Microsoft`.
85+
> For e.g if the private tag is `001910FF` then the private creator tag will be `00190010`.
86+
87+
### Search (QIDO-RS)
88+
89+
The [Search (QIDO-RS)](dicom-services-conformance-statement-v2.md#search-qido-rs) transaction allows 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.
90+
91+
```http
92+
GET {dicom-service-url}/{version}/studies?00191100=PersonName
93+
msdicom-request-meta: true
94+
Content-Type: application/dicom
95+
```
96+
97+
> [!NOTE]
98+
> Only study level tags are supported.
99+
> If there is 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 included as part of response data.
100+
101+
## Other Transaction
102+
103+
There are no changes to other transactions like WADO-RS, Delete, ChangeFeed and Update.
104+
105+
[!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

0 commit comments

Comments
 (0)