Articles, Blogs, Videos, Podcasts, Share projects - Experiences from the field
Hi there,
Struggling with making a PDF export from a record? For example wanting to generate a user agreement, with data from the current record? The default form export to PDF isn't that pretty, and scripting such an export yourself used to be pretty tough or limited looking at layout possibilities.
Used to be! With the Quebec release a nice new API has been introduced, an API which somehow hasn't got that much attention, I missed it also 🙂 An API with methods with which you can easily:
- Dynamically generate a PDF from an HTML string and attach it to a record
- Fill fields in a PDF
- Sign a PDF
- Unflattened, flattened, or partially flattened
- Retrieving PDF field data
In this article, I'll highlight "Fill fields in a PDF".
Pre-Quebec
Having a template PDF with fillable fields and filling it, through for example a UI Action, was already possible pre-Quebec. Dylan Lindgren wrote a nice piece of art on this, "Filling PDF forms in ServiceNow".
Quebec
With Quebec ServiceNow introduced a new API called "PDFGenerationAPI". One of the methods allows you to fill fields in a PDF easier, more robust, and... This can be combined with other methods which I'll write about in a future article.
PDFGenerationAPI fillDocumentFields
Let's just start with sharing working code 😀.
// Define variables
var pdfTemplateSysId = '<sys_id of the template PDF containing fillable fields>',
tableName = current.getTableName(),
recordSysId = current.getUniqueValue(),
pdfName = '<Name of the newly created PDF>';
// Setup field mapping
var fieldMap = {
"company" : "Company X"
"employee" : current.assigned_to.getDisplayValue(),
"ci" : current.category.getDisplayValue(),
"brand" : current.manufacturer.getDisplayValue(),
"model" : current.model_id.getDisplayValue()
};
// Execute API
var v = new sn_pdfgeneratorutils.PDFGenerationAPI;
var result = v.fillDocumentFields(fieldMap, pdfTemplateSysId, tableName, recordSysId, pdfName);
// Log result
gs.info(JSON.stringify(result, null, '\t'));
A successful return would provide you with something like:
{
"attachment_id": "35cc9b6d2f9db010cd5dd99df699b62f",
"message": "Request completed successfully.",
"status": "success"
}
In this example, I'm assuming this code is used on the current record. If that's not the case, do update tableName and recordSysId. Also this example is code used in a UI Action. Though you could go crazy on this! Automating the generation of the PDF, or sending the created PDF by email to the user, uploading the PDF to a server, etcetera. You don't have to limit this to manually executing a UI Action which just attaches a PDF to the current record.
Comparing this code with the Docs page on fillDocumentFields, you'll notice some slight differences. I'd like to see this code as a bit more improved. The code mentioned on the Docs page does work already, unlike the code for one of the other methods ☹️.
What is incorrect on the Docs page, is the description of the Parameters:
- fieldMap is not optional.
- sysId concerns the sys_id of the pdfTemplate (that why I changed this into pdfTemplateSysId).
- tableName is not the table containing the PDF, it's the table on which the newly created PDF will be attached.
- tableSysId is not the sys_id of the record containing the PDF, it's the sys_id of the record on which the newly created PDF will be attached.
- pdfName is optional, if left out the name of the newly created PDF will be the sys_id of the attachment + ".pdf".
Note
We are working with a template PDF with fillable fields. In this case I've added the template PDF to the UI Action. If you would promote your development through an Update Set, by default the attachment will not be included. So that would be a one-time fix in the environment on which you are previewing and committing the Update Set.
Because the template PDF is in the sys_attachment table, when performing system clones to lower environments, by default sys_attachments are excluded. Either you need to change the system clone, or after performing the System Clone adding the template PDF again on the lower environment.
Flatten
Good to mention, the fillDocumentFields method flattens all the fields in the PDF automatically. If you would like a different behavior, that's possible using the fillDocumentFieldsAndFlatten method instead. The basic working is the same, only an additional 6th param is used. This 6th param should contain one of the following values:
- "donot_flatten" - Do not flatten any fields.
- "partially_flatten" - Flatten only the fields which are modified.
- "fully_flatten" - Flattens all the fields.
// Define variables
var pdfTemplateSysId = '<sys_id of the template PDF containing fillable fields>',
tableName = current.getTableName(),
recordSysId = current.getUniqueValue(),
pdfName = '<Name of the newly created PDF>';
// Field mapping
var fieldMap = {
"company" : "Company X"
"employee" : current.assigned_to.getDisplayValue(),
"ci" : current.category.getDisplayValue(),
"brand" : current.manufacturer.getDisplayValue(),
"model" : current.model_id.getDisplayValue()
};
// Flatten document
var flatten = {
"FlattenType" : "partially_flatten"
};
// Execute API
var v = new sn_pdfgeneratorutils.PDFGenerationAPI;
var result = v.fillDocumentFieldsAndFlatten(fieldMap, pdfTemplateSysId, tableName, recordSysId, pdfName, flatten);
// Log result
gs.info(JSON.stringify(result, null, '\t'));
Result
After having transformed a Word document into a PDF with fillable fields and having the PDF attached in ServiceNow (see attachments added to this article), the result of the above code (using a UI Action) would be something like:
In a follow-up article I'll dive into adding an image into your template PDF.
---
And that's it actually. Hope you like it. If any questions or remarks, let me know!
| C |
If this content helped you, I would appreciate it if you hit bookmark or mark it as helpful.
Interested in more Articles, Blogs, Videos, Podcasts, Share projects I shared/participated in? |
Kind regards,
Mark Roethof
ServiceNow Technical Platform Architect @ Quint Technology
2x ServiceNow Developer MVP
2x ServiceNow Community MVP
---
Hi there,
Thx.
In my next article I can share some extra attention on how to create a fillable PDF. Though it is something that has nothing to do with ServiceNow. You can use for example Adobe Acrobat Pro.
In short really quick, within Adobe (depending on your version) using something like:
Then fields will be automatically generated where possible (for example if your PDF uses underscores like _________, that would be automatically discovered as possible fillable field. If not and wanting to add your own fillable field (or a different type), right mouse click in your PDF:
Pretty basic, though you do need an Adobe Acrobat version which allows you to add fillable fields.
If you like the articles, don't forget to mark them as helpful.
Kind regards,
Mark
Hello Mark,
Thanks, the above article is really helpful.
I am too working with the PDF document template and facing few issues, hoping if you have any solution for them.
1. I am trying to Map a HTML field in PDF Template, but when it happens, the data appears with all the Tags, and if I remove the tags, then the formatting is lost.
So is there a way that I could remove the tags without losing the formatting of the text?
2. While mapping the signature Date field, I could see the name of person whose signature date is supposed to be there is the previewed over the date field, although it gets replaced with the date after the document is signed, but it would be really helpful if we could remove it.
Thanks for the help in advance.
Best Regards,
Anubha Datey
Hi Mark,
Do you have any suggestions on what I should do if I want to set the font for the fill PDF?
Thanks for the help in advance.
Best Regards
