DocumentationAEM 6.5User Guide

Installing and configuring document services installing-and-configuring-document-services

Last update: Wed Jun 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • User
  • Developer

AEM Forms provides a set of OSGi services to accomplish different document level operations, for example, services to create, assemble, distribute, and archive PDF documents, add digital signatures to limit access to documents, and decode Barcoded Forms. These services are included in AEM Forms add-on package. Collectively, these services are known as document services. The list of available document services and their major capabilities is as below:

  • Assembler service: Enables you to combine, rearrange, and augment PDF and XDP documents and obtain information about PDF documents. It also helps convert and validate PDF documents to PDF/A standard, transforms PDF forms, XML forms, and PDF forms to PDF/A-1b, PDF/A-2b, and PDFA/A-3b. For more information, see Assembler Service.

  • ConvertPDF service: Enables you to convert PDF documents to PostScript or image files (JPEG, JPEG 2000, PNG, and TIFF). For more information, see ConvertPDF Service.

  • Barcoded Forms service: Enables you to extract data from electronic images of barcodes. The service accepts TIFF and PDF files that include one or more barcodes as input and extracts the barcode data. For more information, see Barcoded Forms Service.

  • DocAssurance service: Enables you to encrypt and decrypt documents, extend the functionality of Adobe Reader with additional usage rights, and add digital signatures to your documents. The Doc Assurance service contains three services: signature, encryption, and reader extension. For more information, see DocAssurance Service.

  • Encryption service: Enables you to encrypt and decrypt documents. When a document is encrypted, its contents become unreadable. An authorized user can decrypt the document to obtain access to its contents. For more information, see Encryption Service.

  • Forms service: Lets you create interactive data capture client applications that validate, process, transform, and deliver forms that are typically created in Forms Designer. The Forms service renders any form design that you develop to PDF documents. For more information, see Forms Service.

  • Output service: Enables you to create documents in different formats, including PDF, laser printer formats, and label printer formats. Laser printer formats are PostScript and Printer Control Language (PCL). For more information, see Output Service.

  • PDF Generator service: The PDF Generator service provides APIs to converts native file formats to PDF. It also converts PDF to other file formats and optimizes the size of PDF documents. For more information, see PDF Generator Service.

  • Reader Extension service: Enables your organization to easily share interactive PDF documents by extending the functionality of Adobe Reader with additional usage rights. The service activates features that are not available when a PDF document is opened using Adobe Reader, such as adding comments to a document, filling forms, and saving the document. For more information, see Reader Extension Service.

  • Signature service: Lets you work with digital signatures and documents on the AEM server. For example, the Signature service is typically used in the following situations:

    • The AEM server certifies a form before it is sent to a user to open by using Acrobat or Adobe Reader.
    • The AEM server validates a signature that was added to a form by using Acrobat or Adobe Reader.
    • The AEM server signs a form on behalf of a public notary.

    The signature service accesses certificates and credentials that are stored in the trust store. For more information, see Signature Service.

AEM Forms is a powerful enterprise-class platform and the document services is only one of the capability of AEM Forms. For the complete list of capabilities, see Introduction to AEM Forms.

Deployment Topology deployment-topology

AEM Forms add-on package is an application deployed onto AEM. Generally, you require only one AEM instance (author or publish) to run AEM Forms document services. The following topology is recommended to run AEM Forms document services. For detailed information about topologies, see Architecture and deployment topologies for AEM Forms.

Architecture and deployment topologies for AEM Forms

NOTE
Although AEM Forms lets you set up and run all the functionalities from a single server, you should do capacity planning, load balancing, and set up dedicated servers for specific capabilities in a production environment. For example, for an environment using the PDF Generator service to convert thousands of pages a day and multiple adaptive forms to capture data, set up separate AEM Forms servers for the PDF Generator service and adaptive forms capabilities. It helps provide optimum performance and scale the servers independent of each other.

System Requirements system-requirements

Before you begin to install and configure AEM Forms document services, ensure that:

  • Hardware and software infrastructure is in place. For a detailed list of supported hardware and software, see technical requirements.

  • Installation path of the AEM instance does not contain white-spaces.

  • An AEM instance is up and running. In AEM terminology, an “instance” is a copy of AEM running on a server in the author or publish mode. Generally, you require only one AEM instance (author or publish) to run AEM Forms document services:

    • Author: An AEM instance used to create, upload, and edit content and to administer the website. Once content is ready to go live, it is replicated to the publish instance.
    • Publish: An AEM instance that serves the published content to the public over the internet or an internal network.

  • Memory requirements are met. AEM Forms add-on package requires:

    • 15 GB of temporary space for Microsoft® Windows-based installations.
    • 6 GB of temporary space for UNIX-based installations.

  • Client software required for PDF generator to perform conversion on Microsoft® Windows and Linux® are installed:

