Pixel Perfect PDF Overview

frevvo's Pixel Perfect PDF generation feature allows you to integrate your form's data with any acroform PDF.  You can view mapped PDFs in your Submissions repository. You can also email mapped PDFs, and/or save them to a file system, Google Drive, or a database. This tool is often used in cases where a specific PDF format is required, such as to complete federal tax forms in an Employee Onboarding Workflow.

• frevvo' Pixel Perfect PDF generation feature is supported in both the Form and Workflow Designers.

• frevvo uses a web-based mapping scheme where the designer can map form fields to PDF fields within the visual context of the PDF. 

• You will need an "acroform" to generate a pixel-perfect PDF. Acroforms (also known as Acrobat forms) are forms that contain writable fields.

• You can generate as many PDFs as you like.

• You can use the Generate Pixel Perfect PDFs#Step 5-FormViewerControl control to allow users to view the mapped PDF from within the form itself.

Limitations

PDFs mapped in the Form Designer will carry over when you add that form to a workflow. However, mapped PDFs will not be preserved when a workflow step is downloaded as a standalone form. 

Import of forms created in previous versions will preserve all PDFs and mappings.

• Adobe XFA Forms are not supported.

• Password or sensitive text fields being transferred to a PDF form will be written in plain text if they are mapped to a PDF field.

Generate a PDF Form

Follow these basic steps for each Pixel Perfect PDF your form/workflow will generate.

1. Obtain the acroform PDF that you want to populate with frevvo data.

2. Design your frevvo form/workflow to collect the information that you will map to the PDF.

3. Upload one or more PDF acroforms.

4. Map the fields in your form to the fields in the PDF acroform.

5. Add the Form Viewer control to your form/workflow.

6. Test the form/workflow and generated PDFs.

Step 1 - Obtain the Acroform

You must have an acroform PDF for successful mapping in frevvo. Acroforms are PDFs that contain writable form fields. There are many acroforms available on the internet. For example, the latest acroform for the federal W-4 Employee's Withholding Allowance Certificate can be downloaded from the IRS website.

If you cannot find an acroform to use, use a tool like PDFescape to create a PDF with writable fields. Refer to the mapping rule guidelines in the Generate Pixel Perfect PDFs#PDFFormGenerationRules below.

Some acroforms may not have a writable field for all of the data that you want to collect. For example, the signature field on W-4 downloaded from the IRS website is not writable. You can use a PDF editor such as PDFescape to add a writable text field for the signature to your acroform template. frevvo signatures are treated as images that can be mapped to text fields. Here is an example of a PDF acroform for the US federal W-4 Employee's Withholding Certificate. Notice the blue highlighted writable form fields, and the green selected signature field that we added.

Step 2 - Design Form/Workflow to Collect Information

Add controls to your forms/workflows to collect the information that you need for the PDF. For example, many forms/workflows contain separate fields for the user's First Name and Middle Initial. The first name field on the W-4 PDF requires the user's first name plus middle initial. To supply the information in this format, the designer can include a hidden control on the form that is populated by a Business Rule that concatenates the data in the first name and middle initial fields.

Designers should give Group Controls meaningful names whenever possible to help differentiate them when using the Generate Pixel Perfect PDFs#Step 4-MaptheLiveFormfieldstotheacroformfields.

Step 3 - Upload PDF

Click PDF Mapping in the Form/Workflow header.

The list of existing PDFs (if any) will appear. For example, the Employee On-boarding workflow shown below will generate a PDF for the NY-W4, CA-W4, and Federal W-4 forms when the user clicks Submit or the Form Viewer control.

Each PDF in the list will have a status icon.

• A green status icon indicates the mapping is complete.

• A yellow status icon indicates the mapping is incomplete.

• A red status icon indicates a mapping error.

Click Add . Upload the acroform for the PDF on the New Form Generation screen. The acroform serves as a PDF form generation template. Enter a template name, or leave this field blank to use the filename instead. The template name can be up to 30 characters. You can use Templatized Strings when naming your template. For example, naming the template 'W-4 {LastName}' results in a PDF filename such as 'W-4 Smith'. If you do not select a file and you try to submit this screen, you will see the message "Form Template file is Required".

Uploading a file that is not an acroform results in the following error “Invalid PDF: Password protected, non-reader Enabled, XFA, etc.”:

