Instant e-mail notification of changes

Category: TWikiPatches

This is what I added to MegaTWiki to have instant notification when somebody changes a web page. I guess it should work for the regular codebase as well, but I didn't try that.

I coded it because we use TWiki on our intranet, and there you typically have much faster turnaround times in the topics. Also, I wanted to have diffs of what had been written, so it is instantly clear if you need to reply or not.

So this is not a replacement, but another option of doing notifications. See EmailNotificationEnhancements for an overview of efforts.

What it does do

• When you save a topic, it calls the program that does the notifications, topicnotify .
• topicnotify will get the list of interested people using the regular TWiki functions.
• Then it will retrieve the diffs using TWiki::Store, and try to make them pretty. I made it so that it supports both regular diffs (where you get a list of added and deleted lines) and uniform diffs (where you get text fragments with added and deleted lines inline). The rendering is done in text.
• Then it sends a mail using a template.

What it doesn't do

• it has no mechanism to register interest in just one page, that is an orthogonal problem.
• it doesn't handle replies (yet). That is an orthogonal problem.
• it has no notifications of renaming/moving/deleting/what have you, only of changes done through the save script. This is not impossible or even difficult, it just needs hooks that need to be written and mail templates. (or only one template with a smart way of saying what happened)
• it doesn't generate a HTML formatted mail section. I don't need one. If you do, please write it
• it doesn't break text in 78 character lines so that larger paragraphs render nicely in mail readers. This would also be nice in the edit script, where it would format paragraphs with better indentation while making sure the TWiki HTML output stays the same.
  Example:

     * this is a long paragraph (just play along ok?) long long long
  long long long
       

  Should be rendered in the editor pane as:

     * this is a long paragraph (just play along ok?) long long long
       long long long
       

  which has the same output. But I digress.

The code

Feel free to put changes to the code here, and I would be really happy if some version of this gets into the main code tree

There is the topicnotifyprogram and the templates (attached), and to use it you need to change save as follows:

--- ../../cvs/twiki/bin/save    Mon Oct 14 12:00:42 2002
+++ save        Wed Aug 28 22:15:07 2002
@@ -131,5 +131,9 @@
         TWiki::redirect( $query, $url );
     } else {
         TWiki::redirect( $query, &TWiki::getViewUrl( "", $topic ) );
+       TWiki::writeDebug("save:  $dontNotify; $TWiki::notifyProgram $webName $topic");
+       if ( $dontNotify eq "" && $TWiki::notifyProgram ne "" ) {
+               system("$TWiki::notifyProgram $webName $topic");
+       }
     }
 }

and you need to add the $TWiki::notifyProgram to the TWiki.cfg file, together with a -u option on diff if you like the unified format:

+#                  Which program will send out immediate notification on save
+#                  Set to "" if you don't want that
+$notifyProgram    = "$wikiRootDir/sbin/topicnotify";
+#                   Who will the mail be sent as?
+$notifyFrom       = 'twiki@bru-cse-apps.cisco.com';

-    diffCmd       => "$rcsDir/rcsdiff $rcsArg -q -w -B -r%REVISION1% -r%REVISION2% %FILENAME%",
+    diffCmd       => "$rcsDir/rcsdiff $rcsArg -u -q -w -B -r%REVISION1% -r%REVISION2% %FILENAME%",

That's it. Let me know if something is missing, I made a lot of changes and I still need to consolidate with the CVS trunk.

Please try it out if you're interested, and maybe we can chunk out useful routines for in TWiki.pm if someone wants to make the Ultimate Notification Tool.

-- WoutMertens - 13 Nov 2002

Comments

Interesting patch - I would like to see this added as an option to the existing mailnotify rather than going into a separate program, and also to have some way of controlling (1) whether this runs at all on topic save (via TWiki.cfg, using an option for mailnotify) and (2) who gets these InstantNotifications.

One possibility would be to have a setting on each WebNotify page that says 'instant' after the WikiName (and optional email address). [It would also be handy to have some other scheduling options, though that's really another feature (e.g. every hour, every 6 hours, every week).]

Also, it would be helpful to have a 'notify someone specific now' at topic save time, by specifying particular users or email addresses to get a notification, as in CopyToEmail and PhotonSkin.

It would be good to get the best of all these ideas, and ideally to create a plugin architecture so that different notification enhancements can be tried out through plugins.

The key steps in a notification action seem to be:

1. Trigger notification (on event or scheduled) - e.g. on topic save, on user-specific schedule, or on per-web or global schedule
2. Determine topics changed - e.g. this topic on topic save, or all topics since last time, or include/exclude specific topics
3. Determine notification recipients - e.g. someone specified in topic change, or through WebNotify, or through specific info in topic (e.g. a 'watch for changes in this topic' feature, a bit like CopyToEmail and many NewsGroups readers, for better ConversationTracking).
4. Determine notification method - e.g. email, InstantMessaging, IRC, JabberWiki, NewsGroups, TWikiSyndication, SMS (text messages to mobile phones), etc.
   • Some methods would require significant filtering - different schedules might be needed for different methods.
5. Generate notification contents - e.g. list of topics, text/HTML, full diffs, different diff formats, etc.
6. Send the notification contents, using method, to selected recipients, covering topics changed

Ideally, all of these steps could involve separate plugin calls - that way, your site could just have a simple plugin that hooks the topic-changed event but doesn't change much else, while other sites could filter the changed topics or recipients, without mandating a particular approach.

Please see the PatchGuidelines as well (have added unified diff as a recommended format )

-- RichardDonkin - 15 Nov 2002

Thanks for those comments.

I agree on most of your ideas (although I don't think they should be part of this patch ). I guess the code that generates the people that are interested in a change (getNotifyList or something along those lines) is due for some feature additions.

I agree with your logic breakdown of notifications. Here's a list of likely hooks for plugins:

• Time interval for bulk notification expired
• A topic was changed
• Somebody is interested in a type of notification
  • The plugin would have to register the type up front
  • The system for registering would likely be a plugin as well...

Hmmm. TWiki should have functions to get the list of interested parties for a certain page and notification method.

I guess we'll just have to crank out some systems and see what we like best.

-- WoutMertens - 23 Nov 2002