| DICOM PS3.18 2016e - Web Services |
|---|
The STOW-RS Service defines one action type. An implementation shall support the following action type:
All request messages are HTTP multipart messages. The organization of SOP Instances into message parts depends on whether the SOP Instances are structured as PS3.10 binary instances, or metadata and bulk data.
PS3.10 binary instances shall be encoded with one message part per DICOM Instance.
When the request message contains compressed bulk data with a Content Type that is one of the media types specified in Table 6.6-1, the request may omit the Image Pixel Description Macro attributes and the origin server will derive them from the compressed bit stream. Some media types do not directly correspond to a DICOM Transfer Syntax and the origin server will transform the received bit stream into an uncompressed or lossless (reversibly) compressed Transfer Syntax.
This allows a user agent to use consumer media types to encode the pixel data even though it may not have:
If the supplied compressed bit stream is in a lossless (reversible) format, the intent is to allow full fidelity retrieval of the decompressed pixels, not the format in which it happened to be submitted.
If the supplied compressed bit stream is in a lossy (irreversible) format, there will be a corresponding DICOM Transfer Syntax, and the origin server is not expected to recompress it causing further loss.
Metadata and bulk data requests will be encoded in the following manner:(see Figure 6.5-1 Mapping between IOD and HTTP message parts):
All XML request messages shall be encoded as described in the Native DICOM Model defined in PS3.19 with one message part per XML object; the attributes of the Image Pixel Description Macro may be omitted for the media types specified in Table 6.6-1.
All JSON request messages shall be encoded as an array of DICOM JSON Model Objects defined in Annex F in a single message part; the attributes of the Image Pixel Description Macro may be omitted for the media types specified in Table 6.6-1.
Bulk data (with the exception of encapsulated document element) and uncompressed pixel data shall be encoded in a Little Endian format using the application/octet-stream media type with one message part per bulk data item.
An Encapsulated Document (0042,0011) bulk data element shall be encoded using the media-type from the MIME Type of Encapsulated Document (0042,0012) attribute with one message part per bulk data item.
Compressed pixel data shall be encoded using the media types and transfer syntaxes specified in Table 6.1.1.8-3b. Media types corresponding to several DICOM Transfer Syntax UIDs may require a transfer-syntax parameter to convey the Transfer Syntax the compressed pixel data is encoded in.
The request header field Content-Type is used to indicate the media type of the payload.
The Service shall support uncompressed bulk data (multipart/related; type="application/octet-stream").
Table 6.6-1 contains a list of media types containing compressed pixel data from which an origin server shall be able to derive the Image Pixel Data Description Macro Attribute values.
Requirements are specified in Table 6.6-1 as follows:
Transform - No DICOM Transfer Syntax exists; shall be transformed by the origin server into an uncompressed or lossless compressed Transfer Syntax (the choice of which is at the discretion of the origin server).
Unchanged - Shall be encapsulated in the corresponding DICOM Transfer Syntax without further lossy compression
In the case of pixel data supplied as image/gif or image/png, the origin server may transform the color representation from indexed color to true color (RGB) as necessary to conform to any Photometric Interpretation constraints specified by the IOD (i.e., if PALETTE COLOR is not permitted); such a transformation is considered lossless.
If the number of bits per channel of an image/png file is not supported by the IOD, a lossless transformation cannot be performed.
An animated image/gif will be converted into a multi-frame image; image/png does not support animation, and MNG is not included in Table 6.6-1.
Any transparency information present in an image/gif or image/png file will be discarded, since DICOM does not support the concept of transparency.
If an alpha channel is supplied in an image/png file, and the IOD does not support the RGBA Photometric Interpretation, the alpha channel will be discarded (i.e., considered to consist of all opaque values, consistent with the policy of discarding any transparency information).
This action stores one or more DICOM instances associated with one or more study instance unique identifiers (SUID). The request message can be DICOM or metadata and bulk data depending on the "Content-Type", and is encapsulated in a multipart request body.
The specific Service resource to be used for the Store Instances action shall be as follows:
{SERVICE}/studies[/{StudyInstanceUID}], where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{StudyInstanceUID} (optional) is the study instance UID for a single study. If not specified, instances can be from multiple studies. If specified, all instances shall be from that study; instances not matching the StudyInstanceUID shall be rejected.
It is not necessary that the study referenced by the StudyInstanceUID in the resource (and in the provided instances) exists on the server, however it is necessary that it be a valid UID. The client may have obtained an appropriate UID from elsewhere or generated it as described in Chapter 9 “Unique Identifiers (UIDs)” in PS3.5 and Annex B “Creating a Privately Defined Unique Identifier (Informative)” in PS3.5.
Content-Type - The representation scheme being posted to the RESTful service. The types allowed for this request header are as follows:
multipart/related; type="application/dicom"; boundary={messageBoundary}
Specifies that the post is PS3.10 binary instances. All STOW-RS providers shall accept this Content-Type.
multipart/related; type="application/dicom+xml"; boundary={messageBoundary}
Specifies that the post is PS3.19 XML metadata and bulk data. All STOW-RS providers shall accept this Content-Type.
multipart/related; type="application/dicom+json"; boundary={messageBoundary}
Specifies that the post is DICOM JSON metadata and bulk data. All STOW-RS providers shall accept this Content-Type.
The XML Metadata and Bulk Data Request Message has a multipart body.
The multipart request body contains all the metadata and bulk data to be stored. If the number of bulk data parts does not correspond to the number of unique BulkDataURIs in the metadata then the entire message is invalid and will generate an error status line.
Each body part is either DICOM PS3.19 XML metadata or a bulk data item from a SOP Instance sent as part of the Store operation. The first part of the multipart message shall be XML metadata.
Each bulk data item shall be preceded by all metadata items that contain a reference to it.
The first part in the multipart request will contain the following HTTP headers:
Subsequent items will contain the following HTTP headers (order is not guaranteed):
Metadata and its associated bulk data shall always be sent in the same POST request.
The JSON Metadata and Bulk Data Request Message has a multipart body.
The multipart request body contains all the metadata and bulk data to be stored. If the number of bulk data parts does not correspond to the number of unique BulkDataURIs in the metadata then the entire message is invalid and will generate an error status line.
The first part in the multipart request will contain a JSON array of DICOM JSON Model Objects (defined in Annex F). Each array element is the metadata from a SOP Instance sent as part of the Store operation. This message part will have the following headers:
Subsequent items will be one of the following:
JSON Metadata and its associated bulk data shall always be sent in the same POST request.
The origin server may coerce or replace values of attributes such as Patient Name, ID, Accession Number, for example, during import of media from an external institution, reconciliation against a master patient index, or reconciliation against an imaging procedure order. The Service may correct, or replace incorrect values, such as Patient Name or ID, for example, when incorrect worklist item was chosen or operator input error occurs.
If any element is coerced or corrected, the Original Attribute Sequence (0400,0561) shall be included in the DICOM Object that is stored and may be included in the PS3.18 XML Store Instances Response Module in the response.
For more information on populating the Original Attribute Sequence, see Section C.12.1 “SOP Common Module” in PS3.3 .
The origin server shall encapsulate or convert any compressed pixel data received as bulk data into an appropriate DICOM Transfer Syntax, as defined in Table 6.6-1.
The origin server shall populate the attributes of the Image Pixel Description Macro, if absent from the Metadata, by deriving them from the compressed pixel data received as bulk data.
The stored Instance(s) shall fully conform to the IOD and encoding requirements of PS3.3 and PS3.5, respectively.
The origin server shall return a status of 415 (Unsupported Media Type) if it cannot convert the bulk data or populate the Image Pixel Description Macro Attribute values.
The RESTful Service shall return an HTTP status line, including a status code and associated textual phrase for the entire set of stored SOP Instances, followed by a message body containing the Store Instances Response Module as defined in Table 6.6.1-2. The message body shall be encoded as either:
If the status for all instances included in the POST request is Success, the RESTful Service shall return an "HTTP 200 - Success" response code.
If the status for all instances included in the POST request is Failure, the RESTful Service shall return an appropriate failure status line with a response code from Table 6.6.1-1. If there are instance specific errors, the response code shall be a 409 and the response payload shall contain the Store Instances Response Module, which contains additional information regarding instance errors.
In all other conditions, the RESTful Service shall return an "HTTP 202 - Accepted" response code. The response payload may contain a Store Instances Response Module, which specifies additional information regarding instance warnings or failures.
Table 6.6.1-1. HTTP Standard Response Code
HTTP Status Codes for Failures and Warnings are returned in HTTP response headers. It is recommended that the text returned in the HTTP Response Warning contain a DICOM Status Code and descriptive reason as defined in Section 6.6.1.3.2.1. For example,
The message body shall provide appropriate status codes for individual SOP Instances indicating success, warning, or failure as defined below.
The message body may also include details about the processing of attributes by the service.
The message body shall also include details of failures that are not associated with a specific SOP Instance.
Table 6.6.1-2 defines the Attributes for referencing SOP Instances that are contained in a Store Instances Response Module in the response message body.
Table 6.6.1-2. Store Instances Response Module Attributes
|
The URL where the Study is available for retrieval via a WADO-RS Retrieve Study service. |
|||
|
A sequence of Items where each Item references a single SOP Instance for which storage could not be provided. |
|||
|
>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3 |
|||
|
The reason that storage could not be provided for this SOP Instance. |
|||
|
A sequence of Items where each Item references a single SOP Instance that was successfully stored. Required if one or more SOP Instances were successfully stored. |
|||
|
>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3 |
|||
|
The URL where the SOP Instance is available for retrieval via a WADO-RS service. |
|||
|
The reason that this SOP Instance was accepted with warnings. |
|||
|
Sequence of Items containing all attributes that were removed or replaced by other values. |
|||
|
Identification of the system that removed and/or replaced the attributes. |
|||
|
Reason for the attribute modification. Defined terms are: COERCE = Replace values of attributes such as Patient Name, ID, Accession Number, for example, during import of media from an external institution, or reconciliation against a master patient index. CORRECT = Replace incorrect values, such as Patient Name or ID, for example, when incorrect worklist item was chosen or operator input error. |
|||
|
Sequence that contains all the Attributes, with their previous values, that were modified or removed from the main data set. |
|||
|
>>Any Attribute from the main data set that was modified or removed; may include Sequence Attributes and their Items. |
|||
|
Reasons not associated with a specific SOP Instance that storage could not be provided. Each Item references a single storage failure. Required if there are one or more failures not associated with a specific SOP Instance. |
|||
|
The reason that storage could not be provided for this message item. |
|||
Table 6.6.1-3 defines the semantics for which the associated value shall be used for the Warning Reason (0008,1196):
Table 6.6.1-3. Store Instances Response Warning Reason Values
|
The STOW-RS Service modified one or more data elements during storage of the instance. See Section 6.6.1.3. |
|||
|
The STOW-RS Service discarded some data elements during storage of the instance. See Section 6.6.1.3. |
|||
|
The STOW-RS Service observed that the Data Set did not match the constraints of the SOP Class during storage of the instance. |
Additional codes may be used for the Warning Reason (0008,1196) to address the semantics of other issues.
In the event that multiple codes may apply, the single most appropriate code shall be used.
Table 6.6.1-4 defines the semantics for which the associated value shall be used for the Failure Reason (0008,1197). Implementation specific warning and error codes shall be defined in the conformance statement:
Table 6.6.1-4. Store Instances Response Failure Reason Values
Additional codes may be used for the Failure Reason (0008,1197) to address the semantics of other issues.
In the event that multiple codes may apply, the single most appropriate code shall be used.
The following is an example of a PS3.18 XML Store Instances Response Module in the response message body containing 2 failed SOP Instances, 1 successful SOP Instance, and 1 accepted SOP Instance with a warning:
<?xml version="1.0" encoding="utf-8" xml:space="preserve"?>
<NativeDicomModel xmlns="http://dicom.nema.org/PS3.19/models/NativeDICOM"
xsi:schemaLocation="http://dicom.nema.org/PS3.19/models/NativeDICOM"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<DicomAttribute tag="00081198" vr="SQ" keyword="FailedSOPSequence">
<Item number="1">
<DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
<Value number="1">1.2.840.10008.3.1.2.3.1</Value>
</DicomAttribute>
<DicomAttribute tag="00081155" vr="UI"
keyword="ReferencedSOPInstanceUID">
<Value number="1">
2.16.124.113543.6003.1011758472.49886.19426.2085542308</Value>
</DicomAttribute>
<DicomAttribute tag="00081197" vr="US" keyword="FailureReason">
<Value number="1">290</Value>
</DicomAttribute>
</Item>
<Item number="2">
<DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
<Value number="1">1.2.840.10008.3.1.2.3.1</Value>
</DicomAttribute>
<DicomAttribute tag="00081155" vr="UI"
keyword="ReferencedSOPInstanceUID">
<Value number="1">
2.16.124.113543.6003.1011758472.49886.19426.2085542309</Value>
</DicomAttribute>
<DicomAttribute tag="00081197" vr="US" keyword="FailureReason">
<Value number="1">290</Value>
</DicomAttribute>
</Item>
</DicomAttribute>
<DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence">
<Item number="1">
<DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
<Value number="1">1.2.840.10008.5.1.4.1.1.2</Value>
</DicomAttribute>
<DicomAttribute tag="00081155" vr="UI"
keyword="ReferencedSOPInstanceUID">
<Value number="1">
2.16.124.113543.6003.189642796.63084.16748.2599092903</Value>
</DicomAttribute>
<DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
<Value number="1">
https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045/
series/2.16.124.113543.6003.2588828330.45298.17418.2723805630/
instances/2.16.124.113543.6003.189642796.63084.16748.2599092903</Value>
</DicomAttribute>
</Item>
<Item number="2">
<DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID">
<Value number="1">1.2.840.10008.5.1.4.1.1.2</Value>
</DicomAttribute>
<DicomAttribute tag="00081155" vr="UI"
keyword="ReferencedSOPInstanceUID">
<Value number="1">
2.16.124.113543.6003.189642796.63084.16748.2599092905</Value>
</DicomAttribute>
<DicomAttribute tag="00081196" vr="US" keyword="WarningReason">
<Value number="1">45056</Value>
</DicomAttribute>
<DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
<Value number="1">
https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045/
series/2.16.124.113543.6003.2588828330.45298.17418.2723805630/
instances/2.16.124.113543.6003.189642796.63084.16748.2599092905</Value>
</DicomAttribute>
</Item>
</DicomAttribute>
<DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL">
<Value number="1">
https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045</Value>
</DicomAttribute>
</NativeDicomModel>
| DICOM PS3.18 2016e - Web Services |
|---|