Using Data Values to Include or Remove PDF Form Pages

AutoMailMerge plug-in for Adobe® Acrobat®

Introduction

This tutorial demonstrates a way to delete or include certain form pages in output forms filled during a mail merge. This is achieved by using data values in the data source with JavaScript code.

To demonstrate this, the tutorial steps below show two different PDF forms being filled during a mail merge. Both will contain a template letter, addressed to different names. They will also be appended with one of two additional pages – “Addendum A” or “Addendum B”.

The input PDF form contains a form field for the "e.g.: Dear John Doe,..." text to be filled in, as well as both addendum pages:

The JavaScript code is used to identify which addendum page is to be added to each output letter, by using the value provided in the data source (spreadsheet). This is shown as an "Account Type" column with either an "A" or "B" value entered for each data entry (John Doe/Mary Smith).

Input Document Description

We demonstrate this function using an input PDF form that contains a one-page letter along with two “addendum” pages (A & B). The data source is a spreadsheet that contains the names of the letter recipients, and an "Account Type" value for both entries (see images above). This is either "A" or "B", and is used to instruct the plug-in on which addendum page the output PDF's should contain. An output PDF letter will be generated for each of the two spreadsheet entries, and they will contain only one of the addendum pages.

Prerequisites

You need a copy of the Adobe® Acrobat® along with the AutoMailMerge™ plug-in installed on your computer in order to use this tutorial. Both are available as trial versions.

Step 1 - Open the "Mail Merge" Dialog

Select Plugins > Mail Merge… to open the Mail Merge dialog.

If you are using a new Adobe Acrobat interface, then you can locate Mail Merge menu here:

Please see the following page for a short video tutorial on how to locate Plugins menu in the new Adobe® Acrobat® interface.

If you are using a "classic" Adobe Acrobat interface (pre-2022), then you can locate Mail Merge menu here:

Step 2 - Edit Mail Merge Settings

If necessary, clear current settings and then press the "Edit Settings…" button.

Press the "Browse…" button in the "Data Source" dialog to select the input data file.

Select a data type to use from the list (e.g.: Microsoft Excel Worksheet), then press "OK". Use the dialog that opens to locate and select the source file, then select the worksheet in the final dialog that opens.

Step 3 - Add Mappings

Use the buttons provided to map data fields to form fields before proceeding to the next settings pages by pressing "Next >".

Step 4 - Specify Output Options

Continue to the "Output Files" page to modify output options. Begin by selecting an output location via the "Browse..." button.

Now ensure that the "Save each copy of the filled form as a separate PDF document" option is selected.

The user also has the option to create a 'compound document' that contains all filled forms combined into one file. Check this option if you want to do this, and enter a filename into the entry box provided. In this example, we have the "Add bookmarks..." option selected so that the compound document can be easily navigated.

Lastly, use the "File Naming" section to create a file naming scheme for the output files. In this example, files will be named using a "Letter_1/2" format.

Press "Next >" to proceed to the final "Advanced" settings page.

Step 5 - Add JavaScript Code

On this screen, check the desired JavaScript action for adding code to be executed either before or after filling out forms. In this example, we use the "Execute this JavaScript code AFTER filling out each copy of the form" option.

See the entire code used in this example detailed here:

if (DataSource['AccountType'] == "A")
{
this.deletePages(2,2);
}
else
{
this.deletePages(1,1);
}

Ensure that the "Provide access to data source fields in JavaScript code" option is checked if it is necessary to access the data source record directly in the JavaScript. If this option is ON, then a DataSource object is automatically generated and added to the script. For example, if a data source record contains 3 fields: "First Name", "Last Name" and "Email", then the values of these fields can be accessed in the JavaScript code as DataSource['First Name'], DataSource['Last Name'] and DataSource['Email'].

The maximum allowed text string that is stored in the DataSource field variable is 1024 characters. The maximum allowed name of the field is 128 characters. Longer text strings will be truncated.

If a data source record has a lot of fields/data, adding a DataSource object to the JavaScript environment may take extra time required for parsing a much longer code. If speed is an issue, turn this option off and use an alternative way to get data source values. The alternative approach is to add a number of hidden form fields to the form and fill them using a regular mail merge approach. This way their values will be available in the script, but not visible on the form.

Press "Finish" once done.

Step 6 - Run the Mail Merge

The confirmed settings summary will now be listed with green circles. Optionally, save the mail merge settings as an *.mms file for later use by pressing the "Save Settings" button - use "Load Settings" to load them.

Click "OK" to start the mail merge process.

Press "Run Mail Merge" to confirm.

Step 7 - Open the Output Files

A results box will confirm the success of the operation. By default, pressing "OK" will open the selected output location.

Open the files to inspect them.

Step 8 - Inspect the Results

Inspect the file(s) to check that the correct form fields are visible/hidden according to the JavaScript code used. Here, we examine the 'compound document' to check that it contains both of the letters containing only "Addendum A or B" respectively.

The image below shows the letter addressed to "John Doe" which is appended with "Addendum A" due to the "Account Type 'A'" data value.

The image below shows the letter addressed to "Mary Smith" which is appended with "Addendum B" due to the "Account Type 'B'" data value.

Click here for a list of all step-by-step tutorials available.