NOTE
  • On Microsoft® Windows, PDF Generator supports WebKit, Acrobat WebCapture, and WebToPDF conversion routes to convert HTML files to PDF documents.
  • On UNIX-based operating systems, PDF Generator supports WebKit and WebToPDF conversion routes to convert HTML files to PDF documents.

Extra requirements for UNIX-based operating system extrarequirements

If you are using a UNIX-based operating system, install the following 32-bit packages from the installation media of the respective operating system:

  • expat
  • libxcb
  • freetype
  • libXau
  • libSM
  • zlib
  • libICE
  • libuuid
  • glibc
  • libXext
  • nss-softokn-freebl
  • fontconfig
  • libX11
  • libXrender
  • libXrandr
  • libXinerama

  • (PDF Generator only) Install the 32-bit version of libcurl, libcrypto, and libssl libraries and create the below symlinks. The symlinks point to the latest version of the respective libraries:

    • /usr/lib/libcurl.so
    • /usr/lib/libcrypto.so
    • /usr/lib/libssl.so

  • (PDF Generator only) PDF Generator service supports WebKit and WebToPDF routes to convert HTML files to PDF documents. To enable conversion for WebToPDF route, install the below listed 64-bit libraries. Generally, these libraries are already installed. If any library is missing, install it manually:

    • linux-gate.so.1
    • libz.so.1
    • libfontconfig.so.1
    • libfreetype.so.6
    • libdl.so.2
    • librt.so.1
    • libpthread.so.0
    • libstdc++.so.6
    • libm.so.6
    • libgcc_s.so.1
    • libc.so.6
    • ld-linux.so.2
    • libexpat.so.1

Pre-installation configurations preinstallationconfigurations

Configurations listed in the pre-installation configurations section are applicable only to the PDF Generator service. If you are not configuring the PDF Generator service, you can skip the pre-installation configuration section.

Install Adobe Acrobat and third-party applications install-adobe-acrobat-and-third-party-applications

If you are going use the PDF Generator service to convert native file formats such as Microsoft® Word, Microsoft® Excel, Microsoft® PowerPoint, OpenOffice, WordPerfect X7, and Adobe Acrobat to PDF Documents, ensure that these applications are installed on the AEM Forms Server.

NOTE
  • If your AEM Forms Server is in an offline or secure environment and internet is not available to activate Adobe Acrobat, see Offline Activation for instructions to activate such instances of Adobe Acrobat.
  • Adobe Acrobat, Microsoft® Word, Excel, and Powerpoint are available only for Microsoft® Windows. If you are using the UNIX-based operating system, install OpenOffice to convert rich text files and supported Microsoft® Office files to PDF documents.
  • Dismiss all the dialog boxes that are displayed after installing Adobe Acrobat and third-party software for all the users configured to use the PDF Generator service.
  • Start all the installed software at least once. Dismiss all the dialog boxes for all the users configured to use the PDF Generator service.
  • Check expiration date of your Adobe Acrobat serial numbers and set a date to update license or migrate your serial number based on the expiry date.

After installing Acrobat, open Microsoft® Word. On the Acrobat tab, click Create PDF and convert a .doc or .docx file available on your machine to a PDF Document. If the conversion is successful, AEM Forms is ready to use Acrobat with PDF Generator service.

Setup environment variables setup-environment-variables

Set environment variables for 64-bit Java Development Kit, third-party applications, and Adobe Acrobat. The environment variables should contain the absolute path of the executable used to start the corresponding application, for example, the table below lists environment variables for a few applications:

Application
Environment variable
Example
JDK (64-bit)
JAVA_HOME
C:\Program Files\Java\jdk1.8.0_74
Adobe Acrobat
Acrobat_PATH
C:\Program Files (x86)\Adobe\Acrobat 2015\Acrobat\Acrobat.exe
Notepad
Notepad_PATH
C:\WINDOWS\notepad.exe
OpenOffice
OpenOffice_PATH
C:\Program Files (x86)\OpenOffice.org4
NOTE

  • All environment variables and respective paths are case-sensitive.

  • JAVA_HOME and Acrobat_PATH (Windows only) are mandatory environment variables.

  • The environment variable OpenOffice_PATH is set to the installation folder instead of the path to the executable.

  • Do not set up environment variables for Microsoft® Office applications such as Word, PowerPoint, Excel, and Project, or for AutoCAD. If these applications are installed on the server, the Generate PDF service automatically starts these applications.

  • On UNIX-based platforms, install OpenOffice as /root. If OpenOffice is not installed as root, the PDF Generator service fails to convert OpenOffice documents to PDF documents. If you are required to install and run OpenOffice as a non-root user, then provide sudo rights to the non-root user.

  • If you are using OpenOffice on a UNIX-based platform, run the following command to set the path variable:

    export OpenOffice_PATH=/opt/openoffice.org4

