PDFGenerationAPI - Scoped, Global

The PDFGenerationAPI provides support for PDF conversion and handling PDF fields.

This API is part of the ServiceNow PDF Generation Utilities plugin (com.snc.apppdfgenerator) and is provided within the sn_pdfgeneratorutils namespace. The plugin is activated by default.

Use the glide.pdf.url.whitelist property to add an extra layer of validation to ensure whether any external URL introduced should be included in the generated PDF. If the system property glide.pdf.url.whitelisting.enabled is set to true, the PDF does not process URL content unless it is listed in the Value field of the com.snc.pdf.whitelisted_urls system property. These properties are listed in the System Properties [sys_properties] table. For more information, see Available system properties.

Note: The maximum PDF size is 50 MB.

The methods in this class enable the following tasks:

• Dynamically generate a PDF from an HTML string and attach it to a record
  • A4 size without headers or footers – PDFGenerationAPI – convertToPDF(String html, String targetTable, String targetTableSysId, String pdfName, String fontFamilySysId, Object documentConfiguration)
  • Customizable page size with options for header and footer – PDFGenerationAPI – convertToPDFWithHeaderFooter(String html, String targetTable, String targetTableSysId, String pdfName, Object headerFooterInfo, String fontFamilySysId, Object documentConfiguration)
• Queue a PDF to be generated from an HTML string and attached to a record
  • A4 size without headers or footers – PDFGenerationAPI – convertToPDFAsync(String html, String targetTable, String targetTableSysId, String pdfName, String fontFamilySysId, Object documentConfiguration)
  • Customizable page size with options for header and footer – PDFGenerationAPI – convertToPDFWithHeaderFooterAsync(String html, String targetTable, String targetTableSysId, String pdfName, Object headerFooterInfo, String fontFamilySysId, Object documentConfiguration)
• Fill fields in a PDF
  • PDFGenerationAPI – fillDocumentFieldsAndFlatten(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName, Object flatten)
  • PDFGenerationAPI – fillDocumentFields(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName)
  • PDFGenerationAPI – isDocumentFillable(String sysId)
• Sign a PDF
  • PDFGenerationAPI – fillFieldsAndMergeSignature(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName, PdfMergeSignRequestor requestor, Object flatten)
  • PDFGenerationAPI – getFilledDocumentWithSignatureAsBase64(Object fieldsMap, String sysId, PdfMergeSignRequestor requestor, Object flatten)
• Restrict editing filled fields as flattened or partially flattened – PDFGenerationAPI – fillDocumentFieldsAndFlatten(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName, Object flatten)
• Retrieve PDF page size and field data
  • PDFGenerationAPI – getPdfPageSizes(String sysId)
  • PDFGenerationAPI – getDocumentFieldsType(String sysId)
  • PDFGenerationAPI – getDocumentFields(String sysId)
• Redact information in a PDF – PDFGenerationAPI – redact(Object inputJson)

Note: These methods can also be used for documents created by non-catalog items.

Related APIs:

• PdfMergeSignRequestor
• SVGToPDFConversionAPI

Parent Topic:Server API reference

PDFGenerationAPI – PDFGenerationAPI()

Instantiates a new PDFGenerationAPI object.

The following example shows how to create a PDFGenerationAPI object.

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;

PDFGenerationAPI – convertToPDF(String html, String targetTable, String targetTableSysId, String pdfName, String fontFamilySysId, Object documentConfiguration)

Converts an HTML string to a PDF document.

This method creates a PDF using the page size A4 – 595 × 842 points. Content will be truncated if it exceeds this size.

To generate a PDF with additional settings, such as page size, orientation, and page numbers, use convertToPDFWithHeaderFooter().

{​
   "accessibilityEnabled" : Boolean,
   "toc_config" : "String",​
   "page_number_config": "String"​
}​

{
  "attachment_id": "String",
  "message": "String",
  "request_id": "String",
  "status": "String"
}

The following example shows how to convert HTML to a PDF and attach it to a record in the Incident [incident] table.

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;

//  (Option) get HTML from the description field of an incident record
var gr = new GlideRecord("incident");
var html;

if (gr.get("<tableSysId>")) {
 html = gr.description.toString();
}

var result = v.convertToPDF(html, "incident", "<target_sys_id>", "myPDF");
gs.info(JSON.stringify(result));

Output:

