Installing and configuring document services
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 signature service accesses certificates and credentials that are stored in the trust store. For more information, see Signature Service .
- 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.
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 .
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 .
Although AEM Forms allows you to 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.
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:
- Linux : Install Apache OpenOffice
- On Microsoft Windows, PDF Generator supports WebKit, Acrobat WebCapture, and PhantomJS conversion routes to convert HTML files to PDF documents.
- On UNIX-based operating systems, PDF Generator supports WebKit and PhantomJS conversion routes to convert HTML files to PDF documents.
Extra requirements for UNIX-based operating system
If you are using the UNIX-based operating system, install the following packages from the installation media of the respective operating system:
- (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:
- (PDF Generator only) PDF Generator service supports WebKit and PhantomJS routes to convert HTML files to PDF documents. To enable conversion for PhantomJS route, install the below listed 64-bit libraries. Generally, these libraries are already installed. If any library is missing, install it manually:
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
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.
- 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.
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
Set environment variables for 32-bit and 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:
C:\Program Files (x86)\Java\jdk1.8.0_74
C:\Program Files (x86)\Adobe\Acrobat 2015\Acrobat\Acrobat.exe
C:\Program Files (x86)\OpenOffice.org4
- All environment variables and respective paths are case-sensitive.
- JAVA_HOME, JAVA_HOME_32, 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:
(Only for IBM WebSphere) Configure IBM SSL socket provider
Perform the following steps to configure IBM SSL socket provider:
- Create a copy of the java.security file. The default location of the file is [WebSphere_installation_directory]\Appserver\java_[version]\jre\lib\security .
- Open the copied java.security file for editing.
- Change the default SSL socket factories to use the JSSE2 factories instead of default IBM WebSphere factories:Default content:
#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.SSLServerSocketFactoryModified content:
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
- 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 Install Ink and Handwriting service
If you are running Microsoft Windows Server, configure the Ink and Handwriting service. The service is required to open Microsoft PowerPoint files which use inking capabilities of Microsoft Office:
- Open the Server Manager. Click the Server Manager icon on the Quick Launch tray.
- Click Add Features in the Features menu. Select the Ink and Handwriting Services check box.
- Select Features dialog box with Ink and Handwriting Services selected. Click Install and the service is installed.
(Windows Only) 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.
- Open a Microsoft Office application. For example, Microsoft Word. Navigate to File > Options . The options dialog box appears.
- Click Trust Center , and click Trust Center Settings .
- In the Trust Center settings , click File Block Settings .
- 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
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:
- 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 .
- 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.
- Add the user to the Replace a Process Level Token entry.
(Windows Only) 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:
- Create an environment variable, PDFG_NON_ADMIN_ENABLED.
- Set value of the environment variable to TRUE.
- Restart the AEM Forms instance.
(Windows Only) Disable User Account Control (UAC)
- To access the System Configuration Utility, go to Start > Run and then enter MSCONFIG .
- Click the Tools tab and scroll down and select Change UAC Settings . Click Launch to run the command in a new window.
- Adjust the slider to the Never notify level. When finished, close the command window and close the System Configuration window.
- Verify that registry setting for UAC is set to 0 (zero). Perform the following steps to verify:
- Microsoft recommends backing up the registry before you modify it. For detailed steps, see How to back up and restore the registry in Windows .
- Open Microsoft Windows Registry editor. To open registry editor, go to Start > Run, type regedit, and click OK.
- Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system\ . Ensure value of EnableLUA is set to 0 (zero).
- Ensure value of EnableLUA is set to 0 (zero). If the value is not 0, change the value to 0. Close the registry editor.
- Restart your computer.
(Windows Only) 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 needs to 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
The PDF Generator service provides WebKit, WebCapture, and PhantomJS 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.
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
On UNIX-based platforms, the PDF Generator service supports WebKit and PhantomJS 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)
Copy the Unicode font to any of the following directories as appropriate for your system:
- /usr/openwin/lib/X11/fonts/TrueType (Solaris)
- On RedHat 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
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:
- Open Software Distribution . You require an Adobe ID to log in to the Software Distribution.
- Tap Adobe Experience Manager available in the header menu.
- In the Filters section:
- Select Forms from the Solution drop-down list.
- Select the version and type for the package. You can also use the Search Downloads option to filter the results.
- Tap the package name applicable to your operating system, select Accept EULA Terms , and tap Download .
- Open Package Manager and click Upload Package to upload the package.
- Select the package and click Install .You can also download the package via the direct link listed in the AEM Forms releases article.
- 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.
Configure Boot Delegation for RSA/BouncyCastle libraries
- Stop the AEM instance. Navigate to the #\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\ .
- Add the following properties to the sling.properties file:
- (AIX only) Add the following properties to the sling.properties file:
- Save and close the file.
Configuring the font manager service
- Log in to AEM Configuration Manager as an administrator.
- 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 .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 with respect to 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
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 .
- Open the AEM Forms PDF Generator Configuration page.
- 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
- 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
- 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:
|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
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:
- Open Acrobat and select Edit > Preferences > Updater . In Check for updates, deselect Automatically install updates , and click OK . Close Acrobat.
- 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.
- Run the PDF Generator utility batch file to configure Acrobat for the PDF Generator service:
- Open AEM Package Manager and download the adobe-aemfd-pdfg-common-pkg-[version].zip file from the package manager.
- Unzip the downloaded .zip file. Open the command prompt with administrative privileges.
- Navigate to the [extracted-zip-file]\jcr_root\etc\fd\pdfg\tools\adobe-aemfd-pdfg-utilities-[version]-win.zip\scripts directory. Run the following batch file:Acrobat_for_PDFG_Configuration.batAcrobat is configured to run with the PDF Generator service.
- Run System Readiness Tool (SRT) to validate Acrobat installation. The tool checks if the machine is configured properly to run PDF Generator conversions and generates a report at the specified path:
- Open command prompt. Navigate to the [extracted-adobe-aemfd-pdfg-common-pkg]\jcr_root\etc\fd\ pdfg\tools\adobe-aemfd-pdfg-utilities-[version]-win.zip\srt folder. Run the following command from the command prompt:cscript SystemReadinessTool.vbs [Path_of_reports_folder] enIf 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]\plugins\x86_win32 directory to the [Acrobat_root]\Acrobat\plug_ins directory.
- Navigate to [Path_of_reports_folder] . Open the SystemReadinessTool.html file. Verify the report and fix the mentioned issues.
(Windows only) Configure primary route for HTML to PDF conversion
The PDF Generator service provides multiple routes to convert HTML files to PDF documents: Webkit, Acrobat WebCapture (Windows only), and PhantomJS. Adobe recommends using PhantomJS route because it has the capability to handle dynamic content and has no dependencies on 32-bit libraries, 32-bit JDK, or requires no extra fonts. Also, PhantomJS 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:
- On AEM author instance, navigate to Tools > Forms > Configure PDF Generator .
- 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
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:
- Log in to AEM Forms instance as an administrator.
- Go to Tools > Security > Trust Store .
- Click Create TrustStore . Set password and tap Save .
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:
- Log in to AEM Author instance as an administrator. Go to Tools > Security > Users .
- 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.
- 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.
- 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 .
- 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.
- Click Save & Close on the Edit User Settings page.
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:
- Log in to URL https://'[server]:[port]'/system/console/bundles as an administrator.
- Search the following service and ensure that the services are up and running:
|Service Name||Bundle Name|
|Reader Extensions Service||com.adobe.aemfd.adobe-aemfd-readerextensions|
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:
- Navigate to [crx-repository]/bedrock/svcnative/HtmlToPdfSvc/bin/ .
- Run the following command to list all libraries that PhantomJS requires for HTML to PDF conversion.ldd phantomjsRun the following command to list missing libraries.ldd phantomjs | grep not
- Manually install the missing libraries.