Working with Modules

You can also review the Extending and Customizing XNAT with Modules presentation from the XNAT Workshop 2012.

The ability to package XNAT customizations into modules, along with the XNAT Marketplace and freely available XNAT modules developed by the XNAT community at large, is one of the major enhancements of the XNAT 1.6 release. This section describes how to extend your XNAT installation:

  • Download and deploy modules from the XNAT Marketplace
  • Create custom behavior with your own XNAT modules
  • Give back to the XNAT community by contributing modules to the XNAT Marketplace

Why Modules?

Modules are a bridge between the existing XNAT customization capabilities and a future plugin architecture. Although modules do have the restriction of not being separable from your XNAT application once the application's been deployed, they have the advantage that they can be easily separated into separate functional groups, instead of needing to be pushed together into the previous projects folder format. This allows you to put all of your XNAT customizations into modules, place the module archives into the modules repository specified in your file, and run setup or update. This is a much cleaner separation of functionality and allows for easier exchange of data types, service enhancements, and so on.

Sources For Modules

There are two primary sources for XNAT modules at this time:

Deploying Modules

The task of deploying a module is relatively straightforward and doesn't change based on the source of the module. That is, you can:

In any case, however you get a module, you start out with two things: a module archive and a module repository folder.

The contents and structure of module archives are described in more detail in the developer documentation and are mostly irrelevant to the deployment process. For purposes of describing how to deploy a module, we'll assume that the contents are properly packaged and you've just got your single module archive.

The module archive can be either a jar or zip file. You'll specify the location of your module repository folder with the xdat.modules.location property in your file. The only requirement for this folder is that it be accessible during the build process. On Unix-based systems, this means that the permissions must be properly set so that the build user can access the contents of the folder. This includes both the folder permissions and the permissions on each of the module archives in the folder.

Unlike previous versions of XNAT, you can process module-based customizations even during setup.

Once you have a module archive, you can deploy it by following this procedure:

  1. Stop your Tomcat server if it's currently running.
  2. Copy or move your module archive into the module repository folder.
  3. Change your working directory to your XNAT builder folder.
  4. Set up or update your XNAT installation.
  5. If any of your modules add new data types or modify existing data types, you'll need to update your database schema as well.
  6. Re-start Tomcat.

That's all you need to do as far as getting the code into your XNAT installation. Depending on the type of customization you added, you may need to perform some administrative tasks to make the customization available. Most significantly, if you added a new data type, you'll need to add the data type to the system and configure the security settings for it.