digital imaging and communications in medicine...
TRANSCRIPT
Digital Imaging and Communications in Medicine (DICOM)
Supplement 171: Unified Procedure Step by REpresentational State Transfer (REST) Services
(UPS-RS)
Prepared by:
DICOM Standards Committee, Working Group 27 Web Technology
1300 N. 17th Street, Suite 900
Rosslyn, Virginia 22209 USA
Contact: [email protected]
VERSION: Working Draft, 2014.04.03
Developed in accordance with: DICOM Workitem 2013-08-B
2
4
6
8
10
12
14
16
18
20
22
24
26
28
Supplement 166 WADO by means of REpresentational State Transfer (REST) ServicesPage ii2
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage iii
Table of Contents
Scope and Field of Application...................................................................................................................... 1TODO List..................................................................................................................................................... 1OPEN ISSUES.............................................................................................................................................. 1CLOSED ISSUES.......................................................................................................................................... 3Changes to NEMA Standards Publication PS 3.2-2011................................................................................4Digital Imaging and Communications in Medicine (DICOM)..........................................................................4Part 2: Conformance..................................................................................................................................... 4ANNEX X (Informative) CONFORMANCE STATEMENT SAMPLE UPS-RS SERVICE..............................4Changes to NEMA Standards Publication PS 3.17-2012..............................................................................5Digital Imaging and Communications in Medicine (DICOM)..........................................................................5Part 17: Explanatory Information................................................................................................................... 5Changes to NEMA Standards Publication PS 3.18-2012..............................................................................6Digital Imaging and Communications in Medicine (DICOM)..........................................................................6Part 18: Web Services................................................................................................................................... 6
Z.X UPS-RS WORKLIST SERVICE..............................................................................................6Z.X.1 workitems Resource (Create)........................................................................................7
Z.X.1.1 Request...............................................................................................................7Z.X.1.1.1 Metadata Request Message Body.................................................................7
Z.X.1.2 Behavior..............................................................................................................7Z.X.1.3 Response............................................................................................................8
Z.X.1.3.1 Response Status Line................................................................8Z.X.1.3.2 Response Headers....................................................................8Z.X.1.3.3 Response Message Body..........................................................8
Z.X.2 workitem Resource (Set)...............................................................................................8Z.X.2.1 Request...............................................................................................................8
Z.X.2.1.1 Metadata and Bulk Data Request Message Body.........................................9Z.X.2.2 Response..........................................................................................................10
Z.X.2.2.1 Response Status Line..............................................................10Z.X.2.2.2 Response Message Body........................................................10
Z.X.3 workitems Resource (Find).........................................................................................10Z.X.3.1 Request.............................................................................................................10Z.X.3.2 Response..........................................................................................................12
Z.X.3.2.1 Matching..................................................................................12Z.X.3.2.1.1 Workitem Matching......................................................................13
Z.X.3.2.2 Query Result Attributes............................................................14Z.X.3.2.2.1 Workitem Result Attributes..........................................................14
Z.X.3.2.3 Response Status Line..............................................................14Z.X.3.2.4 Response Message Body........................................................15
Z.X.3.2.4.1 XML Response Message Body....................................................15Z.X.3.2.4.2 JSON Response Message Body..................................................15
Z.X.4 workitem Resource (Get)............................................................................................16Z.X.4.1 Request.............................................................................................................16
4
30
32
34
36
38
40
42
44
46
48
50
52
54
56
58
60
62
64
66
68
70
72
Supplement 166 WADO by means of REpresentational State Transfer (REST) ServicesPage iv
Z.X.4.2 Response..........................................................................................................16Z.X.4.2.1 XML Response Message Body.......................................................16Z.X.4.2.2 JSON Response Message Body.....................................................17
Z.X.5 state Resource (ChangeUPSState).............................................................................17Z.X.5.1 Request.............................................................................................................17Z.X.5.2 Response..........................................................................................................17
Z.X.5.2.1 Response Status Line..............................................................17Z.X.5.2.2 Response Message Body........................................................17
Z.X.6 cancelrequest Resource (RequestUPSCancel)...........................................................18Z.X.6.1 Request.............................................................................................................18Z.X.6.2 Response..........................................................................................................18
Z.X.7 subscribers Resource (Subscribe)..............................................................................18Z.X.7.1 Request.............................................................................................................18Z.X.7.2 Response..........................................................................................................18
Z.X.7.2.1 Response Status Line..............................................................18Z.X.7.2.2 Response Message Body........................................................19
Z.X.8 subscribers Resource (Unsubscribe)..........................................................................19Z.X.8.1 Request.............................................................................................................19Z.X.8.2 Response..........................................................................................................19
Z.X.8.2.1 Response Status Line..............................................................19Z.X.8.2.2 Response Message Body........................................................20
Z.X.9 subscribers Resource (StartReceivingEvents)............................................................20Z.X.9.1 Request.............................................................................................................20Z.X.9.2 Response..........................................................................................................20
Z.X.9.2.1 Response Status Line..............................................................20Z.X.9.2.2 Response Message Body........................................................21
Z.X.10 events Resource (Placeholder for the N-EVENT-REPORT Stuff)...............................21
6
74
76
78
80
82
84
86
88
90
92
94
96
98
100
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 1
Scope and Field of Application
This Supplement defines a set of REpresentational State Transfer (REST) Services for interfacing with the Unified Procedure Step Services. This could be implemented as a proxy to an existing UPS service or as a web service interacting directly with a Workflow Manager.
<<Elaborate a little bit>>
Security is beyond the scope of the RESTful services defined in this supplement. However generic Web security mechanisms are fully compatible. Several security programming recipes are provided for reference.
TODO List
Consider a Whitepaper on how all the pieces/mechanisms of UPS can/should be used to address various challenges.Eg look at what was done for the Mammo Workflow diagrams and XDW
- be clear that the overall flow is external and is not represented explicitly in any of the individual artifacts
- the manager might know the overall flow/business logic and create UPS items accordingly- the overall flow might be implicit in various UPS items being created in response to events
(such as the completion of an antecedent UPS item, or availability of some object)- high-level workflow managers should be able to use a (UPS) task manager for the individual
task nodes. They might have not separated that clearly, but you could build a proxy client/creator.
This is where we could discuss the idea of a “Plan Task X” Task. (Like Plan better than Ordered State)Explain how separate worklists can work (either part of Service – so separate SCPs, or as the attribute in a query) The separate SCPs could be on different boxes or could be different ports/endpoints on the same box.
Figure out if anything about using UPS access locks through a proxy need changing?
If we use POST for both CREATE and SET we need to make sure the SCP is clear (although currently thinking to use POST for SET)The State will differentiate for the SCP. Differing rules will come into play.During Create it will be SCHEDULED with lots of Scheduled and no Performed and visa versa for IN PROGRESS.
Ensure push workflow scenarios work.
8
102
104
106
108
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 2
OPEN ISSUES
Topic
If you have sophisticated business logic managing your workflow, and it is feeding on specific triggers and events like the presence of a certain study or study type in the local image manager, when you spread the workflow across multiple sites, the logic engine might not have access to the same degree of low level triggers from a remote site, thus it is not transparent to having work done “anywhere” across the “affinity domain”. Polling mechanisms could be quite costly. If RWF-UPS is to address cross enterprise reading, these issues come to the fore.
Do we allow Create to omit the UID if the SCU doesn’t want to be able to generate UIDs?
Could be proxied, but keep the same as DIMSE for now.
Do we want to allow Query results to be provided in DICOM Binary? Really shouldn’t DICOM instance information always be available in any of the three representations (Binary, XML, JSON) – although are there implementation loads for the SCP?
Tentatively no.
QIDO doesn’t allow this and we are paralleling QIDO.Note that if you can extract the Instance UID, you can still do a GET that requests the Binary.There are some questions about whether there would be a performance gain from getting UPS items sets in Binary.Maybe we should add to both to allow Binary in all the subservices, not just the GETS and PUTS
Should Part 10 objects be allowed or just XML / JSON?
Is there a better option than websockets?
Any websockets sub-protocols worth inheriting?
CLOSED ISSUES
Topic
10
110
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 3
Should query use POST (instead of GET) due to possible URL length limitations?
A: No.It works OK for QIDO and this is likely to be similar.
Should the creation of multiple workitems in a single request be permitted?
A: No.The DIMSE UPS does not permit this. Although it could be proxied, it would raise additional questions about partial failures. Leave it out for now.
Should the Worklist (Label) be exposed in the resource or treated as an attribute?
A. No
DICOM treats it as an attribute.It might be convenient to get all workitems in a Worklist via a resource (but you could include as a query parameter)When you are interacting with a UPS instance, you don’t really care about the worklist. It’s mostly a query/grouping.Hmm. What about Global Subscription to a given worklist? Might be handy but DICOM doesn’t support this now (so it would be awkward but possible to proxy)
What types of Push Workflow do we consider to be in scope?
A. All push workflow can be supported.
There might be implications on what we expect from a web application and/or browser system, etc. If we envisage them being SCPs too.
Could we do without Transaction UID in SET and use other mechanisms for identifying claiming system?
A. Transaction UID works and maps to existing UPS.
Also, would make it harder to borrow Part 4 text.
12
14
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 4
Should SET use PUT or POST?
A. PUT.
Some firewalls and proxys might not support POST for the reverse proxies.But they do support WebDAV (which does? Support POST?)We could GET, fix and PUT a full set of attributes.An advantage of POST is that it communicates the Before as well as the After allowing the SCP to detect blind collisions between two updates. (While PUT would let one unintentionally overwrite the other)JSON has a POST format that might be relevant to this.
16
112
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 5
Changes to NEMA Standards Publication PS 3.2-2011
Digital Imaging and Communications in Medicine (DICOM)
Part 2: Conformance
Add to PS 3.2
ANNEX X (Informative) CONFORMANCE STATEMENT SAMPLE UPS-RS SERVICE
Disclaimer:
This document is an example DICOM Conformance Statement for a fictional application service called EXAMPLE-QIDO-SERVICE produced by a fictional vendor called EXAMPLE-PACS-PRODUCTS.
As stated in the annex title, this document is truly informative, and not normative. A conformance statement of an actual product might implement additional services and options as appropriate for its specific purpose. In addition, an actual product might implement the services described in a different manner and, for example, with different characteristics and/or sequencing of activities. In other words, this conformance statement example does not intend to standardize a particular manner that a product might implement DICOM functionality.
—
18
114
116
118
120
122
124
126
128
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 6
Changes to NEMA Standards Publication PS 3.17-2012
Digital Imaging and Communications in Medicine (DICOM)
Part 17: Explanatory Information
Add Annex if needed.
20
130
132
134
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 7
Changes to NEMA Standards Publication PS 3.18-2012
Digital Imaging and Communications in Medicine (DICOM)
Part 18: Web Services
Insert into PS 3.18 Section 5.2 Symbols and abbreviated terms (in correct alphabetical order)
UPS-RS Unified Procedure Step by RESTful Services
Add Section Z.X UPS-RS WORKLIST SERVICE
Z.X UPS-RS WORKLIST SERVICE
This DICOM Web Service defines a RESTful interface to the UPS SOP Classes (See PS 3.3 & PS 3.4).
Table Z.X-1UPS RESTFUL INTERFACE MAPPING
UPS DIMSE Section
RESTful Method & Resource
N-CREATEZ.X.1 POST {SERVICE}/workitems
N-SETZ.X.2
POST {SERVICE}/workitems/{InstanceUID}[?transaction={TransactionUID}]
C-FINDZ.X.3 GET {SERVICE}/workitems[?query]
N-GETZ.X.4 GET {SERVICE}/workitems/{InstanceUID}
N-ACTION (ChangeUPSState)
Z.X.5 PUT {SERVICE}/workitems/{InstanceUID}/state
N-ACTION (RequestUPSCancel)
Z.X.6 POST {SERVICE}/workitems/{InstanceUID}/cancelrequest
N-ACTION (Subscribe)
Z.X.7POST {SERVICE}/workitems/{InstanceUID}/subscribers[?deletionlock=true]
N-ACTION (Unsubscribe)
Z.X.8DELETE {SERVICE}/workitems/{InstanceUID}/subscribers/{SubscriberID}
N/A Z.X.9 GET
22
136
138
140
142
144
146
24
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 8
UPS DIMSE Section
RESTful Method & Resource
(StartReceivingEvents)
{WSSERVICE}/workitems/{InstanceUID}/subscribers/{SubscriberID}
N-EVENT-REPORT Z.X.10 N/A
** Review error codes from UPS for anything troublesome
Consider adding a “Common” section if reiteration of common text becomes a problem in the sections below.
The RESTful Service shall comply with all requirements placed on the SCP for the corresponding services in PS 3.4 Annex CC (Unified Procedure Step Service and SOP Classes).
Z.X.1 workitems Resource (Create)This resource supports the creation of a new UPS workitem.
Z.X.1.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems
where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
Method
o POST
Headers
o 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 PS 3.19 XML metadata. See Z.X.1.1.1
application/json
Specifies that the post is PS 3.18 JSON metadata. See Z.X.1.1.1
26
148
150
152
154
156
158
160
162
164
166
168
170
172
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 9
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 PS 3.4 Table CC.2.5-3.
Z.X.1.1.1 Metadata Request Message BodyThe Metadata Request Message has a single part body.
Content-Type:
o application/dicom+xml
o application/json
The request body contains all the metadata to be stored in either DICOM PS 3.19 XML metadata, DICOM PS 3.18 JSON metadata. Any binary data contained in the message shall be inline.
Z.X.1.2 BehaviorThe origin-server is going to create the workitem.
Z.X.1.3 ResponseThe RESTful Service shall return an HTTP response message.
Z.X.1.3.1 Response Status LineIf the Create request is successful, the RESTful service shall return an “HTTP 201 - Created” response code.
If the request fails, the RESTful Service shall return an appropriate failure status line with a response code from Table XXX.
Z.X.1.3.2 Response HeadersIf the request is successful, the HTTP response message shall include the following HTTP/1.1 header:
Content-Location: {WorkitemURL}
Where {WorkitemURL} is the URL from which the created Workitem can be retrieved (see Z.X.4 workitem Resource (Get))
If the UPS was created with modifications, the response message shall include the following HTTP/1.1 header:
Warning: 299 {SERVICE}: The UPS was created with modifications.
Z.X.1.3.3 Response Message BodyThe response message body shall be empty.
Z.X.2 workitem Resource (Set)This resource supports the modification of attribute values of an existing UPS workitem.
28
174
176
178
180
182
184
186
188
190
192
194
196
198
200
202
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 10
Z.X.2.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems/{WorkItemInstanceUID}[?transaction={TransactionUID}]
where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance
{TransactionUID} is the Transaction UID / Locking UID for the specified Unified Procedure Step Instance
If the UPS instance is currently in the SCHEDULED state, the {TransactionUID} shall not be specified.
If the UPS instance is currently in the IN PROGRESS state, the {TransactionUID} shall be specified.
Method
o POST
Headers
o 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+xml; boundary={messageBoundary}
Specifies that the post is PS 3.19 XML metadata and bulk data. See Z.X.2.1.1
multipart/related; type=application/json; boundary={messageBoundary}
Specifies that the post is PS 3.18 JSON metadata and bulk data. See Z.X.2.1.1
The request body describes changes to a single Unified Procedure Step Instance. It shall include all Attributes for which it wants to set the Attribute Values. The changes shall comply with all requirements described in the Req. Type N-SET column of PS 3.4 Table CC.2.5-3.
The request shall be atomic (indivisible) and idempotent (repeat executions have no additional effect). All changes contained in the request shall leave the UPS instance in an internally consistent state.
Z.X.2.1.1 Metadata and Bulk Data Request Message BodyThe Metadata and Bulk Data Request Message has a multipart body.
30
204
206
208
210
212
214
216
218
220
222
224
226
228
230
232
234
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 11
Content-Type:
o multipart/related; type=application/dicom+xml; boundary={MessageBoundary}
o multipart/related; type=application/json; boundary={MessageBoundary}
The 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 PS 3.19 XML metadata, DICOM PS 3.18 JSON metadata or a bulk data item from a SOP Instance sent as part of the POST operation. The first part of the multipart message must be metadata.
The first part in the multipart request will contain one of the following HTTP headers:
o Content-Type: application/dicom+xml; transfer-syntax={TransferSyntaxUID}
o Content-Type: application/json; transfer-syntax={TransferSyntaxUID}
Subsequent items will contain the following HTTP headers (order is not guaranteed):
o an uncompressed bulk data element encoded in Little Endian binary format with the following headers:
Content-Type: application/octet-stream
Content-Location: {BulkDataURI}
o a compressed pixel data object from a SOP Instance in the Study with the following headers:
Content-Type: {MediaType}
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 sent separately in multiple POST requests since the service always requires the metadata for context.
Z.X.2.2 ResponseThe Service shall return an HTTP status line, including a status code and associated textual phrase.
If the POST request is successful, the response message shall include the following HTTP/1.1 header:
Content-Location: {WorkitemURL}
Where {WorkitemURL} is the URL from which the updated UPS Instance can be retrieved (see Z.X.4 workitem Resource (Get))
32
236
238
240
242
244
246
248
250
252
254
256
258
260
262
264
34
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 12
If the UPS was POSTed with modifications, the response message shall include the following HTTP/1.1 header:
Warning: 299 {SERVICE}: Coerced invalid values to valid values.
If optional attributes were rejected, the response message shall include the following HTTP/1.1 header:
Warning: 299 {SERVICE}: Requested optional Attributes are not supported.
Z.X.2.2.1 Response Status LineIf the POST request is successful, the RESTful service shall return an “HTTP 204 - Accepted” response code.
If the POST request fails, the RESTful Service shall return an appropriate failure status line with a response code from Table XXX.
Z.X.2.2.2 Response Message BodyThe response message body shall be empty.
Z.X.3 workitems Resource (Find)This resource returns a list of UPS workitems that match specified search query parameters along with requested attributes for each workitem.
Z.X.3.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems/[?query]
where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
Method
o GET
Headers
o Accept – The representation scheme in which the RESTful service is requested to return the results. The types allowed for this request header are as follows:
multipart/related; type=application/dicom+xml; boundary={messageBoundary}
Specifies that the results should be PS 3.19 XML metadata.
36
266
268
270
274
276
278
280
282
284
286
288
290
292
294
296
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 13
application/json
Specifies that the results should be PS 3.18 JSON metadata.
o Cache-control: no-cache (recommended)If included, specifies that search results returned should be current and not cached.
Query key=value pairs
o {attributeID}={value}
0-n / {attributeID}={value} pairs allowed
o includefield={attributeID} | all
0-n includefield / {attributeID} pairs allowed, where “all” indicates that all attributes with values should be included for each response.
o fuzzymatching=true | false
o limit={maximumResults}
o offset={skippedResults}
Each {attributeID} must refer to an attribute of the Unified Procedure Step IOD (see PS 3.3 B.26.2).
Each {attributeID} query value must be unique within the query unless the associated DICOM Attribute allows UID List matching (see DICOM PS3.4 C.2.2.2.2), in which case each {value} will be interpreted to be an element of the UID List.
The acceptable values for {value} are determined by the types of matching allowed by C-FIND for its associated {attributeID} (see PS3.4 C.2.2.2). All characters in {value} that are disallowed for URLs must be URL encoded. See IETF RFC 1738 for details.
If an {attributeID} is passed as the value of an “includefield” query key this is equivalent to C-FIND Universal matching for the specified attribute (see DICOM PS3.4 C.2.2.2.3).{attributeID} can be one of the following:
{dicomTag} {dicomKeyword} {dicomTag}.{attributeID}, where {attributeID} is an element of the sequence specified by
{dicomTag} {dicomKeyword}.{attributeID}, where {attributeID} is an element of the sequence
specified by {dicomKeyword}
{dicomTag} is the eight character hexadecimal string corresponding to the Tag of a DICOM Attribute (see PS3.6 Section 6).
{dicomKeyword} is the Keyword of a DICOM Attribute (see PS3.6 Section 6).
38
298
300
302
304
306
308
310
312
314
316
318
320
322
324
326
328
330
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 14
Z.X.3.2 BehaviorThe Server shall perform the query indicated in the request.
If the limit query key is not specified or its value exceeds the total number of matching results then {maximumResults} is the lesser of the number of matching results and the maximum number of results supported by the Server.
If the offset query key is not specified or its value is less than zero then {skippedResults} is zero.
The first result returned shall be result number ({skippedResults} + 1). The last result returned shall be result number ({skippedResults} + {maximumResults}). If ({skippedResults} + 1) exceeds {maximumResults} then no results are returned.
If the number of results exceeds the maximum supported by the server, the server shall return the maximum supported results and the response shall include the following HTTP/1.1 Warning header (see RFC 2616 Section 14.46):
Warning: 299 {SERVICE}: “The number of results exceeded the maximum supported by the server. Additional results can be requested.
Note: The client can request additional results by specifying a value for the “offset” query key.
The server response shall be idempotent so that if the list of results is the same, the response to a request with a specific set of parameters shall always be the same, including order. If the complete list of results is different for subsequent requests the responses may be different. In a situation where results are changing due to changes in the server contents, queries using the limit and offset may be inconsistent.
Z.X.3.2.1 MatchingThe matching semantics for each attribute are determined by the types of matching allowed by C-FIND (see PS3.4 C.2.2.2).
Combined Datetime matching shall be performed (see DICOM PS3.4 C.2.2.2.5).
Note: If a UPS-RS provider is acting as a proxy for a C-FIND SCP that does not support combined Datetime matching the UPS-RS provider will need to perform a C-FIND request using Date only and filter results outside the time range before returning a UPS-RS response
If the TimezoneOffsetFromUTC / 00080201 query key is included in the request, dates and times in the request are to be interpreted in the specified time zone.
If the “fuzzymatching=true” query key/value is included in the request and it is supported then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the service provider.
If the “fuzzymatching=true” query key/value is included in the request and it is not supported, the response shall include the following HTTP/1.1 Warning header (see RFC 2616 Section 14.46):
40
332
334
336
338
340
342
344
350
352
354
356
358
362
364
366
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 15
Warning: 299 {SERVICE}: “The fuzzymatching parameter is not supported. Only literal matching has been performed.”
Note: The Warning header is separate from the Status Line and does not affect the returned Status Code.
Providers of the SearchForWorkitems service shall support the search query keys described in Table Z.X.3-1:
Table Z.X.3-1Workitem Search Query Keys
Key Word Tag
SOPInstanceUID 00080018
PatientName 00100010
PatientID 00100020
IssuerOfPatientID 00100021
PatientBirthDate 00100030
PatientSex 00100040
AdmissionID 00380010
IssuerOfAdmissionIDSequence 00380014
ScheduledStationNameCodeSequence 00404025
ScheduledStationClassCodeSequence 00404026
ScheduledStationGeographicLocationCodeSequence 00404027
ScheduledHumanPerformersSequence 00404034
ScheduledProcedure Step Start Date and Time 00404005
Expected Completion Date and Time 00400011
Scheduled Workitem Code Sequence 00404018
InputReadinessState 00404041
ReferencedRequestSequence 0040A370
ProcedureStepState 00741000
ScheduledProcedureStepPriority 00741200
ProcedureStepLabel 00741201
WorklistLabel 00741202
ReplacedProcedureStepSequence 00741224
Z.X.3.3 ResponseFill in some response text details, including mention that no results = success with empty results.
42
368
374
376
378
44
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 16
Z.X.3.3.1 Response Status LineTable Z.X.3-3 lists the HTTP/1.1 status codes that shall be used to report the success of the query and any of the associated error and warning situations. Other error codes may be present for other error and warning situations and should be documented in a Conformance Statement.
Table Z.X.3-3STATUS CODES
HTTP/1.1 Code Reason Phrase Description200 OK The query completed and any
matching results are returned in the message body.
206 Partial Content Only some of the query results were returned and the rest can be requested through the appropriate UPS-RS request.
400 Bad Request The UPS-RS Service was unable to perform the query because the Service Provider cannot understand the query component.
401 Unauthorized The UPS-RS Service refused to perform the query because the client is not authenticated.
403 Forbidden The UPS-RS Service understood the request, but is refusing to perform the query (e.g. an authenticated user with insufficient privileges).
413 Request entity too large The query was too broad and a narrower query or paging should be requested.
503 Busy Service is unavailable.
Z.X.3.3.2 Query Result AttributesFor each matching Workitem, the UPS-RS provider shall return all attributes in accordance with Table Z.X.3-2:
Table Z.X.3-2Workitem Returned Attributes
Attribute Name Tag NotesIssuer of Patient ID (0010,0021)
Referenced Request Sequence (0040,A370)
Input Information Sequence (0040,4021) Shall be present if it
46
380
382
384
386
388
390
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 17
contains one or more Sequence Items.
If present each sequence item shall contain one or more Retrieve URL (0008,1190) elements.
Unified Procedure Step Performed Procedure Sequence
(0074,1216) Shall be present if it contains one or more Sequence Items.
Any Output Information Sequence (0040,4033) elements present shall contain one or more Retrieve URL (0008,1190) elements.
All Unified Procedure Step Instance Attributes in PS 3.4 Table CC.2.5-3 with a Return Key value of 1.
All Unified Procedure Step Instance Attributes in PS 3.4 Table CC.2.5-3 with a Return Key value of 1C for which the conditional requirements are met.
All Unified Procedure Step Instance Attributes in PS 3.4 Table CC.2.5-3 with a Return Key value of 2 if they contain a Value.
All other Unified Procedure Step Instance Attributes passed as {attributeID} query keys that are supported by the service provider as matching or return attributes
All other Unified Procedure Step Instance Attributes passed as “includefield” query values that are supported by the service provider as return attributes
Z.X.3.3.3 Response Message BodyThe response message body contains the results.
The format of the response message body depends on the Accept header specified in the request.
Z.X.3.3.3.1 XML Response Message Body Content-Type:
o multipart/related; type=application/dicom+xml The response is a multipart message body where each part is a DICOM PS 3.19 XML
DicomNativeModel element containing the attributes for one matching Workitem (see DICOM PS 3.19 Annex A.1).
If there are no matching results, the message body will be empty.
Each part in the multipart body includes the following HTTP/1.1 headers:
o Content-Type: application/dicom+xml
48
392
394
396
398
400
402
404
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 18
Z.X.3.3.3.2 JSON Response Message Body Content-Type:
o application/json The response is a DICOM JSON message containing a DICOM JSON property for each matching
Workitem containing sub-properties describing the matching attributes for each Workitem (see F.2).
If there are no matching results, the JSON message is empty.
Z.X.4 workitem Resource (Get)This resource supports the retrieval of attribute values of an existing UPS workitem.
Z.X.4.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems/{WorkItemInstanceUID}
where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance
Method
o GET
Headers
o Accept – The representation scheme in which the RESTful service is requested to return the result. The types allowed for this request header are as follows:
multipart/related; type=application/dicom+xml; boundary={messageBoundary}
Specifies that the result should be PS 3.19 XML metadata.
application/json
Specifies that the result should be PS 3.18 JSON metadata.
o Cache-control: no-cache (recommended)If included, specifies that results returned should be current and not cached.
Z.X.4.2 ResponseResult is a specific work-item excluding the Transaction UID (0008,1195) element.
50
408
410
412
414
416
418
420
422
424
426
428
430
432
434
436
438
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 19
Encoding is XML or JSON.
Z.X.4.2.1 XML Response Message Body Content-Type:
o multipart/related; type=application/dicom+xml The response is a multipart message body with a single part message part containing a DICOM
PS 3.19 XML DicomNativeModel element containing the attributes for the requested Workitem (see DICOM PS 3.19 Annex A.1).
Each part in the multipart body includes the following HTTP/1.1 headers:
o Content-Type: application/dicom+xml
Z.X.4.2.2 JSON Response Message Body Content-Type:
o application/json The response is a DICOM JSON array containing a DICOM JSON representation of the requested
Workitem (see F.2).
Z.X.5 state Resource (ChangeUPSState)This resource supports the modification of the state of an existing UPS workitem.
Z.X.5.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems/{WorkitemInstanceUID}?state={DesiredState}&transaction={TransactionUID}
where:
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance
{DesiredState} is the one of (IN PROGRESS, COMPLETED, CANCELED)
{TransactionUID} is the Transaction UID / Locking UID for the specified Unified Procedure Step Instance
Method
o PUT
Headers
52
440
442
444
446
450
452
456
458
460
462
464
466
468
470
472
54
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 20
o Content-Length: 0
The request body shall be empty.
Z.X.5.2 ResponseThe Service shall return an HTTP status line, including a status code and associated textual phrase.
Z.X.5.2.1 Response Status LineIf the State Change was successful, the Service shall return an “HTTP 204 - Accepted” response code.
If the State Change fails, the Service shall return an appropriate failure status line with a response code from Table XXX.
Z.X.5.2.2 Response Message BodyThe response message body shall be empty.
Z.X.6 cancelrequest Resource (RequestUPSCancel)This resource records a request that the specified UPS workitem be canceled.
Z.X.6.1 RequestPOST {service}/workitems/{WorkitemInstanceUID}/cancelrequest
parameters from UPS N-ACTION
The body would contain the (text and coded) Reason and (URI and name) Contact attributes from CC.2.2-1.
Cancels a UPS item for which the client does not have control
Does not allow/support/define providing a Transaction UID
Z.X.6.2 Response
Z.X.7 subscribers Resource (Subscribe)This resource records subscribers to whom future events associated with the UPS workitem or defined worklist will be reported.
Z.X.7.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems/{WorkitemInstanceUID}/subscribers[?deletionlock=true|false]
where
56
474
476
478
480
482
484
486
488
490
492
494
496
498
500
502
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 21
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance or a well-known UID
Method
o POST
Headers
o Content-Length: 0
The request body shall be empty.
Z.X.7.2 ResponseZ.X.7.2.1 Response Status LineThe Service shall return an HTTP status line, including a status code and associated textual phrase.
If the subscription was successful, the Service shall return an “HTTP 201 - Created” response code. The response shall contain a “Content-Location” header of the following format:
Content-Location: {SERVICE}/{WorkitemInstanceUID}/subscribers/{SubscriberID}
where:
o {SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
o {WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance or a well-known UID
o {SubscriberID} is the server-assigned identifier to be used to receive subscriptions or to modify the existing subscription
If the subscription fails, the Service shall return an appropriate failure status line with a response code from Table XXX.
Z.X.7.2.2 Response Message BodyThe response message body shall be empty.
Z.X.8 subscribers Resource (Unsubscribe)This resource removes existing subscriptions from a UPS Workitem or defined worklist.
Z.X.8.1 RequestThe request message shall be formed as follows:
Resource
o {SERVICE}/workitems/{WorkitemInstanceUID}/subscribers/{SubscriberID}
58
504
506
508
510
512
514
516
518
520
522
524
526
528
530
532
534
536
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 22
where
{SERVICE} is the base URL for the service. This may be a combination of scheme (either HTTP or HTTPS), host, port, and application.
{WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance or a well-known UID
{SubscriberID} is the user-agent token id
Method
o DELETE
The request body shall be empty.
Z.X.8.2 ResponseZ.X.8.2.1 Response Status LineThe Service shall return an HTTP status line, including a status code and associated textual phrase.
If the unsubscription was successful, the Service shall return an “HTTP 204 – No Content” response code.
If the subscription fails, the Service shall return an appropriate failure status line with a response code from Table XXX.
Z.X.8.2.2 Response Message BodyThe response message body shall be empty.
Z.X.9 subscribers Resource (StartReceivingEvents)This resource initiates the receiving of events to which the client is subscribed.
Z.X.9.1 RequestThe request message shall be formed as follows:
Resource
o {WSSERVICE}/workitems/{WorkitemInstanceUID}/subscribers/{SubscriberID}
where
{WSSERVICE} is the base URL for the websocket service. This shall include the websockets scheme (either WS or WSS) and may include a combination of host, port, and application
Method
o GET
Headers
60
538
540
542
544
546
548
550
552
554
556
558
560
562
564
566
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 23
o Origin: {SERVICE}/workitems/{WorkitemInstanceUID}/subscribers/{SubscriberID}
o Connection: Upgrade
o Host: {WSSERVICE}/workitems/{WorkitemInstanceUID}/subscribers/{SubscriberID}
o Upgrade: websocket
o Accept:
application/dicom+xml
application/json
If the websocket connection is lost at any point it can be re-established by repeating this request. Messages are not queued. Existing subscriptions are unaffected by the current state of the websocket connection.
Check to see if there are N-EVENT details that don’t fit this case (e.g. failures that need to be handled differently) and necessary re-wording given connection details.
Z.X.9.2 ResponseZ.X.9.2.1 Response Status LineThe Service shall return an HTTP status line, including a status code and associated textual phrase.
If the request was successful, the Service shall return an “HTTP 101 - Switching Protocols” response code. The response shall contain the following HTTP headers:
Connection: Upgrade
Upgrade: WebSocket
If the reuqest fails, the Service shall return an appropriate failure status line with a response code from Table XXX.
Z.X.9.2.2 Response Message BodyThe response message body shall be empty, though the connection remains open and may be used by the server to send Event messages (see Z.X.10).
Z.X.10 events Resource (Placeholder for the N-EVENT-REPORT Stuff)The server shall send all events as text data frames.
The events shall be encoded as DICOM JSON.
The events shall comply with all requirements described in PS 3.4 Table CC.2.4-1 for the event type.
Example websocket payload:
“upsStateReport”: {“00741000”: [ “SCHEDULED” ],“00744041”: [ “READY” ]
62
568
570
572
574
576
578
580
582
584
586
588
590
592
594
596
598
64
Supplement 166 WADO by means of Representational State Transfer (REST) ServicesPage 24
}
66
600