DICOMwebTM 2015 Conference & Hands-on Workshop University of Pennsylvania, Philadelphia, PA September 10-11, 2015 DICOMweb Workflow API (UPS-RS) Jonathan Whitby Vital, a Toshiba Medical Systems Group Company Product Manager

UPS Overview DICOM Unified Procedure Step (UPS) is a set of services for managing Workitems A Workitem is a unit of work related to medical imaging: Reporting on a Study (imaging exam) Creating 3D models for a Study … UPS also includes a notification service for tracking progress of Workitems Workflow logic – when you should create certain types of Workitems – is out of scope UPS is described in DICOM PS 3.4 Section CC2

UPS-RS Overview UPS-RS is a set of RESTful web services for managing DICOM Workitems UPS-RS can be proxied to UPS and vice-versa An origin server could allow a common set of Workitems to be managed by either interface All payloads can be either DICOM XML or DICOM JSON For notification, UPS-RS uses Websockets UPS-RS is described in DICOM PS 3.18 Section 6.93

UPS-RS Core Services DICOM PS 3.18 Table Action TypeMethod & Resource Create WorkitemPOST {+SERVICE}/workitems{?InstanceUID} Change Workitem StatePUT {+SERVICE}/workitems/{InstanceUID}/state Update WorkitemPOST {+SERVICE}/workitems/{InstanceUID}{?transaction} Search For WorkitemGET {+SERVICE}/workitems{?query*} Retrieve WorkitemGET {+SERVICE}/workitems/{InstanceUID} Request Workitem Cancellation POST {+SERVICE}/workitems/{InstanceUID}/cancelrequest

Contents of a Workitem A Workitem includes four key modules: Relationship Module Scheduled Procedure Information Module Progress Information Module Performed Procedure Information Module Different UPS-RS services affect different Workitem modules 5