(Only for IBM® WebSphere®) Configure IBM® SSL socket provider only-for-ibm-websphere-configure-ibm-ssl-socket-provider

Perform the following steps to configure IBM® SSL socket provider:

  1. Create a copy of the java.security file. The default location of the file is [WebSphere_installation_directory]\Appserver\java_[version]\jre\lib\security.

  2. Open the copied java.security file for editing.

  3. Change the default SSL socket factories to use the JSSE2 factories instead of default IBM® WebSphere® factories:

    Default content:

    code language-shell 
    #ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
#ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
#WebSphere socket factories (in cryptosf.jar)
ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

    Modified content:

    code language-shell 
    ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl

#WebSphere socket factories (in cryptosf.jar)
#ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
#ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

  4. To enable AEM Forms Server to use the updated java.security file, while starting the AEM Forms server, add the following java argument:

    -Djava.security.properties= [path of newly created Java.security file].

(Windows Only) Configure the file block settings for Microsoft® Office configure-the-file-block-settings-for-microsoft-office

Change the Microsoft® Office trust center settings to enable the PDF Generator service to convert files created with older versions of Microsoft® Office.

  1. Open a Microsoft® Office application. For example, Microsoft® Word. Navigate to File> Options. The options dialog box appears.

  2. Click Trust Center, and click Trust Center Settings.

  3. In the Trust Center settings, click File Block Settings.

  4. In the File Type list, deselect Open for the file type that the PDF Generator service should be allowed to convert to PDF documents.

(Windows Only) Grant the Replace a process level token privilege grant-the-replace-a-process-level-token-privilege

The user account used to start the application server requires the Replace a process level token privilege. The local system account has the Replace a process level token privilege by default. For the servers running with a user of the Local Administrators group, the privilege must be granted explicitly. Perform the following steps to grant the privilege:

  1. Open the Group Policy Editor for Microsoft® Windows. To open the Group Policy Editor, click Start, type gpedit.msc in the Start Search box, and click Group Policy Editor.
  2. Navigate to Local Computer Policy > Computer Configuration > Windows Settings > Security Settings > Local Policies > User Rights Assignment and edit the Replace a process level token policy and include the Administrators group.
  3. Add the user to the Replace a Process Level Token entry.
NOTE
As implied above, if the AEM server is running as a service under the LocalSystem account (LSA), explicitly assigning this privilege to a user is not necessary.

(Windows Only) Enable the PDF Generator service for non-administrators enable-the-pdf-generator-service-for-non-administrators

You can enable a non-administrator user to use the PDF Generator service. Normally, only users with administrative privileges can use the service:

  1. Create an environment variable, PDFG_NON_ADMIN_ENABLED.
  2. Set value of the environment variable to TRUE.
  3. Restart the AEM Forms instance.
NOTE
It is recommended to use the ‘Ctrl + C’ command to restart the SDK. Restarting the AEM SDK using alternative methods, for example, stopping Java processes, may lead to inconsistencies in the AEM development environment.

(Windows Only) Disable User Account Control (UAC) disable-user-account-control-uac

  1. To access the System Configuration Utility, go to Start > Run and then enter MSCONFIG.

  2. Click the Tools tab and scroll down and select Change UAC Settings. Click Launch to run the command in a new window.

  3. Adjust the slider to the Never notify level. When finished, close the command window and close the System Configuration window.

  4. Verify that registry setting for UAC is set to 0 (zero). Perform the following steps to verify:

    1. Microsoft® recommends backing up the registry before you modify it. For detailed steps, see How to back up and restore the registry in Windows.
    2. Open Microsoft® Windows Registry editor. To open registry editor, go to Start > Run, type regedit, and click OK.
    3. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system\. Ensure value of EnableLUA is set to 0 (zero).
    4. Ensure value of EnableLUA is set to 0 (zero). If the value is not 0, change the value to 0. Close the registry editor.

  5. Restart your computer.

(Windows Only) Disable Error Reporting service disable-error-reporting-service

While converting a document to PDF using the PDF Generator service on Windows Server, occasionally, Windows Server reports that the executable has encountered a problem and must close. However, it does not impact the PDF conversion as it continues in the background.

To avoid receiving the error, you can disable the Windows error reporting. For more information on disabling error reporting, see https://technet.microsoft.com/en-us/library/cc754364.aspx.

(Windows Only) Configure HTML to PDF conversion configure-html-to-pdf-conversion

The PDF Generator service provides WebKit, WebCapture, and WebToPDF routes or methods to convert HTML files to PDF documents. On Windows, to enable conversion for WebKit and Acrobat WebCapture routes, copy the Unicode font to %windir%\fonts directory.