{"attachment_id":"<sys_id>","message":"Conversion is successful.","request_id":"<change_sys_id>","status":"success"}

PDFGenerationAPI – convertToPDFAsync(String html, String targetTable, String targetTableSysId, String pdfName, String fontFamilySysId, Object documentConfiguration)

Stages a job that converts an HTML string to a PDF document asynchronously. Asynchronous processing enables you to work in the instance while the PDF conversion is in progress. This is especially helpful for larger PDF exports.

This API creates a PDF using the page size A4 – 595 × 842 points. Content will be truncated if it exceeds this size.

To generate a PDF with additional settings, such as page size, orientation, and page numbers, use convertToPDFWithHeaderFooterAsync().

{​
   "accessibilityEnabled" : Boolean,
   "toc_config" : "String",​
   "page_number_config": "String"​
}​

{
  "message": "String",
  "request_id": "String"
}

The following example shows how to queue a task that converts HTML to a PDF. When the conversion is complete, the PDF named "myPDF" is attached to the target record in the Incident [incident] table.

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;

//  (Option) get HTML from the description field of an incident record
var gr = new GlideRecord("incident");
var html;

if (gr.get("<tableSysId>")) {
 html = gr.description.toString();
}

var result = v.convertToPDFAsync(html, "incident", "<target_sys_id>", "myPDF");
gs.info(JSON.stringify(result));

Output:

{"message":"HTML to PDF Conversion is in progress.","request_id":"<sys_id>"}

PDFGenerationAPI – convertToPDFWithHeaderFooter(String html, String targetTable, String targetTableSysId, String pdfName, Object headerFooterInfo, String fontFamilySysId, Object documentConfiguration)

Converts an HTML string into a PDF with header and footer content.

Use this method to generate PDFs with page settings:

• Header and footer information
• Margin sizes
• Orientation
• Enumeration
• Page size

{
  "FooterImageAlignment": "String",
  "FooterImageAttachmentId": "String",
  "FooterImageHeight": "String",
  "FooterText": "String",
  "FooterTextAlignment": "String",
  "GeneratePageNumber": "String",
  "HeaderImageAlignment": "String",
  "HeaderImageAttachmentId": "String",
  "HeaderImageHeight": "String",
  "LeftOrRightMargin": "String",
  "PageOrientation": "String",
  "PageSize": "String",
  "TopOrBottomMargin": "String"
}

{​
   "accessibilityEnabled" : Boolean,
   "toc_config" : "String",​
   "page_number_config": "String"​
}​

{
  "attachment_id": "String",
  "message": "String",
  "request_id": "String",
  "status": "String"
}

The following example shows how to convert HTML to a PDF named "myPDF" and add the PDF as an attachment to a record in the Incident [incident] table. The PDF contains header and footer provided via attachment.

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;

//  (Option) get HTML from the description field of an incident record
var gr = new GlideRecord("incident");
var html;

if (gr.get("<tableSysId>")) {
 html = gr.description.toString();
}

var hfInfo = new Object();
hfInfo["HeaderImageAttachmentId"] = "<hdrImgAttSysId>";
hfInfo["HeaderImageAlignment"] = "left";
hfInfo["FooterImageAttachmentId"] = "<ftrImgAttSysId>";
hfInfo["FooterImageAlignment"] = "TOP_CENTER";
hfInfo["FooterText"] = "Sample Footer Message";
hfInfo["PageSize"] = "A4";
hfInfo["GeneratePageNumber"] = "false";
hfInfo["TopOrBottomMargin"] = "36";
hfInfo["LeftOrRightMargin"] = "24";

var result = v.convertToPDFWithHeaderFooter(html, "incident", "<targetTbl_sys_id>", "myPDF", hfInfo);
gs.info(JSON.stringify(result));

Output:

{"attachment_id":"<sys_id>","message":"Conversion is successful.","request_id":"<change_sys_id>","status":"success"}

PDFGenerationAPI – convertToPDFWithHeaderFooterAsync(String html, String targetTable, String targetTableSysId, String pdfName, Object headerFooterInfo, String fontFamilySysId, Object documentConfiguration)

Stages a job that converts an HTML string into a PDF with header and footer content asynchronously. Asynchronous processing enables you to work in the instance while the PDF conversion is in progress. This is especially helpful for larger PDF exports.

Use this method to generate PDFs with page settings:

