Mail Merge

With its mail merge feature, n2pdf lets you create form letters of predominantly identical content except for the placeholders, or merge fields, in which variable information can be inserted. This means you don't have to manually generate the PDF file x number of times. You simply use n2pdf to make a PDF template and then use the n2pdf fields to generate x number of documents with different text replacements from this PDF template. You can create a unique PDF file for each replacement or you can merge all the documents into one complete PDF file.

The fields work under the same principle as the variables, but can be defined (filled with data) x number of times, thus forming one data record each time they are filled. Each data record then generates one new document from the PDF template. Just like the variables, the fields are positioned within the Notes RichText fields or in plain text with a name and a specific syntax.

Content for a field is specified with the command N2PDFAddField. At the present time only unformatted content can be supported. A new field is defined each time the function is activated. To generate a data record, assign the parameter N2PDFVALUE_MAIL_MERGE_NEW_RECORD to the function. Fields within the PDF template are introduced with the character "{", followed by the name of the field and then closed with the character "}". A name formatted in such a way (see delimiters under "System Settings") is recognized as a field and can then be filled with the content that was specified by N2PDFAddField.

The following is an example of creating data records, defining fields in the text and the results of text replacement:

Example for defining fields (2 data records with 2 fields):

Call N2PDFAddField (JobID, N2PDFVALUE_MAIL_MERGE_New_RECORD,_

"Salutation", "Mr. " )

Call N2PDFAddField (JobID, 0, "Lastname", "Doe" )

Call N2PDFAddField (JobID, N2PDFVALUE_MAIL_MERGE_New_RECORD,_

"Salutation", "Mrs. " )

Call N2PDFAddField (JobID, 0, "Lastname", "Smith" )

Example for two fields in one RichText field:

Dear {Salutation} {Lastname},

n2pdf has received a considerable increase in functionality: The table of contents …

The two examples above result in the following text:

Dear Mr. Doe,

n2pdf has received a considerable increase in functionality: The table of contents …

Dear Mrs. Smith,

n2pdf has received a considerable increase in functionality: The table of contents …

The mail merge function of n2pdf must be activated to ensure it will be performed (according the example above) when N2PDFProcess is initiated. Activation is made using the N2PDFSetOption function:

Call N2PDFSetOption ( JobID, N2PDFOPTION_MAIL_MERGE_MODE,_

N2PDFVALUE_True,"" )        

You can also specify if one single PDF file is to be created for the mail merge. This means you can decide for each PDF template if the content is to be written as the fields are inserted, i.e. together in one file, or if one single PDF file will be created. This option can be set using N2PDFSetOption and the parameter N2PDFOPTION_MAIL_MERGE_SINGLE_FILE.

Examples of a PDF File:

Call N2PDFSetOption ( JobID, N2PDFOPTION_MAIL_MERGE_Single_FILE,_

N2PDFVALUE_True,"" )

If the entire content of the mail merge is to be made in one PDF file, then it makes sense to have each new document start on a new page. This can be activated using the option N2PDFOPTION_MAIL_MERGE_PAGE_BREAK.

Example:

Call N2PDFSetOption ( JobID, N2PDFOPTION_MAIL_MERGE_PAGE_BREAK,_

N2PDFVALUE_True,"" )

Once all the options and fields have been set, you can activate the entire mail merge procedure using N2PDFProcess. The file name of the PDF to be created is specified when the function is called up. In the event that you chose the option of having a single PDF file created for each data record, then the number of the data record will be attached to the PDF's file name.

Example:

Call N2PDFSetOption ( JobID, N2PDFOPTION_MAIL_MERGE_Single_FILE,_

N2PDFVALUE_False,"" )

PDFFileName = "C:\Temp\Default.PDF"

Call N2PDFProcess ( JobID, PDFFileName, 0 )

File names created during a mail merge in multiple PDF files:

"C:\Temp\Default[1].PDF"

"C:\Temp\Default[2].PDF"

"C:\Temp\Default[3].PDF"

…