The generated PDF are read-only by default, meaning the fields you mapped from frevvo cannot be changed on the published document. Choose Generate as fillable form to keep all fields in the final document editable, including any fields that contain mapped data. This would be useful if, for example, an Office Use Only section of the PDF would need to be completed after the workflow is submitted.

Notice that your newly uploaded template is added to the PDF list. Click the  icon to edit the template name. 

Click the  icon to remove the template. This action removes the generated form and all field mappings.

Preconditions for PDF

You can set up the logic for the PDF via a precondition that will control when the PDF will be generated or skip the PDF entirely. For example, let's say you want to generate an English version and a Spanish version of a PDF. Preconditions can be used to determine which PDF is used at runtime.

For example, your form/workflow contains a Radio control named Language with two options: English and Spanish. You have mapped an English PDF and a Spanish PDF. Click Precondition for the English form. The Precondition Rule Builder is automatically toggled "on." Click Edit to launch the Precondition Editor and add the condition.

If you prefer to use JavaScript to create or edit the precondition, click on Precondition then toggle the Precondition Builder Off. Type the JavaScript into the field.

The Precondition Editor checks the expression for valid JavaScript and displays appropriate error messages when necessary. Preconditions are re-validated when you Save and Test, Save and Close, or return the PDF Mapping page. If there is an error, an on-screen notification will give you the option to edit it or cancel (ignore.)

With this precondition in place, the English version of the PDF is generated when the user selects the English option for Language.

Step 4 - Map Form Fields to the Acroform

The PDF mapping screen enables designers to map form fields to PDF fields. Mapping is performed one field at a time in the context of a PDF page. There are two ways to map fields.

1. Drag-and-drop a field from the outline to the PDF field

2. Click on a PDF field to activate the PDF Mapping Dialogue

The quickest way to map your PDF is to use the drag-and-drop method, but if you need to Generate Pixel Perfect PDFs#MappingTableandRepeatControls for a table or repeat control, the Mapping dialogue must be used. You can change mapping choices on the Generate Pixel Perfect PDFs#Method2-ClickingonaPDFField as well.

Open the PDF Mapper

1. Click the Map Fields icon.

   

2. In the forms designer only, the following message will display when you click on the Map Fields link. Click Ok to save the PDF form before any further mapping is performed. Click Cancel to cancel the mapping operation and not save.
   

   The prompt and save of the PDF form mapping is controlled by a web.xml context parameter named: form.save.on.mapping. The parameter defaults to true. If set to false, the designer will not be prompted with the save option and the editing instance will not be saved. This parameter applies only to forms, not workflows.

   
   

3. Click the Map Fields icon. You may see this message as the PDF mapping screen loads.

   

The PDF view screen is divided into two areas: the Mapping Form Outline and the PDF Canvas. On the canvas, the PDF fields will be color coded to show you whether they have already been mapped, are not yet mapped, or have an error.

Notice the Done, Clear, and PDF Page icons at the top of the page.

The Mapping Form Outline contains all mappable controls along with sections, panels, and special mapped items such as Signed Section signatures and selection control options. Click the plus and  minus icons in the Mapping Form Outline to expand/contract the Group Controls and display the mappable controls in your form/workflow.

 In the Mapping Workflow Outline, the top level elements in the tree correspond to separate forms in the workflow.

Method 1 - Drag and Drop Mapping

1. Drag form fields from the Mapping Form Outline and drop them onto the PDF fields. The color of the hovered field will be changed slightly to indicate that the drop can happen there. If the mapping complies with the PDF Form Generation Rules, then the PDF field is filled in with the name of the control and colored green to indicate that it is mapped. Non-mappable control types can be dragged, but you will not be able to drop them on any PDF field.
   
   

   

2. Repeat for all fields on each page of the PDF template. 
   

   

3. Click Done when finished and remember to save your form/workflow.

Method 2 - Clicking on a PDF Field

Another way to map fields is to click the field in the PDF Canvas, which opens the PDF Mapping Dialogue. 

•  Click on a yellow unmapped field to create a new mapping

•  Click on a green mapped field to modify an existing mapping

The upper portion of the PDF Mapping dialogue names and describes the PDF field being mapped. Below is a table that shows frevvo fields. The top row of the table shows the field that is currently mapped to the PDF field. Below that is a scrollable table of candidate fields that may be selected for mapping. If there are no mappable fields in your form, you will see the message 'No frevvo fields mappable to this PDF field.' Only a single form field may be mapped to a PDF field. If field names or labels are too long to read in this view, hovering the cursor over the text will display a tooltip with the full name/label. 