• Header and footer information
• Margin sizes
• Orientation
• Enumeration
• Page size

{
  "FooterImageAlignment": "String",
  "FooterImageAttachmentId": "String",
  "FooterImageHeight": "String",
  "FooterText": "String",
  "FooterTextAlignment": "String",
  "GeneratePageNumber": "String",
  "HeaderImageAlignment": "String",
  "HeaderImageAttachmentId": "String",
  "HeaderImageHeight": "String",
  "LeftOrRightMargin": "String",
  "PageOrientation": "String",
  "PageSize": "String",
  "TopOrBottomMargin": "String"
}

{​
   "accessibilityEnabled" : Boolean,
   "toc_config" : "String",​
   "page_number_config": "String"​
}​

The following example shows how to queue a task that converts HTML to a PDF. The PDF contains header and footer provided via attachment. When the conversion is complete, the PDF named "myPDF" is attached to the target record in the Incident [incident] table.

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;

//  (Option) get HTML from the description field of an incident record
var gr = new GlideRecord("incident");
var html;

if (gr.get("<tableSysId>")) {
 html = gr.description.toString();
}

var hfInfo = new Object();
hfInfo["HeaderImageAttachmentId"] = "<hdrImgAttSysId>";
hfInfo["HeaderImageAlignment"] = "left";
hfInfo["FooterImageAttachmentId"] = "<ftrImgAttSysId>";
hfInfo["FooterImageAlignment"] = "TOP_CENTER";
hfInfo["FooterText"] = "Sample Footer Message";
hfInfo["PageSize"] = "A4";
hfInfo["GeneratePageNumber"] = "false";
hfInfo["TopOrBottomMargin"] = "36";
hfInfo["LeftOrRightMargin"] = "24";

var result = v.convertToPDFWithHeaderFooterAsync(html, "incident", "<targetTbl_sys_id>", "myPDF", hfInfo);
gs.info(JSON.stringify(result));

Output:

{"message":"HTML to PDF Conversion is in progress.","request_id":"<sys_id>"}

PDFGenerationAPI – fillDocumentFields(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName)

Fills fields in an editable PDF and attaches it to the provided record.

Use the following methods to determine if the PDF is fillable and get field information:

• isDocumentFillable()
• getDocumentFields()
• getDocumentFieldsType()

PDFGenerationAPI provides additional fill methods with different options:

• fillDocumentFieldsAndFlatten() – Fills fields in an editable PDF, flattens the data fields, and attaches it to the provided record.
• fillFieldsAndMergeSignature() – Fills fields in an editable PDF, adds signature image, flattens the data fields, and attaches it to the provided record.
• getFilledDocumentWithSignatureAsBase64() – Fills fields in an editable PDF, creates an image, and converts it to a Base64-encoded PDF.

{
  "attachment_id": "String",
  "message": "String",
  "status": "String"
}

The following example shows how to fill fields in an editable PDF.

var fieldMap = new Object();
fieldMap["Address"] = "Address value here";
fieldMap["State"] = "State value here";

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;
var result = v.fillDocumentFields(fieldMap, "<attachmentSysId>", "<tableName>", "<tableSysId>", "pdfName");
gs.info(JSON.stringify(result));

Output:

{"attachment_id":"<sys_id>","message":"Request completed successfully.","status":"success"}

PDFGenerationAPI – fillDocumentFieldsAndFlatten(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName, Object flatten)

Fills fields in an editable PDF, flattens the data fields, and attaches it to the provided record.

Use the following methods to determine if the PDF is fillable and get field information:

• isDocumentFillable()
• getDocumentFields()
• getDocumentFieldsType()

PDFGenerationAPI provides additional fill methods with different options:

• fillDocumentFields() – Fills fields in an editable PDF and attaches it to the provided record.
• fillFieldsAndMergeSignature() – Fills fields in an editable PDF, adds signature image, flattens the data fields, and attaches it to the provided record.
• getFilledDocumentWithSignatureAsBase64() – Fills fields in an editable PDF, creates an image, and converts it to a Base64-encoded PDF.

{
  "FlattenType": "String" 
}

{
  "attachment_id": "String",
  "message": "String",
  "status": "String"
}

The following example shows how to fill fields and flatten an editable PDF.

