Embed Size (px)
DESCRIPTION
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
Citation preview
DICOMwebTM 2015 Conference &Hands-on WorkshopUniversity of Pennsylvania, Philadelphia, PASeptember 10-11, 2015
DICOMweb Workflow API(UPS-RS)
Jonathan WhitbyVital, a Toshiba Medical Systems Group CompanyProduct 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 CC 2
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.9 3
UPS-RS Core Services
DICOM PS 3.18 Table 6.9-1 4
Action Type Method & ResourceCreate Workitem POST {+SERVICE}/workitems{?InstanceUID}
Change Workitem State PUT {+SERVICE}/workitems/{InstanceUID}/state
Update Workitem POST {+SERVICE}/workitems/{InstanceUID}{?transaction}
Search For Workitem GET {+SERVICE}/workitems{?query*}
Retrieve Workitem GET {+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
• Relationship Module
• other entities to which the Workitem is related (
• Patients
• Orders
• …
6
Scheduled Procedure Information Module
• 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
• Progress Information Module
• current state of the Workitem
• reason for cancellation • if cancelled
8
Performed Procedure Information Module
• 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 6.9-1 16
Action Type Method & Resource
Create Subscription POST {+SERVICE}/workitems/{UID}/subscribers/{AETitle}{?deletionlock,query*}
Delete Subscription DELETE {+SERVICE}/workitems/{UID}/subscribers/{AETitle}
Suspend GlobalSubscription
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 slide 18
Global Subscriptions
• A user agent can subscribe to a global worklist with a specified UID• 1.2.840.10008.5.1.4.34.5 – Global Worklist• 1.2.840.10008.5.1.4.34.5.1 – 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 worklist19
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 slide 20
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 details 24
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 progress 25
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
StudiesOrigin Server
CardiacApplication
WorklistOrigin Server
1. NADO-RS notification – new Study created
2. Create Workitem 3. Notification – Workitem created4.Notification – Input Data ready
5. Change Workitem State – In Progress6. Retrieve Workitem
9. Update Workitem10. Change Workitem State -- Complete
7. WADO-RS – Retrieve Study
8. STOW-RS – Store Instances
11. Notification – Workitem complete
Workflow manager creates Workitem
*in the future 29
• 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 = http://dicomweb.somehospital.org/studies/1.2.3.4
Cardiac application subscribes to Workitems
*in the future 30
• 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 future 31
• 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 future 32
• After claiming the Workitem, the cardiac application will:
• Retrieve Workitem (6)
• Parse the Workitem details
Cardiac application performs Workitem
*in the future 33
• 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 future 34
• 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
