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
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
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:
<!--- 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:
// 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 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):
// 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:
// 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
- 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
- Use asynchronous generation for long-running operations
- For cfhtmltopdf, set the conversion timeout with the
-Dcoldfusion.pdfg.connectionTimeoutJVM 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
- 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