User Notification Service

The notification framework provides a way to notify the users regarding different events as they happen in the system.

A notification is an alert that is sent to some users when an event takes place in the system (e.g. a document is created or deleted, a document is modified or published, a comment was entered, etc.).

A notification is defined by following attributes:

In order to define a notification, one must declare all these attributes in a contribution file.

The channel is the communication channel used by the notification service to send alerts(notifications) to users.

In order to define a new channel (by default only email channel is used) the ChannelNotificator interface must be implemented.

It has 2 methods:

A notification must be defined in a xml file like the default notification-contrib.xml that is used by default.

Default defined notification may be disabled by setting enabled="false".

In order to define a new notification one must place a definition like this one in his contribution file :

<notification name="Modification" channel="email" enabled="true" 
              availableIn="workspace" autoSubscribed="false" 
              template="modif" subject="Document modified" 
              subjectTemplate="subjectModif"
              label="label.nuxeo.notifications.modif">
  <event name="documentModified"/>
  <event name="contentSubdocumentModified"/>
</notification>

As you may see above a notification must declare a list of events to which it reacts. In our case documentModified contentSubdocumentModified.

Also a notification must have a name that must be unique within the application. A label must also be specified for i18n.

The attribute enabled is used to enable / disable specific notifications.

The attribute autoSubscribed is set to true when we want that a notification is sent to all concerned users. In this case within the eventInfo map there must be loaded also the users that are concerned. For example if we want that some users (ex: administrators or workflow manager) to get a notification each time a task is assigned to them, we must use autoSubscribed="true" and put the usernames of all users in the eventInfo of the event under the key recepients.

The attribute availableIn is used in order to restrict the scope of a notification. For example if we want to define a notification that is triggered each time the document is modified, then it would not be used inside a section, because sections contain documents that cannot be modified, only published. So in order to hide this notification inside a section, we specify availableIn="workspace". The accepted values are workspace, section and all.

The template attribute specifies the name of a template that will be used for generating the body of the email(notification). This name is associated with a file using another extension point like this: <template name="modif" src="templates/modif.ftl" />.

Inside a *.ftl file there may be inserted some dynamic parts like the document name, the user triggering the event, etc. Any data that one wishes to put inside the body of the email, or its subject, he must put that data in the eventInfo map under a unique key. Then inside the template file that data will be displayed using ${key}.

For the email notification a subject is used. This subject is a string but is also dynamic following the same rules as the body inside the template files. For those who wants more parameterizable subject, you can use the subjectTemplate attribute : it specfiies the name of the template used for generating the subject and into which you can write dynamic content. As for the template attribute, the association between the name and the file is done using an extension point like <template name="subjectModif" src="templates/subjectModificationTemplate.ftl" />.

If both subject and subjectTemplate attributes are filled, the subjectTemplate attribute will be used to generate the subject.

Note that if you are writing an HTML based template it will be advised to use HTML encoded letters when there is accentuated letters (in french for example "é" will be "é"). The htmlEscape method is provided while writing templates to transform accentued characters in data from the eventInfo map.

<p> Your comment here : ${htmlEscape(key)} </p>