Getting Started

The Application Menu

Access to the UXstorm PDF Application is controlled by two roles

• x_uxs_pdf.user – Enables the user to create and edit Forms and have access to the Support Link.
• x_uxs_pdf.admin – Enables the Administration menu and the Properties module.

With both roles the application will look like the following:

With only the x_uxs_pdf.user role the application will appear as:

With only the x_uxs_pdf.admin role the application will appear as:

Create a PDF Form

To create a new PDF form, go to the UXstorm PDF Forms -> Form module and select New.

A new Form will appear. At minimum you must:

• Attach a fillable nonprotected/encrypted PDF
• Give the form a Name that will appear as the attached PDF
• Specify a Table from ServiceNow to use for the mapping
• Default value for Handle Attachments: Single Attachment covers how the PDFs will be handled when generated. After the above information is entered and the form is saved, then the UI Action Get Fields will be available. Pressing this button will send the PDF to a MID Server and when done all the available fillable fields from the PDF will be added to the Form. You then must specify how each field is to be mapped. By default, no field is mapped. See later section on Field Mapping.

Fields on the Form:

Name	Description
Name	This is the name that is used when the PDF is attached to the ServiceNow record.
Number	Unique identifier for each Form
Status	Specifies what state the definition of the form is in: Draft – Initial state, no fields are retrieved yet. Retrieving – The PDF is being sent to a MID Server and is being processedReady – The PDF has been processed by a MID Server and all Fields have been added to the Form
Active	Only active forms are used for generation
Create Conditionally	Specifies that this Form is generated based upon a Specific Condition. See the Previous description for more info (provide link)
Condition	Only appears if Create Conditionally is checked. This is the specific condition on the mapped table to watch for to generate this PDF. This condition will be checked on the specific record on Insert and Update actions.
Application	Specifies which application this form belongs to.
Run Post Script	When checked, a JavaScript will be run after the normal generation of the data mapping for the form. This enables mass mapping of fields with JavaScript and is how to handle relationship data that is not directly related to the record by a reference field. For instance querying another table that points to the current record and filling in data using the queried data.
Script	Appears only when Run Post Script is checked. A variable current is passed to the script with the GlideRecord object of the record that is being used to generate the PDF. Another variable, fields, is present. It is a hash that specifies what each field on the form should be set to. The name used is the Internal Name. You can rename any field to a more meaningful name for your support, but the Internal Name must be used . For instance, the following field is named Supervisor Approval but it’s Internal Name is undefined_2. To set this field you would use the following JavaScript statement:fields[‘undefined_2’] = “On”;
Table	Specifies which ServiceNow table to use for the PDF mapping
Catalog Item	Only appears if Table is Requested Item [sc_req_item]. This specifies the catalog item to use in field mappings. Directly mapped fields will have the option to map to fields on the Requested Item or any variable on the specified catalog item. NOTE: If Create Conditionally is checked, then the check for this catalog item on the sc_req_item is added to the condition automatically so that the PDF is not processed on all requests, only for those for the specified catalog item.
Handle Attachments	When a PDF is generated, it is attached to the ServiceNow record used for the mapping. This selection specifies how to handle multiple generations and attachments.Multiple Attachments – Every generation will attach to the record with the same nameSingle Attachment – Only one attachment will be attached to the record with this nameVersion by Number – Each generation is attached to the record but with a suffix of _XXX where XXX is a number with leading zeros indicating which version/generationVersion by Date – Each generation is attached to the record and the current date/time is appended to the name
Flatten	The produced PDF will no longer be fillable and can not be changed
Password Protect	Enables encrypting the generated PDF with a password.
Password Field	Appears only if Password Protect is checked. All fields on the mapped table are listed but only select a Text field for the password. This will be the password used to protect the PDF. Ensure you have good ServiceNow ACL’s around this field so that only authorized users can see the password.
Wait for MID Server	When checked, UXstorm PDF will queue up the request to generate the PDF even if there is no MID Server currently available. If unchecked, then an error is returned if there is no MID Server available to generate the PDF.
Run Pre Attach Script	When checked, a JavaScript will be ran before the attachment is created on the current record.
Pre Attach Script	Only appears if Run Pre Attach Script is checked. Variables are passed to the script for the name, current record, and attachment payload. If the script returns false, then the attachment creation is aborted.
Run Post Attach Script	When checked, a JavaScript will be ran after the attachment is created on the current record.
Post Attach Script	Only appears if Run Post Attach Script is checked. Variables are passed to the script for the name, current record, attachment payload, and sys_id of the created attachment in the sys_attachment table.
Type	Specifies the Name Type to use to generate the attachment name.
Classification	Can be used by a Name Type for naming purposes.
Audience	Can be used by a Name Type for naming purposes.

