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.

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 shortcodes used to configure the message (outlined in more detail below):

User Registration Notifications

When editing the Password Reset Email:

The email that is sent to users who request a password reset has a unique shortcode in it that must be included: RESET_LINK. This shortcode will be replaced with a clickable URL that the user must 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.

Email Trigger Event	Available Shortcodes
User Registration The email message sent to users upon their registration.	USER_FIRSTNAME - The first name of the user who will be sent the message. USER_LASTNAME - The last name of the user who will be sent the message. SITE_NAME - The name of the xnat site. SITE_LINK - The link to the xnat site. USER_USERNAME - The username of the new user. ADMIN_MAIL_LINK - The link to email the site admin.
New User Request The email message sent out when a new user account is created but has not yet been enabled.	TIME - The time of user creation. SITE_NAME - The name of the xnat site. SITE_LINK - The link to the xnat site. USER_USERNAME - The username of the new user. USER_FIRSTNAME - The first name of the new user. USER_LASTNAME - The last name of the new user. USER_PHONE - The phone number of the new user. LAB_NAME - The name of the lab the new user is under. USER_EMAIL - The email address of the new user. PROJECT_ACCESS_REQUESTS - Projects for which the new user has access requests (blank if none) REVIEW_LINK - The link used to accept or deny the request. USER_COMMENTS - The comments provided to the administrator by the new user.
New User Notification The email message sent out when a new user account registration has been created.	TIME - The time of user creation. SITE_NAME - The name of the xnat site. SITE_LINK - The link to the xnat site. USER_USERNAME - The username of the new user. USER_FIRSTNAME - The first name of the new user. USER_LASTNAME - The last name of the new user. USER_PHONE - The phone number of the new user. LAB_NAME - The name of the lab the new user is under. USER_EMAIL - The email address of the new user. PROJECT_ACCESS_REQUESTS - Projects for which the new user has access requests (blank if none). REVIEW_LINK - The link used to accept or deny the request. USER_COMMENTS - The comments provided to the administrator by the new user.
New User Verification The email message sent to a newly registered user's email to verify the newly created account.	USER_FIRSTNAME - The new user's first name. USER_LASTNAME - The new user's last name. VERIFY_URL - The URL used to verify the new account. ENABLED_MESSAGE - A message indicating whether the user account is now enabled, includes a login link. FORGOT_LOGIN_URL - The URL used if the user has forgotten their login information.
Disabled User Verification The email message sent out when a previously disabled user account is verified and reactivated.	DATE_INPUT - The date on which the user was re-verified. SITE_NAME - The name of the xnat site. SITE_LINK - The link to the xnat site. USER_USERNAME - The username of the re-verified user. USER_FIRSTNAME - The first name of the re-verified user. USER_LASTNAME - The last name of the re-verified user. ENABLED_MESSAGE - A message indicating whether the user account is now enabled, includes a login link.

User Account Management Notifications

Email Trigger Event	Available Shortcodes
Forgot Username The email message sent to a user's email address when they have lost their username.	USER_USERNAME - The requested username SITE_LINK - The link to the xnat site
Forgot Password The 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.	USER_FIRSTNAME - The first name of the user receiving the password reset. USER_LASTNAME - The last name of the user receiving the password reset. RESET_LINK - The link used to reset the password.
Email Change Request The 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.	USER_USERNAME - The username of the account. NEW_EMAIL - The new email for the account. ADMIN_MAIL_LINK - The link to email the site admin
Verify Email Change Request The email message sent out to verify a change of email address when one has been requested by the user within the XNAT system.	USER_USERNAME - The username of the account. CHANGE_EMAIL_LINK - The link to change the email address.
Email Address Change Successful Text 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.	NEW_EMAIL - The new email address for the account

Project Access Request Notifications

Email Trigger Event	Available Shortcodes
Project Access Request The email message sent out to project owners when a user requests access to their project.	PROJECT_NAME - The name of the project the user is attempting to access. SITE_NAME - The name of the xnat site. RQ_ACCESS_LEVEL - The level of access (member, collaborator, etc.) that is being requested. LIST_PERMISSIONS - The permissions associated with the level requested. USER_USERNAME - The username of the requesting user. USER_EMAIL - The email of the requesting user. USER_FIRSTNAME - The first name of the requesting user. USER_LASTNAME - The last name of the requesting user. RQA_COMMENTS - The comments that the user attached to their request. ACCESS_URL - The URL used to respond to the access request. SITE_LINK - The link to the xnat site. ADMIN_MAIL_LINK - The link to email the site admin.
Project Access Approval The email message sent out to a user when their request for project access has been accepted.	PROJECT_NAME - The name of the project. RQ_ACCESS_LEVEL - The level of access (member, collaborator, etc.) that is being granted. ACCESS_URL - The URL used to access the project. SITE_LINK - The link to the xnat site. SITE_NAME - The name of the xnat site. ADMIN_MAIL_LINK - The link to email the site admin.
Project Access Denial The email message sent out to a user when their request for project access has been denied.	PROJECT_NAME - The name of the project for which access was requested. USER_EMAIL - The email of the project manager. SITE_LINK - The link to the xnat site. SITE_NAME - The name of the xnat site. ADMIN_MAIL_LINK - The link to email the site admin.
Project Access Invitation The email message sent out to a user when they have been invited to join a project.	PROJECT_NAME - The name of the project. USER_FIRSTNAME - The first name of the user extending the invitation. USER_LASTNAME - The last name of the user extending the invitation. ACCEPT_URL - The URL to be used to accept the invitation to join the project. SITE_LINK - The link to the xnat site. SITE_NAME - The name of the xnat site. ADMIN_MAIL_LINK - The link to email the site admin.

