Version: 1.28 (Current)

Overlay PDF

Audience: Low-code Engineers

Skill Prerequisites: Tokens

Draws the pages of one PDF (the overlay) on top of the pages of another PDF, and saves the result as a new PDF. Use it to stamp a letterhead, watermark, logo or footer onto an existing document. The new file's URL, path and file ID can be saved as tokens for the actions that follow.

The original files aren't changed.

note

This action requires the PDF feature to be licensed.

`Typical Use Cases`

Add a company letterhead to every page of a generated document
Stamp a DRAFT or CONFIDENTIAL watermark on a PDF
Place a different overlay on each page, for example a first-page header followed by a continuation-page header

`Don't use it to`

Add the pages of one PDF after another. Use Merge PDF instead.
Add HTML content to a PDF. Generate the content with Generate PDF first, then overlay the result.

`Related Actions`

Action Name	Description
Generate PDF	Creates a PDF from an HTML template, which can be the document or the overlay.
Merge PDF	Combines the pages of two PDFs into one file.
Extract PDF	Copies selected pages of a PDF into a new file.
Send Email	Sends the new PDF as an attachment.

`Input Parameter Reference`

Parameter	Description	Supports Tokens	Default	Required
File Path	The PDF to draw on. Use one of the supported file identifiers. If the value doesn't end with `.pdf`, `.pdf` is added.	Yes	`empty string`	Yes
Overlay PDF File Path	The PDF to draw on top of the pages of `File Path`. It can have one or more pages. Use one of the supported file identifiers. If the value doesn't end with `.pdf`, `.pdf` is added.	Yes	`empty string`	Yes
Overlay Startig Page	The index of the first page that gets the overlay. The first page is `0`. Pages before it are left unchanged.	Yes	`0`	No
Overlay Recursively	Decides what happens when the document has more pages than the overlay. When checked, the overlay starts again from its first page. When unchecked, the remaining pages are left unchanged.	Yes	`Checked`	No
Folder	The portal folder where the new PDF is saved. Select a folder from the list, or switch to expression mode and enter a folder path relative to the portal root. The folder must already exist.	Yes	`none selected`	Yes
File Name	The name of the new file, without the extension. `.pdf` is always added. If empty, a random GUID is used as the name.	Yes	`empty string`	No
Overlay Starting X Position	The horizontal position, in points, of the overlay's top-left corner, measured from the left edge of the page.	Yes	`0`	No
Overlay Starting Y Position	The vertical position, in points, of the overlay's top-left corner, measured from the top edge of the page.	Yes	`0`	No

`Supported file identifiers`

The files must be in the portal's file system.

Format	Example
Path relative to the portal root	`Documents/Letterhead.pdf`
Path that includes the portal folder	`/Portals/0/Documents/Letterhead.pdf`
Absolute URL of a file on the site	`https://example.com/Portals/0/Documents/Letterhead.pdf`
Physical path inside the portal folder	`C:\inetpub\site\Portals\0\Documents\Letterhead.pdf`

File IDs don't work here, because .pdf is added to any value that doesn't end with it. Use a path or URL token instead, for example the Relative URL output of another PDF action.

`Output Parameters Reference`

Each output parameter is the name of a token to create. Leave it empty if you don't need that value.

Parameter	Description
Absolute URL	Token that stores the absolute URL of the new file, for example `https://example.com/Portals/0/Letters/Letter-1024.pdf`.
Relative URL	Token that stores the URL relative to the site root, for example `/Portals/0/Letters/Letter-1024.pdf`.
Physical Path TokenName	Token that stores the physical path of the new file on the server.
Link Click TokenName	Token that stores a LinkClick URL that downloads the new file.
DNN FileId TokenName	Token that stores the file ID of the new file.

`How pages are matched`

Starting at Overlay Startig Page, each page of the document gets the next page of the overlay:

Document page (index)	Overlay page, with `Overlay Recursively` checked	Overlay page, with it unchecked
0	1	1
1	2	2
2	1	none
3	2	none

This table assumes a 2-page overlay and Overlay Startig Page = 0. With a 1-page overlay and Overlay Recursively checked, every page gets the same overlay.

The overlay page is drawn on top of the existing content at its own size. It isn't scaled to fit the page. Areas of the overlay that are transparent let the document show through, so a watermark or letterhead PDF should have a transparent background.

`Considerations`

Existing files are overwritten. If a file with the same name already exists in the folder, it's replaced.
The action fails with Pdf file not found. or Overlay file not found. if a file can't be found.
If the document has no pages, or Overlay Startig Page is past the last page, no overlay is drawn. If the document has no pages, no file is created.
Password-protected PDFs aren't supported. There's no password parameter, so a PDF that needs a password to open can't be used.
The overlay is done with the PDFsharp library. Temporary files are written to the portal's Temp folder and deleted when the action finishes.

`Examples`

tip

To understand how to use the below examples, please see Running Examples.

`1. Add a letterhead to a generated letter`

This action draws Documents/Letterhead.pdf on every page of the letter whose relative URL is in the LetterUrl token. The result is saved as Letters/Letter-<OrderId>.pdf, and its URL is saved in the FinalLetterUrl token.

{
    "Title": "Overlay PDF",
    "ActionType": "OverlayPdf",
    "Description": "Add the company letterhead",
    "Parameters": {
        "FilePath": "[LetterUrl]",
        "OverlayFilePath": "Documents/Letterhead.pdf",
        "OverlayStartigPage": "0",
        "OverlayRecursively": true,
        "Folder": {
            "Expression": "",
            "Value": "/Letters",
            "IsExpression": false,
            "Parameters": {}
        },
        "FileName": "Letter-[OrderId]",
        "OverlayStartingXPosition": "0",
        "OverlayStartingYPosition": "0",
        "AbsoluteUrlTokenName": "FinalLetterUrl",
        "RelativeUrlTokenName": "",
        "PhysicalPathTokenName": "",
        "LinkClickTokenName": "",
        "FileIdTokenName": ""
    }
}

`2. Watermark only the pages after the cover`

This action stamps a 1-page Documents/Draft.pdf watermark on every page except the first. Overlay Startig Page is 1, so the cover page (index 0) is left unchanged.

{
    "Title": "Overlay PDF",
    "ActionType": "OverlayPdf",
    "Description": "Watermark all pages except the cover",
    "Condition": "[Status] == \"Draft\"",
    "Parameters": {
        "FilePath": "[ReportUrl]",
        "OverlayFilePath": "Documents/Draft.pdf",
        "OverlayStartigPage": "1",
        "OverlayRecursively": true,
        "Folder": {
            "Expression": "",
            "Value": "/Reports",
            "IsExpression": false,
            "Parameters": {}
        },
        "FileName": "Report-[ReportId]-Draft",
        "OverlayStartingXPosition": "0",
        "OverlayStartingYPosition": "0",
        "AbsoluteUrlTokenName": "DraftReportUrl",
        "RelativeUrlTokenName": "",
        "PhysicalPathTokenName": "",
        "LinkClickTokenName": "",
        "FileIdTokenName": ""
    }
}

The action only runs when the Status token is Draft.

Revised 09/26/2026

Typical Use Cases​

Don't use it to​

Related Actions​

Input Parameter Reference​

Supported file identifiers​

Output Parameters Reference​

How pages are matched​

Considerations​

Examples​

1. Add a letterhead to a generated letter​

2. Watermark only the pages after the cover​