Relationship Module other entities to which the Workitem is related ( Patients Orders … 6

Scheduled Procedure Information Module work to be performed input data by reference (e.g. WADO-RS URL) type of device or user to perform the Workitem 7

Progress Information Module current state of the Workitem reason for cancellation if cancelled 8

Performed Procedure Information Module work actually performed output data (by reference) 9

Create Workitem POST {+SERVICE}/workitems{?InstanceUID} Requests the creation of a Workitem Sets Relationship and Scheduled Procedure Information Modules Sets Progress to “SCHEDULED” Returns the URL of the created Workitem 10

Set Workitem State PUT {+SERVICE}/workitems/{InstanceUID}/state Sets the state of a Workitem Setting to “IN PROGRESS” claims a Workitem Specifies a transaction parameter, which acts as a lock on the Workitem If a Workitem is “IN PROGRESS”, a transaction parameter must be specified in order to modify the state The requirements of a Workitem should be completed before setting it to “COMPLETE” 11

Update Workitem POST {+SERVICE}/workitems/{InstanceUID}{?transaction} Updates a Workitem Progress information Work performed Cannot be used to change the state / claim a Workitem Change Workitem State is used instead The transaction parameter must be specified If a Workitem is “IN PROGRESS” 12

Search for Workitems GET {+SERVICE}/workitems{?query*} Searches for Workitems matching specified query parameters Patient information Type of work Device or device type to perform work User or user group to perform work … All origin servers must support a default set of parameters but may support others Search results include a subset of the metadata for each matching Workitem 13

Retrieve Workitem GET {+SERVICE}/workitems/{InstanceUID} Retrieves a specific Workitem Includes all metadata for the Workitem (except the Transaction UID) 14

Request Workitem Cancellation POST {+SERVICE}/workitems/{InstanceUID}/cancelrequest Requests the cancellation of a specific Workitem and the reason for the request Only applies to an “IN PROGRESS” Workitem Used by a device that is not in control of the Workitem Request passed on to device in control of Workitem via notification 15

UPS-RS Subscription Services DICOM PS 3.18 Table Action TypeMethod & Resource Create SubscriptionPOST {+SERVICE}/workitems/{UID}/subscribers/{AETitle} {?deletionlock,query*} Delete SubscriptionDELETE {+SERVICE}/workitems/{UID}/subscribers/{AETitle} Suspend Global Subscription POST {+SERVICE}/workitems/{UID}/subscribers/{AETitle} /suspend Open Event Channel {+WSSERVICE}/subscribers/{AETitle}

Subscription and Notification To receive Workitem notifications, a user agent must: Subscribe to a Workitem (or a set of Workitems) Open a Websockets channel to receive notifications Any change to a Workitem results in a notification 17

Create Subscription POST {+SERVICE}/workitems/{UID}/subscribers/{AETitle} {?deletionlock,query*} Subscribes to the specified Workitem (or global worklist*) Returns the URL of the Websockets service The deletionlock parameter requests a deletion lock on the Workitem in addition to a subscription The AETitle is an identifier for the user agent Used again when opening the Websockets channel The query parameters only apply to global worklists* * See next slide18

Global Subscriptions A user agent can subscribe to a global worklist with a specified UID – Global Worklist – Filtered Global Worklist The Global Worklist is used to subscribe a user agent to all current and future Workitems The Filters Global Worklist is used to subscribe a user agent to all current and future Workitems that match the query parameters in the request Query parameters are the same as Search for Workitem query parameters Each AETitle can only have one subscription to each global worklist 19

Delete Subscription DELETE {+SERVICE}/workitems/{UID}/subscribers/{AETitle} Deletes a subscription to the specified Workitem (or global worklist*) No further notifications will be received Deletion locks will be released Also used to unsubscribe from global worklists Will also unsubscribe from all subscribed Workitems * See next slide20

Suspend Global Subscription POST {+SERVICE}/workitems/{UID}/subscribers/{AETitle}/suspend Stops the user agent from being automatically subscribed to future Workitems Does not unsubscribe the user agent from any existing Workitems Only applies to the global worklists 21

Notification Overview All notifications will be sent using the open channel Notifications generally not queued if channel is not open they are missed A user agent can open multiple channels with different AETitles For example, to have multiple filtered worklist subscriptions All information sent via notification can also be retrieved through polling using Search For Workitems or Retrieve Workitem endpoints 22

Open Event Channel {+WSSERVICE}/subscribers/{AETitle} Opens Websockets notification channel for specified AETitle Websockets URL returned by subscription request 23

Notification Content Notifications sent using Websockets data frames opcode of “%x1” (text) Payload is a DICOM JSON object containing the notification details No XML option See IETF RFC 6455 for Websockets protocol details24

Summary UPS-RS provides REST APIs for managing Workitems Largely following the same model as Studies services (WADO-RS, QIDO-RS, STOW-RS) UPS-RS also defines a subscription and notification service for Workitems Currently not used by Studies services But will be!* Enables workflow collaboration between different imaging systems Both web-based applications and conventional DICOM devices *NADO-RS service in progress25

Questions? 26

UPS-RS Example 27 Scenario: An imaging department wants to make sure that cardiac functional analysis is performed on all multiphase cardiac CTs A workflow manager monitors Study creation and creates workitems based on the Study metadata A cardiac application monitors the worklist for workitems it can perform

UPS-RS Example 28

Workflow manager creates Workitem *in the future29 The workflow manager monitors Study creation (1) Means of doing this outside of UPS-RS scope but could use QIDO-RS or NADO-RS* When a matching Study is created, the workflow manager creates a Workitem (2): Status = Scheduled Priority = Normal Patient = FRANKLIN^BENJAMIN Label = CT CARDIAC FUNCTIONAL ANALYSIS Workitem Code = (1123, X23, CT Cardiac Functional Analysis) Station Class = Cardiac Analysis Application Input Readiness = READY Input WADO-RS URL =

Cardiac application subscribes to Workitems *in the future30 The cardiac application subscribes to the Filtered Global Worklist with the following parameters: Station Class = Cardiac Analysis Application It will receive a Websockets notification whenever a Workitem matching those parameters is created or updated (3) It will ignore these Workitems until a notification indicates that the Input Readiness attribute has been set to Ready (4)

Cardiac application claims Workitem *in the future31 Once the input data is available, the cardiac application will: Change Workitem State to “IN PROGRESS” (5) Sets a Transaction UID Other cardiac applications on the network can no longer work on the Workitem

Cardiac application retrieves Workitem *in the future32 After claiming the Workitem, the cardiac application will: Retrieve Workitem (6) Parse the Workitem details

Cardiac application performs Workitem *in the future33 After retrieving the Workitem, the cardiac application will: Retrieve the imaging data via WADO-RS (7) Perform the analysis and create additional DICOM instances Store the DICOM instances via STOW-RS (8) Update Workitem with the following information (9): Progress (now complete) Work performed Output information (WADO-RS URL)

Cardiac application completes Workitem *in the future34 After completing the work, the cardiac application will: Change Workitem State to “COMPLETE” (10)

Additional workflow manager tasks After the Workitem has been completed, the workflow manager will receive a notification (11). It may create additional Workitems, such as: Report on the Study Export the Study to DVD … 35

Questions? 36

Author Contacts Jonathan Whitby Vital 37 Thank you for your attention!