var fieldMap = new Object();
fieldMap["Last Name First Name Middle Initial"] = "Tuter Abel E.";
fieldMap["Date of Birth"] = "08101952";
fieldMap["US SSN"] = "111-22-9999";
fieldMap["Address"] = "PO Box 344";
fieldMap["City"] = "Jerome";
fieldMap["State"] = "AZ";
fieldMap["Zip"] = "86331";

var flatten = new Object();
flatten["FlattenType"] = "partially_flatten";

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;
var result = v.fillDocumentFieldsAndFlatten(fieldMap, "<attachmentSysId>", "<tableName>", "<tableSysId>", "pdfName", flatten);
gs.info(JSON.stringify(result));

Output:

"attachment_id":"<sys_id>","message":"Request completed successfully.","status":"success"

PDFGenerationAPI – fillFieldsAndMergeSignature(Object fieldsMap, String sysId, String tableName, String tableSysId, String pdfName, PdfMergeSignRequestor requestor, Object flatten)

Fills fields in an editable PDF, adds signature image, flattens the data fields, and attaches it to the provided record.

Use the following methods to determine if the PDF is fillable and get field information:

• isDocumentFillable()
• getDocumentFields()
• getDocumentFieldsType()

PDFGenerationAPI provides additional fill methods with different options:

• fillDocumentFields() – Fills fields in an editable PDF and attaches it to the provided record.
• fillDocumentFieldsAndFlatten() – Fills fields in an editable PDF, flattens the data fields, and attaches it to the provided record.
• getFilledDocumentWithSignatureAsBase64() – Fills fields in an editable PDF, creates an image, and converts it to a Base64-encoded PDF.

{
  "FlattenType": "String" 
}

{
  "attachment_id": "String",
  "message": "String",
  "status": "String"
}

The following example shows how to fill fields with signature with default settings to completely flatten the fields.

var fieldMap = new Object();
fieldMap["Address_Salutation"] = "Address value here";

var paramMap = new Object();
paramMap["FlattenType"] = "partially_flatten";

var requestor = new sn_pdfgeneratorutils.PdfMergeSignRequestor;
requestor.createRequest("<attachmentSysId>", "incident", "<tableSysId>", "filledPdf");
requestor.addSignatureMapping(6, 40, 50, 188, 44, "<signatureSysId>");

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;
var result = v.fillFieldsAndMergeSignature(fieldMap, "<attachmentSysId>", "incident", "<tableSysId>", requestor, "filledPdf", paramMap);
gs.info(JSON.stringify(result));

Output:

{"attachment_id":"5440d993dbed3010d66be1191396194e","message":"Request completed successfully.","status":"success"}

PDFGenerationAPI – getDocumentFields(String sysId)

Gets a list of editable fields in a PDF document. Enables listing editable PDF fields without manually opening the file to check.

The following example shows how to retrieve field types in a PDF attachment. Results include manual returns for readability and are truncated for brevity.

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;
var result = v.getDocumentFieldsType("<attachmentSysId>");
gs.info(JSON.stringify(result));

Output:

