Compose PDF stories and automate web page workflows with PSWriteOffice

When somebody asks me to “automate a PDF,” I first ask what they imply. Are we making a report from information, or altering a PDF that already exists? Each finish with a .pdf file, however the scripts ought to look very completely different.

PSWriteOffice helps each jobs by the OfficeIMO PDF engine. For a brand new report, I exploit the composition DSL for headings, paragraphs, wealthy textual content, tables, lists, pictures, types, headers, footers, bookmarks, and attachments. For an current file, I attain for centered instructions that examine, extract, merge, cut up, reorder, stamp, overlay, redact, sanitize, or optimize it.

Preserving these paths separate makes the script simpler to grasp. A paragraph ought to circulate onto the subsequent web page with out coordinates. A evaluate stamp ought to land on the actual coordinates I give it.

Earlier than you begin

Use PowerShell 7 and set up the present public modules used for this text:

Set up-Module PSWriteOffice -Scope CurrentUser -Power
Import-Module PSWriteOffice

Run the examples from a folder the place you possibly can write the generated information. Substitute the pattern information and repair particulars with your personal after the primary profitable run.

Compose a report in doc circulate

If my script owns the report, I begin with the DSL and let the web page structure engine place the content material. The report can develop with out turning each web page break into one other calculation.

$findings = @(
    [pscustomobject]@{ Severity = 'Excessive'; Discovering = 'Dormant administrator account'; Proprietor="Id" }
    [pscustomobject]@{ Severity = 'Medium'; Discovering = 'Lacking proof hyperlink'; Proprietor="Operations" }
)

PdfNew -Path '.Entry-Overview.pdf' {
    PdfTheme Report
    PdfHeading 'Entry evaluate'
    PdfParagraph 'Ready for the weekly safety evaluate.'
    PdfTable -InputObject $findings
    PdfText 'Overview standing: Draft' -Italic -Colour '#B45309'
}

I exploit the quick PDF aliases all through this block. The longer equivalents are New-OfficePdf, Set-OfficePdfTheme, Add-OfficePdfHeading, Add-OfficePdfParagraph, Add-OfficePdfTable, and Add-OfficePdfText. Each types name the identical engine; mixing them in a single report simply makes the script more durable to scan.

The constructor doesn’t write an object to the pipeline after saving, so Out-Null is pointless. Add -PassThru solely when the subsequent command wants the saved file.

Format one line with out constructing paragraphs by hand

For combined formatting on one line, I exploit a textual content run. The columnar type is very readable when the values come from an object:

$discovering = [pscustomobject]@{
    Proprietor="Id"
    Due="2026-08-28"
    Severity = 'Excessive'
}

PdfNew -Path '.Discovering-Abstract.pdf' {
    PdfHeading 'Discovering abstract'
    PdfText -Run @{
        Textual content="Proprietor: ", $discovering.Proprietor, '    Due: ', $discovering.Due, '    Severity: ', $discovering.Severity
        Daring  = $true, $false, $true, $false, $true, $false
        Colour = $null, $null, $null, $null, $null, 'Crimson'
    }
}

A single type worth applies to each section. In case you move a method array, it should comprise both one worth or the identical variety of entries as Textual content. A lacking entry can not silently transfer daring or coloration onto the fallacious worth.

Place textual content at actual coordinates

PdfText and PdfParagraph belong to regular doc circulate, so they don’t have X and Y parameters. After I want a web page label, signature, or one other merchandise at a set level, I add canvas content material to an current PDF:

Add-OfficePdfCanvas -Path '.Entry-Overview.pdf' -OutputPath '.Entry-Overview-Positioned.pdf' -Content material   REVIEW COPY' -Italic
    ) -X 36 -Y 24 -FontSize 10

Canvas coordinates use PDF factors measured from the visible top-left of the web page. The canvas matches web page labels, registration marks, mounted headers, signatures, and generated overlays. For one textual content or picture mark, Add-OfficePdfStamp is shorter. To position a whole imported web page over one other web page, use Add-OfficePdfPageOverlay.

The canvas command accepts regular strings and wealthy textual content runs immediately. You don’t want to assemble a runtime-typed .NET array in PowerShell.

Add types and alternate their information

Kind fields might be a part of the unique composition:

PdfNew -Path '.Change-Request.pdf' {
    PdfHeading 'Change request'
    PdfText 'Proprietor'
    PdfFormField -Title Proprietor -Sort Textual content -Worth 'Platform' -Width 280
    PdfText 'Determination'
    PdfFormField -Title Determination -Sort Selection -Choices Approve,Reject,Defer -Worth Defer -Width 220
}

When one other system must alternate or archive the sphere values individually, I exploit XFDF:

