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 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

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.

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:

  • Microsoft® Windows: Install Microsoft® Office or Apache OpenOffice
  • Linux®: Install Apache OpenOffice

Extra requirements for UNIX-based operating system

If you are using a UNIX-based operating system, install the following 32-bit 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:

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

• (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:

  • 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

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.

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 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:

(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:

   #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:

   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

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

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.

(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:

1. Create an environment variable, PDFG_NON_ADMIN_ENABLED.
2. Set value of the environment variable to TRUE.
3. Restart the AEM Forms instance.

(Windows Only) 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

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

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.

(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/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™)

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. Tap 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. Tap the package name applicable to your operating system, select Accept EULA Terms, and tap 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

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:

   sling.bootdelegation.class.com.rsa.jsafe.provider.JsafeJCE=com.rsa.*
   

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

   sling.bootdelegation.xerces=org.apache.xerces.*
   

4. Save and close the file.

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

   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

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

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:

(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:

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

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 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:

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

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 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:

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

   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

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:

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 PhantomJS 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)

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

   • 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

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.

Business.Adobe.com resources

Content Insights Managed Cloud Content As A Service Dynamic Media Customer Experience Management Content Management System