OsiriX is a DICOM Viewer, aka PACS Workstation, but it is not a HIS or a RIS software. If you have such software installed, it can be useful to ‘control’ OsiriX or ‘get’ informations from/to another application:
This application should be able to control OsiriX to facilitate the integration. For example, the other application should be able to:
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 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.
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.
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"?>
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:
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.
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:
As you see in the source code, a unique plugin can support multiples messages and parameters decoding is easy.
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"