Creates an Image object representing an image and its layout insert in a PDF. Enables defining attributes such as scale, alignment, and border color.

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.

This API is a component used with the Document API to generate a PDF.

You can add an image to a PDF using one of the following methods:

Image - Image(String attachmentSysId)

Instantiates a new Image object. Used to verify if an image attachment exists and is available for modification.

Table 1. Parameters
Name Type Description
attachmentSysId String Sys_id of an image in the Attachments [sys_attachment] table.

Example

The following example shows how to create a Image object.

var image = new sn_pdfgeneratorutils.Image("<sys_id>");

Image – scaleAbsolute(Number width, Number height)

Scales an image to absolute width and height sizes. This setting does not preserve the width-height ratio of the image and might result in undesired stretching if settings are not precise.

To scale to an absolute size that preserves width-height ratio of an image, use the scaleToFit() method.

Table 2. Parameters
Name Type Description
width Number Image width in points.
height Number Image height in points.
Table 3. Returns
Type Description
None

Example

The following example shows how to add an image to a PDF with absolute width and height settings.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);

var scaleAbsPic = new sn_pdfgeneratorutils.Image("<img_sys_id>");
scaleAbsPic.scaleAbsolute(25,50);

document.addImage(scaleAbsPic);

document.saveAsAttachment("incident", "<record_sys_id>", "docWithImg.pdf");

Image – scaleToFit(Number width, Number height)

Scales an image to an absolute size while preserving the width-height ratio.

Resulting output varies by image aspect ratio. If the width and height parameter values do not match the image aspect ratio, one value renders smaller in output than the value given.

Table 4. Parameters
Name Type Description
width Number Maximum image width in points.
height Number Maximum image height in points.
Table 5. Returns
Type Description
None

Example

The following example shows how to insert an image scaled to fit using the Cell – addImage() method.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);
 
// add a table
var table = new sn_pdfgeneratorutils.Table([1,3],false);

// text for the left column
var text = "sample image";

// add a table cell for the image in the right column
var imgCell = new sn_pdfgeneratorutils.Cell(1, 1);

// add an image and set it scale-to-fit
var scaleToFitPic = new sn_pdfgeneratorutils.Image("<img_sys_id>");
scaleToFitPic.scaleToFit(90,175);

// add the image to the cell
imgCell.addImage(scaleToFitPic);
 
table.addTextCell(text);
table.addCell(imgCell);

// Here's a paragraph
var para = new sn_pdfgeneratorutils.Paragraph("The following table image uses scale to fit.");

document.addParagraph(para);
document.addTable(table);

document.saveAsAttachment("incident", "<record_sys_id>", "imgScaleToFit.pdf");

Image – setAutoScale(Boolean value)

Enables scaling width and height to a page or cell while retaining dimensions.

Table 6. Parameters
Name Type Description
value Boolean

Flag that indicates whether to automatically scale an image.

Valid values:
  • true: Automatically scales the image
  • false: Image does not scale

Default: false
Table 7. Returns
Type Description
None

Example

The following example shows how to add an image to a PDF with automatic scaling. The image is added using the Table – addImageCell() method.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);

// Add a table
var table = new sn_pdfgeneratorutils.Table([1,2],false);

// Text in left column
var text = "sample image";

// Image in right column
var autoScaledPic = new sn_pdfgeneratorutils.Image("<image_sys_id>");
autoScaledPic.setAutoScale(true);

table.addTextCell(text);
table.addImageCell(autoScaledPic);

document.addTable(table);
document.saveAsAttachment("incident", "<record_sys_id>", "imgAutoScale.pdf");

Image – setColoredBorder(Color color, Number width)

Sets a border on a PDF in the specified color.

Table 8. Parameters
Name Type Description
color Color Image border color.
width Number Width of the border in points.
Table 9. Returns
Type Description
None

Example

The following example shows how to set a five-point red-colored border on an image.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);

var borderColor = new sn_pdfgeneratorutils.Color([1.0,0.0,0.0]);
 
// declare image using sys attachment
var image = new sn_pdfgeneratorutils.Image("<imgAttachment_sys_id>");

image.setColoredBorder(borderColor, 5);

document.addImage(image);
document.saveAsAttachment("incident", "<record_sys_id>", "docWithBorderedImage.pdf");

Image – setHorizontalAlignment(String alignment)

Sets the horizontal alignment of the image.

Table 10. Parameters
Name Type Description
alignment String Positions image alignment on a page or block element.
Valid values:
  • Center
  • Left
  • Right

Default: Left
Table 11. Returns
Type Description
None

Example

The following example shows how to add a centered image on a PDF page.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);
 
// declare image using sys attachment
var image = new sn_pdfgeneratorutils.Image("<imgAttachment_sys_id>");

String alignment = "Center";
image.setHorizontalAlignment(alignment);

document.addImage(image);
// save pdf as attachment to target record in the Incident table
document.saveAsAttachment("incident", "<sys_id>", "docWithImageCentered.pdf");

Image – setNoBorder()

Sets an image to have no border.

Table 12. Parameters
Name Type Description
None
Table 13. Returns
Type Description
None

Example

The following example shows how to add an image to a document without a border.

var pageSize = new sn_pdfgeneratorutils.PdfPage("LETTER");
var document = new sn_pdfgeneratorutils.Document.createDocument(pageSize);
 
// declare image using sys attachment
var image = new sn_pdfgeneratorutils.Image("<imgAttachment_sys_id>");

image.setNoBorder();

document.addImage(image);
document.saveAsAttachment("incident", "<sys_id>", "docWithImgNoBorder.pdf");