frevvo Latest - This documentation is for frevvo v10.0. Not for you? Earlier documentation is available too.
Looking for a section on this page? Hover your cursor over the Table of Contents iconto the right to quickly navigate this page.
frevvo offers an automatic PDF snapshot of your forms and workflows, which is a great option that requires no code, no mapping and no PDF to build. You can customize the print layout, fonts, headers/footers, file name, and more with just a few clicks. It is also responsive to repeat controls like tables, so the PDF will grow with more entries vs. the static number of rows available in a typical PDF.
Check the Save PDF option in the Form/Workflow Properties Wizard to save a a PDF snapshot in the frevvo submission repository.
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.
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.
|Form → Workflow||Workflow Step → Standalone Form|
|Do mapped PDFs carry over?||Yes||No|
Import of forms created in previous versions will preserve all PDFs and mappings.
Follow these basic steps for each Pixel Perfect PDF your form/workflow will generate.
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.
The tool that Adobe uses to create PDF's may not always support integration with third party software like frevvo.
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.
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.
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.
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 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:
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.
When viewed with the form viewer control, mapped PDFs are always read only. This ensures they are viewable on mobile devices.
Notice that your newly uploaded template is added to the PDF list. Click theicon to edit the template name.
Click theicon to remove the template. This action removes the generated form and all field mappings.
You can set up 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 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 controlPrecondition Editor and add the condition.
With this precondition in place, the English version of the PDF is generated when the user selects the English option for Language.
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.
The quickest way to map your PDF is to use the drag-and-drop method, but if you need to change an index for a table or repeat control, the Mapping dialogue must be used. You can change mapping choices on the Mapping dialogue as well.
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.
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.
|Done Button||Click this button when mapping is complete or you wish to exit back to the PDF Generated Forms Screen. Field mappings are saved to the in-memory form/workflow as they are performed. Mappings are not persisted until the form/workflow is saved.|
|Clear Button||Clicking this button clears all mappings for the whole PDF. All fields are then displayed as not mapped (colored yellow and cleared of all text).|
|PDF Page thumbnail Image|
Thumbnail images are displayed for each page found in the PDF with no limit. The HTML element containing the PDF page thumbnails will be scrollable if there are a large number of pages and all cannot fit in the displayable area. Click the thumbnail image for the page in the acroform where you want to map fields. When clicked, that page is selected for mapping and it is displayed along with any previous mappings filled into the fields.
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 and display the mappable controls in your form/workflow.plus and minus icons in the Mapping Form Outline to expand/contract the
In the Mapping Workflow Outline, the top level elements in the tree correspond to separate forms in the workflow.
Another way to map fields is to click the field in the PDF Canvas, which opens the PDF Mapping Dialogue.
The upper portion of the PDF Mapping dialogue names and describes the PDF field being mapped. Below this 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:
|more>> less<< links||Used to hide and show more details about the PDF field being mapped, including Type, selectable values and the name of the field in the acroform. This information is useful when trouble shooting. Selecting more>> shows the details and changes the link to less<<. Selecting less<< hides the details.|
|Clear Mapping||Clears the mapping (if any). Any selected radio button is cleared. Changes take place immediately.|
|Selection Radio Buttons||The first column consists of radio buttons for each mapping choice. Click the radio button corresponding to the frevvo control to map it to the field in the PDF. Radios may not be de-selected. frevvo fields are unmapped using the clear button or by selecting another e-form field.|
|Index Edit Boxes||For repeating frevvo fields, the 1-based index is used to select the field to be mapped. The value must be ≥ 1. The default is 1. Changes take effect immediately upon tabbing/clicking off the the index field. The index field is disabled for non-repeating frevvo fields.|
|Search Text Box||Use this to search for mapping choices for the PDF field that was clicked. Entering filter text causes the possible mapping selections to change. Only those matching the filter text will be shown. If the name, label or form name (workflows) is either a partial or full match of the filter text (case insensitive), then the field is shown in the list of candidate fields selectable for mapping. E-form fields that are incompatible with the PDF field are not shown in the list . Search will find special mapped items such as Signed Section signature, date signed as well as the single select comment field. Use option control values to search for selection control options.|
|PDF Field||The name of the field in the acroform is displayed here.|
Let's say you want to map the Employee Signature on the W-4 to the Confirmation step signature control in your workflow.
Mapping validation will detect the following conditions and report them as invalid:
If you try to save a PDF with mapping errors, you will see the message
Changing the nesting levels of mapped controls does not produce this error. For example, mapping for selection control options, signature and date fields and repeats are automatically updated mappings when controls are moved in/out of Sections.
Clicking the OK button will bring you back to the designer canvas. Clicking the Cancel button returns you to the form/workflow home page.
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.
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.
When the user fills out the form, it will map the correct table cell to the correct PDF field.
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.
When the user fills out the form, it will map the correct table cell repeat item to the correct PDF field.
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.
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.
Let's say you wants to take a photo using a mobile device and then map the photo to a PDF. frevvo supports mapping of the Upload control that can be used to upload the image to a form/workflow.
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:
|Form Control Types||Acroform Field Types|
|Checkbox||Choice/Combobox (Single select)||List||Radio Button||Text||Signature|
|CheckBox||Mapping is done by option value. If the value of any of the selected option(s) on the form control matches the 'on' value of the check box, then it is selected. Otherwise it is unchecked. *See note.||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.||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.||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.
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.
The Push Button Acroform field type cannot be mapped at this time.
frevvo Image controls cannot be mapped to a PDF at this 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:
You can map both the signature and signature date from a Signed Section to a PDF. However, in a workflow the Signed Section must also contain some other data in addition to the signature - an empty Signed Section will appear to map when you use the Form Viewer control on the same step as the signature, but will not be mapped on the final PDF. This is a known issue. If your business requirements call for an empty signed section, you should add a hidden text control in that section with a default value to ensure it appears on the final mapped PDF.
For example, here is a simple workflow where the employee completes Step 1, then the Manager approves Step 2 and finally, the VP approves Step 3. The Manager and VP do not need to add any information, so their Signed Sections are empty:
Each of the three signed sections is mapped to a PDF.
However, after running the workflow we get an unexpected result - the Manager Signature is not mapped to the final PDF.
To work around this issue, let's add a hidden text control to the Manager Section, and set the default value to "map me".
Now when we run the workflow, the Manager Signature is successfully mapped.
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 from the new employee.
The option/label values for the radio control in the form are:
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.
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 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 use 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 workflow are like a single form broken into pieces. Workflows using this design pattern have a single schema which 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 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:
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:
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 PDF Form Generation Rules 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.
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.#pageSet.Right.Educator".
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.
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.
If you delete an acroform and then upload a different one, you will have to redo the PDF selection in the Form Viewer control that was configured to view that PDF.
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.
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
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.