NOTE
Whenever you install new fonts to the fonts folder, restart the AEM Forms instance.

(UNIX-based platforms only) Extra configurations for HTML to PDF conversion extra-configurations-for-html-to-pdf-conversion

On UNIX-based platforms, the PDF Generator service supports WebKit and WebToPDF routes to convert HTML files to PDF documents. To enable HTML to PDF conversion, perform the following configurations, applicable to your preferred conversion route:

(UNIX-based platforms only) Enable support for Unicode fonts (WebKit only) enable-support-for-unicode-fonts-webkit-only

Copy the Unicode font to any of the following directories as appropriate for your system:

  • /usr/lib/X11/fonts/TrueType
  • /usr/share/fonts/default/TrueType
  • /usr/X11R6/lib/X11/fonts/ttf
  • /usr/X11R6/lib/X11/fonts/truetype
  • /usr/X11R6/lib/X11/fonts/TrueType
  • /usr/X11R6/lib/X11/fonts/TTF
  • /usr/openwin/lib/X11/fonts/TrueType (Solaris™)
NOTE
  • On Red Hat® Enterprise Linux® 6.x and later, the courier fonts are not available. To install the courier fonts, download the font-ibm-type1-1.0.3.zip archive. Extract the archive at /usr/share/fonts. Create a symbolic link from /usr/share/X11/fonts to /usr/share/fonts.
  • Delete all the .lst font cache files from the Html2PdfSvc/bin and /usr/share/fonts directories.
  • Ensure that the directories /usr/lib/X11/fonts and /usr/share/fonts exist. If the directories do not exist, then use the ln command to create a symbolic link from /usr/share/X11/fonts to /usr/lib/X11/fonts and another symbolic link from /usr/share/fonts to /usr/share/X11/fonts. Also ensure that the courier fonts are available at /usr/lib/X11/fonts.
  • Ensure that all the fonts (Unicode and non-unicode) are available in the /usr/share/fonts or /usr/share/X11/fonts directory.
  • When you run PDF Generator service as a non-root user, provide the non-root user read and write access to all the font directories.
  • Whenever you install new fonts to the fonts folder, restart the AEM Forms instance.

Install AEM Forms add-on package install-aem-forms-add-on-package

AEM Forms add-on package is an application deployed onto AEM. The package contains AEM Forms Document Services and other AEM Forms capabilities. Perform the following steps to install the package:

  1. Open Software Distribution. You require an Adobe ID to log in to the Software Distribution.

  2. Select Adobe Experience Manager available in the header menu.

  3. In the Filters section:

    1. Select Forms from the Solution drop-down list.
    2. Select the version and type for the package. You can also use the Search Downloads option to filter the results.

  4. Select the package name applicable to your operating system, select Accept EULA Terms, and select Download.

  5. Open Package Manager and click Upload Package to upload the package.

  6. Select the package and click Install.

    You can also download the package via the direct link listed in the AEM Forms releases article.

  7. After the package is installed, you are prompted to restart the AEM instance. Do not immediately stop the server. Before stopping the AEM Forms Server, wait until the ServiceEvent REGISTERED and ServiceEvent UNREGISTERED messages stop appearing in the [AEM-Installation-Directory]/crx-quickstart/logs/error.log file and the log is stable.

Post-installation configurations post-installation-configurations

Configure Boot Delegation for RSA/BouncyCastle libraries configure-boot-delegation-for-rsa-bouncycastle-libraries

  1. Stop the AEM instance. Navigate to the [AEM installation directory]\crx-quickstart\conf\ folder. Open the sling.properties file for editing.

    If you use [AEM installation directory]\crx-quickstart\bin\start.bat to start an AEM instance, edit the sling.properties located at [AEM_root]\crx-quickstart\.

  2. Add the following properties to the sling.properties file:

    code language-shell 
    sling.bootdelegation.class.com.rsa.jsafe.provider.JsafeJCE=com.rsa.*

  3. (AIX® only) Add the following properties to the sling.properties file:

    code language-shell 
    sling.bootdelegation.xerces=org.apache.xerces.*

  4. Save and close the file.

Configuring the font manager service configuring-the-font-manager-service

  1. Log in to AEM Configuration Manager as an administrator.

  2. Locate and open the CQ-DAM-Handler-Gibson Font Managers service. Specify the path of the System Fonts, Adobe Server Fonts, and Customer Fonts directories. Click Save.

    note note
    NOTE
    Your right to use fonts provided by parties other than Adobe is governed by the license agreements provided to you by such parties with those fonts, and is not covered under your license to use Adobe software. Adobe recommends that you review and ensure that you are in compliance with all applicable non-Adobe license agreements before using non-Adobe fonts with Adobe software, particularly concerning use of fonts in a server environment.
    When you install new fonts to the fonts folder, restart the AEM Forms instance.

