Notifications and Alerts in XNAT

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 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 when a variety of situations occur within your Xnat. These events are outlined below along with a list of the shortcuts used to configure the message (outlined in more detail below):

EventDescription
User RegistrationThe email message sent to users upon their registration. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, USER_USERNAME, SITE_NAME, SITE_LINK, ADMIN_MAIL_LINK
Forgot UsernameThe email message sent to a user's email address when they have lost their username. Shortcuts: USER_USERNAME, SITE_LINK
Forgot PasswordThe email message sent to a user's email address when they have forgotten their password. This email will be sent with a password reset link to allow the user to input a new password. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, RESET_LINK
New User VerificationThe email message sent to a newly registered user's email to verify the newly created account. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, VERIFY_URL, FORGOT_LOGIN_URL

Project Access Request

The email message sent out to project owners when a user requests access to their project. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, USER_USERNAME, USER_EMAIL, PROJECT_NAME, SITE_NAME, SITE_LINK, RQ_ACCESS_LEVEL, LIST_PERMISSIONS, ACCESS_URL, ADMIN_MAIL_LINK
Project Access ApprovalThe email message sent out to a user when their request for project access has been accepted. Shortcuts: PROJECT_NAME, SITE_NAME, SITE_LINK, RQ_ACCESS_LEVEL, ACCESS_URL, ADMIN_MAIL_LINK
Project Access DenialThe email message sent out to a user when their request for project access has been denied. Shortcuts: PROJECT_NAME, SITE_NAME, SITE_LINK, USER_EMAIL, ADMIN_MAIL_LINK
Project Access InvitationThe email message sent out to a user when they have been invited to join a project. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, PROJECT_NAME, SITE_NAME, SITE_LINK, ADMIN_MAIL_LINK, ACCEPT_URL
Disabled User VerificationThe email message sent out when a previously disabled user account is verified and reactivated. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, USER_USERNAME, USER_LOGIN, SITE_NAME, SITE_LINK, DATE_INPUT, LOGIN_URL
Error MessageThe email message sent out to site administrators when an error has occurred within the system. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, USER_LOGIN, SITE_LINK, ERROR_TIME, ERROR_MESSAGE
New User NotificationThe email message sent out when a new user account registration has been created. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, USER_USERNAME, SITE_NAME, SITE_LINK, USER_EMAIL, USER_PHONE, LAB_NAME, TIME, PROJECT_ACCESS_REQUESTS, REVIEW_LINK, USER_COMMENTS
New User RequestThe email message sent out when a new user account is created but has not yet been enabled. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, USER_USERNAME, SITE_NAME, SITE_LINK, USER_EMAIL, USER_PHONE, LAB_NAME, TIME, PROJECT_ACCESS_REQUESTS, REVIEW_LINK, USER_COMMENTS
Pipeline SuccessThe email message sent out when an experiment pipeline has completed successfully without errors. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, PIPELINE_NAME, EXPERIMENT_NAME, SUCCESS_URL, SITE_NAME
Pipeline FailureThe email message sent out when an experiment pipeline has failed before completion due to an error. Shortcuts: PROJECT_NAME, PIPELINE_NAME, EXPERIMENT_NAME, PIPELINE_STEP, SITE_NAME, CONTACT_EMAIL, ATTACHMENTS_STATEMENT, STDOUT, STDERR
Autorun Pipeline SuccessThe email message sent out to the user when the autorun pipeline field is enabled in Xnat and the automatically run pipeline completes successfully. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, SITE_NAME, PROJECT_NAME, SUBJECT_NAME, EXPERIMENT_NAME, SUCCESS_URL
Batch Transfer CompleteThe email message sent to the initiating user when a batch data transfer to the archive has been successfully completed. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, SITE_NAME, SITE_LINK, ADMIN_MAIL_LINK, PROCESS_NAME, NUMBER_MESSAGES, MESSAGES_LIST, ERRORS_LIST
Unauthorized Data AttemptThe email message sent when one of a several types of unauthorized data or login access attempts are recognized by the system. Shortcuts: TYPE, USER_DETAILS
Email Change RequestThe email message sent to alert a user that someone has requested to change the email for the account which is currently associated with the recipient email address. Shortcuts: USER_USERNAME, NEW_EMAIL, ADMIN_MAIL_LINK
Verify Email Change RequestThe email message sent out to verify a change of email address when one has been requested by the user within the Xnat system. Shortcuts: USER_USERNAME, CHANGE_EMAIL_LINK
Email Address Change SuccessfulText of the email message sent to both the original and new email address associated with a user account to alert both that the email address for that account has been successfully changed. Shortcuts: NEW_EMAIL
System Path ErrorThe email message sent to the site admin when Xnat is unable to find the file system (e.g. archive, build, prearchive directories). Shortcuts: ERRORS_LIST
Upload By Reference SuccessThe email message sent when a user has uploaded a file or files to the system by reference successfully. Shortcuts: USER_USERNAME, DUPLICATES_LIST
Upload By Reference FailureThe email sent when a user's upload by reference attempt has failed. Shortcuts: USER_USERNAME
Data AlertThe email message sent from one user to another to alert each other about possibly useful data within their Xnat. Shortcuts: USER_FIRSTNAME, USER_LASTNAME, SITE_NAME, SITE_LINK, REQUEST_LINK, SENDER_MESSAGE, TIME_SENT, HELP_CONTACT


