Contents

Overview

This page describes the process for mapping fillable PDF Forms to QEST Platform database fields for inclusion in QESTField Forms workflows using the QEST Form Mapper application. Information is provided on commonly used fields. 

Requirements

The following will be required to carry out the steps below.

1. QEST Form Mapper installed, see QEST Form Mapper Installation Guide for more information

2. An XSD file from a form definition, see Creating New Forms for more details

3. A fillable PDF form created in a third party PDF editor such as Adobe Acrobat. Some notes and best practices on creating such a form are provided in the next section.

Creating a Fillable PDF Form for QEST Platform

This section assumes Adobe Acrobat is being used, which is traditionally thought of as the "gold standard" for PDF editing, but most other PDF editors will provide the same functionality for the purposes described here.

Read Only Mapped Fields

It is recommended that any fields on a fillable PDF that will be mapped to a QESTLab field should be made read-only. This will ensure the user of the form doesn't accidentally overwrite the value imported into the field:

The text boxed in red above are actually mapped form fields that have been made read-only when the form was created. This ensures that the values mapped to these fields from the QEST Platform database are not accidentally overwritten by the user.

The Form Mapper gives the option of setting all mapped fields to read-only when saving a mapped PDF. For example if 5 fields on a form are mapped but 2 of those fields are not read only, when saving the PDF, the Form Mapper will display the prompt:

• Selecting Yes will save the PDF and set all mapped fields to be read-only

• Selecting No will save the PDF and leave read-only properties as is

• Selecting Cancel will cancel the save

If all the mapped fields are already read-only then the prompt will not show.

Date Fields

Whenever a date or time field is mapped from QEST Platform, the appropriate date format should set on the form field. The reason for this is that date and time fields are stored in SQL Server in the ISO format i.e. '2018-03-23T00:00:00'. If this is then mapped to a field with no format, the value shown will be '2018-03-23T00:00:00'. If an appropriate date/time format is set on the field, the value will be formatted before being placed in the field. For example '2018-03-23T00:00:00' formatted to dd-mmm-yyyy will become 23-Mar-2018. 

Signatures

Field Types

Consider the case where a field is desired which, upon approving the report, will place the user's signature into the PDF. When designing a form, it is tempting to use the built-in Signature field type (and Adobe Acrobat may suggest this field type when automatically generating form fields from a base file). 

Such fields are designed so that, when clicked, the user provides a digital signature which may end up visually looking more like this:

In the context of PDFs, these signatures use cryptography to provide guarantee that:

• the document was signed using a valid digital signature associated with the signer

• changes have not been made to the document subsequent to signing

It is perfectly acceptable to add such signature fields to the template if the business processes require it. If these field types are used, the following should be recognized:

• The user applying the signature will need an appropriate signature file to apply to the PDF file. These are provided by third party providers or can be self-created using popular PDF editing software such as Adobe PDF

• These signatures are not recognized by the QEST Platform workflow, when the form synchronizes back to the system it is still unsigned as far as the QEST Platform itself is concerned

• No signature image will be inserted by the QEST Platform to these files

For the reasons above, if the QEST Platform approval workflow is to be used, and the signing user's signature image mapped to the form, a normal text field should be used to contain the mapped signature image. This text field should be set to read-only and hidden in the PDF editor.

Assuming that this field is subsequently mapped to the Signature field in the Forms Mapper, QEST Platform will identify the field as a signature and overlay the image directly into the rectangle used to define the field.

Signature Size

The signature image will be automatically scaled to fit within the bounds of the mapped field, but without stretching the image. Signatures will be horizontally centered and vertically bottom-aligned in the bounding box of the field to which they are mapped.

Javascript

It is possible to add calculations and other logic into fillable PDF forms using PDF JavaScript. This behaviour can be very simple calculations and pre-filled values through to much more complex behaviours of including buttons on forms that change the appearance and content in the form. It is well beyond the scope of these instructions to cover the possibilities but some examples are given for context.

Day From Date

In the example daily form provided here, the "Day of the week" is determined from the date, which will be of a fixed format dd-mmm-yy. This script is attached to the Day field. 

var sDate = this.getField("Date").value;
var arrDate = sDate.split("-");
var sDay = "";
 
if(sDate != null && sDate != ""){
    var month = 0;
    var year = parseInt(arrDate[2]);
     
    if (arrDate[1]=="Jan"){
        month = 1;
    }else if(arrDate[1]= "Feb"){
        month = 2;
    }else if(arrDate[1]= "Mar"){
        month = 3;
    }else if(arrDate[1]= "Apr"){
        month = 4;
    }else if(arrDate[1]= "May"){
        month = 5;
    }else if(arrDate[1]= "Jun"){
        month = 6;
    }else if(arrDate[1]= "Jul"){
        month = 7;
    }else if(arrDate[1]= "Aug"){
        month = 8;
    }else if(arrDate[1]= "Sep"){
        month = 9;
    }else if(arrDate[1]= "Oct"){
        month = 10;
    }else if(arrDate[1]= "Nov"){
        month = 11;
    }else if(arrDate[1]= "Dec"){
        month = 12;
    }
     
    if(year < 1600){
        year += 2000;
    }
 
    if(month > 0 && month < 13 && year > 2000){       
        var oDate = new Date(year,month,arrDate[0]);
        if(oDate != null){
            sDay = util.printd("ddd", oDate);
        }  
    }
}
event.value = sDay;