{"fields_type":{"1ADDLINE2.25":{"pageNumber":2,"type":"text"},"1ADDLINE2.24":{"pageNumber":2,"type":"text"},
"1ADDLINE2.23":{"pageNumber":2,"type":"text"},"1ADDLINE2.22":{"pageNumber":2,"type":"text"},
"1ADDLINE2.11":{"pageNumber":2,"type":"text"},
"Check Box1":{"fieldsDetails":[{"fieldName":"Yes"}],"pageNumber":2,"type":"check_box"},
"4consentDate.6":{"pageNumber":4,"type":"text"},"4consentDate.7":{"pageNumber":4,"type":"text"},
"3SSN.9":{"pageNumber":3,"type":"text"},"3SSN.8":{"pageNumber":3,"type":"text"},"3SSN.7":{"pageNumber":3,"type":"text"},
"pageNumber":2,"type":"check_box"},"Check Box8":{"fieldsDetails":[{"fieldName":"Off"},{"fieldName":"yes"}],
"4planAdminDate.8":{"pageNumber":4,"type":"text"},"4planAdminDate.7":{"pageNumber":4,"type":"text"},
"1FirstName_ID.7":{"pageNumber":2,"type":"text"},
"Check Box9":{"fieldsDetails":[{"fieldName":"Yes"}],"pageNumber":3,"type":"check_box"},
"1LN.1":{"pageNumber":2,"type":"text"},"1LN.2":{"pageNumber":2,"type":"text"},
"Check Box11":{"fieldsDetails":[{"fieldName":"Yes"}],"pageNumber":3,"type":"check_box"},
"1LN.9":{"pageNumber":2,"type":"text"},
"Check Box17":{"fieldsDetails":[{"fieldName":"Yes"}],"pageNumber":3,"type":"check_box"},
"Check Box16":{"fieldsDetails":[{"fieldName":"Yes"}],"pageNumber":3,"type":"check_box"},
"1LN.7":{"pageNumber":2,"type":"text"},"Check Box19":{"fieldsDetails":[{"fieldName":"Yes"}],
"1LN.8":{"pageNumber":2,"type":"text"},"Check Box18":{"fieldsDetails":[{"fieldName":"Yes"}],
"print":{"pageNumber":2,"type":"push_button"},"4planAdministrator.1":{"pageNumber":4,"type":"text"},
"1TaxID.9":{"pageNumber":2,"type":"text"},"4SSN.1":{"pageNumber":3,"type":"text"},"4SSN.2":{"pageNumber":3,"type":"text"},
"Signature.1":{"pageNumber":4,"type":"text"},"1ZIP.2":{"pageNumber":2,"type":"text"},"1ZIP.3":{"pageNumber":2,"type":"text"},
"message":"Request completed successfully.","status":"success"}

PDFGenerationAPI – getFilledDocumentWithSignatureAsBase64(Object fieldsMap, String sysId, PdfMergeSignRequestor requestor, Object flatten)

Fills fields in an editable PDF, creates an image, and converts it to a Base64-encoded PDF.

Base64 encoding enables you to output a PDF as a string within a text document, such as HTML or JSON, without damaging the binary character syntax.

Use the following methods to determine if the PDF is fillable and get field information:

• isDocumentFillable()
• getDocumentFields()
• getDocumentFieldsType()

PDFGenerationAPI provides additional fill methods with different options:

• fillDocumentFields() – Fills fields in an editable PDF and attaches it to the provided record.
• fillDocumentFieldsAndFlatten() – Fills fields in an editable PDF, flattens the data fields, and attaches it to the provided record.
• fillFieldsAndMergeSignature() – Fills fields in an editable PDF, adds signature image, flattens the data fields, and attaches it to the provided record.

{
  "attachment_id": "String",
  "message": "String",
  "status": "String"
}

</td></tr><tr><td>

&lt;Object&gt;.message

</td><td>

Message confirming success or error. Possible values:

-   Exception while reading Source document contents. PDF header not found. – Input attachment provided is not a valid PDF. Provide the correct attachment sys\_id.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] did not pass security scan – The PDF did not pass the antivirus scan.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] is pending security scan – The PDF requires an antivirus scan.
-   Request completed successfully – Operation is successful.
-   Undefined – Sys\_id provided does not exist or is not a PDF attachment.

 Data type: String

</td></tr><tr><td>

&lt;Object&gt;.status

</td><td><p>Status indicating whether the operation is successful.Possible values:</p>
<ul>
<li>success - Operation was successful.</li>
<li>failure – Operation was not successful. The <strong>message</strong> provides details.</li>
</ul>
<p>Data type: String</p></td></tr></tbody>
</table>

The following example shows how to retrieve fields in a PDF attachment.

Output:

## PDFGenerationAPI – getDocumentFieldsType\(String sysId\)

Gets the field type of set of editable fields from a PDF document.

|Name|Type|Description|
|----|----|-----------|
|sysId|String|Sys\_id of a PDF in the Attachments \[sys\_attachment\] table.|

<table id="table_jxx_whk_34b" class="returns"><thead><tr><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

Object

</td><td>

Object containing each PDF field type if successful, error message otherwise.

</td></tr><tr><td>

&lt;Object&gt;.fields\_type

</td><td>

Object listing each field in the specified PDF if successful, error message otherwise.Data type: Object

 ```
"fields_type": {
  "<field type>": {Object},
}

</td></tr><tr><td>

&lt;Object&gt;.fields\_type.​&lt;field&gt;.fieldsDetails

</td><td>

List of objects containing field name and corresponding value of each option for choice field types.Applicable types:

-   Check box
-   Choice box
-   Combo box
-   Multi select choice box

 Data type: Array

 ```
"fieldsDetails": [ 
  "fieldName": "String",
  "value": "String"
]

{
  "FlattenType": "String" 
}

The following example shows how to load two fields in a PDF attachment, flatten the fields, and convert the PDF to Base64 format.

var mymap = new Object();
mymap["City"] = "City value here";
mymap["State"] = "XX";

// create a requestor
var requestor = new sn_pdfgeneratorutils.PdfMergeSignRequestor;
requestor.createRequest("<sys_id>", "tableName", "<tableSysId>", "pdfName");
requestor.addSignatureMapping(6, 40, 50, 188, 44, "<signImgSysId>");
var processedRequestObj = requestor.processRequest();

var v = new sn_pdfgeneratorutils.PDFGenerationAPI;

var result = v.getFilledDocumentWithSignatureAsBase64(mymap, "<attachmentSysId>", processedRequestObj);
gs.info (JSON.stringify(result));

PDFGenerationAPI – getPdfPageSizes(String sysId)

Gets the page size of a PDF document.

{
  "pages_size": {Object},
  "message": "String",
  "status": "String"
}

</td></tr><tr id="row_pdfgen_ret_msg"><td>

&lt;Object&gt;.message

</td><td>

Message confirming success or error. Possible values:

-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] did not pass security scan – The PDF did not pass the antivirus scan.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] is pending security scan – The PDF requires an antivirus scan.
-   Request completed successfully – Operation is successful.
-   Undefined – Sys\_id provided does not exist or is not a PDF attachment.

 Data type: String