System emails are configured using a set of shortcodes which will allow for the emails to be customized both to your Xnat site as well as to the recipient of the email itself. These shortcuts are listed below and the shortcuts related to a specific email message can be seen above.

Shortcode Reference

ShortcodeReplacement Value
SITE_NAMEYour XNAT's site name, which is set in Administer > Site Administration > Site Setup.
SITE_URLA link to your Xnat site, the url of 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.
USER_LOGINThe login information for the user.
USER_EMAILThe email provided by the registered user. This can be edited by the user in their profile, or by the site administrator in Administer > Users.
USER_PHONEThe phone number provided by the registered user. This can be edited by the user in their profile, or by the site administrator in Administer > Users.
LAB_NAMEThe name of the lab where the user is registered.
ADMIN_MAIL_LINKThe primary XNAT administration contact email, which is set in Site Administration > Site Setup. This email will be sent to the user as a link so they may quickly compose a help message.
HELP_EMAILThe Help Contact Info email specified above.
DATE_INPUTThe date when the action occurred.
TIMEThe time at which the action occurred.
PROJECT_NAMEThe name of the project referred to in the email.
STDOUTThe stdout of the related error.
STDERRThe stderr for the error.
ERRORS_LISTA list of the encountered errors.
RESET_LINKUsed in the Forgot Password email only, this link will be provided to allow the user to reset their password.
VERIFY_URLUsed in the New User Verification email only, this link will be used to verify the new user within the Xnat system.
FORGOT_LOGIN_URLUsed in the New User Verification email only, this link is used if the user has forgotten their login information.
RQ_ACCESS_LEVELUsed in project access emails only, this is the level of access being requested or given to the user within the project.
LIST_PERMISSIONSUsed in project access emails only, this is a list of the permissions the user will be given based on the level of access defined above.
ACCESS_URLUsed in project access emails only, this is the link used to respond to the project access request.
ACCEPT_URLUsed in Project Access Invitation email only, this is the link sent to allow the user to accept the invitation to work on the project.
LOGIN_URLUsed in Disabled User Verification only, this is a link to the login page for the Xnat site.
ERROR_TIMEUsed in Error Message email only - the time at which the error occurred.
ERROR_MESSAGEUsed in Error Message email only, this is the message related to the error.
PROJECT_ACCESS_REQUESTSUsed in new user emails only, these are the projects which a new user has open access requests for when they join.
REVIEW_LINKUsed in new user emails only, the link used to accept or deny the request to join the Xnat.
USER_COMMENTSUsed in new user emails only, these are the comments that the system administrator has provided to the new user.
PIPELINE_NAMEUsed in Pipeline emails only - the name of the pertinent pipeline.
EXPERIMENT_NAMEUsed in pipeline emails only - the name of the experiment on which the pipeline is being run.
SUCCESS_URLUsed in pipeline emails only - the link where the user can navigate to see details of the pipeline run.
PIPELINE_STEPUsed in the Pipeline Failure email only - the step in the pipeline at which the run failed.
CONTACT_EMAIL
Used in Pipeline Failure email only - the email to which the user can direct their help questions to.
ATTACHMENTS_STATEMENTUsed in Pipeline Failure email only - other information about the pipeline failures, if applicable.
PROCESS_NAMEUsed for Batch Transfer email only - the name of the process that has been completed.
NUMBER_MESSAGESUsed for Batch Transfer email only - the number of messages that were transferred.
MESSAGES_LISTUsed for Batch Transfer email only - the list of transferred messages.
TYPEUsed for Unauthorized Data Attempt email only - the type of data attempt.
USER_DETAILSUsed for Unauthorized Data Attempt email only - the details of the user who attempted to access the data.
NEW_EMAILUsed for email change messages only - the new email to be associated with the user account.
CHANGE_EMAIL_LINKUsed for Email Change Verification only - the link used to verify the user account's change of email address.
DUPLICATES_LISTUsed only in Upload By Reference Success email - a list of the duplicate files within the upload.
REQUEST_LINKUsed only in Data Alert message - the link the user can follow to view the data.
SENDER_MESSAGEUsed only in Data Alert message - the message sent by the user alongside the data alert.
TIME_SENTUsed only in Data Alert message - the time at which the message was sent.


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, 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


$label.name