Configure a local user account to run the PDF Generator service configure-a-local-user-account-to-run-the-pdf-generator-service

A local user account is required to run the PDF Generator service. For steps to create a local user, see Create a user account in Windows or create a user account in UNIX-based platforms.

  1. Open the AEM Forms PDF Generator Configuration page.

  2. In the User Accounts tab, provide credentials of a local user account, and click Submit. If Microsoft® Windows prompts, allow access to the user. When added successfully, the configured user is displayed under the Your user accounts section in the User Accounts tab.

Configure the time-out settings configure-the-time-out-settings

  1. In AEM configuration manager, locate and open the Jacorb ORB Provider service.

    Add the following to the Custom Properties.name field and click Save. It sets the pending reply timeout (also known as, CORBA client timeout) to 600 seconds.

    jacorb.connection.client.pending_reply_timeout=600000

  2. Log in to the AEM author instance and navigate to Adobe Experience Manager > Tools > Forms > Configure PDF Generator. The default URL is http://localhost:4502/libs/fd/pdfg/config/ui.html.

    Open the General Configuration tab and modify the value of the following fields for your environment:

Field
Description
Default Value
Server Conversion Timeout
A PDFG conversion stays active for the number of seconds defined in the Server Conversion timeout
270 seconds
PDFG Cleanup Scan Seconds
The number of seconds required to perform post-conversion operations.
3600 seconds
Job Expiration Seconds
Duration for which PDF Generator service is allowed to run a conversion. Ensure that the value of the Job Expiration Seconds is greater than the PDFG Cleanup Scan Seconds value.
7200 seconds

(Windows only) Configure Acrobat for the PDF Generator service configure-acrobat-for-the-pdf-generator-service

On Microsoft® Windows, the PDF Generator service uses Adobe Acrobat to convert supported file formats to a PDF document. Perform the following steps to configure Adobe Acrobat for the PDF Generator service:

  1. Open Acrobat and select Edit> Preferences> Updater. In Check for updates, deselect Automatically install updates, and click OK. Close Acrobat.

  2. Double-click a PDF document on your system. When Acrobat starts for the first time, the dialog boxes for Sign-in, Welcome screen, and EULA appear. Dismiss these dialog boxes for all the users configured to use PDF Generator.

  3. Run the PDF Generator utility batch file to configure Acrobat for the PDF Generator service:

    1. Open AEM Package Manager and download the adobe-aemfd-pdfg-common-pkg-[version].zip file from the Package Manager.

    2. Unzip the downloaded .zip file. Open the command prompt with administrative privileges.

    3. Navigate to the [extracted-zip-file]\jcr_root\etc\packages\day\cq60\fd\adobe-aemds-common-pkg-[version]\jcr_root\etc\packages\day\cq60\fd\

    4. Unzip the adobe-aemfd-pdfg-common-pkg-[version].

    5. Navigate to the [downloaded-adobe-aemfd-pdfg-common-pkg]\jcr_root\libs\fd\pdfg\tools\adobe-aemfd-pdfg-utilities-[version] directory. Run the following batch file:

      Acrobat_for_PDFG_Configuration.bat

      Acrobat is configured to run with the PDF Generator service.

  4. Run System Readiness Tool (SRT) to validate Acrobat installation.

(Windows only) Configure primary route for HTML to PDF conversion configure-primary-route-for-html-to-pdf-conversion-windows-only

The PDF Generator service provides multiple routes to convert HTML files to PDF documents: Webkit, Acrobat WebCapture (Windows only), and WebToPDF. Adobe recommends using WebToPDF route because it has the capability to handle dynamic content and has no dependencies on 32-bit libraries or requires no extra fonts. Also, WebToPDF route does not require sudo or root access to run the conversion.

The default primary route for HTML to PDF conversion is Webkit. To change the conversion route:

  1. On AEM author instance, navigate to Tools> Forms> Configure PDF Generator.

  2. In the General Configuration tab, select the preferred conversion route from the Primary Route for HTML to PDF conversions drop-down.

Initialize Global Trust Store intialize-global-trust-store

Using the Trust Store Management, you can import, edit, and delete certificates that you trust on the server for validation of digital signatures and certificate authentication. You can import and export any number of certificates. After a certificate is imported, you can edit the trust settings and trust store type. Perform the following steps to initialize a trust store:

  1. Log in to AEM Forms instance as an administrator.
  2. Go to Tools > Security > Trust Store.
  3. Click Create TrustStore. Set password and select Save.

Set up certificates for Reader extension and encryption service set-up-certificates-for-reader-extension-and-encryption-service

