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:
CreateUPS
This action requests the creation of a UPS Instance on the Origin-Server. It corresponds to the UPS DIMSE N-CREATE operation.
UpdateUPS
This action sets the attributes of a UPS Instance managed by the Origin-Server. It corresponds to the UPS DIMSE N-SET operation.
SearchForUPS
This action searches for UPS Instances known to the Origin-Server. It corresponds to the UPS DIMSE C-FIND operation.
RetrieveUPS
This action retrieves a UPS Instances. It corresponds to the UPS DIMSE N-GET operation.
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".
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".
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".
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".
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".
OpenEventChannel
This action initiates a WebSocket connection to allow the User-Agent to start receiving Event Report messages.
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 |
POST {+SERVICE}/workitems{?AffectedSOPInstanceUID} |
|
|
UpdateUPS |
POST {+SERVICE}/workitems/{UPSInstanceUID}{?transaction} |
|
|
SearchForUPS |
GET {+SERVICE}/workitems{?query*} |
|
|
RetrieveUPS |
GET {+SERVICE}/workitems/{UPSInstanceUID} |
|
|
ChangeUPSState |
PUT {+SERVICE}/workitems/{UPSInstanceUID}/state |
|
|
RequestUPSCancellation |
POST {+SERVICE}/workitems/{UPSInstanceUID}/cancelrequest |
|
|
CreateSubscription |
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 |
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 |
DELETE {+SERVICE}/workitems/{UPSInstanceUID}/ subscribers/{AETitle} |
|
|
OpenEventChannel |
GET {+WSSERVICE}/subscribers/{AETitle} |
|
|
SendEventReport |
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.
This resource allows a User-Agent to instruct an Origin-Server to create a UPS instance.
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 .
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.
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.
The Origin-Server shall return an HTTP/1.1 response message.
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. |
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.