DICOM PS3.18 2016c - Web Services
6.6 STOW-RS Request/Response
Prev  6 Data Communication Requirements  Next
PS3.18 > Data Communication Requirements > STOW-RS Request/Response

6.6 STOW-RS Request/Response

The STOW-RS Service defines one action type. An implementation shall support the following action type:

  1. Store Instances

    This action creates new resources for the given SOP Instances on the Server or appends to existing resources on the Server.

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.

Metadata and bulk data requests will be encoded in the following manner:(see Figure 6.5-1 Mapping between IOD and HTTP message parts):

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").

6.6.1 STOW-RS - Store Instances

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.

6.6.1.1 Request

The specific Service resource to be used for the Store Instances action shall be as follows:

  • Resource

    • {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.

  • Method

    • POST

  • Headers

    • 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.

Note

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.

6.6.1.1.1 DICOM Request Message Body

The DICOM Request Message has a multipart body.

  • Content-Type:

    • multipart/related; type="application/dicom"; boundary={MessageBoundary}

  • The multipart request body contains every instance to be stored. Each instance is in a separate part of the multipart body.

  • Each part in the multipart body represents a DICOM SOP Instance with the following HTTP headers:

    • Content-Type: application/dicom

6.6.1.1.2 XML Metadata and Bulk Data Request Message Body

The XML Metadata and Bulk Data Request Message has a multipart body.

  • Content-Type:

    • multipart/related; type="application/dicom+xml"; boundary={MessageBoundary}

  • 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.

    Note

    This requires that all bulk data items for an instance shall be preceded by the XML metadata for that instance and if a bulk data item is included in multiple instances it shall be preceded by the XML metadata for each instance in which it is included.

  • The first part in the multipart request will contain the following HTTP headers:

    • Content-Type: application/dicom+xml; transfer-syntax={TransferSyntaxUID}

  • Subsequent items will contain the following HTTP headers (order is not guaranteed):

    • additional metadata with the following headers:

      • Content-Type: application/dicom+xml; transfer-syntax={TransferSyntaxUID}

        Where {TransferSyntaxUID} is the UID of the DICOM Transfer Syntax used to encode the inline binary data in the XML metadata.

    • an uncompressed bulk data element encoded in Little Endian binary format with the following headers:

      • Content-Type: application/octet-stream

      • Content-Location: {BulkDataURI}

    • a compressed pixel data object from a SOP Instance in the Study with the following headers:

      • Content-Type: {media-type} [dcm-parameters]

      • Content-Location: {BulkDataURI}

  • Metadata and its associated bulk data shall always be sent in the same POST request.

    Note

    It is not intended that metadata and bulk data be stored separately in multiple POST requests since the service always requires the metadata for context.

6.6.1.1.3 JSON Metadata and Bulk Data Request Message Body

The JSON Metadata and Bulk Data Request Message has a multipart body.

  • Content-Type:

    • multipart/related; type="application/dicom+json"; boundary={MessageBoundary}

  • 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:

    • Content-Type: application/dicom+json; transfer-syntax={TransferSyntaxUID}

      Where {TransferSyntaxUID} is the UID of the DICOM Transfer Syntax used to encode the inline binary data in the JSON metadata.

  • Subsequent items will be one of the following:

    • an uncompressed bulk data element encoded in Little Endian binary format with the following headers:

      • Content-Type: application/octet-stream

      • Content-Location: {BulkDataURI}

    • a compressed pixel data object from a SOP Instance in the Study with the following headers:

      • Content-Type: {media-type} [dcm-parameters]

      • Content-Location: {BulkDataURI}

  • JSON Metadata and its associated bulk data shall always be sent in the same POST request.

Note

It is not intended that metadata and bulk data be stored separately in multiple POST requests since the service always requires the metadata for context.

6.6.1.2 Action

The Service 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.

Note

For more information on populating the Original Attribute Sequence, see Section C.12.1 “SOP Common Module” in PS3.3 .

6.6.1.3 Response

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:

  • an XML object as described in the Native DICOM Model defined in PS3.19, or

  • a DICOM JSON Model Object defined as defined in Annex F.

6.6.1.3.1 Response Status Line

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

Service Status

HTTP Status Codes

STOW-RS Description

Failure

400 - Bad Request

This indicates that the STOW-RS Service was unable to store any instances due to bad syntax.

401 - Unauthorized

This indicates that the STOW-RS Service refused to create or append any instances because the client is not authorized.

403 - Forbidden

This indicates that the STOW-RS Service understood the request, but is refusing to fulfill it (e.g., an authorized user with insufficient privileges).

409 - Conflict

This indicates that the STOW-RS Service request was formed correctly but the service was unable to store any instances due to a conflict in the request (e.g., unsupported SOP Class or StudyInstanceUID mismatch).

This may also be used to indicate that a STOW-RS Service was unable to store any instances for a mixture of reasons.

Additional information regarding the instance errors can be found in the XML response message body.

415 - Unsupported Media Type

This indicates that the STOW-RS Service does not support the Content-Type specified in the storage request (e.g., the service does not support JSON metadata).

503 - Busy

This indicates that the STOW-RS Service was unable to store any instances because it was out of resources.

Warning

202 - Accepted

This indicates that the STOW-RS Service stored some of the instances but warnings or failures exist for others.

Additional information regarding this error can be found in the XML response message body.

Success

200 - OK

This indicates that the STOW-RS Service successfully stored all the instances.

Note

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,

Warning: "A700: Out of memory"

6.6.1.3.2 Response Message Body

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

Attribute Name

Tag

Type

Attribute Description

Retrieve URL

(0008,1190)

2

The URL where the Study is available for retrieval via a WADO-RS Retrieve Study service.

Note

The VR of this attribute has changed from UT to UR.

Failed SOP Sequence

(0008,1198)

1C

A sequence of Items where each Item references a single SOP Instance for which storage could not be provided.

Required if one or more SOP Instances failed to store.

>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3

>Failure Reason

(0008,1197)

1

The reason that storage could not be provided for this SOP Instance.

See Section 6.6.1.3.2.1.2.

Referenced SOP Sequence

(0008,1199)

1C

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

>Retrieve URL

(0008,1190)

2

The URL where the SOP Instance is available for retrieval via a WADO-RS service.

Note

The VR of this attribute has changed from UT to UR.

>Warning Reason

(0008,1196)

1C

The reason that this SOP Instance was accepted with warnings.

Required if there was a warning for this SOP Instance.

See Section 6.6.1.3.2.1.1.

>Original Attributes Sequence

(0400,0561)

3

Sequence of Items containing all attributes that were removed or replaced by other values.

One or more Items are permitted in this sequence.

>>Attribute Modification DateTime

(0400,0562)

1

Date and time the attributes were removed and/or replaced.

>>Modifying System

(0400,0563)

1

Identification of the system that removed and/or replaced the attributes.

>>Reason for the Attribute Modification

(0400,0565)

1

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.

>>Modified Attributes Sequence

(0400,0550)

1

Sequence that contains all the Attributes, with their previous values, that were modified or removed from the main data set.

Only a single Item shall be included in this sequence.

>>Any Attribute from the main data set that was modified or removed; may include Sequence Attributes and their Items.

Other Failures Sequence

(0008,119A)

1C

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.

>Failure Reason

(0008,1197)

1

The reason that storage could not be provided for this message item.

See Section 6.6.1.3.2.1.2.

6.6.1.3.2.1 Store Instances Response Attribute Description
6.6.1.3.2.1.1 Warning Reason

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

Status Code (hexadecimal)

Status Code (decimal)

Meaning

Explanation

B000

45056

Coercion of Data Elements

The STOW-RS Service modified one or more data elements during storage of the instance. See Section 6.6.1.3.

B006

45062

Elements Discarded

The STOW-RS Service discarded some data elements during storage of the instance. See Section 6.6.1.3.

B007

45063

Data Set does not match SOP Class

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.

6.6.1.3.2.1.2 Failure Reason

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

Status Code (hexadecimal)

Status Code (decimal)

Meaning

Explanation

A7xx

42752 - 43007

Refused out of Resources

The STOW-RS Service did not store the instance because it was out of resources.

A9xx

43264 - 43519

Error: Data Set does not match SOP Class

The STOW-RS Service did not store the instance because the instance does not conform to its specified SOP Class.

Cxxx

49152 - 53247

Error: Cannot understand

The STOW-RS Service did not store the instance because it cannot understand certain Data Elements.

C122

49442

Referenced Transfer Syntax not supported

The STOW-RS Service did not store the instance because it does not support the requested Transfer Syntax for the instance.

0110

272

Processing failure

The STOW-RS Service did not store the instance because of a general failure in processing the operation.

0122

290

Referenced SOP Class not supported

The STOW-RS Service did not store the instance because it does not support the requested SOP Class.

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.

6.6.1.3.2.2 Response Message Body Example

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>
Prev  Up  Next
6.5.8.4 Media Types  Home  6.7 QIDO-RS Request/Response
DICOM PS3.18 2016c - Web Services