Data Transfer Notifications

Email Trigger Event

Available Shortcodes

Batch Transfer Complete

The email message sent to the initiating user when a batch data transfer to the archive has been successfully completed.

USER_FIRSTNAME - The first name of the contacted user.
USER_LASTNAME - The last name of the contacted user.
PROCESS_NAME - The name of the process that has been completed.
NUMBER_MESSAGES - Number of messages transferred.
MESSAGES_LIST - List of transferred messages.
ERRORS_LIST - List of any errors that occurred during the transfer.
SITE_LINK - The link to the xnat site.
SITE_NAME - The name of the xnat site.
ADMIN_MAIL_LINK - The link to email the site admin.

Upload By Reference Success

The email message sent when a user has uploaded a file or files to the system by reference successfully.

USER_USERNAME - The user who requested the upload.
DUPLICATES_LIST - The list of the duplicate files (if applicable).

Upload By Reference Failure

The email sent when a user's upload by reference attempt has failed.

USER_USERNAME - The user who requested the upload.

Pipeline Processing Notifications

Email Trigger Event

Available Shortcodes

Pipeline Success

The email message sent out when an experiment pipeline has completed successfully without errors.

USER_FIRSTNAME - The first name of the contacted user.
USER_LASTNAME - The last name of the contacted user.
PIPELINE_NAME - The name of the pipeline.
EXPERIMENT_NAME - The name of the experiment on which the pipeline ran.
SUCCESS_URL - Link for details on the pipeline run.
SITE_NAME - The name of the xnat site.

Pipeline Failure

The email message sent out when an experiment pipeline has failed before completion due to an error.

PIPELINE_NAME - The name of the pipeline.
PROJECT_NAME - The name of the project in which the pipeline failed.
EXPERIMENT_NAME - The name of the experiment on which the pipeline failed.
PIPELINE_STEP - The step at which the pipeline failed.
SITE_NAME - The name of the xnat site.
CONTACT_EMAIL - The email at which a user can contact the site team for help.
ATTACHMENTS_STATEMENT - Other information about the pipeline failures if applicable.
PIPELINE_PARAMETERS - The parameters of the specific pipeline run.
STDOUT - The stdout of the pipeline error.
STDERR - The stderr of the pipeline error.

Autorun Pipeline Success

The email message sent out to the user when the autorun pipeline field is enabled in Xnat and the automatically run pipeline completes successfully.

USER_FIRSTNAME - The first name of the contacted user.
USER_LASTNAME - The last name of the contacted user.
SITE_NAME - The name of the xnat site.
PROJECT_NAME - The name of the project in which the pipeline ran.
SUBJECT_NAME - The name of the subject on which the pipeline ran.
EXPERIMENT_NAME - The name of the experiment on which the pipeline ran.
SUCCESS_URL - Link for details on the pipeline run.

Error Handling Notifications

Email Trigger Event

Available Shortcodes

Error Message

The email message sent out to site administrators when an error has occurred within the system.

SITE_NAME - The name of the xnat site.
USER_LOGIN - The login information for the user associated with the error.
USER_FIRSTNAME - The first name of the associated with the error.
USER_LASTNAME - The last name of the associated with the error.
ERROR_TIME - The time of the error.
ERROR_MESSAGE - The error message.

Unauthorized Data Attempt

The email message sent when one of a several types of unauthorized data or login access attempts are recognized by the system.

TYPE - The type of data attempt.
USER_DETAILS - The details on the user who attempted to access the data (if known and applicable).

System Path Error

The email message sent to the site admin when Xnat is unable to find the file system (e.g. archive, build, prearchive directories).

ERRORS_LIST - The list of the errors that have been found.

Data Of Interest Notifications

Email Trigger Event

Available Shortcodes

Data Alert

The email message sent from one user to another to alert each other about possibly useful data within their XNAT.

