Proposal: Content user notifications

[ssddanbrown]

This is a proposal that aims to add an initial content notification system to BookStack. The below may be updated and developed further based upon feedback.

Note: This has been designed with the intent of being an initial implementation meeting 80% of the common needs, while being a base that does not hinder future potential to be built upon. It is not intended to meet every single use-case & potential requirement.

Proposal

• Notifications will be sent on the three following activities:
  • Page creation
  • Page update
    • Specifically content updates, whenever the main "Save" button is used in the editor.
    • Updated for this event will only be sent if not already last updated by the same user in the last 10 minutes. This is to "debounce" multiple rapid updates.
  • Page comment creation
• Notifications will be email-based.
  • Page create/update notifications will contain the page name and link, and creator/updater name.
  • Page update notifications will mention the debounce behaviour/text (in a user friendly way) to make it clear that a notification may not be received for every near-future update.
  • Page comment notifications will contain commenter name and comment plaintext.
• Users will have three notification preference checkboxes to control:
  • Notify upon changes to pages I own.
  • Notify upon comments on pages I own.
  • Notify upon replies to my comments.
    • A "reply" is a direct child comment using that's specifically created using a built-in reply functionality.
• None of the user notification preferences will be checked by default.
• A new "Can receive & manage notifications" role permission will be added.
  • If a user lacks this permission from any of their assigned roles, all notification management options will be hidden and they will not be sent notifications. Any of their previously set notification/watch preferences will still remain.
  • Only the default "Admin" role will receive this permission by default.
• Books, chapters and pages will have item-level "Watch" notification option available.
  • The user can select only one of these (think sliding scale or radio button).
  • The options are:
    • Default: No specific settings upon user-level preferences.
    • Ignore: Ignores any notifications, including those from user-level preferences.
    • New Pages: Notify on any new page. Does not interfere/affect user-level preferences at all.
      • This will only be shown for chapters/books, not pages.
    • All page updates: Notify upon page creations and page update events.
    • All page updates and comments: Notify upon page creations, page updates and any comment creation.
  • Options set for books and chapters will cascade and apply to all pages below.
    • There will be some level of indication on the "Watch" notification option if a (non-default) parent item "Watch" option is already set.
    • If "Watch" options are set at multiple levels for a page, the lowest (most specific) option will be used.

Out of scope

Here are a couple of things not specifically stated in the above, but may be important to note:

Shelves. They will have no added support for this within this implementation, due to their more complex relationship and optional existence. I'd prefer for an initial implementation to be implemented first so any desired usage with shelves can be risen and discussed based upon actual need and experience of notifications in the system, so we can best decide how/if they fit into such a system.

Other notification options. Only email-based notifications will be supported. The system will be built with potential other notification avenues in mind, but this implementation is focused solely on email.

Other notification events. Only the page-level events will emit notifications. The intent of this system is for normal users in their task of creating, collaboration and discovery. It's hard to see wide appeal for other event types outside of the role of auditing/administration, which I view as a separate goal that already has options available (webhooks, audit log, theme system etc..).

Infrastructure level considerations

This will have a performance impact on most systems where enabled, but we already have the queue system in place and guidance for queues in the docs due to Webhooks, but email notifications are likely to be more commonly used. We'll have to make sure our guidance is visible and accessible when it comes to emails and/or performance. It may be a good idea to review/update our docs and, where reasonable, provide easier use and deployment of a worker. Perhaps a task for the new System CLI? (Limited to systemd machines to keep scope reasonable).

Feedback

Feel free to comment below with any feedback. I'm particularly interested to hear if there's anything logically unsound, or if there's anything that we may hinder future ideas/development/growth for notifications, or if there's anything believed to potentially negatively impact existing BookStack use on release of such an implementation.

If you read this and are happy with the implementation, that would be good to hear too, just as positive confirmation that this all makes sense and is considered acceptable to proceed. Even just a thumbs-up reaction (found at the bottom of this comment box) would be good for this.

If there's not much to further to think about or discuss here, I may proceed with this and start implementation from the 17th with an aim for end-of-july release, otherwise this can be pushed into a wider/later release cycle.

[Doctor-Macintosh]

1. Thought: I vote for having a digest mode for the notification eMails. Typically an editor will work for longer times (sometimes hours) an editing a page and will save the changes multiple times - so immediate update notifications via eMail will produce a lot of noise for the users and will make them ignore the notifications. A digest mode that will send a notification every morning with a list (with links) to all of the pages changed yesterday makes more sense, doesn't it?

2. Thought: Notification just to the owner (or creator) of a page is not suitable for most applications. We are using BookStack for documentation of our SOP (Standard Operations Procedures) so all readers (not editiors) should be notified of changes. Does this make sense?

