Mapping Form Fields

This article assumes you have already installed the PDF Forms Filler for WPForms plugin and attached a PDF file containing form fields to your WPForms form.

Now we’ll focus on creating a seamless experience where website visitors can complete your WPForms form and automatically receive a filled PDF file—either via email or through a download link. This functionality is achieved by mapping your WPForms fields to corresponding fields in your PDF document.

For demonstration purposes, this guide uses a demo PDF file.

Mapping WPForms Fields to PDF Fields

The Field Mapper Tool allows you to create connections between your WPForms fields and PDF form fields. To access this tool, navigate to the Settings screen and select the PDF Forms tab.

The Field Mapper Tool consists of three main components:

1. Manual Field Mapping Section - Contains two dropdown lists (WPForms field dropdown and PDF field dropdown), allowing you to create one-to-one mappings between existing fields in your WPForms and PDF forms.

2. Field Creation and Mapping Tools - Provides options to create new WPForms fields and map them automatically. You can either map individual fields or generate fields for all unmapped PDF fields at once.

3. Mapping Management List - Displays all existing field mappings and value mappings. Here you can review, modify, or remove mappings as needed.

WPForms Field Dropdown

The WPForms fields dropdown displays all existing fields within your form. To map an existing WPForms field to a PDF field, first select the appropriate field from this dropdown list.

PDF Field Dropdown

The PDF field dropdown displays all available form fields found in your attached PDF document.

At the end of the dropdown list, you may notice duplicate field names with a numeric identifier [ID] preceding the field name. These specially marked fields are associated with specific PDF attachments, while fields without an [ID] apply to all attached PDFs. This distinction is important when your form has multiple PDF attachments that might share field names.

When creating your mappings, you can choose whether to map to a specific PDF file or to all PDFs with matching field names:

• Selecting a field without an [ID] will apply the mapping to all PDF files that have a field with that name
• Selecting a field with an [ID] will apply the mapping only to the specific PDF attachment with that ID

Important: Only use field mapping with [ID] when necessary. If you delete or detach the PDF attachment from your WPForms form, all field mappings associated with that specific attachment ID will be permanently deleted.

PDF Replacement Tip: If you need to update your PDF file with a newer version, replace it directly on the server (via FTP or file manager) rather than detaching and reattaching it. This preserves all your existing field mappings associated with the PDF’s ID.

Creating & Mapping Fields

The plugin offers several efficient methods to create and map fields in a single operation. Choose the approach that best fits your workflow:

1. Insert & Link All button (Recommended)

   This is the most efficient method for new forms. With a single click, this button automatically:

   • Creates WPForms fields for all unmapped PDF fields
   • Inserts these new fields into your WPForms form
   • Creates mappings between the WPForms fields and their corresponding PDF fields

   This approach saves significant time when working with complex PDF forms containing many fields.

2. Insert and Link button (For individual fields)

   When you select a specific field in the PDF field dropdown, a New Field hint appears below the dropdowns. This option allows you to:

   • Create a single new WPForms field based on the selected PDF field
   • Insert it into your form
   • Create the mapping in one operation

   Insert and Link Field Option

   

3. Manual Mapping (For existing fields)

   If you’ve already created your WPForms fields and simply need to establish the connections to your PDF fields:

   • Select the corresponding field in the WPForms field dropdown
   • Select the matching field in the PDF field dropdown
   • Click the Add Mapping button to create the connection

Input Format Requirements

One of the most critical aspects of successful field mapping is ensuring that the format of data from your WPForms fields matches the expected format of your PDF fields. Format mismatches are a common cause of fields not being filled correctly.

For example, if your PDF contains a date field expecting the format dd/mm/yyyy, your WPForms field must provide data in exactly this format. Different PDF field types have specific format requirements that must be met.

Important: If the data format from your WPForms field doesn’t match what the PDF field expects, the PDF field will remain empty in the final document.

PDF Field Types and Format Requirements

The table below outlines the various PDF field types and their format requirements. Understanding these requirements is essential for successful field mapping:

PDF Field Type	Expected Format	Description
Text	Any text	Standard text fields that accept any string input
Text (Numeric)	Numeric value	Text fields configured to accept only numbers
Text (Percentage)	Percentage value	Text fields formatted to display percentages
Text (Date)	Specific date format	Text fields that require dates in a specific format (e.g., MM/DD/YYYY)
Text (Time)	Specific time format	Text fields that require time in a specific format (e.g., HH:MM)
Text (Zip Code)	5 or 9 digit format	Text fields formatted for postal codes (e.g., 12345 or 12345-6789)
Text (Phone)	Phone number format	Text fields expecting phone numbers in a specific format
Text (SSN)	XXX-XX-XXXX format	Text fields formatted for Social Security Numbers
Text (Custom)	Custom JS validation	Text fields with custom JavaScript validation requirements
Checkbox	Export value (e.g., “Yes”)	Binary fields that are either checked or unchecked
Radio Button	Exact export value	Fields that allow selecting one option from multiple choices
List Box	Valid option value	Fields that allow selecting one or more items from a list
Combo Box	Valid option or custom text	Dropdown fields that may also accept custom text input

Note: For date fields, you can use WPForms Smart Tags with custom formatting to ensure your dates match the required format.

Testing Your Field Mappings

Important: Always remember to save your form after creating or modifying field mappings. Your mapping configurations won’t be preserved until you click the save button.

After completing your field mapping configuration, it’s essential to test your form to ensure everything works as expected. Click the Preview button in the WPForms editor to view your form. You can then fill it with test data to verify the layout and functionality:

When you submit the test form, the designated recipient (as configured in your form’s notification settings) will receive an email with the filled PDF attachment. The PDF should contain all the form data properly placed in the corresponding fields, as shown in this example:

Troubleshooting Field Mapping Issues

If you encounter problems with your field mappings, check these common issues:

1. Format Mismatch - Ensure the format of your WPForms field data matches what the PDF field expects (especially for dates, times, and numbers)

2. Missing Mappings - Verify that all necessary fields are mapped by reviewing the mapping list

3. PDF Field Restrictions - Some PDF fields have validation scripts that reject improperly formatted data

4. Checkbox Values - For checkbox fields, ensure the WPForms field value matches the PDF field’s export value (typically “Yes” or “On”)

5. Multiple-Choice Fields - For radio buttons and dropdowns, the WPForms field value must exactly match one of the PDF field’s predefined options

For more complex issues, refer to the FAQs section or consider using value mappings to transform your form data into the format expected by the PDF.