USER_FIRSTNAME - The first name of the user who initiates the message.
USER_LASTNAME- The last name of the user who initiates the message.
SITE_NAME - The name of the xnat site.
REQUEST_LINK - The link the user can follow to view the data.
SENDER_MESSAGE - The message sent by the user alongside the data alert.
SITE_LINK - The link to the xnat site.
TIME_SENT - The time at which the information was sent.
HELP_CONTACT - Email address at which help can be reached

Full Shortcode Reference

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	Replacement Value
SITE_NAME	Your XNAT's site name, which is set in Administer > Site Administration > Site Setup.
SITE_URL	A link to your Xnat site, the url of which is set in Administer > Site Administration > Site Setup.
USER_USERNAME	The username or login of the registered user, which is unique and set by the user.
USER_FIRSTNAME	The 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_LASTNAME	The 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_LOGIN	The login information for the user.
USER_EMAIL	The 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_PHONE	The 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_NAME	The name of the lab where the user is registered.
ADMIN_MAIL_LINK	The 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_EMAIL	The Help Contact Info email specified above.
DATE_INPUT	The date when the action occurred.
TIME	The time at which the action occurred.
PROJECT_NAME	The name of the project referred to in the email.
STDOUT	The stdout of the related error.
STDERR	The stderr for the error.
ERRORS_LIST	A list of the encountered errors.
RESET_LINK	Used in the Forgot Password email only, this link will be provided to allow the user to reset their password.
VERIFY_URL	Used in the New User Verification email only, this link will be used to verify the new user within the Xnat system.
FORGOT_LOGIN_URL	Used in the New User Verification email only, this link is used if the user has forgotten their login information.
RQ_ACCESS_LEVEL	Used in project access emails only, this is the level of access being requested or given to the user within the project.
RQA_COMMENTS	Used in project access emails only, these are comments provided by the user to justify access to a requested project role.
LIST_PERMISSIONS	Used 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_URL	Used in project access emails only, this is the link used to respond to the project access request.
ACCEPT_URL	Used 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_URL	Used in Disabled User Verification only, this is a link to the login page for the Xnat site.
ERROR_TIME	Used in Error Message email only - the time at which the error occurred.
ERROR_MESSAGE	Used in Error Message email only, this is the message related to the error.
PROJECT_ACCESS_REQUESTS	Used in new user emails only, these are the projects which a new user has open access requests for when they join.
REVIEW_LINK	Used in new user emails only, the link used to accept or deny the request to join the Xnat.
USER_COMMENTS	Used in new user emails only, these are the comments that the system administrator has provided to the new user.
PIPELINE_NAME	Used in Pipeline emails only - the name of the pertinent pipeline.
EXPERIMENT_NAME	Used in pipeline emails only - the name of the experiment on which the pipeline is being run.
SUCCESS_URL	Used in pipeline emails only - the link where the user can navigate to see details of the pipeline run.
PIPELINE_STEP	Used 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_STATEMENT	Used in Pipeline Failure email only - other information about the pipeline failures, if applicable.
PROCESS_NAME	Used for Batch Transfer email only - the name of the process that has been completed.
NUMBER_MESSAGES	Used for Batch Transfer email only - the number of messages that were transferred.
MESSAGES_LIST	Used for Batch Transfer email only - the list of transferred messages.
TYPE	Used for Unauthorized Data Attempt email only - the type of data attempt.
USER_DETAILS	Used for Unauthorized Data Attempt email only - the details of the user who attempted to access the data.
NEW_EMAIL	Used for email change messages only - the new email to be associated with the user account.
CHANGE_EMAIL_LINK	Used for Email Change Verification only - the link used to verify the user account's change of email address.
DUPLICATES_LIST	Used only in Upload By Reference Success email - a list of the duplicate files within the upload.
REQUEST_LINK	Used only in Data Alert message - the link the user can follow to view the data.
SENDER_MESSAGE	Used only in Data Alert message - the message sent by the user alongside the data alert.
TIME_SENT	Used only in Data Alert message - the time at which the message was sent.

Sending Custom Notifications to Users via Email

See: Sending Emails to Registered Users

Creating Site-wide Alerts

See: Admin UI - Site Wide Alerts

Developer Note

Notifications Prerequisite: Configure the XNAT Email Server

Editing Default Email Messages

User Registration Notifications

User Registration

New User Request

New User Notification

New User Verification

Disabled User Verification

User Account Management Notifications

Forgot Username

Forgot Password

Email Change Request

Verify Email Change Request

Email Address Change Successful

Project Access Request Notifications

Project Access Request

Project Access Approval

Project Access Denial

Project Access Invitation

Data Transfer Notifications

Batch Transfer Complete

Upload By Reference Success

Upload By Reference Failure

Pipeline Processing Notifications

Pipeline Success

Pipeline Failure

Autorun Pipeline Success

Error Handling Notifications

Error Message

Unauthorized Data Attempt

System Path Error

Data Of Interest Notifications

Data Alert

Full Shortcode Reference

Sending Custom Notifications to Users via Email

Creating Site-wide Alerts