QEST Platform Documentation Working Version

Applies to QESTField Forms

This article describes the process for mapping fillable PDF Forms to QEST Platform database fields for inclusion in QESTField Forms workflows.

1 Overview
2 Creating a Fillable PDF Form for QEST Platform
- 2.1 Read Only Mapped Fields
- 2.2 Date Fields
- 2.3 Signatures
  - 2.3.1 Field Types
  - 2.3.2 Signature Size
- 2.4 Javascript
  - 2.4.1 Javascript Compatibility
  - 2.4.2 Day From Date
  - 2.4.3 Simple Calculation
- 2.5 Mapping Fields
- 2.6 Custom Fields
- 2.7 Out of Specification Values
  - 2.7.1 Valid Export Values when Designing the PDF
- 2.8 Common Fields
- 2.9 Refreshing Mapped Fields
- 2.10 Logging

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.

QEST Form Mapper installed, see QEST Form Mapper Installation Guide for more information
An XSD file from a form definition, see Creating New Forms for more details
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

Javascript Compatibility

Not all PDF form filling software supports all of the available Adobe PDF javascript functionality. Especially on mobile devices, support for JavaScript can be quite limited so care should be taken when adding scripts to fillable PDF forms. If JavaScript is used the functionality should be tested and verified on the software that end users will be using to fill out their forms, not just in Adobe products.

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.

Open the QEST Form Mapper application
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.

The out of specification status will be recognized when publishing to Construction Hive.

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.

Object	Field	Description

Object	Field	Description
Client	Client Code	The client code, or identifying number in the QEST Platform database
Client	Client Name	The name of the client as it is set in the QEST Platform database
Client	Street	The first line of the street address of the client
Client	Street2	The second line of the street address of the client (often blank)
Client	City	The city set in the client record's address
Client	Post Code	The post (zip) code set in the client record's address
Client	State	The state set in the client record's address
Client	City State Postcode	A special field that combines these three elements into one line for easier mapping to an individual field
Client	Type Name	The client "Type" set in the client record
Client	QestID	Internal identifier for the client record in QEST Platform. Will always be 20001 for client records.
Project	Project Code	The project code, or identifying number in the QEST Platform database
Project	Project Name	The name of the project as it is set in the QEST Platform database
Project	Street	The first line of the street address of the project
Project	Street2	The second line of the street address of the project (often blank)
Project	City	The city set in the project record's address
Project	Post Code	The post (zip) code set in the project record's address
Project	State	The state set in the project record's address
Project	City State Postcode	A special field that combines these three elements into one line for easier mapping to an individual field
Project	Type Name	The client "Type" set in the project record
Project	QestID	Internal identifier for the project record in QEST Platform. Will always be 20002 for project records.
Project	Project Owner Name	The name of the individual set as the project owner in the project record.
Project	Work Instruction	A default work instruction set on the project, is automatically copied to work orders in QEST Platform.
Work Order	Work Date	Date on which the field work took place.
Work Order	Field Technician Name	Name of the field technician assigned to the work order.
Work Order	Work Order ID	The ID of the work order, this number is usually automatically generated by QEST Platform and often forms the basis of the ID number of anything (reports, samples) under the work order.
Work Order	Client Requirements	The work instructions on the work order.
Work Order	TRN	Test request number on the work order.
Work Order	General Location	The location set on the work order.
Form	Report No	The report number for the form.
Form	Issue No	The issue number of the form, automatically incremented every time the form is signed.
Form	Signatory Name	If the form is signed, the name of the signing user.
Form	Signatory Title	If the form is signed, the title of the signing user.
Form	Signature Image	If the form is signed, the image of the signing user's signature.
Form	Signed Date	If the form is signed, the date at which the form was signed. If the form was signed using QESTLab, the date here will represent the time on the QESTLab server at time of signing. If the form was signed using the QESTField app, then it will be the local date and time on the device at time of signing. If the form was signed using the QESTField Forms web view, then it will be the local date and time of the server on which QESTNet (the background service) is running.
Form	QESTID	Internal identifier for the form type in QEST Platform. Will be the same as the identifying number set when the form definition was first created (e.g. 190001) see Creating New Forms for more information.

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.

QEST Platform 5.7 Documentation

Mapping Forms

Contents