DICOM PS3.18 2018a - 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/dicom+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/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.

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

DICOM PS3.18 2018a - Web Services