Post Script

The Post Script is processed after all the automatic mapping is performed by UXstorm PDF Application. You can use this script to fill in fields that:

• May not be easy to map directly
• Require the combination of multiple fields, such as a mailing address may be a combination of street address + city + state + zip
• Requires advanced querying to find the data to map to tables
• To specify what pages in the PDF should not be generated

The following fields are used in the Post Script

Locking fields on a PDF

When moving a PDF through a process, you may want to have certain Fields “Locked” so that the form cannot be edited by Adobe Reader and the data changed. This is especially true when certain sections are “signed” by a person. Those fields that were signed should not be changeable. This can be accomplished using the Post Script and the variable _lockAfter. The following is an excerpt from a Post Script that locks certain fields when the request is in certain states. Note, that when generating a PDF, it starts from a blank template. You can not lock fields “before” the data is set as they are blank. This will produce a PDF that has fields locked, but they will be filled in each time the PDF is generated. It is up to you to ensure that those fields do not change in ServiceNow between each generation.

var state = current.form_state + '';
var userFields = ['CIVILIAN',
    'CONTRACTOR',
    'DEACTIVATE',
    'FN',
    'IA training',
    'IA ttraining date',
    'INITIAL',
    'location',
    'MILITARY',
    'MODIFICATION',
    'name',
    'OTHER',
    'request date',
    'requestor department',
    'requestor email',
    'requestor mailing address',
    'requestor organization',
    'requestor phone',
    'requestor rank',
    'Signature of User date',
    'system name',
    'US',
    'USER ID',
    'user signature text',
    'userid Specified'
];

var supervisorFields = ['ACCESS OTHER',
    'AUTHORIZED',
    'CLASSIFIED',
    'PRIVILEGED',
    'Signature of Supervisor date',
    'UNCLASSIFIED',
    'VERIFICATION OF NEED TO KNOW',
    'access expiration date',
    'classified category',
    'contractor info',
    'justify',
    'requies access to other',
    'supervisor department',
    'supervisor email',
    'supervisor phone',
    'supervisor signature text'
];

switch (state) {
    case 'Request Approval':
        _lockAfter = userFields;
        break;
    case 'OPR Approval':
        _lockAfter = userFields.concat(supervisorFields);
        break;
    default:
        _lockAfter = userFields.concat(supervisorFields);
}

Removing Pages from a PDF

To have pages removed from a generated PDF, set the selectPages variable in the Post Script on the form The required format is the same as used in specifying print ranges in applications.

Examples:

• "2-" -- keeps all pages in document starting at page 2
• "1,3,5-10" -- keeps pages 1, 3, 5, 6, 7, 8, 9, 10

To help with setting this field, a utility function is available for you to use.

/* Determine variable length PDF.  The autoTables contain the pages used by the
 * autoTable mappings.
 */

var pages = new x_uxs_pdf.PDFPages();

// Add page one to always be generated
pages.addPage(1);

// Process the autoTables
pages.processAutoTables(autoTables);

// Set the selectPages to all the pages to have in the generated PDF
selectPages = pages.getPages();

PDFPages

A helper routine is provided to help with the selectPages variable in the Post Script. The routine is a script include and is created by:

var pages = new x_uxs_pdf.PDFPages();

The following methods are available:

processAutoTables( autoTables )

