Developing XNAT Plugins

XNAT supports customizing and extending its functionality through the use of plugins. A plugin is a compiled, self-contained package separate from your XNAT server but installed into the XNAT plugins folder. Once installed, the plugin runs in the same process space with XNAT as a fully integrated extension to the core XNAT server. The XNAT plugin framework gives you the tools to:

• Add and configure XNAT data types

• Create new user interface elements or extend existing ones

• Create new services

• Store service and plugin preferences

• Create HTML-free configuration and administration interfaces

• Provide REST API access to plugin services and settings

This documentation provides technical instruction and reference for working with the XNAT plugin framework, including:

Creating a plugin project

This section describes the build files and infrastructure required for an XNAT plugin project.

Defining plugin metadata

Plugin metadata helps XNAT load your plugin when it starts up, as well as initialize and use any data models, services, and any other resources in your plugin package.

Creating and configuring data types

XNAT data types provide the framework for XNAT's primary domain model. This includes representations of medical imaging sessions, research subjects, clinical assessment instruments, and so on.

Adding services and scheduled tasks

Services and scheduled tasks are the main way you can manage your custom data in the system, storing it in XNAT's archive and database, and maintaining and synchronizing data across the system.

Managing service and feature preferences, including HTML-free configuration interfaces

Most services require some amount of configuration to allow users to adapt and tune the system to the requirements for their particular deployment and usage context. The XNAT preferences system provides an easy and intuitive way to create and maintain preference class implementations without having to deal with lots of database configuration and schema development.

Adding Configurable Settings for your Plugin to the Admin UI or Project Settings

Your plugin may want to expose features and configurations to your site admins or project owners, so they can set their own values. Or, in the case of the Container Service Plugin plugin, an Admin UI may be required to pull additional functionality into your XNAT.

Creating REST APIs

Working with user interface elements, including overriding default elements and adding new ones

Creating data models and writing software services is not very useful if you can't also interact with your target users. The XNAT plugin framework provides a number of ways to add UI elements to the application, inject elements into existing pages, and even override the functionality of default XNAT UI elements.

UI elements that control settings for your plugin can be automatically injected into specific areas in XNAT. As of this writing, you can add site- and project-level settings for your plugin using the Spawner service and widget library. By creating specially-named YAML files and adding them to a folder in your plugin, XNAT will find these files, parse them, and display a UI to control your plugin's parameters. Basic user interfaces can be very easily configured – more advanced interfaces may still require custom HTML and/or JavaScript. Spawner widgets work best with back-end services that accept and return JSON data – form values can be easily populated from saved data, and submitted just as easily. Configuring your plugin's back-end services to conform to this format is recommended, but not required.

Advanced: Adding a Custom Importer & Session Builder via a Plugin

It is possible for plugin developers to customize image import methods by coding up a custom importer and session builder.

Deploying Plugins in XNAT

You could write the most extraordinary plugin for XNAT ever, but if you can't get the plugin where it needs to be no one will ever know. Deploying new plugins and updating your existing plugins are the final tasks in delivering your functionality to your users.

Much of the information in this documentation requires at least some knowledge of the Java programming language, as well as some familiarity with building and deploying Java libraries. There are some tasks that can be accomplished with little or no programming knowledge and using only common tools like zip and a text editor. Over the next few months, we will add descriptions of these tasks, as well as technical references and explanations to help non-programmers create workable plugins with a minimal investment of effort.

Until then, we will add explanations, glossary entries, and pointers to resources to explain technical subjects that may not be easily described in the flow of the documentation. Keep your eye out for footnotes

and call-out boxes that may provide more information.