RIS Integration

XML-RPC Protocol

In OsiriX, we introduced a very easy and powerful protocol for such control. OsiriX integrates an HTTP server with an XML-RPC protocol. It means that any software/computer that knows the network address of the OsiriX workstation can execute methods in OsiriX. These methods can be built-in OsiriX or added in plugins. To turn the XML-RPC HTTP server, go to the Listener Preferences window in OsiriX. This interface is compatible with POST (standard XML-RPC protocol) and GET http requests (URL query string).

“osirix://” URL Scheme

OsiriX also handles a specific protocol for such control: the “osirix://” URL scheme. With this custom URL interface, your web browser can execute orders in OsiriX. The limitation, compared to XML-RPC, is that you cannot get an answer from OsiriX. For example the DBWindowFind method (see bellow) cannot return the corresponding elements. The other limitation is that this URL is only supported locally: a web browser can only start and control the installed OsiriX, running on the same computer. That means you cannot use the “osirix://” URL scheme to send a message from a server to a distant OsiriX. But the server can display an HTML page on the client computer, and the user can click on an “osirix://” enabled link to execute an action.

Supported Messages

For now, only a few basic messages are supported. If you need more, write a simple XML-RPC plugin (see below). If you think that your plugin source code should be included in OsiriX, contact us.

• Method: Retrieve
  • Parameters:
    • serverName (mandatory): Server name, as displayed in Preferences->Locations
    • filterKey (mandatory): DICOM field, such as ‘PatientID’, ‘AccessionNumber’, …
    • filterValue (mandatory): Searched value, such as ‘296228’, ‘A1288372’, …
    • then (optional): ‘open’ or ‘select’
    • retrieveOnlyIfNeeded (optional): test if all images are already available
  • Example:
    • serverName: "MainPACS"
    • filterKey: "PatientID"
    • filterValue: "296228"
    • then: "display"
    • retrieveOnlyIfNeeded: "yes"
  • Another Example in XML
  • Response: error: "0"
• Method: DisplayStudy
  • Parameters: (requires at least one parameter)
    • patientID: DICOM field “PatientID” (0010,0020)
    • studyInstanceUID: DICOM field “StudyInstanceUID” (0020,000d)
    • accessionNumber: DICOM field “AccessionNumber” (0008,0050)
    • studyID: DICOM field “StudyID” (0020,0010)
  • Example:
    • patientID: "290302"
    • studyInstanceUID: "2.16.840.1.113669.632.20.121711.10000493369"
  • Response: error: "0"
• Method: DBWindowFind
  • Parameters:
    • request: SQL request, see “Predicate Format String Syntax” from Apple’s documentation.
    • table: one of OsiriX’s database table (Image, Series or Study).
    • execute: Nothing, Select, Open or Delete. (Note: execute is performed at the study level. You cannot delete a single series of a study.)
  • Example:
    • request: "name == 'OsiriX'"
    • table: "Study"
    • execute: "Select"
  • Example:
    • request: "(name LIKE '*OSIRIX*')"
    • table: "Study"
    • execute: "Open"
  • Response: error: "0", elements: ... where elements is an array of elements corresponding to the request.
• Method: DownloadURL
  • Parameters:
    • URL: the URL of the file to download. Currently only zip files or DICOM files are supported.
    • Display: a boolean value, indicating if the study has to be selected and opened, after the download is complete. This parameter is optional.
  • Example: URL: "http://www.myserver.com/dicomfile.dcm"
  • Example: URL: "http://www.myserver.com/dicomfile.dcm", Display: "YES"
  • Response: error: "0"
• Method: CloseAllWindows
  • No Parameters
  • Response: error: "0"
• Method: OpenDB
  • Parameter:
    • path: path of the folder containing the “OsiriX Data” folder. If path is valid, but no database is found, OsiriX will create a new one.
  • Example: path: "/Users/USERNAME/Documents/"
  • Response: error: "0"
• Method: SelectAlbum
  • Parameter:
    • name: name of the album.
  • Example: name: "Today"
  • Response: error: "0"
• Method: GetDisplayed2DViewerSeries
  • No Parameters
  • Response: error: "0", elements: ... where elements is an array of series corresponding to displayed windows.
• Method: GetDisplayed2DViewerStudies
  • No Parameters
  • Response: error: "0", elements: ... where elements is an array of studies corresponding to displayed windows.
• Method: Close2DViewerWithSeriesUID
  • Parameter:
    • uid: Series Instance UID to close.
  • Example: uid: "1.3.12.2.1107.5.1.4.51988.4.0.1164229612882469"
  • Response: error: "0"
• Method: Close2DViewerWithStudyUID
  • Parameter:
    • uid: Study Instance UID to close.
  • Example: uid: "1.2.840.113745.101000.1008000.37915.4331.5559218"
  • Response: error: "0"

XML Format

You need to send these messages in XML format: for example Close2DViewerWithStudyUID, with parameters: uid: "1.2.840.113745.101000.1008000.37915.4331.5559218" corresponds in XML to:

<?xml version="1.0"?>
<methodCall>
<methodName>Close2DViewerWithStudyUID</methodName>
<params><param><value><struct><member>
<name>uid</name>
<value>
<string>1.2.840.113745.101000.1008000.37915.4331.5559218</string>
</value>
</member></struct></value></param></params>
</methodCall>

If you send non-ASCII characters (like é, ç ä, …), use UTF-8 encoding:

<?xml version="1.0" encoding="UTF-8"?>

URL Query String Messages

You can also use all the XML-RPC methods with the “osirix://” URL scheme or the XML-RPC http server, with standard URL query strings:

For example, you can do:

• osirix://?methodName=displayStudy&PatientID=123819
• http://localhost:8080/?methodName=displayStudy&AccessionNumber=A23123819
• osirix://?methodName=displayStudy&StudyInstanceUID=1.2.8540.54.5.143.541
• osirix://?methodName=downloadURL&URL='http://www.myserver.com/dicomfile.dcm'
• osirix://?methodName=retrieve&serverName=Minipacs&filterKey=PatientID&filterValue=296228
• http://192.168.1.45:8080/?methodName=retrieve&serverName=Minipacs&filterKey=PatientID&filterValue=296228
• osirix://?methodName=findObject&request=(name CONTAINS[cd] 'KNEE')&table=Study&execute=Open

To test this URL scheme, launch OsiriX and clic on this link: osirix://?methodName=KillOsiriX (this should close the OsiriX Application on your Mac).

These messages are executed locally. You cannot execute an URL scheme on a distant computer.

Adding custom XML-RPC methods

If you need to add specific functions and behavior in OsiriX for your XML-RPC messages, you can write a simple plugin. Thanks to the XML support in Cocoa (NSXMLDocument), it is very easy to add your own methods in OsiriX.

An example plugin called XML-RPC-Plugin is available in the OsiriX Plugins git repository. In this plugin, two new messages are added to OsiriX:

• exportSelectedToPath
  • path:"/Users/USERNAME/Desktop/"
• openSelectedWithTiling
  • rowsTiling:2, columnsTiling:2

As you see in the source code, a unique plugin can support multiples messages and parameters decoding is easy.

Sending an XML-RPC Message

To test a XML-RPC message from a file, use curl tool from the Terminal to send a POST http message to OsiriX:

$ curl -d @/Users/USERNAME/Desktop/test.xml "http://localhost:8080"