Skip to content

Latest commit

 

History

History
224 lines (167 loc) · 8.42 KB

README.md

File metadata and controls

224 lines (167 loc) · 8.42 KB
Raw

Prevem: Open source preview manager for emails

Prevem is a batch manager for email previews. It provides a RESTful CRUD API which works with two agents:

  • Composer - The mail user-agent (MUA) in which a user prepares a mailing. Generally, the Composer submits a PreviewBatch and polls to track its progress.
  • Renderer - The backend service which prepares a screenshot of how an email would appear when read in different MUAs. Generally, a Renderer polls for a pending PreviewTask record, prepares a screenshot, and then marks it as completed.

All three components (prevem, the composer, and the renderer) have been/are being developed as a part of a project called Email Preview Cluster which is meant to help users (of CiviCRM) to generate previews (screenshots) of their emails to see what they'll look like to receivers on various email clients.

Getting Started

1. Setup the Preview Manager (prevem)

The preview manager (prevem) is based on Loopback, an open-source framework for creating RESTful APIs in NodeJS. It stores the list of pending jobs as well as the resulting image files. To set up prevem on your machine, follow these steps:

$ git clone https://github.com/civicrm/prevem
...
$ cd prevem
$ npm install
...
$ node .
Browse your REST API at http://0.0.0.0:3000/explorer
Web server listening at: http://0.0.0.0:3000/

2. Setup the Webmail Renderer

The Webmail Renderer is a Node.js application which periodically polls prevem to claim a pending preview task, prepare a screenshot, and upload the final image. Currently, there are two webmail renderers (Gmail and YahooMail). The renderer depends on Selenium Server for browser automation.

The webmail-renderer is automatically downloaded by npm install, but you must configure and start it:

$ cd node_modules/webmail-renderer
## If you don't already have Selenium Standalone Server installed on your machine, run the following 2 commands.
## You can skip them otherwise.
$ npm install selenium-standalone@latest -g
$ selenium-standalone install

## Create a config file
$ cp config.json.template config.json
$ vi config.json   (<== Put in gmail and yahoo credentials==>)
## The sender credentials should be of a gmail account with reduced security, i.e., "Allow Less Secure Apps" should be ON.
## You don't need to change the prevemURL and prevemCredentials fields.
## These entries match the default Prevem URL and the credentials that the renderers use to login to the Prevem.

## Run the renderers
$ nodejs gmail.js
$ nodejs yahoo.js ##In a new Terminal tab
##These nodejs scripts will keep running in the background and render any tasks pitched up to them.

3. Setup CiviCRM

  • Pull this branch of civicrm-core to your machine.
  • Now in your CiviCRM, navigate to Administer > CiviMail > CiviMail Component Settings.
  • Set your Prevem URL from there.
  • Alternatively, you can use the CLI to configure the prevem_url:
$ drush cvapi setting.create prevem_url="http://consumerId:consumerPass@localhost:3000"

The prevemURL is to be written in the said format. Here's what those terms in it's definition mean.

consumerId Your consumer ID on the Prevem. Every preview batch you request would be carrying this Id to distinguish your preview batches from the others. This will also be used to login to the Prevem.

consumerPass Your secret password which will be used to login to the Prevem.

localhost:3000 Change this if you are hosting your Prevem somewhere other than localhost:3000

4. Create a prevem user account

Start your prevem, by doing node . as given in section 1 of the setup. Go to prevem_url/explorer/#!/Users/create (e.g. http://0.0.0.0:3000/explorer/#!/Users/create). You'll find your REST APIs there. In POST Users/ section, inside the data input box enter your details in the following format and then click on the Try it Out box.

{
  "email":"consumerId@foo.com",
  "password":"consumerPass"
}

That completes your setup. You are now ready to use your Email Preview Cluster Service. You can simply go to your CiviCRM mailing page and request previews.

See also