Simple Calculation

Consider the following calculation presented on a form:

The estimated value can be automatically calculated by attaching the following JavaScript to the field.

// Initialize value to zero
var height = 0.00;
 
if(getField("a").value!=null &&
    getField("b").value!=null &&
    getField("x").value!=null &&
    getField("HI").value!=null
    ){
        var a = getField("a").value;
        var b = getField("b").value;
        var x = getField("x").value;
        var HI = getField("HI").value;
         
        if(!isNaN(a) &&
            !isNaN(b) &&
            !isNaN(x) &&
            !isNaN(HI)){
                 
            if(Math.sin(a-b)!=0){
                height = Math.sin(a)*Math.sin(b)*x/Math.sin(a-b)+HI;
            }
     
        }
}
// Set this field's value to the calculated value
event.value = height;

Much like mapped fields any field that contains a value that is determined using JavaScript should be made read-only.

Mapping Fields

With the XSD file containing all the QESTNET data definitions, the QEST Form Mapper can now be used to map the fields on a PDF form.

1. Open the QEST Form Mapper application

2. Using the Toolbar icons (or using the File menu), load the exported XSD file and a PDF form  containing the fields that that are to be mapped

With both files loaded, the QEST Form Mapper application will appear similar to the below 

The left hand pane contains the Design and Log tabs with the Design tab being of most interest, showing at top the fields that can be mapped from the currently selected object and the objects that are available at the bottom. The right hand pane shows the loaded PDF form, with fields colored in grey, this will be referred to as the PDF View. The grey fields are the elements that QEST Platform fields can be mapped to, when the mouse is moved over the fields, they turn green to indicate which is currently under the cursor. This assists in ensuring fields are dropped onto the appropriate form field.

Mapping a field entails dragging it from the left hand pane onto one of the grey fields. Once a mapping has been made, the field in the PDF View will turn blue and will display the mapping ID. In the following example, the Work Date from the Work Order has been dragged over to the Date field on the example PDF report template:

To remove a mapping, left click to select the field in the PDF View and press the delete key on the keyboard. 

Custom Fields

Custom fields associated with a Client, Project, Work Order or Form object can also be mapped to the form. These fields will be displayed on the Design tab grouped under the heading "Custom Fields".

Out of Specification Values

Forms can have the Is Out of Specification field for a form mapped to a field in the PDF form (a checkbox or otherwise) such that filling out the form sets this flag.

Forms with a mapping for Is Out of Specification will update this field in the QEST Platform database when a form is uploaded. The QESTLab tree will display in red if a form is out of specification.

If the form has been edited in QESTLab in such a manner that the Is Out of Specification status changes, the user will need to step off the form in the tree for the status to visually update.

Please note that no additional feedback is displayed in the QESTField web or mobile applications when a form is out of specification so the design of the form should make this clear.

Valid Export Values when Designing the PDF

When designing the PDF, the value that is exported can be defined by a checkbox field . Here is an example of a checkbox exporting Yes using the PDF editor Adobe Acrobat Standard DC:

As long as this field exports a value that can be interpreted as true, it will allow setting the "out of specification" field in the QEST Platform database.

Valid values include:

• True or true

• Yes or yes

• T or t

• Y or y

• 1

Common Fields

Some common fields that are mapped onto forms are explained below.

Refreshing Mapped Fields

Users have the ability to refresh mapped fields. It is recommended that mapped fields be made read-only.

Logging

To view the Log, click on the log tab:

The QEST Form Mapper will display warnings, errors and other information about program execution here. The logs will also be saved to an external file that should be provided to Spectra QEST when contacting the Service Desk for assistance or troubleshooting of the QEST Form Mapper. For more details on logging see the QEST Form Mapper Installation Guide for more information on configuring logging. Spectra QEST may request a copy of the log file generated by the QEST Form mapper for troubleshooting purposes.

Products described on these pages, including but not limited to QESTLab®, QESTNet, QESTField, Construction Hive, and associated products are Trademarks (™) of Spectra QEST Australia Pty Ltd and/or related companies.

The content of this page is confidential. Do not share, duplicate or distribute without permission.

© 2020 Spectra QEST® Australia Pty Ltd and/or related companies.  Terms of Use and Privacy Statement