The DocAssurance service can apply usage rights to PDF documents. To apply usage rights to PDF documents, configure the certificates.

Before setting up the certificates, ensure that you have a:

  • Certificate file (.pfx).

  • Private Key password provided with the certificate.

  • Private Key Alias. You can execute the Java keytool command to view the Private Key Alias:
    keytool -list -v -keystore [keystore-file] -storetype pkcs12

  • Keystore file password. If you are using Adobe’s Reader Extensions certificate, the Keystore file password is always the same as Private Key password.

Perform the following steps to configure the certificates:

  1. Log in to AEM Author instance as an administrator. Go to Tools > Security > Users.

  2. Click the name field of the user account. The Edit User Settings page opens. On the AEM Author instance, certificates reside in a KeyStore. If you have not created a KeyStore earlier, click Create KeyStore and set a new password for the KeyStore. If the server already contains a KeyStore, skip this step. If you are using Adobe’s Reader Extensions certificate, the Keystore file password is always the same as Private Key password.

  3. On the Edit User Settings page, select the KeyStore tab. Expand the Add Private Key from Key Store file option and provide an alias. The alias is used to perform the Reader Extensions operation.

  4. To upload the certificate file, click Select Key Store File and upload a <filename>.pfx file.

    Add the Key Store Password, Private Key Password, and Private Key Alias that is associated with the certificate to the respective fields. Click Submit.

    note note
    NOTE
    In the production environment, replace your evaluation credentials with production credentials. Ensure that you delete your old Reader Extensions credentials, before updating an expired or evaluations credential.

  5. Click Save & Close on the Edit User Settings page.

Enable AES-256 enable-aes

To use AES 256 encryption for PDF files, obtain and install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy files. Replace the local_policy.jar and US_export_policy.jar files in the jre/lib/security folder. For example, if you are using Sun JDK, copy the downloaded files to the [JAVA_HOME]/jre/lib/security folder.

The Assembler service depends on the Reader Extensions service, Signature service, Forms service, and Output service. Perform the following steps to verify that the required services are up and running:

  1. Log in to URL https://'[server]:[port]'/system/console/bundles as an administrator.
  2. Search the following service and ensure that the services are up and running:
Service Name
Bundle Name
Signatures Service
adobe-aemfd-signatures
Reader Extensions Service
com.adobe.aemfd.adobe-aemfd-readerextensions
Forms Service
com.adobe.livecycle.adobe-lc-forms-bedrock-connector
Output Service
com.adobe.livecycle.adobe-lc-forms-bedrock-connector

(Windows only) Configure registry entry for Microsoft® Project configure-registry-entry-for-microsoft-project

After you install AEM Forms add-on and Microsoft® Project on your machine, Register an entry for Microsoft® Project in the 64-bit location. It facilitates the execution of Project to PDFG conversions tests. Following are the steps outlining the process for registry entry:

  1. Open Microsoft® Windows Registry editor (regedit), To open registry editor, go to Start > Run, type regedit, and click OK.
  2. Navigate to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Adobe\Acrobat PDFMaker\<version>\Office\SupportedApp, and create a new Binary Value registry and rename it to Project.
  3. Modify the data value of created Binary registry to 01 and click OK.
  4. Close the registry entry.

Known issues and troubleshooting known-issues-and-troubleshooting

  • The HTML to PDF conversion fails if a zipped input file contains HTML files with double-byte characters in filenames. To avoid this problem, do not use double-byte characters when naming HTML files.

  • On UNIX-based operating systems, do the following to find any missing libraries:

  1. Navigate to [crx-repository]/bedrock/svcnative/HtmlToPdfSvc/bin/.

  2. Run the following command to list all libraries that WebToPDF requires for HTML to PDF conversion.

    ldd phantomjs

    Run the following command to list missing libraries.

    ldd phantomjs | grep not

  3. Manually install the missing libraries.

System Readiness Tool (SRT) SRT

The System Readiness tool checks if the machine is configured properly to run PDF Generator conversions. The tool generates report at the specified path. To run the tool:

  1. Open command prompt. Navigate to the [extracted-adobe-aemfd-pdfg-common-pkg]\jcr_root\libs\fd\pdfg\tools folder.

  2. Run the following command from the command prompt:

    java -jar forms-srt-[version].jar [Path_of_reports_folder] en

    The command generates report and also creates the srt_config.yaml file. You can use it to configure options for SRT tool. It is optional to configure options for SRT tool.

    note note
    NOTE
    • If the System Readiness Tool reports that the pdfgen.api file is not available in the Acrobat plug-ins folder then copy the pdfgen.api file from the [extracted-adobe-aemfd-pdfg-common-pkg]\jcr_root\libs\fd\pdfg\tools\adobe-aemfd-pdfg-utilities-[version]\plugins\x86_win32 directory to the [Acrobat_root]\Acrobat\plug_ins directory.

  3. Navigate to [Path_of_reports_folder]. Open the SystemReadinessTool.html file. Verify the report and fix the mentioned issues.