Export-OfficePdfXfdf -Path '.Change-Request.pdf' -OutputPath '.Change-Request.xfdf'
Import-OfficePdfXfdf -Path '.Change-Request.pdf' -XfdfPath '.Change-Request.xfdf' -OutputPath '.Change-Request-Up to date.pdf'

PSWriteOffice can examine fields, work with annotations, and flatten the shape. I flatten solely the supply copy, after no one must edit the fields once more.

Connect proof to the supply copy

Typically the proof belongs with the report however shouldn’t change into one other seen web page. In that case I connect it:

PdfNew -Path '.Audit-Report.pdf' {
    PdfTheme Report
    PdfHeading 'Audit report'
    PdfParagraph 'The supporting proof is embedded on this PDF.'
    PdfAttachment `
        -Path '.Proof-Abstract.pdf' `
        -Title 'evidence-summary.pdf' `
        -MimeType 'utility/pdf' `
        -Relationship Information `
        -Description 'Supporting evaluate proof'
}

This works properly for proof packs, digital invoices, supply information, or signed supporting paperwork. The attachment stays a separate file contained in the PDF.

Reorder, merge, and cut up current pages

Web page operations don’t require rebuilding the doc. This instance strikes the approval web page to the entrance and writes a brand new file:

Transfer-OfficePdfPage `
    -Path '.Overview-Pack.pdf' `
    -PageRange '3' `
    -BeforePage 1 `
    -OutputPath '.Overview-Pack-Reordered.pdf'

Be part of-OfficePdf assembles a pack, whereas Cut up-OfficePdf separates it by web page vary or variety of pages per doc. I hold the supply file till the end result has been checked. Efficiently writing a PDF doesn’t show that each superior function within the authentic survived the transformation.

Export an Workplace doc to PDF intentionally

For Phrase, Excel, PowerPoint, Markdown, and RTF, I create the supply artifact first and request PDF as a separate supply step. That retains a failed conversion from being hidden inside a New-* or Save-* command:

New-OfficeWord -Path '.Service-Overview.docx' {
    WordParagraph -Textual content 'Service evaluate' -Fashion Heading1
    WordParagraph 'This editable report is the supply artifact.'
    WordTable -InputObject $findings -Format AutoFitToWindow
}

Export-OfficeDocumentPdf `
    -InputPath '.Service-Overview.docx' `
    -Path '.Service-Overview.pdf'

This command intentionally makes use of InputPath for the supply as a result of Path names the PDF being produced. Elsewhere, instructions use Path for the first file, OutputPath for a reworked copy, and DestinationPath for a replica vacation spot.

Extract and examine earlier than altering

Earlier than I modify an unfamiliar PDF, I examine it. The read-only instructions additionally make the identical information helpful in search, compliance, and ingestion workflows:

$pages = Get-OfficePdfText -Path '.Coverage.pdf' -ByPage
$pages | Choose-Object PageNumber, Textual content

There are instructions for doc info, fonts, pictures, attachments, type fields, annotations, signatures, compliance, interactions, optimization alternatives, and rewrite security. I exploit that proof earlier than redaction, sanitization, optimization, or harmful web page modifications.

For delicate content material, construct a redaction plan from detected textual content and write a brand new supply copy. Drawing a black rectangle isn’t redaction; the underlying textual content should be current. ConvertTo-OfficePdfRedacted removes it by the PDF engine.

Ship the end result with Mailozaurr

After the PDF has been reviewed, Mailozaurr can ship the supply copy:

$mailCredential = Get-Secret -Title 'Reporting-Smtp-Credential'

Ship-EmailMessage `
    -From 'stories@instance.com' `
    -To 'reviewers@instance.com' `
    -Topic 'Entry evaluate' `
    -Textual content 'The editable supply and PDF supply copy are hooked up.' `
    -Attachment '.Service-Overview.docx', '.Service-Overview.pdf' `
    -Server 'smtp.instance.com' `
    -Credential $mailCredential `
    -UseSsl

PSWriteOffice creates the information; Mailozaurr handles the message, authentication, transport, and mailbox operations. The report code stays the identical whether or not supply makes use of SMTP, Microsoft Graph, Gmail, SendGrid, Mailgun, or Amazon SES.

Get-Secret comes from Microsoft.PowerShell.SecretManagement. Retailer the credential within the secret supplier trusted by the scheduled job or CI runner, quite than within the report script.

Which command ought to I exploit?

The PSWriteOffice PDF recipes comprise full scripts for invoices, audit stories, types, attachments, extraction, web page reordering, merging, splitting, positioned content material, redaction, sanitization, and preflight. They use easy native file names so you possibly can run one first and substitute the pattern information afterward.

My rule is straightforward: compose new stories in doc circulate, use coordinates just for content material that basically has a set place, and use a centered command when altering an current PDF. That retains a big PDF workflow readable even after types, proof, supply, and compliance checks are added.