DICOM PS3.18 2016a - Web Services

6.9 UPS-RS Worklist Service
Prev | 6 Data Communication Requirements | Next

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

    - application/dicom+xml

      Specifies that the post is DICOM PS3.19 XML metadata. See Section 6.9.1.1.1.

    - application/json

      Specifies that the post is DICOM PS3.18 JSON metadata. See Section 6.9.1.1.1.

- 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/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/1.1 Status Line applicable to the associated request.

#### 6.9.1.3 Response

The Origin-Server shall return an HTTP/1.1 response message.

##### 6.9.1.3.1 Response Status Line

If the Create request is successful, the Origin-Server shall return an HTTP/1.1 "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/1.1 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/1.1 response message shall include the following HTTP/1.1 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/1.1 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.

Prev | Up | Next
6.8 RS Capabilities Service | Home | 6.9.2 UpdateUPS

DICOM PS3.18 2016a - Web Services