Configuring options for the SRT tool srt-configuration

You can use the srt_config.yaml file to configure various settings for the SRT tool. The format of the file is:


   # =================================================================
   # SRT Configuration
   # =================================================================
   #Note - follow correct format to avoid parsing failures
   #for example, <param name>:<space><param value>
   #locale: (mandatory field)Locale to be used for SRT. Supported locales [en/fr/de/ja].
   locale: en

   #aemTempDir: AEM Temp direcotry
   aemTempDir:

   #users: provide PDFG converting users list
   #users:
   # - user1
   # - user2
   users:

   #profile: select profile to run specific checks. Choose from [LCM], more will be added soon
   profile:

   #outputDir: directory where output files will be saved
   outputDir:
  • Locale: It is a mandatory parameter. It supports English(en), German (de), French (fr), and Japanese(ja). The default value is en. It has no impact on PDF Generator services running on AEM Forms on OSGi.
  • aemTempDir: It is an optional parameter. It specifies temporary storage location of Adobe Experience Manager.
  • users: It is an optional parameter. You can specify a user to check if the user has required permissions and read/write access on directories required to run PDF Generator. If no user is specified, user-specific checks are skipped and displayed as failed in the report.
  • outputDir: Specify the location to save the SRT report. The default location is the current working directory of SRT tool.

Troubleshooting

If you face issues even after fixing all the problems reported by SRT tool, perform the following checks:

Before performing the following checks, ensure that System Readiness Tool does not report any error.

Adobe Acrobat
  • Ensure only supported version of Microsoft® Office (32-bit) and Adobe Acrobat is installed and opening dialogs are cancelled.
  • Ensure that Adobe Acrobat Update Service is disabled.
  • Ensure that the Acrobat_for_PDFG_Configuration.bat batch file was run with administrator privileges.
  • Ensure a PDF Generator user is added in PDF configuration UI.
  • Ensure that the Replace a process level token permission is added for the PDF Generator user.
  • Ensure the Acrobat PDFMaker Office COM Addin is enabled for Microsoft Office applications.
OpenOffice

Microsoft® Windows

  • Ensure that 32-bit supported versionof Microsoft Office is installed and opening dialogs are cancelled for all applications.

  • Ensure a PDF Generator user is added in PDF configuration UI.

  • Ensure the PDF Generator user is a member of administrators group and the Replace a process level token privilege is set for the user.

  • Ensure that the user is configured in PDF Generator UI and performs the following actions:

    1. Log in to the Microsoft® Windows with PDF Generator user.
    2. Open Microsoft® Office or OpenOffice applications and cancel all dialogs.
    3. Set AdobePDF as default printer.
    4. Set Acrobat as default program for PDF files.
    5. Perform manual conversion using options File > Print and Acrobat ribbon in Microsoft Office applications and cancel all dialogs.
    6. End all the processes related to conversion such as winword.exe, powerpoint.exe, and excel.exe.
    7. Restart the AEM Forms Server.

Linux®

  • Install the supported version of OpenOffice. AEM Forms supports both 32-bit and 64-bit versions. After installing, open all the OpenOffice applications, cancel all the dialog windows, and close the applications. Reopen the applications and ensure that no dialog box is displayed on opening an OpenOffice application.

  • Create an environment variable OpenOffice_PATH and set it to point it to OpenOffice installation is set in the console or the dt (Device Tree) profile.

  • If there are issues in installing OpenOffice, ensure that 32-bit libraries required for OpenOffice installation are available.

HTML to PDF conversion issues
  • Ensure that fonts directories are added in PDF Generator config UI.