Processes the pages used by any processed AutoTable. This function takes an argument of the autotables object provided in the Post Script.

var pages = new x_uxs_pdf.PDFPages();

// Process the autoTables
pages.processAutoTables(autoTables);
addPage( page )

Adds a page to the pages to keep. Takes a single argument of the page number to keep.

var pages = new x_uxs_pdf.PDFPages();

// Add page one to always be generated
pages.addPage(1);

addPages( first, last )

Adds a page range to the pages to keep. First argument is the starting page and the second argument is the last page in the range.

var pages = new x_uxs_pdf.PDFPages();

// Page 1, 2, and 3 should always be generated in each PDF

pages.addPages(1,3);

getPages()

Returns the valid selectPage format for the pages processed by the page utility.

See last line in this example:

/* Determine variable length PDF.  The autoTables contain the pages used by the
 * autoTable mappings.
*/

var pages = new x_uxs_pdf.PDFPages();

// Add page one to always be generated
pages.addPage(1);

// Process the autoTables
pages.processAutoTables(autoTables);

// Set the selectPages to all the pages to have in the generated PDF
selectPages = pages.getPages();

Mapping Fields

Once you have retrieved all the fields, the Status on the form will be Ready and all the Fields will be listed at the bottom of the form. By default, no fields are mapped. You must determine which fields are to be mapped and how.

Each field will have a Name and Internal Name field. You can change the Name of the field if you need to make it more meaningful. Most of the time this won't be necessary, but sometimes the PDF Field names are generated or named like the following:

Notice that the Internal Name is undefined_3. This did not help determine what the field represents on the PDF. To help out Generate PDF with Field was clicked and the PDF that is attached to this Field was generated. Viewing this PDF will show you what the PDF looks like with this field used. Since this field is a CheckBox, that box will be checked. If it was Text, then "XXXXXXXXXXXXXXX" will be put in the Text area. For List, RadioButton, and ComboBox a PDF is generated for each choice value. Looking at this PDF shows the following:

You can see that the Disapproval button is checked. With this in mind, the name of the Field was manually changed from undefined_3 to Supervisor Disapproval.

Looking at the first image, you can see the basic methodology used to do the mapping.

• Check Map
• Select Mapping Type
• Specify the needed mapping for the Mapping Type

This example is for a CheckBox so the only two Mapping Type options are Script and Conditional. This Field uses Conditional and specifies that the CheckBox is checked when the Supervisor Recommendation is set to Disapproval on the mapped record in ServiceNow.

Available Fields:

Mapping Types

Direct

Direct field mapping enables you to map a ServiceNow field or catalog variable directly to the PDF field. The DisplayValue of the field or variable will be retrieved for the ServiceNow field and placed in the PDF field. The following shows mapping a Field CONTROL NUMBER to the ServiceNow field Number

With Mapping Type set to Direct, and Mapping Type not checked, the Field field on the form will list all fields on the related record. You can also expand out related fields and select their fields to be used. Here is an example where the related Personel record is expanded and their Full Name is mapped to the NAME field on the PDF.

Supported PDF Field Types

• Text

Catalog Variables

If the table on the PDF Form is Requested Item [sc_req_item], then this form will have additional options for direct mapping to handle catalog variables. A field Map Catalog Variable will appear and if checked, then the variables on the selected Catalog Item for the PDF Form will be displayed. All variables, including those in variable sets, are displayed. The variables are selected by their questions.

If Map Catalog Variable is not checked, then regular direct field mapping is done.

Template

A Template field mapping takes a template either as a string on the field record or from a field that can be on the current record or dot-walked from the current record. This template is used to generate the text that will be mapped to the field.

Template mappings allow you to combine values from ServiceNow fields, values from catalog variables, and static text to create a string to be mapped into a PDF field. Values are specified using string replacement using the following syntax:

{{current.field}} – field specifies the field on the current record.

{{variable.name}} – name is variable associated with the current record.