Functions for buttons in the PDF Mapping dialogue box:

Let's say you want to map the Employee Signature on the W-4 to the Confirmation step signature control in your workflow.

1. Click the Employee Signature field in the PDF.

2. Type the name of the form, in this case, Confirmation, into the search box. Mappable fields from the Confirmation step in the workflow will display as possible mapping choices.
   

   

3. Hover your cursor over the name field on the mapping dialog to display a complete path to the control's hierarchy as a tooltip. This is helpful when mapping nested controls. 
   

   

   
   The label and form columns of the Mapping Dialogue displays a maximum of 40 characters. If you have long labels in your form/workflow, hover over the displayed text to see the full label text in the tooltip.
   

   

4. Click the Done button when the mapping is completed and don't forget to save your form/workflow changes.

Error Conditions:

Mapping validation will detect the following conditions and report them as invalid:

• A mapped field that has been deleted from the form.

• A comment that was mapped and then the control's comment property was deselected.

• A signed section's signature or sign date that was mapped and then the section's signed property was set to none.

• An option value that was mapped and then the option is changed or deleted.

If you try to save a PDF with mapping errors, you will see the message

Clicking the OK button will bring you back to the designer canvas. Clicking the Cancel button returns you to the form/workflow home page.

Mapping Table and Repeat Controls

Form controls placed within repeats or tables use the max number property to create multiple "instances" of the field for mapping. Controls within a repeat (or table) are indexed to allow the user to select the specific control for mapping. For example, the first instance of a repeat/table control with a min value of 1 and a max value of 3 has an index of 1, the second instance has an index of 2 and the third instance has an index of 3. There are no restrictions to the number of repeating items or rows in a table. You can map controls from a table or repeat using the drag and drop method but you must click on the table/repeat field in the PDF and change the index value for instances greater than 1 in the PDF Mapping dialogue.  

Entering an invalid index number displays an error message.

Example 1: Map Table to PDF

Let's take a look at examples that will clarify the mapping process. An Emergency Contact Form has a table to list additional authorized individuals that a student can be released to in the event the school is unsuccessful at contacting the parents. This table has a min value of 1 and a max value of 3.

1. Locate the table in the outline and simply drag the Name, Relationship, Home, Mobile and Work controls from the outline and drop them into the correct column in all 3 rows of the table.

   

2. Click on the field 'Name' in the second row of the table (on the PDF canvas.) This will open the PDF Mapping Dialogue.

3. Change the Index to '2'.
   

   

4. Repeat steps 2 & 3 for the field 'Name' in the third row of the table, changing the index to '3.'

5. Repeat steps 2-4 for the additional fields (columns) changing the index in the second row to '2', and the third row to '3.'

When the user fills out the form, it will map the correct table cell to the correct PDF field.

Example 2: Map Repeat to PDF

The Application for IRS Individual Taxpayer Identification Number (W-7) has fields for Name and Name at Birth - if different.

A Repeat control containing a section with name fields and min/max values of 1 and 2 respectively can be used in your form to capture both pieces of information.

1. Locate the repeat control in the outline. Drag and drop the control 'FirstName' to the 'Name' row in the PDF. Repeat, dropping it onto the second row.
   

   

2. Repeat Step 1 for MiddleName and LastName controls.

3. One at a time, click on the First Name, Middle Name and Last Name fields in the 'Name at birth if different' row. For each, change the index to '2'.
   

When the user fills out the form, it will map the correct table cell repeat item to the correct PDF field.

Nested Repeats

For nested repeats, use the max number of each repeating level multiplied to determine the total max index of an item. This is illustrated in the example below showing repeat 2 nested in repeat 1. Each repeat has a section with a text control. Each repeat level has a max of 2. The inner most text control will have an index of 4 (2 * 2) as shown.

Form
    repeat1
        section1  (max 2)
            text1                     -- index = 1
            repeat2
                section2   (max 2)
                    text2             -- index = 1
                section2
                    text2             -- index = 2
        section1 
            text1                     -- index = 2
            repeat2
                section2   
                    text2             -- index = 3
                section2
                    text2             -- index = 4

Empty Rows/Items

If you have empty rows in a table control or blank repeating items in your form, PDF mapping may shift a bit. To keep the mapping predictable, set the min value equal to the max value for the table/repeat controls. This will give you options to map the missing/blank items in the PDF mapper.

Mapping the Upload Control

