Pre-Generating PDF Conversions
  Print This Page
Two ways to build the cached PDF that the flipbook viewer and other PDF tools use before anyone opens a document: the Temp PDF File Generator scheduled task (recommended) and the PDF Pre-Generation module property on GenericEnhanced modules. Covers setup, scheduling, what can and cannot be pre-generated, and how to read the results in the Process Monitor.

Pre-Generating PDF Conversions

Functionality

Centralpoint tools that show or link to documents as PDF, such as the PDF flipbook viewer and any tool that uses the PDF conversion handler, convert Word, Excel, PowerPoint, Visio, image, email and HTML files to PDF the first time the document is opened. For large files that first conversion can take many seconds (a 29.5 MB Word document took about 9 seconds), and the first visitor to open the document waits while it runs. After that the converted PDF is cached, and later requests open almost instantly.

Two features build the cached PDF ahead of time so that no visitor waits for the first conversion:

  • Scheduled Task: Temp PDF File Generator. Sweeps every record in the chosen modules on a schedule. This is the recommended option.
  • Module Property: PDF Pre-Generation. Queues a record's files for conversion each time the record is saved, on GenericEnhanced modules.

Supported source types: .doc .docx .docm .xls .xlsx .xlsb .xlsm .ppt .pptx .vsd .vsdx .jpg .jpeg .png .gif .tif .tiff .eml .msg .htm .html.

Scheduled Task: Temp PDF File Generator (Recommended)

The scheduled task is the recommended option for three reasons:

  • It runs off-hours. Conversions happen when the server is quiet rather than while visitors and administrators are working.
  • It covers every record. Every record in the chosen modules is checked, including imported records and records that are never re-saved.
  • It does not compete with daytime traffic. Conversion is CPU and memory intensive, and a scheduled window keeps that load away from peak hours.

Setup

In Master, create a scheduled task instance of Temp PDF File Generator and complete the settings below. Each task instance covers one site; create one instance per site.

Setting Description
Web Site The site whose documents are pre-generated. One site per task instance.
Modules The modules that hold relative paths or Resource.ashx links to documents that are viewed as PDF.
Attributes Comma separated list of attribute system names that hold those documents, for example FileUpload1, FileUpload2.
Maximum Execution Time (Minutes) The form reads: "This task never runs longer than 4 hours (240 minutes). Enter a lower number to stop it sooner; 0 uses the full 4 hours. Files it does not reach are generated on its next run." A very large module simply finishes over several runs, because each run skips files that are already generated.

Scheduling

Schedule the task to recur, weekly and off-hours as a starting point. Cached PDFs are removed by the monthly temporary-file cleanup about a month after they are created, so a one-time run does not keep documents fast indefinitely. A run over files that are already generated is quick, so a recurring schedule adds little load once the first full pass is complete.

What the process log shows

  • Failures. Each file that fails to convert is logged with its file path and the error.
  • Progress. A running summary line is written every 25 files or every 5 minutes, whichever comes first, and a final summary is written when the task finishes:
Sweep - Checked: n, Converted: n, Already Cached: n, Skipped: n, Failures: n
  • Queued files. Before its sweep, the task processes any files queued by the PDF Pre-Generation module property that are still waiting. Those lines are logged with the prefix Queue - .
  • Skipped. Counts PDF files (they are served as they are), file types that cannot be converted, missing files, and links to handlers other than Resource.ashx. Attribute values that are not file paths are not counted at all.
  • Retries. Failed files are retried on the next run.

Module Property: PDF Pre-Generation

GenericEnhanced modules carry two module properties that convert a record's files as the record is saved:

Property Default Description
Is PDF Pre-Generation Enabled? No Set to Yes to queue files for conversion when a record is saved. Selecting Yes reveals PDF Pre-Generation Attributes.
PDF Pre-Generation Attributes (blank) Comma separated list of attribute system names whose files are converted, for example FileUpload1,FileUpload2.

When a record is saved, the files in the listed attributes are queued and converted by the Master application, one file at a time across the whole server. The save does not wait for the conversion. This applies to saves in the Console and to Data Transfers that use Console Utilities. PDF files and unsupported file types are ignored.

Conversions run during working hours, as records are saved, and share the server with daytime traffic. This option suits modules with light, steady saves. For large modules and bulk imports, use the Temp PDF File Generator scheduled task instead.

  • Retries. A file that fails to convert is attempted up to 3 times, then kept as a failed entry; saving the record again queues it again. Queue entries are kept for 30 days.
  • Master unavailable. If the Master application is unavailable when a record is saved, the file waits in the queue and is converted by the next save or the next run of the scheduled task.
  • Process log. Entries appear under PDF Conversion Queue, with the same Queue - Checked: ... summary lines and failure lines as the scheduled task.

What Is and Is Not Pre-Generated

Document or view Pre-generated Notes
Word, Excel, PowerPoint, Visio, image, email and HTML files viewed without a watermark Yes The cached PDF is built ahead of time and served on first view.
PDF files Not needed PDF files are served directly, with no conversion.
Views with a watermark, static or user-specific (UserInfo:) No Watermarked PDFs are built when the document is viewed.
Documents in a virtual directory (stored outside the site's Root folder) Yes, when the same virtual directory is also mapped on the Master application The Master application converts these files, so it must be able to reach them at the same URL path. Map the virtual directory on the Master application to the same folder the site uses, the same way the Integrations virtual directory is mapped on every application. Without that mapping, these files are converted when they are first opened.

Checking Results

Both features write to the Process Monitor. Look for entries named TempPdfFileGenerator (the scheduled task) and PDF Conversion Queue (the module property).

Symptom Cause and resolution
A failure line names a file and an error The document itself could not be converted, often because the file is corrupt. The PDF tools still attempt the conversion when someone opens the document. Replace or re-save the source file to resolve it.
A failure line reads "no attempt finished; the conversion hung or ended the worker" Each of the file's 3 attempts started but never reported a result, so the conversion hung or stopped the Master application. The file is not attempted again from the queue. Check the source file, and the Windows Application event log on the server for the time of the attempts.
The Skipped count is high Skipped files are PDF files, unsupported file types, missing files, or links to handlers other than Resource.ashx. Check that the Attributes setting names only attributes that hold documents.
The task stops before every file is checked The run reached its Maximum Execution Time (Minutes). The remaining files are generated on the next run.
Documents that were fast become slow again after several weeks The monthly temporary-file cleanup removed the cached PDFs. Schedule the task to recur so the cache is rebuilt.