Bhima Mail Plugin

Introduction

The mail plugin allows for customized reports to be emailed on a regular basis. The plugin is modular, and designed to allow reports to be added, easily configured, and scheduled both on the fly and at start up via config files.

Dependencies

This plugin depends on q and later installed. Both are available via npm: npm install q later. If you have bhima installed (you should), q is installed with bhima.

Folder organization

The mail plugin is organized in a modular fashion to be relatively stand-alone. Like all plugins, it is meant to be run as a child process via the bhima plugin manager. A breakdown of the components is as follows:

# contents of plugins/mail/
addresses/
  - lists.json        # contains the specifications for an address list (composed of contacts from contacts.json)
  - contacts.json     # contains each individual contact's information
archive/
  -                   # contains gzipped archives of previously sent emails (generated by lib/archive)
index.js              # entry point of module.  Instantiates the email plugin, schedules email
config.js             # contains the plugin configuration, including address lists and schedules for emails
lib/
  - archiver.js       # performs gzipped backups of sent emails for future reference
  - query.js          # mail plugin interface to the bhima database
  - render.js         # micro templating engine
reports/              # email reports are specified in individual folders here
  daily/              # template, queries, and data for daily report
    - daily.tmpl.html # html template to be rendered
    lang/             # contains i18n JSONs
      - en.json       # English text
      - fr.json       # french text
    - queries.json    # database queries required for this report.

Philosophy

The mail plugin tries to be as modular and clear as possible. A single html template is used with handlebarjs-style markup. All data queries are contained in a single file, with name conventions enforced within the templating scheme.

Internationalization is identical to data queries. Each recipient has a specified language. Every line of text is stored in a i18n/{{language}}.json file, and is templated into the email. Be sure that you have a contacts language stored before you attempt to send an email to them.

Each email report must be self-contained, with the idea that the mail plugin will call a preprocess script to generate the HTML template before passing it along to the email sending client. The benefit of having to call this preprocessing script for each email is that new reports can be dropped in simply by copying a file folder and modifying the list of plugins in config.js.

Developing new reports

All emails are defined in the reports/. To add a new report, ensure that the report name is the same as in the configuration file and simply drop the report folder into reports/.

LICENSE

All work herein is licensed as GPLv2.