Page tree
Skip to end of metadata
Go to start of metadata

XNAT can be configured to send automated notifications on system events to a series of email address of your choice. It also provides multiple mechanisms for allowing you to alert XNAT users.

Developer Note

This functionality has been overhauled in XNAT 1.7 and now uses the XAPI notifications api. You can find additional documentation and working examples of this in the Swagger XAPI browser embedded in your XNAT application by going to Administer > Site Administration > Miscellaneous > View Swagger

 

Notifications Prerequisite: Configure the XNAT Email Server

In order to send any automated or manual notifications, SMTP must be enabled in your XNAT and the XNAT Email Server must be properly configured. These settings can be updated at Administer > Site Administration > Email Server. Contact your local network administrator if you are not sure which settings to use here.

Managing Automated Notifications

When you go through your initial site setup, you are asked to provide an administrative contact email. This email is then used as the default contact method for all XNAT notifications. However, you can easily split this up into multiple emails for various system events if you prefer, using the Admin UI. Go to Administer > Site Administration > Notifications to begin.

You can also edit your Admin contact email at Administer > Site Administration > Site Setup.

System Event Contacts

By default, XNAT will allow you to specify any email address as recipients of notifications, including non-users. You can limit these email address to those of registered users by setting "Allow Non-user Subscribers" to FALSE on the Notifications Admin page.

EventDescription
Help Contact InfoThe email address provided will be the recipient of any user query sent through the contact form located in the Help > Report An Issue page. It will also be listed as a contact in emails sent to users on various error conditions. It is recommended that this email address be monitored by a real person, and not an auto-response agent.
Error MessagesThis is not currently used by default in XNAT, but data processing scripts and pipelines could be configured to send error messages to the listed email address.
Issue ReportsThis is not currently used by default in XNAT, but new plugins, scripts or pipelines could be configured to send issue reports to the listed email address.
New User AlertThis is not currently used by default in XNAT, but a future release will send new user registration notifications to this email address. Currently, these notifications are sent to the primary site admin email address.
UpdatesThis is not currently used by default in XNAT, but new plugins, scripts or pipelines could be configured to send update reports to the listed email address.

 

Editing Default Email Messages

The Notifications Admin page allows you to edit the default email messages sent to users on new user registration events, or on user "forgot username" or "forgot password" events. Please note that these system emails are configured to use a series of shortcodes, or strings that will be replaced with system values.

Shortcode Reference

ShortcodeReplacement Value
SITE_NAMEYour XNAT's site name, which is set in Administer > Site Administration > Site Setup
SITE_URLYour XNAT's URL, which is set in Administer > Site Administration > Site Setup
USER_USERNAMEThe username or login of the registered user, which is unique and set by the user
USER_FIRSTNAMEThe first name provided by the registered user. This can be edited by the user in their profile, or by the site administrator in Administer > Users
USER_LASTNAMEThe last name provided by the registered user. This can be edited by the user in their profile, or by the site administrator in Administer > Users
ADMIN_EMAILThe primary XNAT administration contact email, which is set in Site Administration > Site Setup
HELP_EMAILThe Help Contact Info email specified above

 

Editing Password Reset Emails

The email that is sent to users who request a password reset has a unique shortcode in it that must be included: RESET_URL. This shortcode will be replaced with the URL the user should go to in order to reset their password. The link includes a newly created token that is only good for one use. This token will expire after the amount of time specified in XNAT Security Settings > User Logins/Session Controls > Alias Token Timeout.

 

Sending Custom Notifications to Users via Email

This UI will be updated in a future release of XNAT 1.7, and these documents will be updated accordingly.

XNAT provides a bare-bones interface for sending email alerts to one or more registered users. This can be accessed at Administer > Send Email. Please note that SMTP must be activated and the XNAT Email server must be configured for this interface to work. See above for info.

 

Creating Site-wide Alerts

Email alerts are not always effective at immediately notifying users of system conditions or upcoming events such as an IT maintenance window, as it relies on users to (A) check their email, and (B) remember what that email said in the wake of a dozen other daily priorities that can come up. If you have a high-priority message that all users of your XNAT should see, we recommend creating a site-wide notification. Go to Administer > Site Administration > Site Setup and scroll down to Site-wide Alerts.

Settings

SettingProperty NameDescription
Enable Alert Message

siteWideAlertStatus

Toggles between three possible settings:

  • "0": Off
  • "1": On, displaying only on the login page
  • "2": On, displaying on login page and site header
Alert Message

siteWideAlertMessage

Message text. Can be plaintext or HTML.
Alert Type

siteWideAlertType

Toggles between three alert types:

  • "Message": Used for non-urgent informational alerts, such as to notify users of a new feature
  • "Alert": Used for urgent informational alerts, such as to notify users of a scheduled outage
  • "Error": Used to notify users of unexpected errors, such as unscheduled downtime or an outage of a related service, such as pipeline processing

Only one site-wide alert can be set up at one time, and it can be positioned in two different places: On the Login Page, and/or in the top navigation section of each page in the site.

The alert message area can accept simple HTML tags such as <a> or <strong> to allow you to add links or emphasis tags. You can also specify an alert type, which will affect the display of the message and its apparent urgency.

If you use HTML, please close your tags properly or you can introduce some unexpected and ugly behavior in the UI.

Viewing Site-wide Alerts on the Login Page

Viewing Site-wide Alerts in the Site Header