DICOM PS3.18 2017c - Web Services

6.9 UPS-RS Worklist Service

This DICOM Web Service defines a RESTful interface to the UPS SOP Classes (see PS3.3 and PS3.4). It consists of the following action types:

  1. CreateUPS

    This action requests the creation of a UPS Instance on the Origin-Server. It corresponds to the UPS DIMSE N-CREATE operation.

  2. UpdateUPS

    This action sets the attributes of a UPS Instance managed by the Origin-Server. It corresponds to the UPS DIMSE N-SET operation.

  3. SearchForUPS

    This action searches for UPS Instances known to the Origin-Server. It corresponds to the UPS DIMSE C-FIND operation.

  4. RetrieveUPS

    This action retrieves a UPS Instances. It corresponds to the UPS DIMSE N-GET operation.

  5. ChangeUPSState

    This action sets the state of a UPS Instance managed by the Origin-Server. It corresponds to the UPS DIMSE N-ACTION operation "Change UPS State".

  6. RequestUPSCancellation

    This action requests the cancellation of a UPS Instance managed by the Origin-Server. It corresponds to the UPS DIMSE N-ACTION operation "Request UPS Cancel".

  7. CreateSubscription

    This action subscribes to a UPS Instance or the Global Worklist managed by the Origin-Server. It corresponds to the UPS DIMSE N-ACTION operation "Subscribe to Receive UPS Event Reports".

  8. SuspendGlobalSubscription

    This action suspends an existing subscription to the Global Worklist managed by the Origin-Server. It corresponds to the UPS DIMSE N-ACTION operation "Suspend Global Subscription".

  9. DeleteSubscription

    This action cancels an existing subscription to a UPS Instance or the Global Worklist managed by the Origin-Server. It corresponds to the UPS DIMSE N-ACTION operation "Unsubscribe from Receiving UPS Event Reports".

  10. OpenEventChannel

    This action initiates a WebSocket connection to allow the User-Agent to start receiving Event Report messages.

  11. SendEventReport

    This action sends an Event Report using an open WebSocket connection. It corresponds to the UPS DIMSE N-EVENT-REPORT operation.

An Origin-Server shall support all of the above action types.

The requirements for a UPS-RS Origin-Server that is also a Unified Worklist and Procedure Step SCP are described in Section CC.1 in PS3.4

Table 6.9-1. UPS Interface Mapping

Action Type

Section

Method & Resource

CreateUPS

6.9.1

POST {+SERVICE}/workitems{?AffectedSOPInstanceUID}

UpdateUPS

6.9.2

POST {+SERVICE}/workitems/{UPSInstanceUID}{?transaction}

SearchForUPS

6.9.3

GET {+SERVICE}/workitems{?query*}

RetrieveUPS

6.9.4

GET {+SERVICE}/workitems/{UPSInstanceUID}

ChangeUPSState

6.9.5

PUT {+SERVICE}/workitems/{UPSInstanceUID}/state

RequestUPSCancellation

6.9.6

POST {+SERVICE}/workitems/{UPSInstanceUID}/cancelrequest

CreateSubscription

6.9.7

POST {+SERVICE}/workitems/{UPSInstanceUID}/subscribers/{AETitle}{?deletionlock}

POST {+SERVICE}/workitems/1.2.840.10008.5.1.4.34.5/

subscribers/{AETitle}{?deletionlock}

POST {+SERVICE}/workitems/1.2.840.10008.5.1.4.34.5.1/

subscribers/{AETitle}{?deletionlock,query*}

SuspendGlobalSubscription

6.9.8

POST {+SERVICE}/workitems/1.2.840.10008.5.1.4.34.5/

subscribers/{AETitle}/suspend

POST {+SERVICE}/workitems/1.2.840.10008.5.1.4.34.5.1/

subscribers/{AETitle}/suspend

DeleteSubscription

6.9.9

DELETE {+SERVICE}/workitems/{UPSInstanceUID}/

subscribers/{AETitle}

OpenEventChannel

6.9.10

GET {+WSSERVICE}/subscribers/{AETitle}

SendEventReport

6.9.11

N/A


The Origin-Server shall comply with all requirements placed on the SCP for the corresponding services in Annex CC “Unified Procedure Step Service and SOP Classes (Normative)” in PS3.4.

6.9.1 CreateUPS

This resource allows a User-Agent to instruct an Origin-Server to create a UPS instance.

6.9.1.1 Request

The request message shall be formed as follows:

  • Resource

    • {+SERVICE}/workitems{?AffectedSOPInstanceUID}

      where

      • {+SERVICE} is the base URL for the service. This may be a combination of protocol (either HTTP or HTTPS), authority and path.

      • {AffectedSOPInstanceUID} specifies the SOP Instance UID of the UPS Instance to be created

  • Method

    • POST

  • Headers

    • Content-Type - The representation scheme being posted to the RESTful service. The types allowed for this request header are as follows:

  • The request body shall convey a single Unified Procedure Step Instance. The instance shall comply with all requirements in the Req. Type N-CREATE column of Table CC.2.5-3 in PS3.4 .

6.9.1.1.1 Request Message

The Request Message has a single part body.

  • Content-Type:

    • application/dicom+xml

    • application/dicom+json

  • The request body contains all attributes to be stored in either DICOM PS3.19 XML or DICOM JSON. Any binary data contained in the message shall be inline.

6.9.1.2 Behavior

The Origin-Server shall create and maintain UPS instances as instructed by CreateUPS requests and as specified by the SCP behavior in Section CC.2.5.3 in PS3.4 .

The Origin-Server shall return the HTTP Status Line applicable to the associated request.

6.9.1.3 Response

The Origin-Server shall return an HTTP response message.

6.9.1.3.1 Response Status Line

If the Create request is successful, the Origin-Server shall return an HTTP "201 - Created" response code.

If the request fails, the Origin-Server shall return an appropriate failure status line with a response code from Table 6.9.1-1.

Table 6.9.1-1. Status Codes

HTTP Code

Reason Phrase

Description

201

Created

The UPS instance was created and the new resource can be retrieved at the Content-Location specified in the response

400

Bad Request

The UPS-RS Origin-Server was unable to understand the request

401

Unauthorized

The UPS-RS Origin-Server refused to accept the request because the client is not authenticated.

403

Forbidden

The UPS-RS Origin-Server understood the request, but is refusing to perform the query (e.g., an authenticated user with insufficient privileges).

409

Conflict

The UID of the posted UPS Instance corresponds to an existing UPS Instance.

503

Busy

Service is unavailable.


6.9.1.3.2 Response Headers

If the request is successful, the HTTP response message shall include the following HTTP header:

  • Content-Location: {+WorkitemURL}

    Where {+WorkitemURL} is the URL from which the created UPS Instance can be retrieved (see Section 6.9.4)

If the UPS instance was created with modifications, the response message shall include the following HTTP header:

  • Warning: 299 {+SERVICE}: The UPS was created with modifications.

6.9.1.3.3 Response Message Body

The response message body shall be empty.

DICOM PS3.18 2017c - Web Services