Image Viewer > Advanced Viewing > External Applications

It is sometimes useful to pass information about the currently viewed images to an external application. The external might be a report generator you want to pass some simple DICOM attributes to like Patient ID or Study ID, or it may be another DICOM viewer application to which you might want to pass the filenames of the selected images. The External Applications feature allows you to define a number of these externals for your convenience without having to find and copy the information manually.

Defining an External

External applications can be defined from its page in the options dialog:

1.	In the main menu, select Tools > Options > External Applications.

2.	Click on the Add New External button and select the way your external application takes input information. Currently, the standard installation only has support for a command line based external application. Screenshot

Fill in the details of your external application such as its name (which will be used in the context menu) and, in the case of a command line based external, the path to the executable or command and any arguments that it needs. You can use certain special fields when defining these parameters.

Technical Notes

•	The types of externals are extensible, and a software programmer can easily create custom plugins to support other ways of interacting with external applications.

4.	Click OK on the external dialog to create an entry for the external application. Screenshot

5.	You can make further modifications to the definition by clicking the Edit External button, or delete it entirely by clicking Remove External. Changes are only saved when the options dialog is closed by clicking Apply or OK.

Using Special Fields with Externals

Most external applications will need to know something about the images, whether it is simply the image's filename or the value of a particular DICOM attribute. These special fields are represented by including $FIELDNAME$ in the command path, working directory or argument text boxes. The appropriate value will then be inserted in place of the $FIELDNAME$ when you launch the external. If you launch the external with more than one file, the values from individual files will all be included, separated by the specified separator.

There are five predefined special fields available:

Field	Description
$FILENAME$	The complete path to the image, such as "C:\datastore\image.dcm"
$FILENAMEONLY$	The filename of the image, such as "image.dcm"
$DIRECTORY$	The directory where the image is located, such as "C:\datastore"
$EXTENSIONONLY$	The extension of the image, such as "dcm"
$$	A literal '$' character

To insert the value of a particular DICOM attribute, use $ggggeeee$ where (gggg,eeee) is the desired DICOM tag. For example, to insert the value of the Study ID (0020,0010) attribute, you would use the field $00200010$.

Additionally, you may use environment variables such as %USERPROFILE%, which will cause the corresponding environment variable to be inserted in its place (in the case of %USERPROFILE%, your Windows user home directory). The names and values of these environment variables are defined in the operating system. For a full list of environment variables and instructions on how to edit them, please consult your operating system user's guide (or look it up on your favourite search engine). To insert a literal '%' character, use %%.

For your convenience, a quick reference cheat sheet can be accessed in the external configuration dialog.

Important Note

•	Please be extra vigilant when passing patient information to an external application. ClearCanvas Workstation does not have any control over the external applications launched and you can potentially leave confidential patient information exposed even after you close the Workstation.

•	Environment variables are always expanded before special fields. Thus, inserting an environment variable with the value "$FILENAME$" will become "C:\datastore\image.dcm", whereas inserting a DICOM attribute containing the value "%USERPROFILE%" will remain simply "%USERPROFILE%".

Launching an External

To launch an external, simply right click any image in the image viewer and select the item on the context menu under Externals.

The selected external application is then launched with the defined arguments. In this example, the Acme DICOM Viewer took the filename of the image as a command line argument, and opened it for display.

The list of available externals may change depending on what information the external requires. For example, if the external does not support multiple images, then the option to open the entire display set with the external will not be available. If the external takes filenames as input and the image is not locally stored (i.e. the image is streamed from an installation of ClearCanvas ImageServer with streaming support) then the external will not be available. An external will only appear on the list if all its requested arguments can be provided by the selected image(s).