Checking the Save PDF option for a flow saves a a PDF image of the flow in the frevvo' submission repository. This generated snapshot is a basic PDF rendering of the forms/flow. You can generate additional PDFs' as part of your workflow, if required. For Example, new employees hired by a company are typically asked to fill out federal forms such as a W-4 or an I-9. frevvo' Pixel Perfect PDF generation feature allows you to design a workflow with forms that capture the information needed and integrate the data from the e-form controls to an Acroform PDF. frevvo adds all generated PDF forms to the document set of a completed flow. See Submissions for more details.
On This Page:
frevvo' Pixel Perfect PDF generation feature allows you to generate additional PDF forms as part of a work flow. This capability is not supported in the form designer in this version although it will be available in a future release. You will need an "Acroform" to generate a pixel perfect PDF. Acroforms (also known as Acrobat forms) are forms that contain writable form fields. You can generate as many PDFs as you like. It is very easy to map frevvo controls to individual Acroform fields for each one. The additional PDF forms are generated at the end of a flow and all generated PDF forms will be added to the document set of a completed flow. This makes it possible for the form designer to specify doc actions on these additional form documents as well. The designer can construct flows in which the generated forms may be viewed at any point in the work flow via a new Form Viewer control. See below for the details.
The Flow designer now has two separate views:
- Flow View - canvas where the designer can drag/drop/edit forms to create activities in a frevvo flow. See Designing Flows for more information.
- Generated Forms View - canvas where the designer can drag/drop/edit PDF forms to be generated. See below for the details.
Launch the Flow Designer. Clicking on the Flow View and Gen Forms View buttons on the toolbar toggles between the two views.
- Digital signatures in PDF forms, and Word doc forms are not supported.
- Currently PDF form creation must be done in the flow designer. Adding an additional PDF as the output of an e-form will be added to the form designer in a future release.
- Adobe XFA Forms are not supported. The tool that Adobe uses to create PDF's does not support integration with third party software. Use PDFescape to generate acroforms for mapping with Live Forms.
- 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.
- PDF files support layers that can be turned on/off as a way of hiding and showing content dynamically. These are the underlying technology behind optional content groups. These can be manipulated programmatically as a way to dynamically build forms.
Generated PDF Forms View
A new button, Gen Forms, has been added to the Flows designer toolbar. Click this button to display the generated PDF forms view screen. The screen is divided into three areas: the palette, the properties pane and the Gen Forms editor. You will see a "Default Generated Form" activity at the top of the canvas if the "Save PDF" property of the flow has been set. This activity will always be first and cannot be edited. It is there as a reminder that it will be created. You can delete the "Default Generated Form" by clicking thedelete icon. The "Save PDF" property of the flow will be reset and the default PDF will not be created as part of the flow. The only way to turn it back on and have the default snapshot PDF be created by the flow is to re-check "Save PDF" on the flow. The text: "Drag and drop form generation activities from the palette" will display on the editor canvas if it is completely empty. This text will disappear once an activity is dropped on the canvas.
Drag and drop the "New PDF Form" from the palette into the editor to create a new PDF form generation activity. You can add related forms to the same activity. For example, the Employee Onboarding flow requires the new employee complete forms for the IRS and possibly some company specific forms. You can set up one PDF activity to include the W4, and the I9 Eligibility Verification form and change the name of the activity to IRS Forms while any forms required by the company can be added to an activity titled HR Forms. The image of the Employee On Boarding flow shows the IRS Forms activity set up to generate three additional PDFs: the W4, the Connecticut W4 and the I-9 Employment Eligibility Verification form. Forms such as 401k and Healthcare enrollment could be added to the HR Forms activity in the flow.
You can only drop the "New PDF Form" below the "Default Generated Form" activity, if present. The default name will be "Generated Form N", where N is a unique number starting at 1. You can change the name of the activity and set up any precondition that your flow may require on the Properties panel. For Example, currently the only way to disable a template is to use a precondition that always evals to false and it will be skipped.
Skipped activities do not affect PDF's generated by Live Forms. For example, controls in flow activities containing default values, that have been mapped in the pdf mapper, will show up in the PDF even if the activity is skipped due to a precondition. Use a form.load rule to set the "initial state" data dynamically instead.
You may have to completely exit the flow and then go back in to see name changes. The new form generation activity will NOT be automatically selected and any previous selections will be maintained. Click on the new activity to select it. The activity will display with a green color and contain theedit and delete icons.
Click thedelete icon to remove the activity from the generated forms section of the flow. You will be asked to confirm the deletion of the PDF form activity.
Click theedit icon to setup or edit PDF generation activities.
Configure PDF Form Generation
There is a three step process to configure PDF form generation. The designer must follow these basic steps for each form to be generated as part of the activity:
- Upload one or more PDF Acroforms that will serve as PDF form generation templates.
- Download a modified version of the uploaded PDF Acroform that contains mapping meta-data. The mapping meta data consists of available selections of appropriate e-form fields for each PDF Acroform field.
- Upload completed mappings for each PDF Acroform to frevvo.
Upload PDF Acroform Templates
Here is an example of a PDF Acroform for the federal Employee's Withholding Allowance. Notice the blue highlighted writable form fields.
Use the New Form Generation screen to upload the Acroform for the PDF you wish to fill using frevvo fields. Click the New icon to begin. If you do not provide a name for your template, the file name will be used.
A list showing all of the PDFs to be generated for this activity of the flow will display.
Click theicon to remove the template. You will be asked to confirm the deletion as the template and all field mappings will be removed.
Click theicon to edit the template name. If you try to delete the template name, you will see the message "Name is Required".
frevvo makes a copy of the uploaded Acroform template and modifies it with available selections of appropriate e-form fields for each PDF Acroform field. The modified PDF Acroform (Mapper) will be re-generated every time because the e-form fields may have changed. Upload the modified template every time you make a change to your Acroform PDF. For example, changing the Acroform to make a field acro-fillable, requires the upload of the modified template again.
frevvo will not allow the use of an owner or user password protected PDF acroform to be used as a template. It is the the flow designer's responsibility to provide an unprotected PDF acroform. There are programs available to "remove" an owner password from a protected PDF such as PDFescape. Simply upload the password protected PDF to PDFescape, then save and download it. The passowrd will be "removed" from the PDf and you will be able to use it as a template.Invalid templates cannot be uploaded either. The message "Invalid PDF or password protected" will display.
Download the Mapper
Download the Mapper by clicking on theicon. The downloaded mapper is a modified template so it will have the same name as the template that you uploaded even if you changed it.
If you add a control from schema with maxOccurs="unbounded" to your form or flow, when you download the mapper, the mapping options show a maximum of 100 items. This is as designed.
Map the E-Form Fields to the Acroform Fields
Open the mapper with an external PDF viewer/editor, such as Adobe Reader (version 11 or higher), Mac Preview or PDFescape.
PDF.js, a PDF Viewer available for the Firefox browser, may not render the PDF properly. If you are using this as your viewer, and the PDf does not look as expected, download the PDF and view it in Adobe or Mac Preview.
Previous mapping selections should be retained. There are some forms where Adobe reader may loose the previous mappings. If this is the case, all fields will have to be manually mapped again. Here is an example of the downloaded mapper for the W-4 PDF. Notice the Acroform fields are re-written with editable combo box controls. The combo boxes are pre-populated with the names of relevant e-form fields from the frevvo flow for the purposes of field mapping.
Click on the arrow to display the e-form fields. Select the appropriate e-form field from the selections provided. The image shows the Acroform field for the Last Name on the W-4 form being mapped to the LastName [form > LastName] [id:_Dpf0vUf3EeK8Grq3Nz0xDg] selection in the list. You may have noticed each entry in the mapping choices has a unique ID as part of the mapping string. This is needed by the PDF mapper at this time but may be removed in a future release.
Mapping selections should be made in all fields. You do not have to map all the fields in one session - you can save the file and return to complete the mapping at a later time.
It is up to the designer to ensure that the content fits within the acroform field. The acroform will truncate it if it does not fit.
Adobe Reader supports the linkage of fields. This means that Acroform fields can share the same values even if the fields have different names. For example: Let's say you have an Acroform pdf consisting of 8 pages. Writable fields for Name, Address, City, State and Zip Code are located on the first, third, fifth and eighth pages. If you are using Adobe Reader to map your PDF, then you can map the Name and Address fields in the frevvo mapper on the first page and the Name and Address fields on pages three, five and eight will automatically become mapped. Adobe enforces the link between these fields even though the field names are different. (the Name field on the first page is named topmostSubform.Page1.f1... while the Name field on the third page is topmostSubform.Page3.f1...). If you are using Adobe Reader, you cannot map the fields on pages three, five and eight separately. If you are using a mapper that does not support field linkage, such as Mac Preview or PDFEscape, you will have to map the Name and Address fields on each page.
Upload the Completed Mappings
Save the completed mapping PDFs and upload them to frevvo by clicking on the Upload Mapping icon on the activity form generation screen. You must upload completed mappings for each PDF Acroform that you want to generate.
The fields in the uploaded mapped PDF must match exactly to the fields in the uploaded form template.
frevvo will process the mappings and post a status that can be viewed by clicking on the [Details] button. Any errors encountered will be listed here. This can be a valuable tool for troubleshooting any problematic issues when mapping your e-form to the Acroform pdf.
The Form Generation Mapping Status screen will display the following information:
- the Acroform Field Name
- the Acroform field type
- the "Selectable Values" column is useful when mapping to PDF comboboxes, lists and radios. It is important to have the eform's mapped checkbox, select or radio's option values be the same as the corresponding PDF fields option values. The values will be shown in the selectable values column. See PDF Form Generation Rules below for more information.
- Mapping Status = Mapped or Not Mapped
- The E-Form Field Name, if the field is mapped.
You will see thiserror icon if the mapping for your form is incomplete. It will change to the critical error icon under the following conditions:
- Incorrect Mapping File - if any fields in the mapped PDF do not match the original set of form fields in the template.
- Mapping File Invalid - the uploaded mapping file must have exactly the same set of form fields as the original uploaded template. A mismatch results in an invalid mapping file.
- Form Template File Invalid - the uploaded template is checked to see if it is a valid, read-able PDF Acroform File.
- Mapping Errors - the form fields in the mapped PDF must be filled with a valid selection corresponding to an e-form field. Any Acroform fields mapped to an unknown e-form field will show the invalid e-form mapping field name. For example, if you delete a field from your form after mapping, or change a control to a different one you will see the "Invalid E-form field" in the Mapping Status column:
Theicon indicates that the mapping is complete and there are no errors.
When you change the name of a control, it is essentially a new control and gets a new id. If the control name is changed, the PDF mapping for that control is broken and it will display with a status of Invalid E-form field. Even if the changes are reverted, the PDF mapping for that control is still broken. The "new" control will have to be mapped again.
Mapping Table and Repeat Controls
E-form controls placed within repeats or tables use the max number property to create multiple "instances" of the e-form field for mapping. Controls within a repeat (or table) are indexed to allow the user to select the specific control for mapping. frevvo will put the correct number of instances of the control in the mapping select list based on the max number of the repeat/table. Each of these instances will be clearly labeled with an index. For example, a table in your form to collect the Education History of a new employee has a column for the Degree earned. The dropdown choices are: High School, Bachelors, Masters and PhD. The Max # property for the table is set to 10.
The mapping selections list the 4 choices (High School, Bachelors, Masters and PhD) with indexes of X of 10 for each choice.
Here is an example of an Application for IRS Individual Taxpayer Identification Number (W-7) that has fields for Name and Name at Birth - if different. A Repeat control with a name field and min/max values of 1 and 2 respectively, can be used in your form to capture both pieces of information.
The choices in the mapper dropdown for the first name control are: FirstName (1 of 2)]:followed by a unique id. or FirstName (2 of 2) ]:followed by a unique id. Choices for the middle and last name controls follow the same format.
In the mapper, selecting the (1 of 2) choice for the First, Middle and last Name controls and the (2 of 2) choice for the repeating first, middle and last name controls that appears after the user clicks theplus sign, maps the data as shown:
Nested repeats, use the max numbers of each repeating level multiplied to determine the total max index of an item. This is best illustrated with the example below showing repeat 2 nested in repeat 1. Each repeat has a section and each section a text control. Each repeat level has a max of 2. The inner most text control will index up 4 (2x2) as shown.
The max number of indexed mapping items put into the mapping options for any repeating control is 10. There will not be any choices in the mapper for table rows or repeat occurrences greater than 10. They cannot be mapped.
Adding a Field to an Acroform
Some Acroforms may not have a writable field for all of the data that you want to collect. An example might be the signature field on such forms as the I-9 or W-4 Acroforms. The Employee On Boarding flow collects information to populate the W-4 PDF after the new employee completes the frevvo screen flow. Another step of the flow asks the new employee to review the PDF and sign if the information is correct. Mapping the frevvo signature to the generated PDF cannot be accomplished unless there is a writable field in the W-4 template. You can use a PDF editor such as PDFescape to add a writable field for the signature to your Acroform template. frevvo signatures are treated as images that can be mapped to text fields so be sure to add the Acroform field as a text field. The table below gives more information on mapping rules. Upload the modified Acroform as your PDF template. See above.
PDF Form Generation Rules
PDF forms are generated as the last step(s) of a flow . All other activities are completed prior to the execution of any form generation activities. PDF forms are generated by using the mapping meta data entered by the user to map the e-form field data into 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.
In general, the following applies to the generation process:
- E-form fields are written into/over the Acroform fields in the PDF in the exact location and space of the Acroform field.
- The data written into a field cannot exceed the original acroform field length.
- The fields are flattened out and made read only in the resulting PDF document.
- The resultant PDF document must have the same name as the original uploaded PDF Acroform file.
The specifics of mapping e-form data fields into Acroform fields are detailed in the table below:
- The horizontal columns represent the Acroform field types and the vertical rows represent the Live Forms control types.
- Blank cells indicate that mapping is not possible. E-form fields will not be made available for mapping for those types of Acroform fields.
- An Acroform check box is a single check box and does not correspond one to one to a Live Forms check box.
- An Acroform radio button is a single radio button and does not correspond one to one to a Live Forms radio control.
- Checkbox, radio and dropdown options are included in the mapping select controls in the PDF (according to the table below). They will be listed as ControlName.OptionName?.
- Live Forms manual 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.
|E-Form Field Types||Acroform Field Types|
|Checkbox||Choice/Combobox (Single select)||List||Radio Button||Text||Push Button||Signature|
|CheckBox||Mapping is done by option value. If the value of any of the selected option(s) on the e-form control matches the 'on' value of the check box, then it is selected. Otherwise it is unchecked. See NOTE below.||Select one item in choice/combo corresponding to selected checkbox options. Equate items/options by the value/option, not label. Only single select supported in some cases (depends on if field is set to multi).||Select items in list corresponding to selected checkbox options. Equate items/options by the value/option, not label. If list box is single select only one option is selected.||Select one item in radio corresponding to selected checkbox options. Equate items/options by the value/option, not label. Only single select supported.||Yes. The label text of the selected option(s) will be comma separated and used.|
|CheckBox Option||Yes. If option selected, check box will be selected.||Yes. If selected, then option label text used.|
|CheckBox Comment||Yes. Only if comment is enabled. Multiple lines will be concatenated (new lines not carried over to PDF).|
|Radio||Mapping is done by option value. If the value of any of the selected option(s) on the e-form control matches the 'on' value of the check box, then it is selected. Otherwise it is unchecked. See NOTE below.||Select item in choice corresponding to selected radio option. Equate items to options by the value, not label.||Select items in list corresponding to selected radio option. Equate items to options by the value, not label.||Select one item in radio corresponding to selected radio option. Equate items/options by the value/option, not label. Only single select supported.||Yes. The label text of the selected option will be used.|
|Radio Option||Yes. If option selected, check box will be selected.||Yes. If selected, then option label text used.|
|Radio Comment||Yes. Only if comment is enabled. Multiple lines will be concatenated (new lines not carried over to PDF).|
|Dropdown||Mapping is done by option value. If the value of any of the selected option(s) on the e-form control matches the 'on' value of the check box, then it is selected. Otherwise it is unchecked. See NOTE below.||Select item in choice corresponding to selected dropdown option. Equate items to options by the value, not label.||Select item in list corresponding to selected radio option. Only select one by definition. Equate items to options by the value, not label.||Select one item in radio corresponding to selected dropdown options. Equate items/options by the value/option, not label. Only single select supported.||Yes. The label text of the selected option will be used.|
|Dropdown Option||Yes. If option selected, check box will be selected.||Yes. If selected, then option label text used.|
|Dropdown Comment||Yes. Only if comment is enabled. Multiple lines will be concatenated (new lines not carried over to PDF).|
|Text & Text Area||Yes. Simple text transfer.|
|Date, Time, DateTime||Yes. Use formatted date/time.|
|Money, Quantity, Number||Yes.|
|T/F||Yes||Put a 'true' or 'false' in as appropriate.|
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.
When mapping selection controls, you will see the name of the control and the options for that control in the downloaded mapper selections. The option values will be listed as ControlName.OptionName?. As an example, let's take a look at the Eligibility field on the I-9 Employment Eligibility federal form. Your frevvo Employee On Boarding flow might contain a form with a radio control to collect the eligibility status from the new employee.
The option/label values for the radio control in the e-form are:
The mapper will offer the choices for each option value.
Select the choice that begins with EligibilityChoices.A_lawful_permanent_resident_(Alien_... [form > from the dropdown in the mapper for the option value of A lawful permanent resident (Alien #) in the frevvo radio control.
Select the choice that begins with EligibilityChoices.A_citizen_of_the_United_States [form > from the dropdown in the mapper for the option value of A citizen of the United States in the frevvo radio control.
Select the choice that begins with EligibilityChoices.An_alien_authorized_to_work_(Alien_... [form > from the dropdown in the mapper for the option value of An Alien authorized to work (Alien # or Admissions #) in the frevvo radio control.
Select the choice that begins with EligibilityChoices.A_noncitizen_national_of the United States from the dropdown in the mapper for the option value of A noncitizen national of the United States (see instructions) in the frevvo radio control.
Correct mapping will result in a checked box on I-9 generated pdf depending on the choice selected by the new employee on the Live Form. The image shows the pdf when the A citizen of the United States is selected.
- When mapping the entire selection control (Dropdown, Checkbox, Radio), then the option values in e-form should match the selectable values, else nothing will be checked in the generated PDF.
- When mapping an individual option of a selection control (Dropdown, Checkbox, Radio) to a PDF control, then the value and selectable value need not match. If it is checked while testing the form, it will be checked in the generated PDF.
Adobe Reader Issue with Grouped Check Boxes
A snapshot of the Filing Status section on the U.S. Individual Income Tax Return Acroform (1040) has checkboxes for 5 status choices:
You can use a frevvo radio control in your e-form which will allow only one of the five choices to be selected.
When you download the mapper and open it using Adobe Reader, you might notice that some of the grouped checkboxes may not have a combo box dropdown, offering choices for mapping to the Acroform field.
This is a case where the Acroform fields look like and are called checkboxes but really is a radio.
Follow these steps to map the Qualifying widow(er) checkbox:
- Upload the 1040 Acroform which will serve as the template.
- Download the mapper. Open it with Adobe Reader (version 11 or higher)
- Select the option choices for Single, Married filing jointly, Married Filing separately from the dropdown lists.
- Map the Head of Household option to the choice that does not show any options for the control. The image below shows the mapper choices for this example:
- Upload the Mapper.
- Click on the [Details] icon. Look at the mapping details and find the mapping for Head of Household and Qualifying Widow(er) in the list. The selectable values for the Acroform fields, c1-041, c1-042 and c1-043. There is the on choice (single, married filing jointly, married filing separately) and an off status. Mapping is done by option value. If the value of any of the selected option(s) on the e-form control matches the 'on' value of the check box, then it is checked on the Acroform. Otherwise it is unchecked.
The image below is a composite of the mapping status for the Filing Status choices. Notice the selectable values for c1_045. They are QW and HoH for the Head of Household and Qualifying widow(er) checkboxes on the 1040 Acroform.
In order to map these two options, you must make sure that the values for the options in the properties pane of the radio control in the e-form EXACTLY match the options you see in the Selectable Values column for the acrofield. The mapping is done when the user selects one item in the frevvo radio corresponding to selected radio option. The items/options are matched to value/option, not label, of the control. Only one selection is supported. See PDF Form Generation Rules for more information.
The options values of the Live Form Status control in the e-form are shown below: Note the Selectable Values from the mapping status are on the option value side of the equal sign. The case of the option values is important. The option values MUST be the same case as listed in the mapping status.
A user who selects the Head of Household radio button in the Live Form will see that option checkbox checked if the mapping is done correctly.
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) use the formatting from the e-form set by the designer.
Mapping of dynamically generated selection control options via a rule is not supported at this time. It will be available in a future release of frevvo.
Form Viewer Control
You may have a flow where you want the user to view the generated PDFs for accuracy. The Employee On Boarding flow 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. The Confirmation form in the Employee On Boarding flow lets the new employee view and approve the generated W-4 form by signing in the provided signature field. Clicking on the generated form name in use mode displays the form in a separate window/tab. The form can then be viewed or downloaded via the Save procedure for the PDF viewer you are using. There may be other methods of downloading/saving the form depending on the browser.
Open the Flow designer for your flow. Select the step in the flow where you want the PDFs to be viewed by clicking on it and then click on the Forms Designer palette.pencil icon to launch the Form Designer. Notice the addition of the Form Viewer control to the palette. The form viewer control is only available in the form editor's palette when the form editor is launched from the flow designer. You will not see this control on the
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 Form Viewer control for each PDF that you want to be reviewed. The generated form will display in Link Mode. Select the PDF to be viewed for each control from the Form dropdown..
The default width is 400px and the default height is 300px. Changes to margin, padding and border properties will have no effect but the rest of properties on the Style tab work as expected. Style properties for the Form Viewer control will be addressed in a future release.
In version 5.1.1. the Form Viewer control added from schema to a form that is not in a flow displays:the message: 'Form viewer control is only supported within a flow.' You will see this message in design and use mode.
The Form Viewer control defaults to link mode. Link mode offers the generated PDF to the user as a link for viewing/downloading/saving it. Clicking on the generated form name in use mode displays the form in a separate window/tab. The form can then be viewed or downloaded via the Save procedure for the PDF viewer you are using. There may be other methods of downloading/saving the form depending on the browser. The download link is inactive in edit mode unless you right-click on it and open the form in a new window/tab. Form Viewer controls in link mode in the designer display as shown in the image. Select the PDF to be viewed for each control from the Form dropdown.
Testing the flow
When the generation of Pixel Perfect PDFs for your flow is completed, and you have saved the updates, click on theTest icon and run the flow and submit it. When you get to the form with the Form Viewer controls, be sure to check the generated Pixel Perfect PDFs such as the W - 4 etc.
If you are using MySQL, and you are running/submitting a form/flow with a large acroform, frevvo, you may see this error:
The default value of the max_allowed_packet parameter in your MySQL server may not be large enough.
Increasing the max_allowed_packet variable setting in your MySQL Server from the default (1M) to something like 16M (16777125) fixes the issue. To fix the issue temporarily, run the following commands: