DANSE Drupal - Audit - Notification - Subscription - Event

Allowing administrators, content editors and users to subscribe to content or other events to get notified about them is nothing that's provided by Drupal core so far. There are many modules around, that allow some of that functionality, but each of them addresses only one particular aspect, e.g. subscribing to comments on the author's content. Having a wide range of requirements results in lots of different subscription and notification components, each of which needs to be configured separately and notifications may even look different to the recipient, even though - from their point of view - they are received from the same source.

What is DANSE and how it came about DANSE is designed to become the framework in Drupal's ecosystem to provide the only required generic approach in offering subscription and notification functionality for anything Drupal.

This may sound like huge - which it is! The developers have worked on large-scale projects for many years and came across the above described requirements over and over again. In 2018, they've decided to turn the various custom solutions into this generic framework which is in production use on larger sites for over 12 months at the time it got published as an open-source module to give back to the Drupal community.

Basic DANSE architecture The best way to understand DANSE is to look at its building blocks:


* Something noticeable happens: this is an Event and gets stored as a content entity
* Users have interests and preferences: those are Subscriptions and get stored as user data
* Recipients selection: this is a Notification and gets stored as a content entity

These building blocks make up for 3 out of 5 parts of the name DANSE: Drupal - Audit - Notification - Subscription - Event. The Audit piece is a resulting building block you will get out of the initial three: for all configured event types the site administrator gets an audit log with all details about what, when, why and by whom has happened on the site.

Supported event types DANSE is designed to be extensible by plugins, each of which defines their event type. The plugin is responsible for these tasks:


* Define the supported events
* Implement listener for each supported event and call into DANSE core when any of those get triggered
* Define which of the events users can subscribe to, ideally role based
* Provide configuration forms if necessary
* Provide rendering callbacks for notifications related to its event type

DANSE comes with 4 sub-modules, each of which providing the most common event types:


* Content: this supports create, update, delete, publish and unpublish for any (!!!) content-type on a Drupal site. Not only nodes, but also all the others, e.g. media, comments, taxonomy terms, commerce orders, you name it. Administrators can configure for each content type and bundle individually, which of the events will be recognized and which user roles are allowed to subscribe to them.
* Config: this is not completed yet but will support config save, config translation save and config import validation. Most likely, these events should only be notified to administrators then.
* Log: this supports log entries above a certain threshold, e.g. error or worse. This allows you to notify administrators when something happens on the website, they should be dealing with.
* Web hook: this provides an external API end-point such that third-party systems can also leverage this functionality and notify the same user base which is registered on that website. This can be useful e.g. if you also run Discourse or Zendesk and want to communicate with your user base only through one single instance, your Drupal site in this case.

The core of DANSE takes care of all the difficult stuff, so the plugins don't have to deal with them. All the events get unified, which will then lead into the next phase:

Determine recipients for each event In DANSE you can configure a recipient selection plugin for each event type individually. In other words, each event type may require a different approach on how to determine, who should be notified.

Out of the box, DANSE comes with two recipient-selection plugins:


* All active users: this plugin selects all active users on the site as recipients
* Admins: this plugin selects all active users with the admin role as recipients

It's simple to develop additional plugins with different recipient selection logic - your imagination is the limit. It's also very likely that DANSE will even provide more of those as part of its core package as we see requirements.

In the background, whenever an event gets stored, DANSE asynchronously determines who should be notified. First, it detects all the subscribers for each event and then calls the associated plugin for that event to probably find additional recipients. But it takes care that no one user gets notified more than once about the same event. Even more so, DANSE eliminates similar notifications, e.g. if a node got updated three times, that will trigger 3 events but each user will only be notified once - unless a user has already seen the first notification before the third event gets triggered, then that user gets another notification because it is something they would have missed otherwise.

How does the user get the notifications DANSE deals with the notifications - it is not dealing with delivery. This is significant and therefore mentioned right away. If you want to push notifications out to users, we recommend the Push Framework module which works well together with DANSE and supports a growing number of different channels like email, Twilio, OneSignal, Slack, Mattermost, Alerta and more to come.

DANSE handles notifications on-site only. There are a number of tools on how to visualize the events and notifications to authenticated users:


* Notification widget: DANSE comes with a view which displays a drop-down widget anywhere on the site (configured as a block). It contains the number of unseen notifications and, when clicking on it, shows a list with links to each of the events.
* Archive: A new tab in the user's profile which gives them access to all legacy notifications with exposed filters to browse through all their received notification on that site to date.
* Audit Log: In the reports section of the site, several views are available to go through all events and notifications. As DANSE even keeps track if a notification has been seen by their recipient, this helps the site admin to determine who got notified and who actually noticed the information.

Summary As you can tell from this description, DANSE is the one-stop-shopping for all requirements around subscription and notifications. Well, maybe not yet. But it is the foundation for future development as it has been carefully designed to address more and more requirements that are related to its realm. It is scaleable and rock solid, both of which has been proven on production sites with business critical use cases.

Give it a try, come back with questions or even contribute to future development. We are inviting everybody to collaborate on this project with us - we strongly believe that this module should turn into one of the top modules in the Drupal-verse.

Documentation While we haven't had the time to work on proper documentation, we'd like to point you to this issue, where @rex.barkdoll has written a great step-by-step tutorial which is well regarded by many users.