Let's say you wants to take a photo using a mobile device and then map the photo to a PDF. frevvo supports the mapping of the Upload control that can be used to upload the image to a form/workflow. 

• You can only map one image file per upload control. In the case of upload controls with more than one file, the mapping simply takes the first image file found. 

• Common image types supported are gif, png, jpg/jpeg, and bmp. 

• Tiff is not supported. 

• Non-image file type uploads are ignored. 

PDF Form Generation Rules

PDF forms are generated as the last step(s) of a form/workflow or when the Form Viewer control is clicked. All other activities are completed prior to PDF form generation. PDF forms are generated by using the mapping meta data entered by the user to map the form field data to the PDF's acroform fields. Precondition properties are supported for form generation activities and operate in a standard fashion, i.e. if the precondition evaluates to true, the activity executes.

The specifics of mapping form data fields into acroform fields are detailed in the table below:

• The columns represent the acroform field types and the rows represent the frevvo control types.

• Blank cells indicate that mapping is not available for the Form Control/Acroform Field Type combination.

• An acroform check box is a single check box and does not correspond one-to-one to a frevvo check box.

• An acroform radio button is a single radio button and does not correspond one-to-one to a frevvo radio control.

• Checkbox, radio and dropdown options can be mapped to certain PDF fields (according to the table below). They will be listed as ControlName.OptionName?.

• Wet signatures are treated as images. They can be mapped to text fields. The image is linearly scaled to fit within both the vertical and the horizontal dimensions of the text field without any distortion.  

In general, all the frevvo controls listed, can be mapped to an acroform text field. Selection controls are mostly handled by mapping the option values as indicated above.

Date/Time

Date/time will be derived from the xml and it will be in ISO format and in UTC (time and date/time only). There are two issues to consider:

• Timezone - Times and date/times must be formatted using the form’s timezone.

• Formatting dates (and times) uses the control's formatting set by the designer.

Mapping Selection Controls

When mapping selection controls, you will see the name of the control and the options for that control in the mapping choices. The option values will be listed as ControlName.OptionName?.  As an example, let's take a look at the Eligibility field on the federal I-9 Employment Eligibility form. A radio control collects the eligibility status of the new employee.

The option/label values for the radio control in the form are:

A citizen of the United States=A citizen of the United States
A noncitizen national of the United States=A noncitizen national of the United States
A lawful permanent resident (Alien Registration Number/USCIS Number)=A lawful permanent resident (Alien Registration Number/USCIS Number)
An alien authorized=An alien authorized to work until a certain date. (If applicable enter date below). Some aliens may write "N/A" in this field. (See instructions)

Map each option to the PDF using the drag and drop or mapper dialogue. Notice the options are listed using the Control Name.OptionName format:

Sometimes you may want to map to the entire control instead of the individual options. For example, the State dropdown control is mapped to the State field in the PDF. Any choice selected by the user will be mapped.

PDFs and Dynamically Populated Selection Controls in workflows

Depending on which step you view the generated PDF in a workflow you may notice the value of the selected option is displayed instead of the label. For example, let's say you have a two step workflow, where each step is a different form and is performed by a different user. In step 1, there is a Select Supervisor dropdown control populated dynamically by a business rule. The options follow the value=label syntax, mary@mycompany=Mary Jones. There is a Form Viewer control to view the PDF when step 1 is being performed. The PDF is mapped to the Select Supervisor dropdown in step 1. Step 2 of the workflow contains only a Form Viewer Control. User 1 selects Mary Jones from the dropdown and then clicks on the Form Viewer to see the generated PDF. The PDF displays the option label, Mary Jones. User 1 clicks Continue.

When user 2 picks up the activity for step 2, the form does not contain the Select Supervisor control and therefore does not have the options loaded by the rule. The visible option is not stored in the document for the workflow, only the value. The PDF mapping logic tries to get any dynamic labels out of the instance in case there were changes and then uses the labels instead of the values. If all this fails to produce a matching label for the value of that mapped control, then the value is used. Clicking on the Form Viewer control in step 2, shows the value for the option, mary@mycompany.

A simple work-around is to put a control by the same name into the second form and uncheck the visible property. Then add the same rule to the second form to populate it. Workflows designed using Linked Activities, should not exhibit this behavior.  Linked steps in the workflow are like a single form broken into pieces. Workflows using this design pattern have a single schema that includes fields from all its steps. So when fields from a workflow are mapped to a PDF, the mapping reflects a single schema or document.

