Help

Contact

If you need help in any way please don't hesitate to contact Craig Broadbear from Broadgun Software.
email: craig@broadgun.com
phone: +61 387260105

First Steps

Create a new merge profile

A merge profile contains all the data and options related to a email merge.

Upload a CSV file

A CSV is a comma separated values file, which allows data to be saved in a table structured format. CSVs look like a garden-variety spreadsheet but with a .csv extension. CSV files can be output by any spreadsheet program, such as Microsoft Excel, Open Office Calc, or Google Spreadsheets. The top row of the CSV must contain column headings. Each heading corresponds to a merge field. When saving a CSV, make sure it's UTF8 encoded.

Setup email headers

A merge field such as 'email' must be selected as the TO address. Some email servers require a FROM address to be specified. Note how merge fields can be placed in the addresses or the subject.

Create email body

Select a pre-existing email body to edit or start with a blank one.

Create email attachment

You can attach any file to be sent with an email (static attachment) or you can setup a dynamic PDF attachment. The dynamic PDF is created from a template. A pre-existing template can be selected and modified. The template fields are replaced with data from the datasource file.

Setup SMTP email account

You need to have your SMTP email configuration details handy. pdfm uses your email server to send the emails. Your email authentication details are encrypted and stored on our server.

Send emails

It is a good idea to test your emails by sending a few to yourself to see if they are ok. Do this by checking 'test mode'.

Templates & Nunjucks

pdfm uses the Nunjucks templating language to convert merge fields into values. The examples below assume the following data source file that looks like:

email name amount startdate
dave@test.com Dave 1230 22/03/2016
dave@test.com Dave 1000 23/03/2016
fred@test.com Fred 100 23/03/2016


When a merge is running, pdfm steps through each row in the data source file, combining each row with templates to produce the email "to" address, email subject, email body and PDF attachment. The email is then delivered.

e.g. Template usage for an email subject line. There exists an output for each row in the data source. 
                Input:  Dear {{name}}, Find attached your details.

                Output 1: Dear Dave, Find attached your details.
                Output 2: Dear Dave, Find attached your details.
                Output 3: Dear Fred, Find attached your details.

Custom Filters & Tags


In addition to the standard Nunjucks features the following custom filters are supported.

sum filter

Totals up a column in the data source. The column name is accessed by the "_cols" variable.

This can be used when the "Rows to emails method" is set to "one or more rows generates an email", which has the effect of grouping the rows based on a merge field, usually the email address. 

                Input: The total for {{name}} is {{ _cols.amount | sum }}

                Output 1:  The total for Dave is 2230
                Output 2:  The total for Fred is 100

date filter

Parses and formats a date. Takes as parameters an input format and an output format. Uses the moment.js library.
e.g. date("input format", "output format")

The input format is described: moment input strings
The output format is described: moment output format 

                Input:  The date is {{ startdate |  date("DDMMYYYY", "MMMM Do YYYY") }}
                Output: The date is March 3rd 2016
                
                Input:  The date is {{ startdate |  date("DDMMYYYY", "YYYY-MM-DD") }}
                Output: The date is 2016-03-03

money filter

Money formatter. Uses the accounting.js library .
The money filter optionally takes parameters :
currency symbol, precision, thousands separator, decimal separator, format 

                Input:  The amount owed is {{ amount |  money }}
                Output: The amount owed is $1,230.00
                
                Input:  The amount owed is {{ amount  | money("€", 2, ".", ",")}}
                Output: The amount owed is €1.230,00

number filter

Number formatter. Uses the accounting.js library .
The number filter optionally takes parameters :
precision, thousands separator, decimal separator 

                Input:  The amount owed is $ {{ amount |  number }}
                Output: The amount owed is $ 1,230.00
                
                Input:  The amount owed is € {{ amount  | number(2, ".", ",")}}
                Output: The amount owed is € 1.230,00

repeat tag

Repeats the current table row, list item or div. This is a shortcut for the Nunjucks 'for' loop.
Specifically, the nunjucks tag "{% for row in _rows %}" is placed in the parent tr, li or div tag.

This can be used when the "Rows to emails method" is set to "one or more rows generates an email", which has the effect of grouping the rows based on a merge field, usually the email address.

The Nunjucks for loop which does not work well for visual html editors when used around table rows, so this is the preferred option.

Note in the example the merge field names must be prefixed with "row." 

                Input:
                     

                        

                            Name
                            Amount
                        

                        

                            {%repeat%}{{row.name}}
                            {{row.amount}}
                        


                    

                Output:
                     

                        

                            Name
                            Amount
                        

                        

                            Dave
                            1230
                        

                        

                            Dave
                            1000

_rows and _cols

These are arrays, containing the rows and columns of the current merge record. 

                Input: {% for r in _rows %} amount {{r.amount}} {% endfor %}, total: {{_cols.amount | sum}}
                Output:  amount 1230 amount 1000,  total: 2230

$page and $maxpage

These are special variables that only work on stationery. They are set to the current page and maximum page number in a PDF.

e.g. if the resulting PDF is 3 pages: 

                Input:  page {{$page}} of {{$maxpage}}
                Output page 1: page 1 of 3
                Output page 2: page 2 of 3
                Output page 3: page 3 of 3

$fn tag

This is the attachment file name.

e.g. if the attachment is named: 'payslip for Jeff Blogs.pdf' 

                Input:  file - {{$fn}}
                Output:  file -  payslip for Jeff Blogs.pdf

Security

pdfm encrypts all sensitive data such as email authentication details and CSV data files in transit and at rest. The master key to the encryption does not reside on disk anywhere - only in the heads of two Broadgun Software employees. Access to our servers is strictly controlled and two factor authentication is used. Our servers live in high security data centers.