[ssddanbrown]

Thanks @Doctor-Macintosh.

I vote for having a digest mode for the notification eMails. [...] eMail will produce a lot of noise

I see digests as essentially a somewhat different form of communication. They would require host system level changes & abilities to support so not are not something I'd primarily target for widespread use, or a base implementation.
In regards to noise, this is touched upon in the denouncing mention for page update activities.

Notification just to the owner (or creator) of a page is not suitable for most applications. We are using BookStack for documentation of our SOP (Standard Operations Procedures) so all readers (not editiors) should be notified of changes.

As per the proposal, users could still choose to watch a book to receive updates for pages they don't own.
I'd have thought that if you have a need to notify all users of all updates, then email notifications would be a noisy system for that. The existing webhooks to an internal chat system (or other company communication channels) may suit those scenarios better. Again, maybe a slightly different use-case than what this proposal is targeting for initial implementation.

[sswany]

Thank you for the thought put into all of this. Bookstack has been a huge positive change for our company.

One suggestion related to 'Watch' is to have a setting that could allow for automatic watching of pages that are edited by the person editing. The use case would be that if we start using Comments (I assume we would with this implementation) I would think that if person A creates a page, person B updates it, followed by person C commenting on it, that the comment could very likely be related to edits by person B. Without person B manually watching the page when they edit, they wouldn't see the comment but person A would because they own it.

[ssddanbrown]

Thanks for the input @sswany.
I could see auto-watch of edited content be handy, as maybe being a future addition, if there's demand for it after the base proposal. Good to know that might be a demand at this stage since we can validate we won't be preventing that kind of addition later, which I don't think we are here, could be a thing that layers upon this fairly well.

[cdrfun]

I really like the proposal. I'd also prefer a digest mode, but I understand this is kind of complex and out of scope. However, I'd prefer to be able to set the debounce time as an environment setting.

Edit: The debounce time should also be mentioned in the notification email.

[ssddanbrown]

Thanks @cdrfun, what would you want to set the debounce to? I probably won't add the option in this initial release, in the event we significantly change direction after releasing the initial implementation, but it would be very simple to add as an env option afterwards if needed.

Edit: The debounce time should also be mentioned in the notification email.

Very good point, I'll update the proposal to include this.

[cdrfun]

I have a hard time guessing a good debounce time - that's one reason I'd favor a configuration variable for it. I think 90 to 120 minutes might be a good time for our editors. I'd rather encourage editors to make smaller changes more often without causing email flooding than being top notch always notified.

[JoeIzzard]

This would be a nice addition and for our use case, really help keep different teams informed over more general or style updates. I agree some form of digest would eventually be the best solution, even if it was something along the lines of delay sending the initial update message until X time (For us probably 9am the next day) and debounce messages until sent.

I'd also like to see the ability for an admin to control notifications at a group level. For example, we have a style document for working in our CAD package, we have five teams that use that package, all of which should be notified when we change our style guide.

Another potential nice feature would be the ability for an owner or admin to manually disable notifications for a book or page. This could further help when large updates are being made to a book over several days for example, but may be something for post initial version.

[ssddanbrown]

Thanks for the input @JoeIzzard. I'd probably stay away from any admin-side controls (outside of what's in the proposal) since that quickly adds a significant amount of UI, process and control level complexity that's I'd prefer to avoid. Though I don't think we'd be blocking ways to achieve that via implementation of this core proposal if deemed required in future. In fact, once this proposal is implemented, you could likely achieve those desired admin controls with a little inventive added logical theme system code to set notification watch preference based upon tags.

[ssddanbrown]

Proposal now implemented as part of #4390, ready for next feature release.

[jefry7]

is it possible to set default values? I would like to have notifications enabled by default

[ssddanbrown]

@jefry7 That is not part of the initial implementation added in v23.08.

[Redsandro]

This is very nice! 👍 I can get rid of the hook I shared here now.

I do have to say that pretty much everyone I'm giving this permission is asking me if I can enable it on a Shelve level. I have to say no:

Shelves. They will have no added support for this within this implementation, due to their more complex relationship and optional existence. I'd prefer for an initial implementation to be implemented first so any desired usage with shelves can be risen and discussed based upon actual need and experience of notifications in the system, so we can best decide how/if they fit into such a system.

In the case of my BookStack, Shelves are usually completely relevant or completely irrelevant to certain users. So people just open every book and set watch notifications. I think, ignoring the technicalities, one can argue that Shelves are the perfect level to set a watch exactly because of their dynamic relationship. It allows an admin to move books to a different Shelve and apprise all the "members of that shelve", or people who have subscribed to that shelve, to receive update notifications.