Digital Imaging and Communications in Medicine...

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.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.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.8 subscribers Resource (Unsubscribe)..........................................................................19Z.X.8.1 Request.............................................................................................................19Z.X.8.2 Response..........................................................................................................19


Z.X.9 subscribers Resource (StartReceivingEvents)............................................................20Z.X.9.1 Request.............................................................................................................20Z.X.9.2 Response..........................................................................................................20


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

jwhitby2, 04/03/14,

Consistent capitalization of worklist and workitem


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


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


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


Changes to NEMA Standards Publication PS 3.2-2011


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




Part 17: Explanatory Information

Add Annex if needed.

20

130

132

134




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

jwhitby2, 04/03/14,

Consistent with Z.X.5


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

jwhitby2, 04/03/14,

Multipart use case?

jwhitby2, 04/03/14,

DICOM binary option

jwhitby2, 04/03/14,

REST names for SCU / SCP: User-Agent / Origin-Server?


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

jwhitby2, 04/03/14,

Add table, either shared or per endpointConsider mapping status tables from UPS Part 4.

jwhitby2, 04/03/14,

Workitems are small so I don’t think there is an issue if a proxy has to wait for a response. The proxy can always return a 503 if it can’t reply in a timely manner.

Kevin O'Donnell, 04/03/14,

Do we need to describe the proxy case? E.g. it’s problematic if the receiver is happy with the message, sends 201, then proxies the DIMSE N-CREATE and has it fail…

jwhitby2, 04/03/14,

Fill out. Include details of success criteria



Resource

o {SERVICE}/workitems/{WorkItemInstanceUID}[?transaction={TransactionUID}]

where


{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

jwhitby2, 04/03/14,

Fix to single-part as above

jwhitby2, 04/03/14,

PATCH is also a contender but has issues with the N_SET warning cases


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


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.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.


Resource

o {SERVICE}/workitems/[?query]

where


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:


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

jwhitby2, 03/28/14,

Add table, either shared or per endpoint

jwhitby2, 04/03/14,

e.g. OtherPatientID sequence


Is there an example of why we would need this? I can edit Kevin’s notes!

jwhitby2, 04/03/14,

These warnings mirror the set of possible UPS responses. The fact they are disallowed by POST may be a reason this should just be a POST.


POST RFP suggests that POST should either fail or succeed fully. Partial success raises awkward issues.Review this policy in the context of UPS N-SET behavior.


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


This block also seems ripe for factoring out into a common piece of text that can be referenced.

jwhitby2, 03/31/14,

Text copied exactly from QIDO. Unique within the scope of the http request, e.g. “?StudyInstanceUID=x&StudyInstanceUID=y” is okay but “AccessionNumber=x&AccessionNumber=y” is _not_ okay


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


Does this mean the maximum number of results the Server can compute, or the maximum number of results the Server can bundle together and return in the Response protocol? The next few paragraphs seem to go both ways.


As part of Part 18 cleanup, is the “SCP” referred to here as “The Server” or “The Service”? We’ve used both.


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

jwhitby2, 04/03/14,

Required by PAWF with some specific sequence elements

jwhitby2, 04/03/14,

Required by PAWF


Need to choose Server, Service or Provider for the subject of Shalls.


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

jwhitby2, 03/28/14,

Required by PAWF with some specific sequence elements

jwhitby2, 03/28/14,

Required by PAWF


Consistency


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


We don’t include this above. Which do we prefer?


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.


Resource

o {SERVICE}/workitems/{WorkItemInstanceUID}

where



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:


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

jwhitby2, 04/03/14,

Open issue – cacheing acceptable or bad?

jwhitby2, 04/02/14,

Since DIMSE requires a list of desired attributes, the distinction between Query and Get is REALLY thin. Like QIDO, omitting the list should result in a (standard) default set of attributes being returned.It would be convenient to have a GET all parameters. Why is this missing in the DIMSE? (Actually, N-GET with no attribute list is supposed to get all parameters as the base behavior for DIMSE. Confirm that this still the case for UPS. Find a reference for this behavior)

jwhitby2, 04/03/14,

Make single part with inline binaries


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.


Resource

o {SERVICE}/workitems/{WorkitemInstanceUID}?state={DesiredState}&transaction={TransactionUID}

where:



{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

jwhitby2, 04/02/14,

Could use different endpoint for each state change or just one endpoint with different params / message contents for different kinds.


We don’t include this above. Which do we prefer?


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.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.


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

jwhitby2, 04/03/14,

Add user-agent token

jwhitby2, 04/02/14,

Can we drop this operation?

jwhitby2, 03/28/14,


jwhitby2, 04/03/14,

Add behavior section



{WorkItemInstanceUID} is the UID of the Unified Procedure Step Instance or a well-known UID

Method

o POST

Headers

o Content-Length: 0


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.8 subscribers Resource (Unsubscribe)This resource removes existing subscriptions from a UPS Workitem or defined worklist.


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

jwhitby2, 04/02/14,



where


{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



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.9 subscribers Resource (StartReceivingEvents)This resource initiates the receiving of events to which the client is subscribed.


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

jwhitby2, 04/03/14,

Replace with user-agent token

jwhitby2, 04/03/14,

User-agent token a better option

jwhitby2, 04/02/14,



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.


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

jwhitby2, 04/03/14,

Add N-EVENT-REPORT content

jwhitby2, 04/02/14,

Need to define attribute for event types? It should be clear from content of the messages.

jwhitby2, 04/02/14,

WS messages are not HTTP messages. Uncertain how much detail is needed.

jwhitby2, 04/02/14,


jwhitby2, 04/03/14,

Websockets have no standardized content negotiation. Server could record preferred format along with other subscriber details and always send that format or we could fix it to one format. Client could change formats by calling this endpoint again


}

66

600

Digital Imaging and Communications in Medicine...

Documents

Transcript of Digital Imaging and Communications in Medicine...