Jump to content

Extension:SemanticMailMerge

From mediawiki.org
MediaWiki extensions manual
SemanticMailMerge
Release status: unmaintained
Implementation Notify
Description Allows sending emails based on the a result-set of a query and specified template.
Author(s) Sam Wilson (samwilsontalk)
Latest version 0.0.2 (2013-11-29)
MediaWiki 1.20+ and SMW 1.8+
PHP 5.3+
Database changes Yes
Tables smw_mailmerge
License GNU General Public License 3.0 or later
Download
README

The SemanticMailMerge extension integrates with Semantic MediaWiki to merge each result of a semantic query into a template and email the resultant HTML to recipients specified in the query.

Installation

[edit]
  • Download and place the file(s) in a directory called SemanticMailMerge in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php file:
    require_once "$IP/extensions/SemanticMailMerge/SemanticMailMerge.php";
    
  • Run the update script which will automatically create the necessary database tables that this extension needs.
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Usage

[edit]

Akin to the standard 'template' result format, this extension requires two pages: one with the {{#ask: }} query, and one template (specified in the query). The output of the query is the same as the 'table' result format, and the data from each row is put into the template and emailed to all email addresses specified in the 'To' column. You have to use mailmerge as the result format option within the semantic query.

To preview the output, change |format=mailmerge to |format=template (although they may run into each other, depending on the formatting in the template).

The actual email-sending is done separately, so that it can be scheduled (by an external task-system such as crontab or Scheduled Tasks). On the required schedule, the SemanticMailMerge/maintenance/send.php file should be called:

php SemanticMailMerge/maintenance/send.php --title=Title_of_page_with_query

Example

[edit]

To send an annual review reminder to all document authors the following three pages could be used:

  1. Joe's Document
    [[Author::Joe Bloggs]], [[Author email address::joe@example.org]].
    
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec a diam lectus. Sed sit amet ipsum mauris.
    
    [[Category:Documents]]
    
    Although individual data pages would be likely to use a template.
  2. Template:Document reminder
    Dear {{{?Author}}},
    
    You are an author of [{{canonicalurl:{{{?Title}}} }} {{{?Title}}}], a document which is up for annual review.
    
    It was last edited on {{{?Modification date}}}.
    
    This could, of course, pull its content from elsewhere in all the usual ways. Note also the use of canonicalurl, because this will be used in a non-wiki context (i.e. a mail client).
  3. Document reminder
    {{#ask:
    [[Category:Documents]]
    [[Modification date::<{{#time:Y-m-d|-1 years}}]]
     |?Author email address=To
     |?Author
     |?Modification date
     |format=mailmerge
     |template=Document reminder
     |mainlabel=Title
     |named args=yes
     |link=none
    }}
    

The reminders would then be sent by calling the following as often as required:

php SemanticMailMerge/maintenance/send.php --title=Document_reminder

Notes

[edit]
  • Uses the $wgPasswordSender value as the 'From' address.
  • Query results must have a 'To' column containing email addresses (multiple addresses in the one result are fine).
  • The email subject is the title of the page which contains the query.

Outstanding problems

[edit]
  • Page moves. If a query page is moved, the data referring to its old location is not purged.
  • Custom recipients' column. Currently hard-coded as 'To'. Perhaps not customizable, but should at least be localized.
  • Links in the HTML for the email need to be expanded to be canonical URLs.
  • Permit more than one query on a page (does an {{#ask:}} query have an identifier?). Currently uses the page title to identify it.
  • Support userparam.