Linux and Solaris (WebToPDF conversion route)

  • Ensure that 32-bit library is available (libicudata.so.42) for Webkit based HTMLToPDF conversion and 64-bit (libicudata.so.42 libs are available for WebToPDF based HTMLToPDF conversion.

  • Run the following command to list missing libraries for WebToPDF:

    code language-none 
    
ldd phantomjs | grep not

Linux® and Solaris™ (WebKit conversion route)

  • Ensure that the directories /usr/lib/X11/fonts and /usr/share/fonts exist. If the directories do not exist, create a symbolic link from /usr/share/X11/fonts to /usr/lib/X11/fonts and another symbolic link from /usr/share/fonts to /usr/share/X11/fonts.

    code language-none 
    
ln -s /usr/share/fonts /usr/share/X11/fonts

ln -s /usr/share/X11/fonts /usr/lib/X11/fonts

  • Ensure that IBM fonts are copied under usr/share/fonts.

  • Ensure that ghost vulnerability fix glibc is available on the machine. Use your default package manager to update to the latest version of glibc. It includes ghost vulnerability fix.

  • Ensure that the latest versions of 32-bit lib curl, libcrypto, and libssl libraries are installed on the system. Also create symlinks /usr/lib/libcurl.so (or libcurl.a for AIX®), /usr/lib/libcrypto.so (or libcrypto.a for AIX®) and /usr/lib/libssl.so (or libssl.a for AIX®) pointing to the latest versions (32-bit) of respective libraries.

  • Perform the following steps for IBM® SSL Socket provider:

    1. Copy the java.security file from <WAS_Installed_JAVA>\jre\lib\security to any location on your AEM Forms Server. The default location is Default Location is = <WAS_Installed>\Appserver\java_[version]\jre\lib\security.

    2. Edit the java.security file at the copied location and change the default SSL Socket factories with JSSE2 factories (Use JSSE2 factories instead of WebSphere®).

      Change the following default JSSE socket factories:

      code language-none 
      
#ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
#ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
WebSphere socket factories (in cryptosf.jar)
ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

      with

      code language-none 
      ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
WebSphere socket factories (in cryptosf.jar)
#ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
#ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory
Unable to add a PDF Generator (PDFG) user
  • Ensure Microsoft® Visual C++ 2012 x86 and Microsoft® Visual C++ 2013 x86 (32-bit) redistributable are installed on Windows.
Automation test failures

  • For Microsoft® Office and OpenOffice, perform at least one conversion manually (as each user) to ensure that no dialogue pops up during conversion. If any dialogue appears, dismissed it. No such dialogue should appear during automated conversion.

  • Before running automation on an AEM Forms on OSGi environment, ensure that the test package is installed and active.

Multiple user conversion failures

  • Verify the server logs to check if the conversion is failing for a particular user.(Process Explorer can help you check running process for different users)

  • Ensure that the user configured for PDF Generator has local admin rights.

  • Ensure that PDF Generator user has read, write, and execute permissions on LC temp and PDFG temp users.

  • For Microsoft® Office and OpenOffice, perform at least one conversion manually (as each user) to ensure that no dialogue pops up during conversion. If any dialogue appears, dismissed it. No such dialogue should appear during automated conversion.

  • Perform a sample conversion.

License of Adobe Acrobat installed on AEM Forms Server expires

  • If you have an existing license of Adobe Acrobat and it has expired, Download the latest version of Adobe Application Manager, and migrating your serial number. Before migrating your serial number.

    • Use the following commands to generate prov.xml and reserialize the existing install using the prov.xml file instead of commands provided in migrating your serial number number article.

      code language-none 
      ```

adobe_prtk --tool=VolumeSerialize --generate --serial=<serialnum> [--leid=<LEID>] [--regsuppress=ss] [--eulasuppress] [--locales=limited list of locales in xx_XX format or ALL>] [--provfile=<Absolute path to prov.xml>]

```

    • Volume serialize the package (Re-serialize the existing install using the prov.xml file and the new serial): Run the following command from the PRTK installation folder as an administrator to serialize and activate the deployed packages on client machines:

      code language-none 
      ```
adobe_prtk --tool=VolumeSerialize --provfile=C:\prov.xml –stream

```

  • For large-scale installations, use the Acrobat Customization Wizard to remove previous versions of Reader and Acrobat. Customize the installer and deploy it to all the machines of your organization.

AEM Forms Server is in an offline or secure environment and internet is not available to activate Acrobat.
  • You can go online within 7 days of the first launch of your Adobe product to complete an online activation and registration or use an internet-enabled device and your product’s serial number to complete this process. For detailed instructions, see Offline Activation.
Unable to convert Word or Excel file to PDF on Windows Server

When user tries to convert Word or Excel files to PDF on Microsoft Windows Server, the following error is encountered as:

Error message from the primary converter:
ALC-PDG-015-003-The system cannot open the input file. Submit your file again or contact your system administrator.

To resolve the issue, see Unable to convert Word or Excel file to PDF on Windows Server.

Unable to convert Excel files to PDF on Windows Server 2019

When you convert Microsoft Excel 2019 to PDF on Microsoft Windows Server 2019, you must ensure the following:

  • While using the PDF Generator service, your Windows machine should not have any active remote connection with the AEM server (Windows RDP session).

  • The default printer must be set to Adobe PDF.

    note note
    NOTE
    • For Apple macOS and Ubuntu OS, you are not required to configure the aforementioned settings.
Unable to convert XPS files to PDFs
To resolve the issue, create a feature-specific registry key on Windows.

Next steps next-steps

You have a working AEM Forms document services environment. You can use document services through:

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2