I know you've said that documentation is on the horizon, but I haven't found anything to help me get started with DANSE and I'm really hoping it can do what I need it to. So I'm going to post what I've learned so far and hope that the Developers can correct me where possible.
Additionally, this will hopefully serve as a proto-tutorial until actual documentation can be written.
So here's what I've got installed so far (with Composer):
- danse
- danse_content_moderation (beta)
- push_framework
- pf_email
- advancedqueue (required by push_framework)
I enabled:
- DANSE Config
- DANSE Content
- DANSE Log
- DANSE User
- Drupal Audit Notification Subscription Event
- DANSE Content Moderation
- Push Framework
- Push Framework Email
- As well as the supporting modules: Advanced Queue, Views, Filter, User, System, Token, Core Event Dispatcher, Hook Event Dispatcher, MimeMail
I opted not to install DANSE Webhook because I didn't need it. I opted not to install DANSE Form because it caused an error when I installed it the first time and on this site I really don't have any forms that I need to monitor with DANSE.
My Objective
The Developers can tell me if this is a good use for DANSE or not.
I'm trying to get an email notification system working for a small forums site. I want users to be able to subscribe to each forum topic they have access to individually and get notified when new comments are posted. Ideally, users could subscribe to a whole topic and/or just get notified when someone comments on their comment thread.
- At a bare minimum, I need them to be able to subscribe to each forum topic individually and get notifications on comments that are part of that topic only when they are published.
Update: DANSE v2.2+ does this.
Step 1: Enable the modules, Clear the cache
Install: Drupal Audit Notification Subscription Event, DANSE Content, Push Framework, Push Framework Email, and the above supporting modules.
Now Clear the cache. I stumbled around for 20 minutes because I didn't think to clear the cache when I first enabled the above modules. Save yourself a headache and just clear the cache immediately. After more testing, I think you only need to clear cache once when you enable the modules. Everything else seems to work pretty well without lots of cache clearing.
Step 2: Go to DANSE Settings
Admin Menu > Configuration > System > DANSE
This is the basic configuration page for DANSE.
- Ignore the Prune button for now.
- I chose to check the Event subscription settings as tab in user profile because that's the user experience I want.
- in version 2.2, there's an additional checkmark: Active subscriptions as tab in user profile, I checked that too because it shows views of what the user is actively subscribed to and I want users to have a single place to manage their subscriptions.
Under Recipient selection plugins, there should be some boxes with "plugins" inside them. A plugin is either a role or a group of users provided by another source. I chose to:
- Config select Administrators - because my admins need to know about all config changes regardless
- Content: Select no roles because I want users to subscribe rather than to receive push notifications.
- Content Moderation: Select no roles - again, no one needs to receive push notifications on my site.
- Skip Log for now
- Skip User for now
Selecting plugins (roles/groups of users) from these boxes means that any user in that group will receive a notification regardless of whether they chose to subscribe to that content or not. This is like an administrative action that says, "We want you to know about this" rather than "please opt-in to get notifications.
If you want your users to subscribe themselves to content, there's a tab on the edit screen of each content type (Content Type, Comment Type, Taxonomy Vocabulary) that says DANSE where you'll choose the plugins that are able to see subscription buttons and subscribe to that content.
Under Settings to prune database records I set everything to 1 month for now, while I'm testing. Later I'll set it to our organization's standards for data retention (THANK YOU FOR THIS DEVs)
NOTE: These settings are what the prune button at the top uses to prune the DANSE logs, which we'll get to next. If stuff isn't deleting from the logs, it's because the stuff still fits within the timeframe you've defined in this section.
save your settings
Step 3: Content Type Updates
Go to Admin Menu > Structure > Content Types > [the one you want]
Make sure you're on the overall Edit page for the content type/comment type/taxonomy vocabulary. In the tabs at the bottom, you'll notice a new DANSE option.
This has a table that could use some explanation from the Developers on what exactly everything does:
Columns: Create, Update, Delete, Publish, Unpublish - these are the states of the content. I'm most interested in Publish for my site users and Create for my Admins/Moderators.
In version 2.2+, there's also a Comments column to allow users to subscribe to all comments of this entity or entity type.
Rows:
- Create Event - when should DANSE create an event/notification?
- Access to Settings - I don't 100% understand this yet, but I'm assuming that only my admins should have access to this. Note that I don't have options in the Publish or Unpublish columns.
- Default Value for push - I check the box under Create. Note that I don't have options in the Publish or Unpublish columns.
- Default Value for force - I check nothing. Note that I don't have options in the Publish or Unpublish columns.
- Default Value for silent - I check nothing. Note that I don't have options in the Publish or Unpublish columns.
- v1.x: Allow Subscription - Under the Create Column, I select my administrators. Under Publish, I only select the Authenticated User role to indicate that I want everyone to be able to subscribe to this content type.
- v2.2+:Allow entity type subscription - Select the plugins (groups) who you want to be able to subscribe to entity-wide events (like all forum topics, all comments, etc)
- v2.2+:Allow individual entity subscription - Select the plugins (groups) who you want to be able to subscribe to events on individual entities in this bundle - like one forum topic and its comments
Now I save the content type.
*
In an issue on this module →
, the Devs add a little explanation:
.. The rows in between are for content editors: while "create event" determines when an event is created, the three rows with checkboxes determine the default value for those events and the "Access to settings" determines which editors will get a widget in the entity edit form to see and overwrite those properties.
You might take a quick peek under the Manage Display for the content type and note which Display modes you have available. I have Default and Teaser. You can also make your own display mode and use that for Push Notifications.
(Optional) Step 3.5: Do the same update from Step 4 on your Comment types & Taxonomies
Go to Admin Menu > Structure > Comment Types > [the one you want]
The Settings are in the same place in the Edit page.
Again, my display modes are Default and Teaser.
Step 4: Push Framework
Admin Menu > Configuration > System > Push Framework
Super quick, pop over to the Email tab here and double check that both boxes are checked. (Active, Use default settings for content)
Now jump back to the General tab.
Under Display Modes, you'll see that the Push Framework is giving you the ability to choose. When you do something that would trigger a push notification to go out, how should that push notification present the content of each content type in the notification?
This can really feel overwhelming, but just focus on the content types you care about. For me it was:
- Comment - Full comment
- Content Moderation State - Teaser
- Content - Teaser
- Everything else I just left as the default.
Content Pattern
Under here, you'll see the Subject and Body.
Subject: [site:name] notification: [push-object:label]
Body:
[user:display-name],
[push-object:content]
I made mine a little more user friendly with a "Hi [user:display-name]" but that's about it for right now. I also personally like to have Pathologic installed and enabled on the text format I'm using on this page to help with sending out absolute URLs. There was also an
odd Drush issue →
I ran into with absolute URLS, but this is in no way related to DANSE or Push Framework.
Pro-tip: There are a few Drupal MailSystem extensions you can install. I personally landed on MimeMail for its simplicity. I have my MailSystem settings set for Push Framework to use MimeMail and then I created a custom MimeMail twig template to format my emails nicely with an HTML email. Directions for that weren't hard to find.
Step 5: User Profile Subscriptions update
Now you need to head over to your user profile. (Go to View Profile)
Look for a navigation item called Subscriptions
There are checkboxes you must OPT-IN to in order to receive notifications.
Step 5 for DANSE 2.2+
Note that I have heavily customized by views by the time I took this screenshot and I'm using the DANSE Label Override module to alter my subscription buttons' language.
In version v2.2, the developers recently added Views Integration for DANSE. Users now have 3 views, plus the original checkboxes to manage their subscriptions in one place.
- Comment Subscriptions - for individual comments
- Content Subscriptions - for individual content entities/nodes
- Taxonomy Subscription - for individual taxonomy terms
- Entity Type Subscription checkboxes - when you've given a user the ability to subscribe to an entire taxonomy bundle, content type, or comment type they'll use these checkboxes to manage those subscriptions.
Step 6: Create some content
This is the part where we go and make some noise. Create a node, create a comment, whatever you set up and generate some events in your system. If you're going for subscriptions in version 2.2+, then make sure you click on some subscription buttons, otherwise you'll want to make sure you've selected some plugins on the DANSE configuration page for push notifications.
Step 7: Go to the DANSE Events (log)
Admin Menu > Reports > DANSE Events
This is basically your log of what DANSE is encountering. I personally get a blank page whenever I click into a notification, so I've come to interpret this more as a dashboard rather than an interactive log.
Update: I now only get blank pages on Notifications that haven't been processed yet. Once Cron has run (I recommend running drush cron manually when you are testing so you can see if there are errors and get notified immediately), the events should be processed and the title links of events in this table will work. Note that DANSE also offers a Drush command of its own to generate outstanding notifications.
Columns:
- Label: the item that you created (Clicking this is broken for me - white page that says Notifications, it's a view with no results)
- Plugin: Tells you which DANSE plugin created the entry (content, log, etc)
- Topic: The action that caused the notification. I get one for create and one for publish because those were what I checked on the Content Type Edit page. Note that if I only have Publish checked, I don't get any notification at all.
- Reference: the entity type and ID number
- Created - date
- Push: did this create a push event? (all of mine are checks, so I'm not sure if there's a state where an X is possible for this column)
- Force: Did you choose to force an event? This is set either on the Content Type Edit page or when you're creating the new content/node
- Silent: Did you choose to make the event silent? (Meaning no notification would have been sent out of the website, it just gets logged here) This is set either on the Content Type Edit page or when you're creating the new content/node
- Processed: Did any active plugin instance of type
@Danse() annotation set the event processed already or not? (an 'X' in this column may indicate an issue with Cron not being processed. Check your cron logs)
~~~Update thanks to @jurgenhaas:~~~
Step 8: A bit of troubleshooting with System Queue and Cron
Based on what @jurgenhaas recommended in his comment below, I checked by Queue logs here:
/admin/config/system/queues
As you can see, there's a queue for the Push Framework. Clicking on List Jobs reveals a screen that looks like this:
Something notable is that I had a number of successful jobs before I found the problem SwiftMailer was causing in my Cron. At the same time, I also had a number of jobs that were queued or were processing. I would recommend if you see a number of queued or processing jobs, that's a good time to head over to your command line and run drush cron and see if it spits back any errors.
~~~End Update~~~
Reading a DANSE Events Log entry
You should have everything working now. At this point, you probably want to see who notifications were sent to, so head into the DANSE Event log and click on an entry that has the Processed column checked.
You should get a page that looks like this:
In the first column, in the example image, you'll see that my first row says subscription. This means that User1 subscribed to this content themselves. They chose the option in their Subscriptions section in their profile, or in v2.2.x, they went to an entity and clicked the button to subscribe.
Rows 2 &3 show the word push. This means that on the DANSE Config page, I had chosen one of the roles from the Content or Content Moderation boxes under Recipient selection plugins. Because these users had a role that was selected, they will get a notification regardless of whether or not they chose to subscribe themselves to the content.
Last, I'd ask the maintainers to please only close this issue once they have posted actual documentation. It also took me a while to think to look in the closed issues queue to find some additional hints from closed tickets.