Data & Services - PDF Service

Configure PDF generation and document processing services

Overview

The PDF Service page registers the PDF service managers (PDFg, the PDF Generator) that cfhtmltopdf uses for HTML-to-PDF conversion. Other PDF operations, such as merging documents, adding watermarks, and password protection, are done in code with tags like cfpdf.

Service Configuration

Configure how ColdFusion generates PDF documents and manages PDFg services.

PDF Service Managers

PurposeRegister the PDF service managers (PDFg) that ColdFusion uses for HTML-to-PDF conversion with cfhtmltopdf
FieldsName: Unique name for the service manager
Hostname: Host name or IP of the service manager
Port: Service manager port (default 8987)
Weight: Load balancing factor that sets how many conversions this manager handles
HTTPS Enabled: Whether the manager runs over HTTPS
ActionsAdd, edit, enable, disable, and verify service managers from the list on this page
RecommendationRegister more than one service manager for high-volume HTML-to-PDF conversion and use weights to distribute the load
Scope: These settings apply to cfhtmltopdf, which converts HTML to PDF through a PDF service manager (PDFg, shipped with the Jetty-based add-on services). In ColdFusion 2025, Jetty also supports IP-based filtering through a jetty-ipaccess.xml file, so you can limit which ColdFusion servers may call the service manager.

PDF Generation Examples

Common PDF operations using ColdFusion's PDF functionality.

Generate PDF from HTML with cfhtmltopdf

cfhtmltopdf sends the conversion to a registered PDF service manager:

cfhtmltopdf
<!--- Convert HTML to PDF through the PDF service manager --->
<cfhtmltopdf destination="output.pdf" overwrite="true">
  <h1>Sample Report</h1>
  <p>Generated by the PDF service.</p>
</cfhtmltopdf>

Generate PDF from HTML with cfdocument

cfdocument is a separate tag that creates PDF output from a block of CFML and HTML. Adobe's knowledge base article on the differences between cfdocument and cfhtmltopdf covers which features each supports:

PDF from HTML
// Generate PDF from HTML content
cfdocument(format="pdf", filename="output.pdf") {
  writeOutput("
    <html>
    <head>
      <style>
        body { font-family: Arial, sans-serif; }
        h1 { color: #d63200; }
        .content { margin: 20px; }
      </style>
    </head>
    <body>
      <h1>Sample Report</h1>
      <div class='content'>
        <p>This is a PDF generated from HTML.</p>
      </div>
    </body>
    </html>
  ");
}
<!--- Generate PDF from HTML content --->
<cfdocument format="pdf" filename="output.pdf">
  <html>
  <head>
    <style>
      body { font-family: Arial, sans-serif; }
      h1 { color: #d63200; }
      .content { margin: 20px; }
    </style>
  </head>
  <body>
    <h1>Sample Report</h1>
    <div class="content">
      <p>This is a PDF generated from HTML.</p>
    </div>
  </body>
  </html>
</cfdocument>

Merge Multiple PDFs

Combine multiple PDF files into a single document:

Merge PDFs
// Merge multiple PDF files
cfpdf(action="merge", destination="merged.pdf") {
  cfpdfparam(source="document1.pdf");
  cfpdfparam(source="document2.pdf");
  cfpdfparam(source="document3.pdf");
}

// Alternative: Merge using array
pdfFiles = ["document1.pdf", "document2.pdf", "document3.pdf"];
cfpdf(action="merge", source=pdfFiles, destination="merged.pdf");
<!--- Merge multiple PDF files --->
<cfpdf action="merge" destination="merged.pdf">
  <cfpdfparam source="document1.pdf">
  <cfpdfparam source="document2.pdf">
  <cfpdfparam source="document3.pdf">
</cfpdf>

<!--- Alternative: Merge using array --->
<cfset pdfFiles = ["document1.pdf", "document2.pdf", "document3.pdf"]>
<cfpdf action="merge" source="#pdfFiles#" destination="merged.pdf">

Add Watermark

Apply a watermark to PDF documents. The addWatermark action takes its watermark from an image or from the first page of another PDF (copyFrom):

PDF Watermark
// Add image watermark (opacity is 0 = transparent to 10 = opaque)
cfpdf(
  action="addWatermark",
  source="original.pdf",
  destination="watermarked.pdf",
  image="logo.png",
  position="0,0",
  opacity=5
);
<!--- Add image watermark (opacity is 0 = transparent to 10 = opaque) --->
<cfpdf
  action="addWatermark"
  source="original.pdf"
  destination="watermarked.pdf"
  image="logo.png"
  position="0,0"
  opacity="5">

Protect PDF with Password

Encrypt and password-protect PDF documents:

PDF Encryption
// Protect PDF with password
cfpdf(
  action="protect",
  source="document.pdf",
  destination="protected.pdf",
  newUserPassword="userPass123",
  newOwnerPassword="ownerPass123",
  permissions="AllowPrinting,AllowCopy",
  encrypt="AES_128"
);

// Remove password protection
cfpdf(
  action="protect",
  source="protected.pdf",
  destination="unprotected.pdf",
  password="ownerPass123",
  newUserPassword="",
  newOwnerPassword=""
);
<!--- Protect PDF with password --->
<cfpdf
  action="protect"
  source="document.pdf"
  destination="protected.pdf"
  newUserPassword="userPass123"
  newOwnerPassword="ownerPass123"
  permissions="AllowPrinting,AllowCopy"
  encrypt="AES_128">

<!--- Remove password protection --->
<cfpdf
  action="protect"
  source="protected.pdf"
  destination="unprotected.pdf"
  password="ownerPass123"
  newUserPassword=""
  newOwnerPassword="">

Best Practices

Server Separation

Run PDFg on separate servers for production environments to isolate resource-intensive PDF operations from web traffic.

Load Balancing

Use multiple PDFg instances for high-volume PDF generation with proper load distribution and failover.

Memory Allocation

Size the JVM heap of the server that hosts the PDF service based on document complexity and generation volume.

Security

Always encrypt PDFs containing sensitive information using strong passwords and AES encryption.

Asynchronous Processing

Generate large PDFs asynchronously to avoid blocking user requests and improve application responsiveness.

Monitoring

Monitor PDFg server health, memory usage, and generation times to identify performance issues early.

Common Issues & Solutions

OutOfMemoryError During PDF Generation

Symptom: PDF generation fails with OutOfMemoryError, especially for complex documents
Solutions:
  • Increase JVM heap size for dedicated PDFg servers
  • Optimize PDF content (reduce image sizes, use efficient fonts)
  • Split large documents into smaller chunks
  • Process PDFs in batches rather than simultaneously

PDF Generation Timeout

Symptom: PDF generation times out before completion, especially for large reports
Solutions:
  • Use asynchronous generation for long-running operations
  • For cfhtmltopdf, set the conversion timeout with the -Dcoldfusion.pdfg.connectionTimeout JVM argument (milliseconds, added in ColdFusion 2025 Update 1)
  • Optimize HTML/CSS for faster rendering
  • Reduce document complexity (images, tables, fonts)
  • Consider using dedicated PDFg servers with more resources

Connection Refused to PDFg Server

Symptom: Unable to connect to remote PDFg service, connection refused errors
Solutions:
  • Verify PDFg server is running and accessible
  • Check firewall rules allow connections on the port configured for the service manager (default 8987)
  • Verify hostname/IP and port configured correctly
  • Test connection from ColdFusion server to PDFg server
  • Check PDFg server logs for startup errors

Related Resources

Data & Services - PDF Service | ColdFusion Administrator | CFGuide