For example, {{current.total}} will be replaced with the value of the total field on the current record. Dot walking is supported in string replacement. For example, {{current.user.first_name}} will be replaced with the value of the first name field on the user record that is referenced by the user field on the current record. Similarly, {{variable.color}} will be replaced with the value of the color catalog variable on the current record.

Example of a Template Mapping:

User: {{current.user}}, Department: 
{{current.user.department}} Manager: 
{{current.user.department. department\_head}}

It would map a string similar to the following:

User: Abel Tuter, Department: 
IT Manager: Rob Phill

Supported PDF Field Types

• Text

Format Script

If Run Format Script is checked, then you can specify a format script to run to assist in formatting the data for the form.

The script will have access to two variables:

• Current -- A GlideRecord to the current record
• value -- The value of the data to place in the field as retrieved from the mapping

To format the data, you may use any Javascript commands to adjust the data and specify the value to use by setting the variable answer to the value.

For instance, to convert the data to uppercase:

/**************************************************
 * Format Script.
 *
 * Set variable answer to the new format.
 *
 * Variables:
 *
 * current -- The record generating the PDF
 * value   -- The current value of the mapped field/variable
 *
 * Example:
 *
 * answer = value.substring(0,10);   // Make sure the value is at most 10 chars
 *
 */

answer = value.toUpperCase();

Conditional

Conditionals are used as a Yes/No decision for the Field. The Condition is evaluated with the current record. If the Condition matches then the Conditional is considered to be true otherwise it's considered false. If the Condition is blank, then it is considered false.

Here is an example where EMERGENCY is a CheckBox and is ON if the Type of Leave is Emergency. The Condition field is the normal ServiceNow Condition creator used throughout ServiceNow. It allows for simple to very complex conditions.

Supported PDF Field Types

• CheckBox -- If True then CheckBox is ON on the PDF form.
• Choices on PDF Fields with Mapping Type set to Mapping -- If True then the Field will contain this Choice.

Memo

The Memo field mapping type provides PDF generation functionality, as opposed to form filling. As a result, it functions very differently from other mapping types. A memo field mapping takes a memo template either as a string on the field record or from a field that can be on the current record or dot-walked from the current record. The Memo template can use string replacement the same way that a Template Mapping Type does and can also use some additional formatting commands.

Another way memo mappings are different from other mapping types is, rather than placing text in the field, the field is flattened and used as a bounding box where the memo is written. An additional overflow field can be selected that will be used in the memo field that overflows the bounding box of the first field. The entire page containing the overflow field will be flattened and duplicated as many times as needed so the entire memo can be written. Extra overflow pages are inserted directly after the original overflow page.

NOTE: If you plan on using the memo overflow field feature, make sure that there are not preexisting page numbers on the PDF. For example, if the page containing the overflow field has, “page 5” written on it and the memo field generates three new pages, then you will have four pages that say, “page 5”. Instead, use the Insert Page Numbers functionality to dynamically generate page numbers.

Memo Template Syntax

String replacement:

{{current.field}} – field specifies the field on the current record. Field can be a dot walk to a related field if field is a reference field.

{{variable.name}} – name is variable associated with the current record.

Formatting Commands use the following syntax [[command]]

Some commands take arguments that can be provided in any order using the following syntax [[command:arg-name=value;arg-name=value;…]]

Unless a command is self-closing, a closing command is required [[/command]]

Commands and arguments are not case-sensitive. Values are case-sensitive.

Available Formatting Commands

Body

Provides styling information used as the default for the whole memo. Must be a top-level command tag. (Not contained in any other tags.) This tag is self-closing and no [[/body]] tag is required.

Arguments:

P

Contains a paragraph. Can provide Styling information as necessary to override the defaults set by the body tag. Arguments:

Image

Inserts an image into memo at the location of the tag. Find more information on configuring images for use in memo fields in the image section of this document. This tag is self-closing.

Arguments:

Bold

Contains text to be made bold.

Italic

Contains text to be made italic.

Underline

Contains text to be underlined.

Line-through

Contains text to put a line through.

Tab

Inserts tab spacing

Supported PDF Field Types

• Text