PDF Generation in ColdFusion

ColdFusion has introduced the high quality PDF generation capability from HTML using WebKit through various enhancements made to the <cfdocument> tag. However, these enhancements have been removed from the <cfdocument> tag in the beta release and hence this tag will function exactly in the same way as how it was functioning in ColdFusion 10.

To generate high quality PDFs from HTML documents, 2 new tags, <cfhtmltopdf> and <cfhtmltopdfitem> have been introduced in the beta release. This document describes the usage and functionalities of these tags.

Terminology

The following terms are the commonly used in <cfhtmltopdf> (WebKit):

• Service - Refers to the process which carries out series of activities to convert HTML documents to PDFs.
• Service Manager - Manages the PDF generation service processes, monitors the service process states, spawns new processes for conversions, and facilitates recycling of processes.
• WebKit - Is a layout engine software designed to allow web browsers to render web pages. 

System requirements

PDF generation is supported on both Windows and Linux operating systems. On Windows, there are no additional requirements for generating PDFs. On Linux, ensure that the following additional requirements are met:

Additional package requirements

On Linux platforms, install the following additional packages:

• glibc.i686

• zlib.i686

• libX11.i686

• ia32-libs

• expat.i686

• freetype.i686

• X Window System

• nss-softokn.i686

• libxcb.i686

• libXau.i686

• libXext.i686

• libSM.i686

• libXrandr.i686

• libXrender.i686

• libXinerama.i686

For instance, you can use YUM to install these packages as shown below:

Additional font requirements

Also, you need to install a few required fonts for generating PDFs on Linux. To install the fonts, perform the following tasks:

1. In your browser, open websitehttp://cgit.freedesktop.org/xorg/font/ibm-type1/

2. Download the compressed filefont-ibm-type1-1.0.3.tar.gz or font-ibm-type1-1.0.3.zip.The compressed file contains the required fonts.

3. Extract the downloaded zip file to the/usr/share/fonts directory.

The new <cfhtmltopdf> tag

<cfhtmltopdf> creates high quality PDF output from a text block containing CFML and HTML using the PDF Service Manager.

The WebKit implementation for <cfhtmltopdf> is referred as PDFG (acronym of PDF Generator) which is shipped as part of the Jetty installer. The component running inside the Jetty  server is referred as the service manager, which takes request for PDF conversion from one or many ColdFusion server/s.

The WebKit implementation for <cfhtmltopdf>:

• Encapsulates the PDF conversion library.
• Performs HTML to PDF conversion in process.

See <cfhtmltopdf> and <cfhtmltopdfitem>.

Using the remote PDF service manager

You need to use a remote PDF service manager instead of the local PDF service manager due to the following reasons:

• When the ColdFusion Server is running on an OS not supported by the local PDF service manager
• When performance of the local ColdFusion Server is critical as PDF generation is a CPU intensive operation.
• When you want to distribute the load of generating the PDFs for maximum throughput.

Adding and editing the PDF service manager

From the Administrator console, click Data & Services > PDF Service.

You can add or edit a PDF service manager by providing the name, host name, port, and other configuration details.

To add or edit a remote service manager, you need to provide the details of Jetty service running on local or remote machine over which the service manager is deployed. Follow the instructions below to complete this process: 

1. Enter the Name. A unique name representing the PDF service manager.
2. Enter the Host Name. This is the host name of the remote PDF service manager.
3. Enter the Port number. This is the port number of the PDF service manager. By default, the port is set to 8987.
4. Enter the Weight detail of the PDF  service manager. Weight is the load balancing factor and determines the amount of PDF conversions that the service manager can handle. Set this based on the configuration of your system. 
5. If the PDF service manager is running on HTTPS protocol, select the HTTPS Enabled check box.
6. Click Add PDF Service Manager button to complete the process.

Using the remote service manager, you can add, edit, delete, enable, disable, and verify the service manager.  

Working with the PDF service manager

PDF Service Managers section lists all the available PDF service managers.

The description for each Action button (in the above image) is as follows: 

Button	Button Description	Action
	Edit	Enables users to edit the settings of the existing service manager.
	Verify	Enables users to verify the current connection status of service manager.
	Delete	Enables users to delete the PDF service.

Note: Verify All Service Manager button is used to verify all the listed PDF Service Managers.

Configuring the PDF service manager

To configure the PDF service manager, use the configuration file (web.xml) located at <cf_install_root>/<CF Instance>/jetty/webapps/PDFgServlet/WEB-INF/. The available configuration settings are:

• minService = Minimum number of services running in process pool. Default value is 1.
• maxService = Maximum number of services that can run in the process pool. Default value is 2. As PDF Conversion is a CPU intense operation, it  should be appropriately configured based on the number of processors in the system. Ideally, keep this value lesser than or equal to the number of CPUs in the machine.
• idlePDFGServiceTimeout = Idle timeout for services in the process pool. After timeout, the services are removed. Default value is 2 minutes. Creation and initialization of service is  a costly operation. Also the service consumes memory for conversion. Based on the conversion frequency and load, this parameter must be tuned.
• waitingQueueSize = The number of PDF conversion requests which can wait in the service manager queue. Default value is 10. Once the available services are engaged in the conversion process,  upcoming conversion requests are queued up. Based on the load on the service manager at the given point of time, the queue size must be configured.
• waitingQueueTimeout= Timeout (in seconds) for queued PDF task in the service manager queue.  Default value is 60 seconds. This value needs to be tuned considering the following parameters:
  • The average PDF generation time.
  • Total number of service managers configured with the Server. If more than one service manager is configured with the Server, having a high value for waitingQTimeout may result in unnecessary wait for conversion task, even though the other service managers have idle service which can take up the task.
  • maxPDFConversionForService = Maximum PDF conversion allowed per service. Default value is 1000.Once service does the specified number of  PDF conversions, the service will be restarted. Note: Based on how large or small PDF your application generates, this value needs to be tuned. For large PDFs, the memory usage of the service increases at faster rate than the smaller PDFs. Hence the maxPDFConversionForService value needs to be lower.
  • startScanPort = Start scanning port used by the services. Default value is 1600.
  • endScanPort  = End scanning port used by services. Default value is 1800.
  • enableLogging =By default logging for PDF service manager is disabled. To enable logging, set the flag to true. Use this option only for debugging purpose.

About logging audit log details

PDF service manager logging is used to track service manager related issues  and generates verbose log that contains complete details about the service and conversion request lifecycle. Use it to track the PDF conversion request.

Support for restricted DDX elements

In ColdFusion 11, the restricted DDX elements are supported for the Enterprise Edition. See this document for the list.