</td></tr><tr><td>

&lt;Object&gt;.status

</td><td><p>Status indicating whether the operation is successful.Possible values:</p>
<ul>
<li>success - Operation was successful.</li>
<li>failure – Operation was not successful. The <strong>message</strong> provides details.</li>
</ul>
<p>Data type: String</p></td></tr></tbody>
</table>

The following example shows how to display the width and height of each page in a PDF attachment.

Output:

## PDFGenerationAPI – isDocumentFillable\(String sysId\)

Checks if the PDF document contains editable fields.

|Name|Type|Description|
|----|----|-----------|
|sysId|String|Sys\_id of a PDF in the Attachments \[sys\_attachment\] table.|

<table id="table_erx_h3k_34b" class="returns"><thead><tr><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

Object

</td><td>

Object containing the size of each page if successful, error message otherwise.

</td></tr><tr><td>

&lt;Object&gt;.​document\_editable

</td><td>

If the operation is successful, flag indicating whether the document is editable.Valid values:

-   true: PDF document has editable fields.
-   false: PDF document does not have editable fields.

 Data type: Boolean value provided as a string

</td></tr><tr><td>

&lt;Object&gt;.message

</td><td>

Message confirming success or error. Possible values:

-   Exception while reading Source document contents. PDF header not found. – Input attachment provided is not a valid PDF. Provide the correct attachment sys\_id.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] did not pass security scan – The PDF did not pass the antivirus scan.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] is pending security scan – The PDF requires an antivirus scan.
-   Request completed successfully – Operation is successful.
-   Undefined – Sys\_id provided does not exist or is not a PDF attachment.

 Data type: String

</td></tr><tr><td>

&lt;Object&gt;.status

</td><td><p>Status indicating whether the operation is successful.Possible values:</p>
<ul>
<li>success - Operation was successful.</li>
<li>failure – Operation was not successful. The <strong>message</strong> provides details.</li>
</ul>
<p>Data type: String</p></td></tr></tbody>
</table>

The following example shows how to determine if PDF document fields are editable.

Output:

## PDFGenerationAPI – redact\(Object inputJson\)

Applies redaction to a PDF document based on the given rectangle coordinates, search keywords, or both. A redacted copy of the original PDF is generated in the Attachments \[sys\_attachment\] table.

**Note:**

-   Redaction results might include an unexpected white redacted text block that overwrites text not intended to be redacted. If this event occurs, you can manually select the content for redaction using the **highlightedSections** property or the PDF Generation Utilities plugin. For more information, see [Redact data from documents](../../servicenow-platform/document-management-services/redact-sensitive-data.md).
-   This method doesn’t support redaction in PDFs containing JBIG2 images.

<table id="table_drx_h3k_34b" class="parameters"><thead><tr><th>

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

inputJson

</td><td>

Object

</td><td>

