Notifications

DOCman provides a built-in notifications system allowing you to send notifications when selected actions get executed on your document library.

Notifications can be set on categories and they apply to both the category itself and the documents it contains. Optionally, these notifications may be set so that they also affect the descending categories and its corresponding documents (inheritance).

The notifications tab

When editing an existing category, a new tab (Notifications) will be made available alongside the Description and Permissions tabs. By clicking on this tab a new selector will allow you to select the type of notification you would like to add.

Notifications types

E-mail

Immediately after selecting the E-mail notification type in the notifier selector, a new E-mail notification form will be made available for adding a new notification.

After selecting which actions should trigger the notification, you need to define, at least, one recipient to notify. For this end you are provided with groups and users selectors allowing you to set as many recipients as you like per notification. The system has been designed to send big amounts of E-mails as long as your webserver or service provider allows for it.

Naturally, the next step would be to provide a subject (optional) and a body for your notification. Some pre-defined body messages are provided by default depending on the selected action(s). You are of course free to define your own by simply editing the corresponding form fields.

Both the subject and body fields provide support for a template engine allowing you to insert notification data on content.

Template objects

Each notification is directly related to data objects which may be referenced inside the notification itself, e.g. the user that triggered the notification by executing some action, the entity that got affected by this action, etc. These objects may be referenced in content by using placeholders, e.g. {entity}, {recipient}, etc.

A template object contain properties that may be accessed by using a dot notation, e.g. {entity.title}, {recipient.name}. While some of these properties may point to scalar values (a number, a string), some others will point to related objects, e.g. suppose that {entity} points to a document, then {entity.category} returns the document's category object. Ultimately {entity.category.title} will resolve as the category title.

The main {entity} object makes reference to the current object on which the action is taking place, e.g. if you are editing a document then {entity} points to the document object being edited. If in the other hand you are executing an action against a category, then {entity} points to the category object instead.

Below is a list of supported template objects in our template engine:

1. Document object

This object points to the document entity, which may be referenced by using {entity} when the action is being executed against a document. If the notification may trigger actions on both documents and categories then {entity} may be either a document or category object depending on the action.

Properties:

• id: the ID
• uuid: the Universally Unique Identifier
• title: the title
• slug: the slug
• category: the category object
• description: the document description
• hits: the number of times the document has been downloaded
• publish_on: the date of publication
• unpublish_on: the unpublish date
• created_on: the date of creation
• created_by: the ID of the user that created the document
• created_by_name: the username of the user that created the document
• modified_on: the modify date
• modified_by: the ID of the user that modified the document
• modify_by_name: the username of the user that modified the document
• storage: the file object
• _type: will print document
• _route: the backend URL to access the document

Example: {entity.title} returns the document's title when the action is executed against a document

2. Category object

The category object may be reached through {entity.category} when {entity} points to a document. If the action is being executed against a category then {entity} is effectively pointing to the category object already.

Properties:

• id: the ID
• uuid: the Universally Unique Identifier
• title: the title
• slug: the slug
• description: the document description
• created_on: the date of creation
• created_by: the ID of the user that created the document
• created_by_name: the username of the user that created the document
• modified_on: the modify date
• modified_by: the ID of the user that modified the document
• modify_by_name: the username of the user that modified the document
• _type: will print category
• _route: the backend URL to access the category

Example: {entity.category.id} returns the ID of the document's category if the action is executed against a document. If the action is executed against a category, then the same is achieved with {entity.id}.

3. Storage object

This object references the actual stored file that is attached to a given document. You may reach this object by using {entity.storage} when {entity} is pointing to a document object.

Properties:

• folder: the folder where the file is located
• name: The filename
• extension: the file extension
• size: the filesize in bytes
• mimetype: the file mimetype

Example: {entity.storage.size} returns de size of the file that's attached to the document.

4. Actor object

This object points to the user executing the action.

Properties:

• id: the ID
• username: the username
• user_nicename: the nice username
• email: ther user E-mail address
• registered_on: the user registration date
• name: the name of the user
• _route: the backend URL to access the user

Example: {actor._route} returns a backend user link of the user that executed the action that triggered the notification.

5. Recipient object

This is the recipient user object.

Properties:

• id: the ID
• username: the username
• user_nicename: the nice username
• email: ther user E-mail address
• registered_on: the user registration date
• name: the name of the user
• _route: the backend URL to access the recipient

Example: {recipient.username} returns the username of the user that's being notified.

Template variables

Additionally there are a few scalar template variables you may also use:

• {result}: the result of the action, e.g. edited for edit, deleted for delete, etc.
• {action}: the action that got executed, e.g. edit, delete, etc.
• {sitename}: the name of the site.
• {site_url}: the site's URL.

Finally you you are presented with an Inheritable checkbox and the notification form buttons (Add / Update / Reset). The checkbox enables/disables the inheritance behavior of the current notification. For example, if you would like the notification to only affect the current category and the documents inside then you should leave this checkbox unchecked, otherwise the notification also applies to the descending categories and their corresponding documents.

When you are done with the notification form you may simply click on Add to get your notification properly saved and added to the current category. You will notice that as soon as you click on this button, the notification form will get reset and your newly added notification will show under a new notifications list under the same tab. You are of course allowed to add as many notifications as you want to each category. You will be also able to edit existing notifications as well as delete them from this list.