Hosted by Three Crickets

Diligence
Web Framework
For Prudence and MongoDB

Diligence is still under development and incomplete, and some this documentation is wrong. For a more comprehensive but experimental version download the Savory Framework, which was the preview release of Diligence.

Diligence logo: sleeping monkey

Notification Service

Sending out email from your application can quickly become difficult to manage when you have hundreds of thousands of emails to send out. But Diligence's Notification Service is here to help! Some key features:
Note that Diligence connects to but is not itself an SMTP server. SMTP servers are complex beasts in their own right: they must handle errors and retries, queuing of outgoing messages, as well as incoming ones if they are configured for relaying or for mailboxes. It's a good idea to keep that separate from your main application. We like Postfix, a mature SMTP server that offers excellent scalability and security.
If you want your application to receive email, which is quite a different task than relaying it onward, then we can recommend the SubEtha SMTP library. If there's interest, we may incorporate it into Diligence directly in the future.

Usage

Make sure to check out the API documentation for Diligence.Notification.
Here's an example of two ways for queuing a notice, the first by a direct address, and the second to all subscribers of a channel:
document.executeOnce('/diligence/service/notification/') 
Diligence.Notification.queueForAddress('Email', 'email@myorg.org', {subject: 'The Subject', text: 'The content.})
Diligence.Notification.queueForChannel('main', {subject: 'The Subject', text: 'The content.'}) 
The first option doesn't require any subscription: it uses "Email" as the implementation (see "configuration," below), with the second argument being an identifier for that implementation (in this case, simply an email address). The second option queues the notice on the channel named "main". To add a subscription, you can do the following:
Diligence.Notification.subscribe('main', {service: 'Email', address: 'email@myorg.org', mode: 'daily'})
The "mode" key can be "immediate", "daily" or "weekly", with the latter two modes for digests. You don't need to create the channel itself: adding at least one subscription will automatically do that.
In the above examples we've sent plain text emails. To add HTML, add an "html" key. Note that if you use "html" you need to also add "text" to specify the plain text version. This is very good practice: not all email clients support HTML, and if they don't your HTML will be unreadable without a plain text fallback.
It might be useful to make use of the Sincerity.Mail.MessageTemplate class, which lets you store messages in text packs. For more information on text packs, see the Internationalization Service.

Configuration

In your application's "settings.js" you want to make sure to enable lazy configuration:
document.executeOnce('/prudence/lazy/')
And then add something like this to your app.globals:
app.globals = {
	...
	diligence: {
		service: {
			notification: {
				services: {
					'.': Prudence.Lazy.build({
						Email: {
							dependencies: '/diligence/service/notification/service/email/',
							name: 'Diligence.Notification.EmailService',
							config: {
								from: 'myaddress@mymail.org',
								site: 'Diligence Example'
							}
						}
					})
				}
			}
		}
	}
}
Note the use of Prudence.Lazy.build: this allows the Notification Service to lazily create the email implementation on demand during runtime. The key, "Email", will be used in subscriptions, as in the examples above. Note that it is case-sensitive. Within the lazy configuration, the "name" key is the class to instantiate, the "config" is sent to the class constructor, and values in the "dependencies" key are used for "document.executeOnce". Also note the use of the "." key to avoid flattening of the resulting lazy build (see Sincerity.Objects.flatten).
If you want to write your own service implementations, see the source code for the Diligence.Notification.EmailService.
To set up the background tasks for sending out queued notices, add something like the following to your application's "crontab":
   <% document.executeOnce('/diligence/service/notification/'); Diligence.Notification.sendQueuedNotices(); %>
 4  <% document.executeOnce('/diligence/service/notification/'); Diligence.Notification.sendQueuedDigests('daily'); %>
 5  0 <% document.executeOnce('/diligence/service/notification/'); Diligence.Notification.sendQueuedDigests('weekly'); %> 
The above will check for and send regular notices every minute, send daily digests at 4am, and send weekly digests every Sunday at 5am. As stated above, you can have this same "crontab" running on many nodes. Because the implementation relies on MongoDB's atomic updates, you can be sure that notices will not be sent more than once.

The Diligence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.

Download manual as PDF Creative Commons License