Identifies the PDF and its content to be redacted.

</td></tr><tr><td>

inputJson.sysId

</td><td>

String

</td><td id="ent_api_pdfgen_parm_attSysIDesc">

Sys\_id of a PDF in the Attachments \[sys\_attachment\] table.

</td></tr><tr><td>

inputJson. highlightedSections

</td><td>

Array of Objects

</td><td><p>List of rectangles coordinates provided as an object. Each coordinate represents the location of the content to be redacted on each page.Optional if including the <strong>searchedKeywords</strong> property.</p>
<div class="highlight"><pre><span></span><code>[
   {
     &quot;pageNumber&quot;: Number,
     &quot;x&quot;: Number,
     &quot;y&quot;: Number,
     &quot;width&quot;: Number,
     &quot;height&quot;: Number
   }
]
</code></pre></div></td></tr><tr><td>

inputJson. highlightedSections. pageNumber

</td><td>

Number

</td><td>

PDF page number containing the content to select for redaction.

</td></tr><tr><td>

inputJson. highlightedSections. x

</td><td>

Number

</td><td>

The X-axis \(horizontal position\) of the redaction rectangle on the PDF in points. The value at the bottom-left corner of the PDF page is 0. For example, a value of `306` places the rectangle approximately in the horizontal center of a letter-size PDF page.

</td></tr><tr><td>

inputJson. highlightedSections. y

</td><td>

Number

</td><td>

The Y-axis \(vertical position\) of the redaction rectangle on the PDF in points. The value at the bottom-left corner of the PDF page is 0. For example, a value of `396` places the rectangle approximately in the vertical center of a letter-size PDF page.

</td></tr><tr><td>

inputJson. highlightedSections. width

</td><td>

Number

</td><td>

Width of the redaction rectangle is in points. This value increases the size of the rectangle horizontally from the lower left point at which the x an y axes intersect.

</td></tr><tr><td>

inputJson. highlightedSections. height

</td><td>

Number

</td><td>

Height of the redaction rectangle in points. This value increases the size of the rectangle vertically from the lower left point at which the x an y axes intersect.

</td></tr><tr><td>

inputJson. searchedKeywords

</td><td>

Array

</td><td><p>List of one or more strings used to find text for redaction. The redaction rectangle size matches the height and width of the text that is blocked out as a result.Optional if including the <strong>highlightedSections</strong> property.</p>
<p><strong>Note:</strong> In some cases, text strings containing special characters or punctuation such as <code>"items:"</code> and <code>"PDF."</code> aren't redacted. You can alternatively remove the character from the string or highlight the area to remove the text.</p></td></tr></tbody>
</table>

<table id="table_phl_lzj_34b" class="returns"><thead><tr><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

Object

</td><td id="desc-fill-only">

Object containing sys\_id of the updated PDF attachment if successful, error message otherwise.

</td></tr><tr><td>

&lt;Object&gt;.​attachment\_id

</td><td id="desc_pdfgen_ret_attID_Fill">

If the operation is successful, sys\_id of the filled PDF. The file is listed in the Attachments \[sys\_attachment\] table.Data type: String

</td></tr><tr><td>

&lt;Object&gt;.message

</td><td>

Message confirming success or error. Possible values:

-   Can't parse this format – Unable to process an image embedded in the PDF. The PDF contains one or more images in an unsupported format, such as a JBIG2 image.
-   Exception while reading Source document contents. PDF header not found. – Input attachment provided is not a valid PDF. Provide the correct attachment sys\_id.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] did not pass security scan – The PDF did not pass the antivirus scan.
-   Request cannot proceed as the attachment with sys\_id \[\{0\}\] is pending security scan – The PDF requires an antivirus scan.
-   Request completed successfully – Operation is successful.
-   Undefined – Sys\_id provided does not exist or is not a PDF attachment.

Data type: String

</td></tr><tr><td>

&lt;Object&gt;.status

</td><td><p>Status indicating whether the operation is successful.Possible values:</p>
<ul>
<li>success - Operation was successful.</li>
<li>failure – Operation was not successful. The <strong>message</strong> provides details.</li>
</ul>
<p>Data type: String</p></td></tr></tbody>
</table>

The following example shows how to redact by rectangle and key word. On the redacted PDF, the areas selected on page 2 are blocked out. The string '23' is redacted on any page that it's found on.

Output: