Blog on [AEM FORMS] (previously Adobe LiveCycle)

Icon

Things to Note When Configuring AEM FORMS PDF Generator

Jayan Kandathil

First published

Let's face it - configuring AEM FORMS (formerly Adobe LiveCycle) PDF Generator is complicated. It is mainly because of the nature of what it does - programmatically invoke [Microsoft Office] applications such as Word/Excel/PowerPoint to convert their native documents (.docx, .xlsx and .pptx) to the PDF format by programmatically invoking [Adobe Acrobat].

Official Adobe documentation for AEM 6.3 is available here. For some reason, the same for AEM 6.4 is currently busted. Here are some high levels things you need to know:

Higher clock-speed CPUs

NativeToPDF conversion is single-threaded. Higher clock speed CPUs will perform better.

Minimum 16 GB memory

Windows Server 2016 requires about 3 GB of main memory. AEM's JVM requires at least 6 GB of heap to perform well. Native2PDF conversions requires additional memory since they invoke [Microsoft Office] Applications such as WINWORD.EXE (64 MB per process) as well as Adobe Acrobat.

Storage

A boot volume of at least 30 GB and a data volume of at least 50 GB will suffice. If possible, use disk types that offer latency of 10 ms or less.

Most Functional OS is Windows

Because Microsoft Office's native OS is Windows, and since Adobe never released an Acrobat version for Linux, the most functional OS for PDF Generator is Windows. The latest Windows version supported in AEM FORMS 6.4 is [Windows Server 2016]. It can be 64-bit.

Latest Office Version Supported is Office 2016

Because of the additional cloud-related complications (mostly licensing-related) of Office 365, it's better to stick with the traditional earth-bound Office 2016 Professional.

Acrobat DC is Supported

It works. Acrobat Professional 2017 is also supported.

It's all 32-bit, even on 64-bit Windows

Because Adobe has so far not ported the 32-bit C++ components of AEM FORMS (see in \crx-quickstart\bedrock\svcnative\) to 64-bit yet, and since those are invoked from AEM (a Java application), you need 32-bit [Microsoft Office], a 32-bit JDK (mapped to the environment variable JAVA_HOME_32), and 32-bit [Adobe Acrobat].

But You Still Need the 64-bit JDK

Because AEM is by now ensconced in the 64-bit world, you need to have a 64-bit JDK mapped to the environment variable JAVA_HOME

Multi-threaded Operation is Possible, with Multiple Windows Users

NativeToPDF conversion is single-threaded. However, if your server instance has four CPU cores, you can configure PDF Generator to concurrently service four nativeToPDF conversion requests by creating/configuring additional Windows users. Ensure that these additional users are registered at /libs/fd/pdfg/config/ui.html (see the tab 'User Accounts'). Ensure that you are logged in to AEM before you load this page - it'll throw an exception otherwise. These users need to be members of the Windows group 'Administrators'.

Gotcha with Registering Multiple Windows Users

When registering additional Windows users for multi-threaded performance using the config UI at /libs/fd/pdfg/config/ui.html, remember to clear the password field each time. For some weird reason, it gets populated with garbage on every initialization. Also note this registration will fail without a proper error message if the user being added is not already a member of the Windows group 'Administrators'.

Remember to Login to Windows as each Configured User, Launch Word/Excel/PowerPoint and Acrobat, Dismiss Registration/Licensing Dialogs

Since Microsoft Office is a desktop application, each configured user needs to launch these applications at least once, register the license key, and accept the license agreement. [Adobe Acrobat] puts up some dialogs when you login for the first time which need to be dismissed.

The Acrobat_PATH Environment Variable Needs Filename as well

Unlike the other environment variables, this requires the file name as well. Example, C:\Program Files (x86)\Adobe\Acrobat DC\Acrobat\Acrobat.exe

The folder structure C:\Windows\SysWOW64\config\systemprofile\Desktop is required

Make sure that the folder \Desktop exists at C:\Windows\SysWOW64\config\systemprofile. If not found, create the \Desktop folder.

Configure AEM LISTEN Ports

The script \crx-quickstart\opt\helpers\instsrv.bat is what is used to create a Windows service for AEM. Before running it, remember to edit it with your changes. Example, set cq_host=0.0.0.0 so that AEM LISTENs on all local network interfaces, set cq_runmode="publish,stage,nosamplecontent" and set cq_port=4503

Verify afterwards in the Windows Registry at HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\cq5\Parameters\Start\Params. There should be a -p argument for cq_port, and a -a argument representing cq_host

Remember to Run the Acrobat Configuration Script

This script does two key things:

  • Creates a set of Windows Registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Adobe\. Note that when you configure AEM to start/stop automatically as a Windows service, those settings are saved in the Registry at HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0. See this for more details.
  • Copies the PDFGen.api plugin to the Acrobat plugins folder at (by default) C:\Program Files (x86)\Adobe\Acrobat DC\Acrobat\plug_ins\. This sometimes fails, forcing you to do this manually.

Adobe provides a batch file to run (Acrobat_for_PDFG_Configuration.bat) and another script (SystemReadinessTool.vbs) to verify the configuration. But these are packaged inside the [AEM FORMS Add-On] package, 3 levels deep!

  1. Inside AEM-Forms-6.4.3.0-WIN-5.1.42.zip (this one's for AEM 6.4 SP3), you need to extract the package \jcr_root\etc\packages\day\cq60\fd\adobe-aemds-common-pkg-5.1.42.zip
  2. Extract the package jcr_root\etc\packages\day\cq60\fd\adobe-aemfd-pdfg-common-pkg-4.1.6.zip
  3. Extract the package jcr_root\libs\fd\pdfg\tools\adobe-aemfd-pdfg-utilities-4.1.6-win.zip
  4. The batch file is in the \scripts folder and the verification script is in the \srt folder
  5. The PDFGen.api file is in \plugins\x86_win32

Remember to Validate the Acrobat Configuration

Adobe provides a script (SystemReadinessTool.vbs) to verify the configuration that produces a nicely-formatted HTML report (see this). It is located in the adobe-aemfd-pdfg-utilities-4.1.6-win.zip package.

High Disk I/O

The folder \crx-quickstart\temp\ experiences high disk I/O (temporary file creation/deletion) during NativeToPDF conversion jobs. For performance reasons, you should think about hosting the \crx-quickstart folder on a more performant disk.

See index for all entries in this blog.