Adobe Reader Issue with Grouped Check Boxes

Adobe Reader has an issue with grouped check boxes. In certain PDFs, it only allows a single selection for all of the check boxes in a group. Clicking on the more>> link shows the selectable values for that control. This extra information can be useful when performing the mapping function for a PDF that exhibits this issue. Let's take a look at an example to clarify:

A Filing Status section on the U.S. Individual Income Tax Return acroform (1040) has checkboxes for 5 status choices:

In your form, you have a radio control which will allow only one of the five choices to be selected.

In the designer, the options for the radio control are:

Single=Single
Married Filing Jointly=Married Filing Jointly
Married Filing Separately=Married Filing Separately
Head of Household=Head of Household
Qualifying widow(er)=Qualifying widow(er)

You map each option to the corresponding checkbox on the PDF but when testing discover that no data is mapped. This is a case where the acroform fields look like and are called checkboxes but function more like a radio control.

Follow these steps to correct the mapping:

1. Click on the Single option checkbox in the PDF to display the Mapping dialogue.

2. Click the more link. Details about the PDF field will display including the selectable value of S.

3. Determine the selectable values for the other options.

4. Change the values for the options in the properties pane of the radio control in the form to match the Selectable Values that you saw when you clicked on the more link. The options values of the frevvo Status control in the e-form must match the Selectable Values EXACTLY. The case of the option values is important. The option values MUST be the same case as listed in the mapping dialogue. 
   

The mapping is done when the user selects one item in the frevvo radio corresponding to the selected radio option. The items/options are matched to value/option, not label, of the control. Only one selection is supported. See Generate Pixel Perfect PDFs#PDFFormGenerationRules for more information.

Note the Selectable Values from the mapping status are on the option value (left) side of the equal sign.

A user who selects the Head of Household radio button in the frevvo will see that option checked if the mapping is done correctly.

Acroform Field Names with a #

If a field in an acroform has a # in the name , you may see this error message when you click on the Form Viewer control to view the mapped PDF.

To view acroform field names, go into the mapper in the designer and click on acroform fields. The name is shown on the dialog. The image shows a a field named "form1[0].#pageSet[0].Right[0].Educator[0]".

To resolve this issue, remove the "#" from the acroform field name. You can use a tool like PDFescape, which is a free online PDF editor, to rename fields. In PDFEscape, right click and unlock the field, then right click again and edit object properties to rename the field. This process may vary for different PDF editors.

Step 5 - Form Viewer Control

You may have a form/workflow where you want the user to view the generated PDFs for accuracy. The Employee On Boarding form/workflow requires that the new employee review the generated PDFs and sign to verify that the information is correct. The Form Viewer control allows a generated form to be viewed as part of a form activity.

In use mode, the Form Viewer button is a link that displays the form in a separate window/tab. The form can then be viewed or downloaded.

Open the form/workflow designer. Drag and drop the Form Viewer control from the palette into your form. It can not be placed in a repeat or table control. You will need a separate Form Viewer control for each PDF that you want to be reviewed.

 Select the PDF to be viewed for each control from the Form dropdown. If you used templatized strings when naming your template, it will show the template unresolved in the drop down. 

Step 6 - Testing the form/workflow

When you are finished mapping your PDFs, click   Save and Test to test the mapped PDFs in your form/workflow via the Form Viewer Control and/or the submission repository. The form/workflow is checked for errors and they are reported before the Test popup displays. This gives the designer the opportunity to make corrections before testing. Refer to Test Forms and Workflows for more information about this feature.

Troubleshooting

Large PDFs with MySQL

Submitting a form/workflow with a large mapped PDF while using MySql may generate an error message like the one below. The default value of max_allowed_packet configuration parameter may not be large enough. See this documentation for the solution.

PDF Will Not Load for Mapping

When you click Map Fields, you will initially see the message “Please wait while the PDF is loaded and prepared for mapping.” If the form fails to load at this point, you may also see an error in the logs similar to 

"Application error processing /frevvo/web/tn/...
java.lang.RuntimeException: javax.servlet.ServletException: java.lang.ClassCastException: org.icepdf.core.pobjects.Reference cannot be cast to java.lang.Number

The PDF may appear normal, but it does not work with frevvo's ICEPDF library. To resolve this, please upload the PDF to a tool like pdf escape, then save and download it. You may notice the version is larger than the original. Upload the new version to frevvo and proceed to map the fields.