GeneralPdfUtils
The PDF Generator plugin comes with a script include called GeneralPdfUtils, which contains the majority of the functions which we can use to interact with PDF forms.
Note: usage of the PDF Generator plugin may have licensing implications.
Detecting fillable fields
Every PDF form is unique, and has different fields which can be completed. We thus need a way to get a list of all the fields that exist on the form so that we know what we can plug into it. To do this we can use the getPDFFields() function:
[js]var pdf = new global.GeneralPdfUtils();
// Sys ID of a PDF form attached to any record
var attachmentSysId = ‘0fd6278d4f25c70022f40ccf0310c7c8’;
var fieldsString = pdf.getPDFFields(attachmentSysId);
var fields = JSON.parse(fieldsString);
[/js]
When running the above code on my example PDF, the fields variable contains the JavaScript object shown below:
[js]{
"Read Terms and Conditions": "",
"First name": "",
"Gender": "",
"Last name": ""
}[/js]
When we fill the form later on, you will see that the function to do this ingests it’s data in this exact format. This means that now that the fields variable contains this structure, we can directly manipulate it and feed it back into the form. We could also loop over it and check if a field of that name exists on a certain table in ServiceNow. If it does, we can set that PDF form field to the value of the field in that table. This is very powerful stuff!
Detecting the types of fields
There are multiple types of fields which can exist on a PDF form. We can use the getFieldType() function to do this.
[js]var pdf = new global.GeneralPdfUtils();
// Sys ID of a PDF form attached to any record
var attachmentSysId = ‘0fd6278d4f25c70022f40ccf0310c7c8’;
var fieldTypesString = pdf.getFieldType(attachmentSysId);
var fieldTypes = JSON.parse(fieldTypesString);[/js]
When running the above code on my example PDF, the fieldTypes variable contains the JavaScript object shown below:
[js]{
"Read Terms and Conditions":
{
"true_value": "[Off, Yes]",
"field_type": "2"
},
"First name":
{
"true_value": "",
"field_type": "4"
},
"Gender":
{
"true_value": "",
"field_type": "3"
},
"Last name":
{
"true_value": "",
"field_type": "4"
}
}[/js]
You can see that the Read Terms and Conditions field is a checkbox (field_type = 2) with a Yes (checked) and Off (unchecked) state. First name and Last name are both text fields (field_type = 4), and Gender is a radio field (field_type = 3).
Fill the form
We can now use the knowledge we’ve gained about the PDF form to fill in the form using the prefillPDF() function.
[js]
var pdf = new global.GeneralPdfUtils();
// Sys ID of an attachment
var attachmentSysId = ‘0fd6278d4f25c70022f40ccf0310c7c8’;
var jsonObject = {
"Read Terms and Conditions": "Yes",
"First name": "Dylan",
"Gender": "Male",
"Last name": "Lindgren"
};
var jsonString = JSON.stringify(jsonObject);
var destinationTableName = ‘incident’;
var destinationTableSysId = ‘9de878bf4f34c300ab4450af0310c722’;
var pdfName = ‘my-completed-form.pdf’;
pdf.prefillPdf(jsonString, destinationTableSysId, attachmentSysId, destinationTableName, pdfName);
[/js]
If we go into the record we’ve targeted in the destinationTableSysId variable, we will see that we have a new attachment called my-completed-form.pdf which is a completed PDF form with the values we supplied!
Other functions
There’s a number of other functions in the GeneralPdfUtils script include, some of which I feel will be worth investigating:
isFillable()mergeImageToPdf()isValidPdfTemplateForPreFill()
Depending on their usefulness, I may write a follow up blog post covering under what situations one would use these, along with examples.
PDF Functionality that is not Supported
The TinyMCE editor allows rich text creation that the PDF generator was not designed to support. TinyMCE is the standard editor for the ServiceNow platform, so it can’t be simply updated to not allow certain HTML elements that PDF generation supports. Some of the more common questions we’ve seen involve expectations of the following non-supported HTML elements:
- Vertical alignment
- Page breaks (workaround to add one manually using document.addNewPage()
- Table-specific color (text color is supported)
- Custom spacing between blocks of text or images
- Custom column width in HTML tables
- Custom column alignment in HTML tables
- Custom border styling in HTML tables
- CSS text manipulation ()including CSS based font tags)
- Inline styling
- Background images
FAQ
- Q: What page sizes can the PDF generator utilize?
- A: Letter, Legal, and A4. A4 is the default if no size is passed in. Pagesize is the final parameter for the generalFormAPI.setDocument() API.
- Q: What version of iText does the PDF generator use?
- A: Currently the PDF generator utilizes iTextPDF version 5.5.2
Please mark helpful if this helped
Thank you,
Vikram
