bb c Administering LiveCycle ES

bb c Administering LiveCycle ES
bc
Administering LiveCycle® ES
Adobe® LiveCycle® ES
August 2008
Version 8.0
© 2008 Adobe Systems Incorporated. All rights reserved.
Adobe® LiveCycle® ES 8.0 Administering LiveCycle ES for Microsoft® Windows®, Linux®, and UNIX®
Edition 1.4, August 2008
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished
under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part
of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording,
or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected
under copyright law even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a
commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or
inaccuracies that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The
unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to
obtain any permission required from the copyright owner.
Any references to company names, company logos and user names in sample material or sample forms included in this documentation
and/or software are for demonstration purposes only and are not intended to refer to any actual organization or persons.
Adobe, the Adobe logo, Acrobat, LiveCycle, PostScript, and Reader are either registered trademarks or trademarks of Adobe Systems
Incorporated in the United States and/or other countries.
AIX, IBM, and WebSphere are trademarks of International Business Machines Corporation in the United States, other countries, or both.
BEA WebLogic Server is a registered trademark of BEA Systems, Inc.
JBoss and Red Hat are a registered trademarks of Red Hat, Inc. in the United States and other countries.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
Microsoft, Vista, Windows, and Windows Server are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries.
Oracle is a trademark of Oracle Corporation and may be registered in certain jurisdictions.
Sun, Java, and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
UNIX is a trademark in the United States and other countries, licensed exclusively through X/Open Company, Ltd.
All other trademarks are the property of their respective owners.
This product contains either BISAFE and/or TIPEM software by RSA Data Security, Inc.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This product includes code licensed from RSA Data Security.
This product includes software developed by the JDOM Project (http://www.jdom.org/).
Macromedia Flash 8 video is powered by On2 TrueMotion video technology. © 1992-2005 On2 Technologies, Inc. All Rights Reserved.
http://www.on2.com.
This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/).
Portions of this code are licensed from Nellymoser(www.nellymoser.com).
MPEG Layer-3 audio compression technology licensed by Fraunhofer IIS and THOMSON Multimedia (http://www.iis.fhg.de/amm/).
This product includes software developed by L2FProd.com (http://www.L2FProd.com/).
The JBoss library is licensed under the GNU Library General Public LIcense, a copy of which is included with this software.
The BeanShell library is licensed under the GNU Library General Public License, a copy of which is included with this software.
This product includes software developed by The Werken Company.
This product includes software developed by the IronSmith Project (http://www.ironsmith.org/).
The OpenOffice.org library is licensed under the GNU Library General Public License, a copy of which is included with this software.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101,
consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R.
§12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable,
the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users
(a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein.
Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA
95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if
appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of
1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60,
60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Contents
About This Document.................................................................................................................. 7
Who should read this document? ............................................................................................................................................ 7
Conventions used in this document ....................................................................................................................................... 8
Additional information................................................................................................................................................................. 9
1
Introduction ............................................................................................................................... 10
Part I: Post-Deployment Tasks
2
First Tasks................................................................................................................................... 12
Restart the application server..................................................................................................................................................12
Change default password .........................................................................................................................................................12
Set the correct date, time, and time zone ...........................................................................................................................12
Document important configuration information.............................................................................................................12
3
Configuring Sources .................................................................................................................. 13
About sources................................................................................................................................................................................13
Creating an email source...........................................................................................................................................................14
Configuring SSL for an email endpoint..........................................................................................................................14
Troubleshooting SSL for email endpoints ..............................................................................................................15
Creating a watched folder source ..........................................................................................................................................15
Submitting files for processing ...............................................................................................................................................16
4
Configuring SSL ......................................................................................................................... 17
Configuring SSL for JBoss Application Server....................................................................................................................17
Configuring SSL for WebLogic Server...................................................................................................................................20
Creating an SSL Credential .................................................................................................................................................21
Configuring SSL for WebSphere Application Server .......................................................................................................24
Creating a local user account on WebSphere..............................................................................................................24
Creating an SSL Credential .................................................................................................................................................26
Configuring WebSphere to use local OS registry instead of LDAP ......................................................................27
Configuring SSL on WebSphere .......................................................................................................................................27
Configuring WebSphere to convert URLs starting with https...............................................................................29
Configuring SSL on Windows Vista........................................................................................................................................30
5
Understanding Digital Certificates and Credentials............................................................... 31
Certificates and credentials ......................................................................................................................................................31
Configuring User Management with LDAPS................................................................................................................31
Configuring digital certificates for trust management ............................................................................................31
Verifying your certificate .....................................................................................................................................................32
Recognizing valid and expired certificates in PDF documents.............................................................................32
Examining certificates in usage rights-enabled PDF documents.........................................................................32
Examining digital certificates on the LiveCycle ES server .......................................................................................33
Certificate types used by Reader Extensions ES .........................................................................................................33
Certificate “friendly” name ...........................................................................................................................................34
Certificate profiles ...........................................................................................................................................................34
Validity period...................................................................................................................................................................35
Reader Extensions ES usage rights............................................................................................................................35
4
Adobe LiveCycle ES
Administrating LiveCycle ES
Contents
5
Trusted certificates for LiveCycle Rights Management ES ......................................................................................36
Using other certificate viewers .........................................................................................................................................36
6
Using Watched Folders............................................................................................................. 37
How Watched Folder works .....................................................................................................................................................37
Configuring the Watched Folder service.......................................................................................................................39
Watched Folder service attributes.............................................................................................................................39
Watched folder endpoint attributes.........................................................................................................................42
Understanding file patterns.........................................................................................................................................46
Understanding how throttling works ......................................................................................................................47
Performance and scalability...............................................................................................................................................48
Clustering ...........................................................................................................................................................................48
Failure Points and Recovery...............................................................................................................................................51
Recovering unprocessed source files in the stage folder .................................................................................51
Security ......................................................................................................................................................................................52
Tips and tricks..........................................................................................................................................................................52
Service-specific recommendations .................................................................................................................................54
Part II: Maintenance Tasks
7
Maintaining LiveCycle ES .......................................................................................................... 57
LiveCycle Administration Console .........................................................................................................................................57
Accessing LiveCycle Administration Console..............................................................................................................57
Starting and stopping the LiveCycle ES services ..............................................................................................................58
User Management........................................................................................................................................................................59
Accessing User Management ............................................................................................................................................59
Configuring User Management for an SSL-enabled LDAP server ........................................................................59
Configuring User Management for dynamic groups................................................................................................59
User roles and permissions.................................................................................................................................................59
Setting user privileges ...................................................................................................................................................60
Administrator user restrictions .........................................................................................................................................60
LiveCycle PDF Generator ES .....................................................................................................................................................60
Fallback font configurations ..............................................................................................................................................61
Modifying the PDF Export conversion settings ..........................................................................................................61
LiveCycle ES Connector for EMC Documentum................................................................................................................62
Enabling the request for sharing Workspace ES task queues with Workspace ES
Connector for EMC Documentum.............................................................................................................................62
LiveCycle ES Connector for IBM FileNet ...............................................................................................................................62
Enabling the request for sharing Workspace ES task queues with Workspace ES with
Connector for IBM FileNet ............................................................................................................................................62
LiveCycle Workbench ES............................................................................................................................................................63
Configuring assertion validity timeout ..........................................................................................................................63
LiveCycle Business Activity Monitoring ES..........................................................................................................................64
Additional documentation.................................................................................................................................................64
Logs ...................................................................................................................................................................................................65
Viewing the error log............................................................................................................................................................65
Patch maintenance......................................................................................................................................................................65
Uninstalling LiveCycle ES...........................................................................................................................................................65
Backing up and restoring the LiveCycle ES directory structure ..................................................................................66
8
Maintaining the Application Server......................................................................................... 67
Starting and Stopping your application server .................................................................................................................67
Adobe LiveCycle ES
Administrating LiveCycle ES
Contents
6
Starting and stopping WebLogic Server .......................................................................................................................67
Starting and stopping WebSphere Application Server............................................................................................69
Application server websites .....................................................................................................................................................70
Global document storage directory ......................................................................................................................................70
About the global document storage directory...........................................................................................................70
Configuring the global document storage directory .........................................................................................70
Changing the default global document storage location ................................................................................71
Cleaning the global document storage directory......................................................................................................71
About Deployment Files......................................................................................................................................................71
Enhancing application server performance .......................................................................................................................72
Configuring application server data sources...............................................................................................................72
Configuring connection pool settings for WebLogic for Oracle and MySQL ............................................72
Configuring connection pool settings for WebLogic for SQLServer.............................................................73
Configuring connection pool settings for WebSphere for DB2......................................................................73
Configuring connection pool settings for WebSphere for Oracle .................................................................74
Configuring connection pool settings for WebSphere for SqlServer ...........................................................74
Optimizing inline documents and impact on JVM memory ..................................................................................74
WebSphere Application Server enhancements..........................................................................................................76
Increasing the maximum memory allocated to the JVM ..................................................................................76
Windows Server 2003 enhancements............................................................................................................................76
Improving Windows Server performance with LDAP ........................................................................................76
Part III: Troubleshooting LiveCycle ES
9
Troubleshooting ........................................................................................................................ 79
Getting help ...................................................................................................................................................................................79
Installation considerations .................................................................................................................................................79
Application server considerations ...................................................................................................................................80
Performance considerations..............................................................................................................................................80
Bootstrapping considerations...........................................................................................................................................80
Login issues..............................................................................................................................................................................81
Troubleshooting LiveCycle ES with log files.......................................................................................................................82
LiveCycle ES log file...............................................................................................................................................................82
LiveCycle ES log file error messages ...............................................................................................................................82
OutOfMemoryError .........................................................................................................................................................82
404 File not found ...........................................................................................................................................................84
Class not found.................................................................................................................................................................84
JNDI name not found .....................................................................................................................................................85
Troubleshooting your application server............................................................................................................................85
Application server does not start .....................................................................................................................................85
Troubleshooting your application server with log files ...........................................................................................86
JBoss log file ......................................................................................................................................................................86
WebLogic log file .............................................................................................................................................................88
WebSphere log file..........................................................................................................................................................88
Troubleshooting your LiveCycle ES database....................................................................................................................89
IBM DB2 configuration settings ........................................................................................................................................89
Troubleshooting output errors ...............................................................................................................................................90
Some output files are not converted from a watched folder ..........................................................................90
Some output files are lost when a clustered WebSphere Application Server shuts down...................90
Password encryption error...........................................................................................................................................90
About This Document
This document provides administrators with details about the daily, weekly, and monthly administrative
tasks that should be completed to keep the Adobe® LiveCycle® ES (Enterprise Suite) installation running
smoothly. Subject areas covered include database table maintenance, error logging files, system
troubleshooting, and system backup recommendations.
This document does not include installation, configuration, or deployment information; this information is
documented in the Installing and Deploying LiveCycle ES document for your application server or the
Installing and Deploying LiveCycle ES for JBoss Using Turnkey document.
This document does not include information about using the LiveCycle Administration Console to
configure system settings; this information is documented in the LiveCycle Administration Console Help.
Who should read this document?
This guide provides information for IT and Product administrators:
IT administrator: Responsible for IT deployment planning and hardware preparation. Knowledgeable
about application servers, LDAP, database and network administration.
Product administrator: Responsible for installing, monitoring, maintaining, and troubleshooting a
multiservice LiveCycle ES environment. This LiveCycle ES administrator will work with the IT
administrator before installing the LiveCycle ES software into the corporate network.
The information provided is based on the assumption that anyone reading this guide is familiar with J2EE
application servers, Linux, and Microsoft Windows, AIX, or Solaris operating systems, MySQL, Oracle®,
DB2®, or SQL Server database servers, and web environments.
7
Adobe LiveCycle ES
About This Document
Administrating LiveCycle ES
Conventions used in this document
Conventions used in this document
This guide uses the following naming conventions for common file paths.
Name
Default value
Description
[LiveCycleES root]
Windows:
C:\Adobe\LiveCycle8\
The installation directory that is
used for all LiveCycle ES solution
components. The installation
directory contains subdirectories for
LiveCycle Configuration Manager,
the LiveCycle ES SDK, and each
LiveCycle ES solution component
installed (along with the product
documentation). This directory also
includes directories relating to
third-party technologies.
Linux and Solaris:
/opt/adobe/livecycle8/
AIX:
/usr/adobe/livecycle8/
[appserver root]
JBoss on Windows:
C:\jboss
JBoss on Linux:
/opt/jboss
The home directory of the
application server that runs the
LiveCycle ES services.
WebLogic on Windows:
C:\bea\weblogic92\
WebLogic on Linux and Solaris:
/opt/bea/weblogic92
WebLogic on AIX:
/usr/bea/weblogic92
WebSphere on Windows:
C:\Program Files\IBM\WebSphere\AppServer
WebSphere on Linux and Solaris:
/opt/IBM/WebSphere/AppServer
WebSphere on AIX:
/usr/IBM/WebSphere/AppServer
BEA_HOME
[appserverdomain]
WebLogic on Windows C:\bea
WebLogic on Linux and UNIX: /opt/bea
The install directory for WebLogic as
specified for the BEA_HOME
environment variable.
WebLogic on Windows:
C:\bea\user_projects\domains\mydomain
The domain you configured on
WebLogic.
WebLogic on Linux and UNIX:
/opt/bea/user_projects/domains/mydomain
[dbserver root]
Depends on the database type and your
specification during installation.
The location where the LiveCycle ES
database server is installed.
Most of the information about directory locations in this guide is cross-platform (all file names and paths
are case-sensitive on Linux® and UNIX®). Any platform-specific information is indicated as required.
8
Adobe LiveCycle ES
About This Document
Administrating LiveCycle ES
Additional information
Additional information
The resources in this table can help you learn about LiveCycle ES.
For information about
See
General information about LiveCycle ES
and the solution components
LiveCycle ES Overview
What’s new in the Adobe LiveCycle ES
(Enterprise Suite) release
What’s New for LiveCycle ES
LiveCycle ES terminology
LiveCycle ES Glossary
Other services and products that
integrate with LiveCycle ES
www.adobe.com/products/livecycle
Other Adobe LiveCycle ES solution
components
partners.adobe.com/public/developer/main.html
Installing Adobe LiveCycle Workbench ES
Installing Your Development Environment
Upgrading to LiveCycle ES from a
previous version.
Preparing for Upgrading to LiveCycle ES
Upgrading to LiveCycle ES for JBoss
Upgrading to LiveCycle ES for WebSphere
Upgrading to LiveCycle ES for WebLogic
All the documentation available for
LiveCycle ES
www.adobe.com/go/learn_lc_documentation
LiveCycle ES release information and
last-minute changes that occur to the
product
Release Notes
Patch updates, technical notes, and
additional information about this
product version
www.adobe.com/support/products/enterprise/index.html
9
1
Introduction
This document provides information to help you understand the types of maintenance and set-up tasks
that you need to perform to keep your LiveCycle ES environment running at peak performance.
Configuring Sources: Describes the tasks related to configuring sources that are required to generate
PDF files from email or watched folder endpoints.
Understanding Digital Certificates and Credentials: Describes the tasks related to configuring
certificates and credentials required to begin creating secured files.
Maintaining LiveCycle ES: Describes maintenance tasks and configurations required to keep your
LiveCycle ES installation performing smoothly.
Troubleshooting your LiveCycle ES database: Describes maintenance tasks and configurations
required to keep your LiveCycle ES database working properly, as well as optional configurations for
tasks for improving database performance.
Maintaining the Application Server: Describes maintenance tasks and configurations required to
keep your LiveCycle ES application server running efficiently, as well as optional configurations tasks
for improving application server performance.
LiveCycle Business Activity Monitoring ES: Describes maintenance tasks and configurations
required to keep your Adobe LiveCycle Business Activity Monitoring ES environment running
efficiently.
Troubleshooting: Provides a first line of support for troubleshooting possible issues with your
LiveCycle ESS environment. Read the troubleshooting information before you contact Adobe Support.
10
Part I: Post-Deployment Tasks
This section of this document describes the additional configuration tasks that you need to perform after
LiveCycle ES solution components are deployed to the application server and the LiveCycle ES database is
initialized.
11
2
First Tasks
This chapter describes the tasks that an administrator needs to perform after the installation is complete.
Restart the application server
When you first deploy LiveCycle ES, the server is in a deployment mode in which most solution
components are in memory. As a result, the memory consumption is high and the server is not in a typical
production state. You must restart the application server to get the server back into a clean state.
Change default password
LiveCycle ES creates one or more default users during the installation. The password for these users is in
the product documentation and is publicly available. You must change this default password, depending
on your security requirements.
The LiveCycle ES administrator user password is set to “password” by default. You must change it in
LiveCycle Administration Console.
Additionally, you must access User Management, within LiveCycle Administration Console, to change the
default password.
Set the correct date, time, and time zone
Setting the correct date, time, and time zone on the server will ensure that time-dependent solution
components, LiveCycle Digital Signatures ES and LiveCycle Reader Extensions ES, will function correctly.
For example, if a signature appears to have been created in the future, it will not validate.
Document important configuration information
It is recommended that you record the following information and keep it conveniently accessible for
future use. This information will be important for activities such as patching and upgrades:
●
MySQL password you provided during the MySQL section of the turnkey installation
●
MySQL port number you provided during the MySQL section of the turnkey installation
●
Expiry date of the LiveCycle Reader Extensions ES certificate
●
LiveCycle ES serial numbers
12
3
Configuring Sources
This chapter describes the tasks required to configure the LiveCycle ES environment to successfully use
email and watched folder endpoints with Adobe LiveCycle PDF Generator ES:
●
About sources
●
Creating an email source
●
Creating a watched folder source
●
Submitting files for processing
See Archive Administration Help for specific configuration information.
About sources
A source is the origin of a file to be converted. LiveCycle ES can create PDF files from the following sources.
Email
You can configure email accounts to which users can send documents (as email attachments) to be
converted. The email inbox acts as a collecting point for the attachments that LiveCycle ES monitors,
which then invokes the appropriate service as defined by the email endpoint (configured in Archive
Administration). The results of the conversion are forwarded to the user defined in the endpoint.
A separate account can be set up for each type of conversion. For example, one account can be configured
to generate standard PDF documents from incoming file attachments, and another account can be
configured to generate secure PDF documents. Each source must have its own email account.
All email endpoints are configured with an authorized user name and password for the email inbox, which
are required when invoking the service. The email account is protected by the mail server system on which
it is configured.
Watched folders
You can configure LiveCycle ES to periodically scan folders called watched folders for files that are to be
converted. When LiveCycle ES finds a file in the input folder of one of these watched folders, it converts the
file according to the configurations and moves the resulting document to the result folder.
A watched folder can have its own PDF, security, and file type settings that apply to all of the files
processed from that folder.
All watched folder endpoints are configured with an authorized user name and password, which are
required when invoking the service. The watched folder root is protected by the file system on which it
resides so that only the owner can access the watched folder.
13
Adobe LiveCycle ES
Configuring Sources
Administrating LiveCycle ES
Creating an email source
14
Creating an email source
If your users send documents with Western European language characters in file and conversion path
names, they must use an email application that supports the required encoding types (Latin1
[ISO-8859-1], Western European [Windows], or UTF-8). For more information, see the Installing and
Deploying LiveCycle ES document for your application server.
➤ To create or edit an email source:
1. Ensure that you have a POP3 or IMAP mail account specifically and solely for LiveCycle ES. The outgoing
and incoming mail accounts can be on the same host.
2. Configure an email endpoint in Archive Administration for the appropriate process. See “Adding an
endpoint” in Archive Administration Help.
3. In LiveCycle Administration Console, click Services > Archive Administration > Service
Management.
4. Navigate through the list of services to locate your process, and then click to select it.
5. Click the End Points tab, select Email from the list, and then click Add.
6. Set the options on the Add Email Endpoint page and then click Add. (For details, see Archive
Administration Help.)
Configuring SSL for an email endpoint
This section describes how to configure POP3, IMAP, or SMTP to use Secure Sockets Layer (SSL) for an email
endpoint.
➤ To configure SSL for an email endpoint:
1. On the email server, enable SSL for POP3, IMAP, or SMTP according to the manufacturer’s
documentation.
2. Export a client certificate from the email server.
3. Use the keytool program to import the client certificate file to the application server’s Java™ Virtual
Machine (JVM) certificate store. The procedure for this step will depend on the JVM™ and client
installation paths.
For example, if you are using a default BEA WebLogic Server® installation with JDK 1.5.0 on Microsoft®
Windows® Server® 2003, type the following text in a command prompt:
keytool -import -file client_certificate -alias myalias -keystore
BEA_HOME\jdk150_04\jre\security\cacerts
4. When prompted, enter the password (for Java, the default password is changeit). You will receive a
message stating that the certificate was imported successfully.
5. Enable SSL for an endpoint by selecting LiveCycle Administration Console > Archive
Administration. See “Adding an endpoint” in Archive Administration Help.
When configuring the endpoint settings, select POP3/IMAP SSL Enabled for incoming messages and
SMTP SSL Enabled for outgoing messages, and change the port properties accordingly.
Adobe LiveCycle ES
Configuring Sources
Administrating LiveCycle ES
Creating a watched folder source
15
Troubleshooting SSL for email endpoints
If you experience problems when using SSL, use an email client such as Microsoft Outlook to check
whether it can access the email server using SSL. If the email client cannot access the email server, the
issue is related to the configuration of either your certificate or your email server.
Creating a watched folder source
The Add WatchedFolder Endpoint page in Archive Administration allows you to configure an endpoint for
an individual process that polls the folder you create on the file system, transforming it into a watched
folder. You must create and configure a watched folder endpoint for each process that requires one. (See
Archive Administration Help.)
You can create a watched folder in the following two ways:
●
In Archive Administration, on the Add WatchedFolder Endpoint page for the selected process, type the
full path to the parent directory in the Path box and append the name of the watched folder to be
created, as shown in this example:
C:\MyPDFs\MyWatchedFolder
Because the MyWatchedFolder folder does not already exist, LiveCycle ES attempts to create it at that
location.
●
Create a folder on the file system prior to configuring a watched folder endpoint on the Add
WatchedFolder Endpoint page in Archive Administration, and then type the full path in the Path box.
In a clustered environment, the folder that will be used as a watched folder must be accessible, writable,
and shared on the file system or network. In this scenario, each application server instance of the cluster
must have access to the same shared folder.
In Windows, if the application server is running as a service, it must be started with appropriate access to
the shared folder in one of the following ways:
●
Configure the application server service Log On As parameter to start as a specific user with
appropriate access to the shared watched folder.
●
Configure the application server service Start as Local System option to Allow Service to Interact with
the desktop. This option requires that the shared watched folder is accessible and writable to everyone.
You can configure watched folders so that the output of one is the input of another. For example, one
watched folder could convert PDF files to Adobe PostScript® and a second watched folder could convert
the PostScript files to PDF/A format. To do this, simply set the result folder of the watched folder defined by
your first endpoint to point to the input folder of the watched folder defined by your second endpoint.
Output from the first conversion would go to \path\result. Input for the second conversion would be
\path\result, and output from the second conversion would go to \path\result\result (or the directory you
define in the Result Folder box for the second conversion).
Adobe LiveCycle ES
Administrating LiveCycle ES
Configuring Sources
Submitting files for processing
16
➤ To configure the watched folder endpoint:
1. In LiveCycle Administration Console, click Services > Archive Administration > Service
Management.
2. Navigate through the list of services to locate your process, and then click to select it.
3. Click the End Points tab, select WatchedFolder from the list, and then click Add.
4. Set the options on the Add WatchedFolder Endpoint page and then click Add. (See Archive
Administration Help for details.)
Submitting files for processing
For an email endpoint, authorized users can invoke a process by emailing files to the appropriate account.
The results will be returned to the submitting user (by default) or to the user defined in the endpoint
settings.
For a watched folder endpoint, users can invoke by copying or dragging input files or folders from their
desktops to a watched folder. The files will be processed in the order in which they arrive.
For watched folder endpoints, if the job requires only one input file, the user can copy that file to the root
of the watched folder.
If the job contains more than one input file, the user must create a folder outside of the watched folder
hierarchy that contains all required files. This new folder should include the input files (and optionally a
DDX file if required by the process). After the job folder has been constructed, it should be copied into the
watched folder’s input folder.
Caution: Ensure that the application server has deleted access to the files in the watched folder. If
LiveCycle ES cannot delete the files from the input folder after they are scanned, the associated
process will be invoked indefinitely.
When the input is a folder and the output consists of multiple files, LiveCycle ES creates an output folder
with the same name as the input folder and copies the output files into that folder. When the output
consists of a document map containing a key value pair, such as the output from an Adobe
LiveCycle Output ES process, the key will be used as the output file name.
The output file names that result from an endpoint process cannot contain characters other than letters,
numbers, and a period (.) before the file name extension. LiveCycle ES converts other characters to their
hexadecimal values.
4
Configuring SSL
This chapter describes how to create SSL credentials and configure SSL on the application server to
enhance the security of communication with your application server:
●
Configuring SSL for JBoss Application Server
●
Configuring SSL for WebLogic Server
●
Configuring SSL for WebSphere Application Server
●
Configuring SSL on Windows Vista
As a security product, Adobe LiveCycle Rights Management ES requires the configuration of SSL.
The information in this chapter applies to turnkey, automatic, and manual installations. It offers an
example of a method for configuring SSL. You can also use other methods that are more appropriate for
your network or organization.
Note: It is recommended that you complete the installation, configuration, and deployment of your
LiveCycle ES solution components and ensure that the products are running correctly before
configuring SSL on the application server.
Note: When creating SSL security certificates and credentials, you must use the same user account
privileges for which the application server is run. If the application server is run using other user
privileges, the form may not render properly for PDFForm renditions when the ContentRootURI
points to https.
Configuring SSL for JBoss Application Server
To configure SSL on JBoss® Application Server, you need an SSL credential for authentication. You can use
the Java keytool to create a credential or request and import a credential from a certificate authority (CA).
You must then enable SSL on JBoss.
You can run keytool by using a single command that includes all of the information needed to create the
keystore.
➤ To create an SSL credential:
1. In a command prompt, navigate to [JAVA HOME]/bin and type the following command to create the
credential and keystore:
keytool -genkey -dname "CN=Host Name, OU=Group Name, O=Company Name,
L=City Name, S=State, C=Country Code" -alias "LC Cert"
-keypass key_password -keystore keystorename.keystore
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace the
text in bold with values that correspond with your environment. The Host Name should be the
fully qualified domain name of the application server.
2. Enter the key_password when prompted for a password. Re-enter the same password again when
prompted
17
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring SSL for JBoss Application Server
18
3. Copy the keystorename.keystore to the [appserver root] conf directory by typing the following
command:
●
(Windows) copy keystorename.keystore [appserver root]\server\all\conf
●
(Linux) cp keystorename.keystore [appserver root]/server/all/conf
4. Export the certificate file by typing the following command:
keytool -export -alias "LC Cert" -file LC_cert.cer -keystore
[appserver root]\server\all\conf\keystorename.keystore
5. Enter the key_password that you entered in step 2 when prompted for a password.
6. Copy the LC_cert.cer file to the [appserver root] conf directory by typing the following command:
●
(Windows) copy LC_cert.cer [appserver root]\server\all\conf
●
(Linux) cp LC_cert.cer [appserver root]/server/all/conf
7. View the contents of the certificate by typing the following command:
keytool -printcert -v -file [appserver root]\server\all\conf\LC_cert.cer
8. To provide write access to the cacerts file in [JAVA_HOME]\jre\lib\security, if required, perform the
following task:
●
(Windows) Right-click the cacerts file and select Properties, and then deselect the Read-only
attribute.
●
(Linux) Type chmod 777 cacerts
9. Import the certificate by typing the following command:
keytool -import -file LC_cert.cer -keystore
[JAVA_HOME]\jre\lib\security\cacerts
10. Type changeit as the password. This is the default password for a Java installation and may have been
changed by the system administrator.
11. When prompted for Trust this certificate? [no]:, type yes. The confirmation “Certificate
was added to keystore” is displayed.
12. If you are connecting over SSL from Workbench ES, you must install the certificate on the
Workbench ES server.
13. In a text editor, open the server.xml file from the [appserver root]/server/all/deploy/
jbossweb-tomcat50.sar directory, and then uncomment the following section:
<!-- SSL/TLS Connector configuration using the SSL domain keystore
<Connector port="8443" address="${jboss.bind.address}"
maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
scheme="https" secure="true" clientAuth="false"
keystoreFile="${jboss.server.home.dir}/conf/keystorename.keystore"
keystorePass="key_password" sslProtocol = "TLS" URIEncoding="UTF-8"/>
-->
14. Change the value for the keystoreFile attribute and the keystorePass attribute to the keystore
password that you specified when you created the keystore (shown in the example above).
15. Save the server.xml file.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring SSL for JBoss Application Server
19
16. Restart the application server:
●
●
For turnkey installations:
●
From the Windows Control Panel, click Administrative Tools, and then click Services.
●
Select JBoss for Adobe LiveCycle v8.0.
●
Select Action > Stop.
●
Wait for the status of the service to appear as stopped.
●
Select Action > Start.
For Adobe preconfigured or manually configured JBoss installations:
●
From a command prompt, navigate to [appserver root]/bin.
●
Stop the server by entering the following command:
●
(Windows) shutdown.bat -S
●
(Linux) ./shutdown.sh -S
●
Wait until the JBoss process has fully shut down (when the JBoss process returns control to the
terminal it was started in).
●
Start the server by entering the following command:
●
(Windows) run.bat -c all
●
(Linux) ./run.sh -c all
17. To access LiveCycle Administration Console using SSL, type the following URL in a web browser:
https://[host name]:[port]/adminui
18. The default SSL port for JBoss is 8443. From this point on, you need to specify this port when accessing
LiveCycle ES.
➤ To request a credential from a CA:
1. In a command prompt, navigate to [JAVA HOME]/bin and type the following command to generate a
certificate request to send to the certificate authority:
keytool -certreq -alias "LC Cert" -keystore keystorename.keystore -file
LCcertRequest.csr
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace the
text in bold with values that correspond with your environment.
2. After your request for a certificate file has been fulfilled, complete the next section.
➤ To use a credential obtained from a CA:
1. In a command prompt, navigate to [JAVA HOME]/bin and type the following command to import the
credential into the keystore:
keytool -import -file CACertificateName.cer
-keystore keystorename.keystore
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace the
text in bold with values that correspond with your environment.
Note: The imported CA signed certificate will replace a self-signed public certificate if it exists.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring SSL for WebLogic Server
20
2. Copy the keystorename.keystore to the [appserver root] conf directory by typing the following command:
●
(Windows) copy keystorename.keystore [appserver root]\server\all\conf
●
(Linux) cp keystorename.keystore [appserver root]/server/all/conf
3. Export the certificate file by typing the following command:
keytool -export -alias "LC Cert" -file CACertificateName.cer
-keystore [appserver root]\server\all\conf\keystorename.keystore
4. Copy the CACertificateName.cer file to the [appserver root] conf directory by typing the following
command:
●
(Windows) copy CACertificateName.cer [appserver root]\server\all\conf
●
(Linux) cp CACertificateName.cer [appserver root]/server/all/conf
5. View the contents of the certificate by typing the following command:
keytool -printcert -v
-file [appserver root]\server\all\conf\CACertificateName.cer
6. To provide write access to the cacerts file in [JAVA_HOME]\jre\lib\security, if required, perform the
following task:
●
(Windows) Right-click the cacerts file and select Properties, and then deselect the Read-only
attribute.
●
(Linux) Type chmod 777 cacerts
7. Import the certificate by typing the following command:
keytool -import -file CACertificateName.cer
-keystore [JAVA_HOME]\jre\lib\security\cacerts
8. Type changeit as the password. This password is the default for a Java installation and may have been
changed by the system administrator.
9. When prompted for Trust this certificate? [no]:, type yes. The confirmation “Certificate
was added to keystore” is displayed.
10. Complete steps 13 - 18 of “To create an SSL credential:” on page 17.
Configuring SSL for WebLogic Server
To configure SSL on WebLogic Server, you need an SSL credential for authentication. You can use the IBM®
Key Management tool that is installed with Java keytool to perform the following tasks to create a credential:
●
Create a public/private key pair, wrap the public key in an X.509 v1 self-signed certificate that is stored
as a single-element certificate chain, and then store the certificate chain and the private key in a new
keystore. This is the application server’s Custom Identity keystore.
●
Extract the certificate and insert it into a new keystore. This is the application server’s Custom Trust
keystore.
You will then need to perform configure WebLogic so that it uses the Custom Identity keystore and
Custom Trust keystore that you created, and disable the WebLogic Hostname Verification feature because
the distinguished name used to create the keystore files did not include the name of the computer that
hosts WebLogic.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Creating an SSL Credential
21
Creating an SSL Credential
The keytool command is typically located in the Java jre/bin directory and must include several options
and option values, which are listed in the following table.
Keytool option
Description
Option value
-alias
The alias of the keystore.
●
Custom Identity keystore:
ads-credentials
●
Custom Trust keystore:
bedrock
-keyalg
-keystore
The algorithm to use to
generate the key pair.
RSA
he location and name of the
keystore file.
●
The location can include the
absolute path of the file, or can
be relative to the current
directory of the command
prompt where the keytool
command is entered.
You can use a different algorithm, depending on
your company’s policy.
Custom Identity keystore:
[appserverdomain]/adobe/
[server name]/ads-ssl.jks
●
Custom Trust keystore:
[appserverdomain]/adobe/
[server name]/ads-ca.jks
-file
The location and name of the
certificate file.
ads-ca.cer
-validity
The number of days that the
certificate is considered valid.
3650
The password that protects
the contents of the keystore.
●
Custom Identity keystore: The keystore
password must correspond with the SSL
credential password that was specified for the
Trust Store component of the Administrator UI.
●
Custom Trust keystore: Use the same password
that you used for the Custom Identity keystore.
-storepass
-keypass
The password that protects
the private key of the key pair.
You can use a different value, depending on your
company’s policy.
Use the same password that you used for the
-storepass option. The key password must be at
least six characters in length.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Creating an SSL Credential
Keytool option
Description
Option value
-dname
The distinguished name that
identifies the person who
owns the keystore.
"CN=[User name],OU=[Group Name],
O=[Company Name], L=[City Name],
S=[State or province], C=[Country
Code]"
●
22
[User name] is the identification of the user
who owns the keystore.
●
[Group Name] is the identification of the
corporate group to which the keystore owner
belongs.
●
[Company Name] is your organization’s name.
●
[City Name] is the city in which your
organization is located.
●
[State or province] is the state or
province in which your organization is located.
●
[Country Code] is the two-letter code for
the country in which your organization is
located.
For more information about using the keytool command, see the keytool.html file that is part of your JDK
documentation.
➤ To create the Custom Identity and Trust keystores:
1. From a command prompt, navigate to [appserverdomain]/adobe/[server name].
2. Enter the following command:
[JAVA_HOME]/bin/keytool -genkey -v -alias ads-credentials -keyalg RSA
-keystore "ads-credentials.jks" -validity 3650 -storepass store_password
-keypass key_password -dname "CN=Hostname, OU=Group Name, O=Company Name,
L=City Name, S=State,C=Country Code"
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace the
text in bold with values that correspond with your environment.
The keystore file is created in the [appserverdomain]/adobe/[server name] directory.
3. Extract the certificate from the ads-credentials keystore by entering the following command:
[JAVA_HOME]/bin/keytool -export -v -alias ads-credentials
-file "ads-ca.cer" -keystore "ads-credentials.jks"
-storepass store_password
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace
store_password with the password for the Custom Identity keystore.
The certificate file is created in the [appserverdomain]/adobe/[server name] directory.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Creating an SSL Credential
23
4. Copy the ads-ca.cer file to any host computers that need secure communication with the application
server.
5. Insert the certificate into a new keystore file (the Custom Trust keystore) by entering the following
command:
[JAVA_HOME]/bin/keytool -import -v -noprompt -alias bedrock
-file "ads-ca.cer" -keystore "ads-ca.jks" -storepass store_password
-keypass key_password
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace
store_password and key_password with your own passwords.
The keystore file is created in the [appserverdomain]/adobe/[server] directory.
You need to configure WebLogic so that it uses the Custom Identity keystore and Custom Trust keystore
that you created. You also need to disable the WebLogic Hostname Verification feature because the
distinguished name used to create the keystore files did not include the name of the computer that hosts
WebLogic Server.
➤ To configure WebLogic to use SSL:
1. Start the WebLogic Server Administration Console by typing
http://[host name]:7001/console in the URL line of a web browser.
2. Under Environment, in Domain Configurations, click Servers > [server] > Configuration > General.
3. Under General, in Configuration, ensure that Listen Port Enabled and SSL Listen Port Enabled are
selected.
4. If this server is a Managed Server, change Listen Port to an unused port value (such as 8001) and
SSL Listen Port to an unused port value (such as 8002). On a stand-alone server, the default SSL port is
7002.
5. Under the Change Center, click Lock & Edit to modify selections and values.
6. Under General, in Configuration, select Keystores.
7. Select Custom Identity And Custom Trust in the Keystores list.
8. Under Identity, specify the following values:
Custom Identity Keystore: [appserverdomain]/adobe/[server name]/ads-credentials.jks, where
[appserverdomain] is the actual path and [server name] is the name of the application server.
Custom Identity Keystore Type: JKS
Custom Identity Keystore Passphrase: mypassword
9. Under Trust, specify the following values:
Custom Trust Keystore File Name: [appserverdomain]/adobe/[server]/ads-ca.jks, where
[appserverdomain] is the actual path
Custom Trust Keystore Type: JKS
Custom Trust Keystore Pass Phrase: mypassword
10. Under the Change Center, click Lock & Edit to modify selections and values.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring SSL for WebSphere Application Server
24
11. Under General, in Configuration, select SSL.
12. Select Custom Identity And Custom Trust in the Identity and Trust Locations list.
13. Under Identity, specify the following values:
Private Key Alias: ads-credentials
Passphrase: mypassword
14. Under the Change Center, click Lock & Edit to modify selections and values.
➤ To disable the Hostname Verification feature:
1. Under General, in Configuration, in SSL, click Advanced.
2. Select None in the Hostname Verification list.
If Hostname Verification is not disabled, the Common Name (CN) must contain the server host name.
3. Under the Change Center, click Lock & Edit to modify selections and values.
4. Restart the application server.
Configuring SSL for WebSphere Application Server
This section includes the following steps to configure SSL with your IBM WebSphere® Application Server.
Creating a local user account on WebSphere
For enabling SSL, WebSphere needs access to a user account in the local OS user registry that has
permission to administer the system:
●
(Windows) You must create a new Windows user that is part of the Administrators group and has the
privilege to act as part of the operating system. (See “To create a Windows user for WebSphere:” on
page 25.)
●
(Linux, UNIX) The user can be a root user or another user with root privileges. When you enable SSL on
WebSphere, you use the server identification and password of this user.
➤ To create a Linux or UNIX user for WebSphere:
1. Log in as the root user.
2. Create a new user by entering the following command in a command prompt:
●
(Linux and Sun™ Solaris™) useradd
●
(IBM AIX®) mkuser
3. Set the password of the new user by entering passwd in the command prompt.
4. (Linux and Solaris) For WebSphere Application Server Local OS security registry to work, a shadow
password file must exist. The shadow password file is usually named /etc/shadow and is based on the
/etc/passwd file. If the shadow password file does not exist, an error occurs after enabling global
security and configuring the user registry as Local OS. Create a shadow password file by entering
pwconv (with no parameters) in the command prompt.
Adobe LiveCycle ES
Administrating LiveCycle ES
Configuring SSL
Creating a local user account on WebSphere
25
5. Open the group file from the /etc directory in a text editor.
6. Add the user that you created in step 2 to the root group.
7. Save and close the file.
8. (UNIX with SSL enabled) Start and stop WebSphere as the root user.
➤ To create a Windows user for WebSphere:
1. Log in to Windows using an administrator user account.
2. Select Start > Control Panel > Administrative Tools > Computer Management > Local Users and
Groups.
3. Right-click Users and select New User.
4. Type a user name and password in the appropriate boxes, and type any other information you require
in the remaining boxes.
5. Deselect User must change password at next login, click Create, and then click Close.
6. Click Users, right-click the user that you just created and select Properties.
7. Click the Member Of tab and then click Add.
8. In the Enter the object names to select box, type Administrators, click Check Names to ensure
that the group name is correct, and then click OK.
9. Click OK.
10. Select Start > Control Panel > Administrative Tools > Local Security Policy > Local Policies.
11. Click User Rights Assignment, and then right-click Act as Part of the Operating System and select
Properties.
12. Click Add User or Group.
13. In the Enter the object names to select box, type the name of the user that you created in step 4, click
Check Names to ensure that the name is correct, and then click OK.
14. Click OK to close the Act As Part Of The Operating System Properties dialog box.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Creating an SSL Credential
26
Creating an SSL Credential
To configure SSL on WebSphere, you need an SSL credential for authentication. You can use the IBM Key
Management tool that is installed with WebSphere to perform the following tasks to create a credential:
●
Create a keystore file and use it to store a new self-signed certificate and associated private key.
●
Export the certificate, and then add it to the same keystore as a signer certificate. The same keystore is
used as the key file and the trust file in the WebSphere SSL configuration.
➤ To create an SSL credential:
1. Open a command prompt and navigate to [appserver root]/etc.
2. Run the IBM Key Management tool by entering the following command:
●
(Windows) [appserver root]\bin\ikeyman.bat
●
(Linux, UNIX) [appserver root]/bin/ikeyman.sh
3. Select Key Database File > New and, from Key database type, select JKS.
4. Click Browse and navigate to the [appserver root]/etc directory.
5. In the File Name box, type ads-credentials.jks, click Save, and then click OK.
6. In the Password Prompt window, type a password, and then retype the same password in the
Confirm Password box. This password must match the SSL credential password for the SSL property
that is set in the Trust Store component of the Administrator UI.
7. Click OK.
8. In the menu in the Key Database Content area, select Personal Certificates and then click New
Self-Signed. The Create New Self-Signed Certificate window appears.
9. In the Key Label box, type ads-credentials, and then specify values for Organization,
Organization Unit, Country or Region, and Validity Period.
10. Edit the Common Name value to be the name of the local user account that you created, and then click
OK. (See “Creating a local user account on WebSphere” on page 24.)
11. In the list, select the ads-credentials certificate, and then click Extract Certificate.
12. Under Data type, select Base64-encoded ASCII data, under Certificate file name, type
ads-cert.arm and, under Location, type [appserver root]/etc.
13. Click OK.
14. In the menu in the Key Database Content area, select Signer Certificates, and then click Add.
15. In the Certificate file name box, click Browse, select the ads-cert.arm created in step 12, click Open,
and then click OK.
16. In the Enter a Label dialog box, type ads-credentials-cert and then click OK.
17. Select Key Database File > Exit.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring WebSphere to use local OS registry instead of LDAP
27
Configuring WebSphere to use local OS registry instead of LDAP
If you are not using LDAP, you must configure WebSphere to use the local OS registry.
➤ To configure custom properties:
1. Ensure that WebSphere is running.
2. In WebSphere Administrative Console, navigate to Local OS.
3. In the navigate tree, click Security > Global Security and, under User Registries, select Local OS.
4. Perform the following tasks:
●
In the Server User ID box, type the name of the user account that you created using the
instructions in “Creating a local user account on WebSphere” on page 24.
●
In the Server User Password box, type the user password for the user entered for Server User ID.
5. Click OK and then save your changes.
Configuring SSL on WebSphere
You must enable SSL for the application server.
➤ To enable SSL on WebSphere:
1. In WebSphere Administrative Console, navigate to LTPA and then click Security > Global Security and,
under Authentication, click Authentication Mechanisms > LTPA.
2. Perform the following tasks:
●
In the Password box, type the password that you specified when you created the ads-credential.jks
file, as described in “Creating an SSL Credential” on page 26.
●
In the Confirm Password box, type the password again.
●
In the Timeout box, type 10. This is the time (in minutes) after which the LTPA token will expire. This
time must be greater than the Cache Timeout property of WebSphere Global Security. You set the
Cache Timeout property in step 5.
3. Click OK.
4. In the navigation tree, click Security > Global Security.
5. Perform the following tasks:
●
Select Enable Global Security and Issue Permission Warning.
●
Deselect Enforce Java 2 Security, User Domain Qualified IDs (or Use Domain-Qualified IDs).
●
Deselect Enforce Fine-Grained JCA Security (if available).
●
Deselect Use FIPS (or Use the Federal Information Processing Standard (FIPS)).
●
Set Cache Timeout to 600.
●
In the Active Protocol list, select CSI and SAS.
●
In the Active Authentication Mechanisms list, select LTPA (Light weight Third Party
Authentication).
●
In the Active User Registries list, select the user registry you are using.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring SSL on WebSphere
28
6. Click OK. If you are prompted to enter Local OS login information, type the information required as you
did in step 2.
7. In the navigation tree, select Security > SSL.
8. Under SSL Configuration Repertoires, click New (or New JSSE repertoire) and perform the following
tasks:
●
In the Alias box, type AdsSSL.
●
In the Key File Name box, type [appserver root]/etc/ads-credentials.jks.
●
In the Key File Password box, type the password you used when you created the
ads-credentials.jks file (see step 6. on page 26).
●
From Key File Format, select JKS.
●
In the Trust File Name box, type [appserver root]/etc/ads-credentials.jks.
●
In the Trust File Password box, type the password you used when you created the
ads-credentials.jks file (see step 6. on page 26).
●
From Trust File Format, select JKS.
●
If you are configuring the server for LiveCycle PDF Generator, select Client Authentication;
otherwise, ensure that Client Authentication is not selected.
9. Click OK and save the configuration.
10. Navigate to CSIv2 Inbound Authentication and then click Security > Global Security and, under
Authentication, click Authentication Protocol > CSIv2 Inbound Authentication.
11. Set Basic Authentication to Supported and Client Certificate Authentication to Required, and
then click OK.
12. Navigate to CSIv2 Outbound Authentication and then click Security > Global Security and, under
Authentication, click Authentication Protocol > CSIv2 Outbound Authentication.
13. Set Basic Authentication to Supported and Client Certificate Authentication to Required, and
then click OK.
14. Navigate to CSIv2 Inbound Transport and then click Security > Global Security and, under
Authentication, click Authentication Protocol > CSIv2 Inbound Transport.
15. Set Transport to SSL-Required and SSL Settings to localhost/AdsSSL, and then click OK.
16. Navigate to CSIv2 Outbound Transport and then click Security > Global Security and, under
Authentication, click Authentication Protocol > CSIv2 Outbound Transport.
17. Set Transport to SSL-Required and SSL Settings to localhost/AdsSSL, and then click OK.
18. Navigate to SAS Inbound Transport and then click Security > Global Security and, under
Authentication, click Authentication Protocol > SAS Inbound Transport.
19. Set SSL Settings to localhost/AdsSSL, and then click OK.
20. Navigate to SAS Outbound Transport and then click Security > Global Security and, under
Authentication click Authentication Protocol > SAS Outbound Transport.
21. Set SSL Settings to localhost/AdsSSL and then click OK.
22. In the navigation tree, click Servers > Application Servers and click the [server name].
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring WebSphere to convert URLs starting with https
29
23. Under Container Settings, click Web Container Settings > Web container.
24. Under Additional Properties, click Web container transport chains and then click
WCInboundDefaultSecure.
25. Click SSL inbound channel (SSL_2) and select the SSL repertoire as localhost/AdsSSL.
26. Click OK and save your changes to the Master Configuration.
27. Stop and restart WebSphere. WebSphere Administrative Console now displays a login dialog box in
which you are required to type the user name and password that you specified in step 2.
28. (Workspace ES, Process Management ES) In the navigation tree, click Resources > JMS > JMS
Providers and then click Default Messaging.
29. Under Connection Factories, select JMS Queue Connection Factory and then select
QueueConnectionFactory.
30. (Workspace ES, Process Management ES) In the Component-Managed Authentication Alias list,
select [computer name]/myAlias and click OK.
31. (Workspace ES, Process Management ES) Under Related Items, select J2C Authentication Data
Entries, ensure that the database user has root privileges, and then click OK.
32. (Workspace ES, Process Management ES) Save your changes to the Master Configuration.
33. (Workspace ES, Process Management ES) Stop and restart WebSphere.
Configuring WebSphere to convert URLs starting with https
In order to convert a URL starting with https, a Signer certificate for that URL has to be added to the
WebSphere server.
➤ To create a Signer certificate for a https enabled site:
1. Ensure that WebSphere is running.
2. WebSphere Administrative Console, navigate to Signer certificates and then click Security > SSL
certificate and key management > Key stores and certificates > NodeDefaultTrustStore > Signer
certificates.
3. Click Retrieve from port and perform these tasks:
●
In the Host box, type the URL. For example, type www.paypal.com.
●
In the Port box, type 443. This is the default SSL port.
●
In the Alias box, type an alias.
4. Click Retrieve signer information and then verify that the information is retrieved.
5. Click Apply and then click Save.
HTML-to-PDF conversion from the site whose certificate has been added will now work from the Generate
PDF service.
Note: For an application to connect to SSL sites from inside WebSphere, a Signer certificate is required. It is
used by Java Secure Socket Extensions (JSSE) to validate certificates sent by the remote side of the
connection during an SSL handshake.
Adobe LiveCycle ES
Configuring SSL
Administrating LiveCycle ES
Configuring SSL on Windows Vista
30
Configuring SSL on Windows Vista
To configure SSL on Windows Vista™, you need an SSL certificate with RSA keys for authentication. You can
use the Java keytool to create the certificate.
Note: Windows Vista will not work with DSA keys.
You can run keytool by using a single command that includes all of the information needed to create the
certificate and keystore.
➤ To create an SSL certificate:
1. In a command prompt, navigate to [JAVA HOME]/bin and type the following command to create the
certificate and keystore:
keytool -genkey -keyalg RSA -dname "CN=Host Name, OU=Group Name,
O=Company Name, L=City Name, S=State, C=Country Code" -alias "LC Cert"
-keypass key_password -keystore keystorename.keystore
Note: You must replace [JAVA_HOME] with the directory where the JDK is installed, and replace the
text in bold with values that correspond with your environment.
2. Type changeit as the password. This password is the default for a Java installation and it may have
been changed by the system administrator.
5
Understanding Digital Certificates and Credentials
Certificates and credentials
This chapter describes how you can determine and understand the details about the digital certificates
you use to activate LiveCycle Reader Extensions ES, and to determine whether the certificate has expired.
This document describes the following concepts:
●
Configuring User Management with LDAPS
●
Configuring digital certificates for trust management
●
Verifying your certificate
●
Recognizing valid and expired certificates in PDF documents
●
Examining certificates in usage rights-enabled PDF documents
●
Examining digital certificates on the LiveCycle ES server
●
Certificate types used by Reader Extensions ES
●
Trusted certificates for LiveCycle Rights Management ES
●
Using other certificate viewers
For information about creating, storing, and uploading certificates and credentials, see Trust Store
Management Help.
Configuring User Management with LDAPS
For synchronization to work properly over LDAPS, the LDAP CA certificates must be present in the
application server’s Java runtime environment. To do this, you import the certificate into the application
server’s JRE™ cacerts file. (For instructions, see User Management Help.)
Configuring digital certificates for trust management
To ensure proper validation of digital signatures and certificate authentication, you can configure
certificates that you trust using the Trust Store Management web pages within LiveCycle Administration
Console. To configure a certificate, you must import it into Trust Store Management and then modify trust
and policy restrictions of the certificate itself. (For instructions, see Trust Store Management Help.)
On the Update Certificate page in Trust Store Management, you can update trust restrictions by selecting
trust store type options:
Trust for Certificate Authentication: Certificates with this trust type are used by LiveCycle ES for
authenticating users using certificate or smart card authentication.
Trust for SSL Connections: This trust store type specifies that LiveCycle ES can use certificates to
connect to external systems over SSL.
Trust for Signature: This trust store type specifies that certificates are trusted in document-signing
operations for non-author digital signatures.
Trust for Certify Signature: This trust store type specifies that certificates are trusted in
document-signing operations for certifying author digital signatures.
31
Adobe LiveCycle ES
Understanding Digital Certificates and Credentials
Administrating LiveCycle ES
Verifying your certificate
32
Trust for OCSP Server: This trust store type specifies that LiveCycle ES can use certificates to connect
to external OCSP responders.
Trust for Identity: This trust store type specifies that certificates can be used to trust information other
than types specified above.
When configuring a certificate, consider the following options when combining trust store types:
Trust for Certificate Authentication with CA: For CRL validation, also select Trust for Identity.
Trust for Certificate Authentication with ICA: Select only Trust for Identity. An ICA should not be
trusted for Certificate Authentication. If you trust the ICA for Certificate Authentication, the ICA
becomes a CA for path building. If the ICA is trusted for both Certificate Authentication and Identity,
the CA vendor certificate will be ignored because the ICA will become the CA.
Trust for OCSP Server with HTTPs: If the OSCP respondent server resides at an HTTPs location, you
must also select Trust for SSL Connections. If the OSCP respondent requires CRL validation, ensure that
you also select Trust for Identity.
Adobe Root: Do not select SSL Connections or OCSP Server Trust Store Types. Adobe Root is not
trusted for SSL Connections and OCSP Server. Adobe does not issue OCSP and SSL certificates. Adobe
Root is implicitly trusted with an alias name="ADOBEROOT".
Verifying your certificate
After you upload your Reader Extensions ES certificate in Trust Store Management, review the log file to
check for errors because they are not always immediately apparent.
Recognizing valid and expired certificates in PDF documents
When a PDF document that has usage rights applied by Reader Extensions ES is opened in Adobe Reader,
a status bar that describes the specific usage rights enabled in the PDF document appears.
When the digital certificate that specifies the usage rights for a PDF document expires and the PDF
document is opened in Adobe Reader, a dialog box appears advising the user that the PDF document has
usage rights, but these rights are disabled. Although the message indicates that the PDF document has
been altered or tampered with, that is not necessarily the case. Adobe Reader displays this message when
a certificate has expired or a document has been modified. In Adobe Reader 7.0.x or later, you cannot
determine which case is currently the issue.
After you close the dialog box, Adobe Reader opens the PDF document. The usage rights that were
applied using Reader Extensions ES are not available, as expected. If the PDF document is an interactive
form, the form fields are locked and the user cannot make changes to the form data.
Examining certificates in usage rights-enabled PDF documents
You can verify that a Reader Extensions ES certificate has expired by using Adobe Acrobat® Professional.
➤ To determine the expiry date of a Reader Extensions ES digital certificate:
1. Using Acrobat Professional, open the PDF document that has usage rights.
2. Select Advanced > JavaScript > Debugger.
Adobe LiveCycle ES
Understanding Digital Certificates and Credentials
Administrating LiveCycle ES
Examining digital certificates on the LiveCycle ES server
33
3. In the JavaScript Debugger window, select Console from the View list, click in the blank area below the
startup messages and type the following command:
this.appRightsValidate({},2,true);
4. To execute the command, select it and press Ctrl-Enter.
5. On the Summary tab of the Signature Properties dialog box, click Show Certificate.
The Certificate Viewer displays the properties of the digital certificate that was used to provide usage
rights to the PDF document. The General tab contains the basic information about that certificate,
including the expiry date. Because the Valid To date (the expiry date) is in the past, the certificate has
expired and is invalid. The user cannot use the usage rights that were applied to the PDF document.
Examining digital certificates on the LiveCycle ES server
A Reader Extensions ES digital certificate is delivered to the customer in a PFX file, which is accompanied
by a password. You can examine the contents of the PFX file that is installed (or intended for installation) in
a LiveCycle ES server environment using Adobe Reader or Acrobat Professional. You must have the
password for the PFX file and the PFX file must be located in an accessible directory.
➤ To view the details of the digital certificate within the PFX file:
1. Start Adobe Reader or Acrobat Professional.
2. Select Advanced > Security Settings.
3. In the Security Settings dialog box, click Add ID.
4. In the File Open dialog box, navigate to the directory where the PFX file is located and click Open.
5. Type the certificate password and click Next and, in the next dialog box, click Finish. The PFX file is
added to the list as a Digital ID File.
6. In the navigation tree in the Security Settings dialog box, expand Digital ID Files and select the PFX file
that you just added. The certificates contained in the PFX file display in the list on the right. The PFX
files issued by Adobe typically contain one certificate.
If the expiry date occurs in the past, the certificate has expired and is invalid. Users cannot use
documents that usage rights were added to with this certificate, and this certificate cannot be used to
apply usage rights to PDF documents by using Reader Extensions ES.
Tip: To open the Certificate View, click the certificate and click Certificate Details. The next section
describes in more detail the information you see in this window.
Certificate types used by Reader Extensions ES
The Certificate Viewer provides the following information about the certificate:
●
Certificate “friendly” name
●
Certificate profiles
●
Validity period
●
Reader Extensions ES usage rights
Adobe LiveCycle ES
Understanding Digital Certificates and Credentials
Administrating LiveCycle ES
Certificate types used by Reader Extensions ES
34
Certificate “friendly” name
The “friendly” name of a Reader Extensions ES certificate is a string describing the properties of the
certificate, as in the following example:
ARE 2D Barcode Full Production V6.1 P8 0002054
The string contains the following elements:
Certificate type: Describes the LiveCycle ES solution components that the certificate activates, and the
level of activation (for example, ARE 2D Barcode Full). For a list of the certificate types available, see the
Type column in the table in the Certificate Profiles section.
Deployment type: Indicates the intended use of the certificate (for example, Production). The value
can be Evaluation or Production. For a list of deployment types associated with each certificate type,
see the Deployment type column in the table in the Certificate Profiles section.
Usage rights version: Describes the version of the usage rights algorithm that the certificate can be
used for (for example, V6.1). This version does not signify the version of Acrobat or
Reader Extensions ES.
Profile code: The profile code is a shorthand description of complete certificate properties (for
example, P8). For a list of the profile codes associated with each file type, see the Profile code column in
the table in the Certificate Profiles section.
Serial number: A serial number is assigned to each certificate issued by Adobe (for example, 0002054).
Adobe Enterprise Support or an Adobe Enterprise account representative can use this serial number to
trace the certificate to a specific product order or to an OEM relationship.
Certificate profiles
The following table lists the certificate profiles that you may encounter when analyzing
Reader Extensions ES certificates.
Profile code
Type
Validity period
Deployment type
P1
SAP Production
Max
Production
P2
SAP Internal Test
2 years
Evaluation and test
P3
Reader Extensions ES, Production
Max
Production
P4
Reader Extensions ES, Internal Adobe Use
2 years
Production
P5
Reader Extensions ES, Partner Integration
2 years
Evaluation and test
P6
Reader Extensions ES, Evaluation
60 days
Evaluation
P7
LiveCycle Barcoded Forms, Production
Max
Production
P8
LiveCycle Forms and LiveCycle Barcoded
Forms, Production
Max
Production
P9
Adobe Acrobat 7.x, Production
Max
Production
I10
LiveCycle Forms (excluding LiveCycle
Barcoded Forms); may be used by OEMs
Max
Production and
evaluation
I11
LiveCycle Forms and LiveCycle Barcoded
Forms; may be used by OEMs
Max
Production and
evaluation
Adobe LiveCycle ES
Understanding Digital Certificates and Credentials
Administrating LiveCycle ES
Certificate types used by Reader Extensions ES
35
Profile code
Type
Validity period
Deployment type
I12
Signature only; may be used by OEMs
Max
Production and
evaluation
I13
Offline Commenting only; may be used by
OEMs
Max
Production and
evaluation
I14
Commenting only; may be used by OEMs
Max
Production and
evaluation
I15
Full permissions; may be used by OEMs
Max
Production and
evaluation
Validity period
Evaluation certificates are issued to customers and developers so that they can evaluate and develop
sample applications for products. The validity period of these certificates is between 60 and 90 days. They
expire at the end of the second month following the data of issue.
Partner Integration certificates are issued to Adobe business partners to support software development,
integration, prototyping, and demonstration. These certificates are valid for two years from date of issue.
Adobe Internal Use certificates are used within Adobe to support software development, integration,
prototyping and demonstration. These certificates are valid for two years from the date of issue.
Production certificates are issued to customers who have purchased a Reader Extensions ES-based
product (such as Reader Extensions ES or LiveCycle Barcoded Forms ES). These certificates are valid for the
maximum period permitted by the certificate authority (CA), (shown as “Max” in the Certificate Profiles
table). Currently, the expiration date for these certificates is the year 2023.
Reader Extensions ES usage rights
When you examine the Reader Extensions ES certificate in the Certificate Viewer, you can select the usage
rights item from the Details tab (if configured) to see an itemized list of the Adobe Reader usage rights that
can be enabled by the certificate. The usage rights enabled on a particular document may be a subset of
those enabled by the certificate.
The Mode property will match the deployment type and be either “production” or “evaluation”.
The permitted Reader Extensions ES usage rights consist of one or more of specific elements. These
elements are used in different combinations to achieve varieties of licensed product functionality.
Usage rights element
Capability enabled in Adobe Reader
(when viewing a rights-enabled PDF document)
FormFillInAndSave
Fill in form fields and save files locally.
FormImportExport
Import and export form data as FDF, XFDF, XML, and XDP files.
FormAddDelete
Add, change, or delete fields and field properties on the PDF form.
SubmitStandalone
Submit data, by email or offline, to a server when it is not running in a
browser session.
Adobe LiveCycle ES
Understanding Digital Certificates and Credentials
Administrating LiveCycle ES
Trusted certificates for LiveCycle Rights Management ES
36
Usage rights element
Capability enabled in Adobe Reader
(when viewing a rights-enabled PDF document)
SpawnTemplate
Create pages from template pages within the same PDF form.
Signing
Digitally sign and save PDF documents, and clear digital signatures.
AnnotModify
Create and modify document annotations such as comments.
AnnotImportExport
Save annotations such as comments in a separate data file and load
comments from a file.
BarcodePlaintext
Print a document with form data barcoded in an unencrypted form that
does not require licensed server software to decode.
AnnotOnline
Upload and download annotations such as comments to and from an online
document review and comment server.
FormOnline
Connect to web services or databases that are defined within a PDF form.
EFModif
Modify embedded file objects associated with the PDF document.
Note: Reader Extensions ES usage rights can be licensed from Adobe only in certain combinations that
work together. It is not possible to license these capabilities independently. For information about
the available combinations of usage rights, contact an Adobe Enterprise account representative.
Trusted certificates for LiveCycle Rights Management ES
Adobe LiveCycle Rights Management displays credentials, for use in Acrobat, only from trusted issuers.
The Common Name (CN) must be present in the certificate.
Using other certificate viewers
The properties of certificates used for Reader Extensions ES can be inspected using any software that
understands standard digital certificates. However, to obtain the most useful information about digital
certificates, use the Acrobat Professional Certificate Viewer. In a non-Adobe certificate viewer, the specific
Reader Extensions ES usage rights item will not be displayed in detail. For example, in the Microsoft
certificate viewer, this group of properties appears as an encoded value associated with the object
identifier (OID) 1.2.840.113583.1.1.7.130.
6
Using Watched Folders
An administrator can configure a network folder, known as a watched folder, so that when a user places a
file (such as a PDF file) in the watched folder, a configured service operation is invoked that manipulates
the file. After the service performs the specified operation, it saves the modified file in a specified output
folder. A watched folder is configured to be scanned at a fixed rate interval or with a cron schedule, such as
every Monday, Wednesday, and Friday at noon.
Users can drag a file or folder that contains multiple files from their desktop and drop it into an assigned
watched folder, having them processed by the configured service. Similarly, a watched folder can also be
used as an integration mechanism between services and a client application, where invocation requests to
services are initiated by placing a file or a folder into a watched folder. The files will be processed in the
order in which they arrive.
If the job contains more than one input file, the user must create a folder outside of the watched folder
hierarchy containing all required files. This new folder should include the input files (and optionally a DDX
file if required by the process). Once the job folder has been constructed, it should be copied into the
watched folder’s input folder.
When the input is a folder and the output consists of multiple files, LiveCycle ES creates an output folder
with the same name as the input folder and copies the output files into that folder. When the output
consists of a document map containing a key-value pair, such as the output from an
Adobe LiveCycle Output ES process, the key will be used as the output file name.
The output file names that result from an endpoint process cannot contain characters other than letters,
numbers, and a period (.) before the file extension. LiveCycle ES converts other characters to their
hexadecimal values.
Client applications pick up the result documents from the watched folder result folder. Process errors are
logged in the watched folder failure folder.
Watched folders can be chained together so that a result document of one watched folder is the input
document of the next watched folder. Each watched folder can invoke a different service. By configuring
watched folders in this manner, multiple services can be invoked.
How Watched Folder works
Watched Folder is a component that contains these services:
●
Watched Folder service
●
provider.file_scan_service
●
provider.file_write_results_service
In addition to the services listed above, Watched Folder also depends on other services, including the
Scheduler service for scheduling the jobs and the Job Manager service to support asynchronous
invocation of target services.
37
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
How Watched Folder works
38
How Watched Folder processes an invocation request
The Watched Folder service handles the creation, update, and deletion of the endpoints. After the
administrator creates the endpoints, they are scheduled to be triggered by the Scheduler service based on
the specified repeat interval or cron expression. For information about adding end points, see Configuring
the Watched Folder service.
This diagram illustrates how Watched Folder processes an invocation request.
The process of invoking a service using watched folders is as follows:
1. A client application places files or folders in the watched folder input folder.
2. When the job scan interval occurs, the Scheduler service invokes the provider.file_scan_service to
process the files or folders in the input folder.
3. The provider.file_scan_service performs these tasks:
●
Scans the input folder for files or folders that match the include file pattern and excludes files or
folders for the specified exclude file pattern. The oldest files or folders are picked up first. Files and
folders that are older than the wait time are also picked up. In one scan, the number of files or
folders that are processed are based on the batch size. For information about file patterns, see
Understanding file patterns. For information about setting the batch size, see Configuring the
Watched Folder service.
●
Picks up the files or folders for processing. If the files or folders are not completely downloaded, they
are picked up in the next scan. To make sure that folders are completely downloaded,
administrators should create a folder with a name by using the exclude file pattern. After the folder
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
39
has all the files, it must be renamed to the pattern specified in the include file pattern. This step
ensures that the folder has all the necessary files needed for invoking the service. For more
information about ensuring that folders are completely downloaded, see Tips and tricks.
●
Moves the files or folders to the stage folder after selecting them for processing.
●
Converts the files or folders in the stage folder to the appropriate input based on the endpoint
input parameter mappings. For examples of input parameter mappings, see Tips and tricks.
4. The target service configured for the endpoint is invoked either synchronously or asynchronously. The
target service is invoked using the user name and password configured for the endpoint.
a) Synchronous invocation calls the target service directly and immediately handles the response.
b) For asynchronous invocation, the target service is called through the Job Manager service, which
places the request in a queue. The Job Manager Service, in turn, calls the
provider.file_write_results_service to handle the results.
5. The provider.file_write_results_service handles the response or failure of the target service invocation.
When successful, the output is saved to the result folder based on the endpoint configuration. The
provider.file_write_results_service also preserves the source if the endpoint is configured to preserve
the results upon successful completion.
When the invocation of the target service results in a failure, the provider.file_write_results_service logs
the reason for the failure in a failure.log file and places that file in the failure folder. The failure folder is
created based on the configuration parameters specified for the endpoint. When the administrator sets
the Preserve On Failure option for the endpoint configuration, the provider.file_write_results_service
also copies the source files into the failure folder. For information about recovering files from the failure
folder, see Failure Points and Recovery.
Configuring the Watched Folder service
An administrator configures the Watched Folder service using Archive Administration. The Watched Folder
configuration parameters have two purposes:
●
To configure attributes that are common for all the endpoints
●
To provide default values for all the endpoints
After configuring the Watched Folder service, the administrator adds a Watched Folder endpoint for the
target service. When adding the endpoint, the administrator sets values, such as the service name and
operation name to invoke when files or folders are placed in the input folder of the configured
Watched Folder service.
For information about configuring the default values for watched folders, see Watched Folder service
attributes. For information about adding endpoints, see Watched folder endpoint attributes.
Watched Folder service attributes
The Watched Folder service handles the creation, update, and deletion of the endpoints. The configuration
parameters are used as default endpoint values when an administrator creates a new endpoint.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
40
Attribute
Description
Cron Expression
The cron expression as used by Quartz to schedule the polling of the
input directory.
Repeat Count
The number of times the input directory is polled. The default repeat
count to use if this value is not specified in the endpoint
configuration. A value of -1 indicates indefinite scanning of the
directory.
The default value is -1.
Repeat Interval
The number of seconds between each poll. The default repeat
interval in seconds if this value is not specified in the endpoint
configuration.
The default value is 5.
Asynchronous
Identifies the invocation type as asynchronous or synchronous.
Transient and synchronous processes can only be invoked
synchronously.
The default value is asynchronous.
Wait Time
The default value for time in seconds after which the files are picked
up from the input folders. If the file or folder is older than the time
specified in the Wait Time, is picked up for processing.
The default value is 0.
Batch Size
The default value for the number of files or folder that are processed
per scan.
The default value is 2.
Overwrite Duplicate Filenames
A Boolean string that specifies whether the watched folder
overwrites duplicate result file names and whether preserved
documents of the same name should be overwritten.
Preserve Folder
The default value for the preserve folder. This folder is used to copy
the source files in case of successful processing of the input. This
value can be an empty, relative, or absolute path with a file pattern as
described for the Failure Folder attribute in this table.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
Attribute
Description
Failure Folder
The name of the folder where the failure files are copied. This value
can be an empty, relative, or absolute path with the following
pattern:
●
%F = file name prefix
●
%E = file name extension
●
%Y = year (full)
●
%y = year (last two digits)
●
%M = month
●
%D = day of month
●
%d = day of year
●
%H = hour (24-hour clock)
●
%h = hour (12-hour clock)
●
%m = minute
●
%s = second
●
%R = random number (between 0 and 9)
●
%P = process or job id
41
For example, C:/Test/WF0/failure/%Y/%M/%D/%H/ would
result in a path like C:/Test/WF0/failure/2006/08/24/20. The folder
with the source name containing failure.log and source files will be
copied to this directory.
If the path is not absolute but relative, the folder is created inside the
watched folder.
For more information about file patterns, see Understanding file
patterns.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
Attribute
Description
Result Folder
The default name for the result folder. This folder is used to copy the
results files. This can be an empty, relative, or absolute with the
following file pattern:
●
%F = file name prefix
●
%E = file name extension
●
%Y = year (full)
●
%y = year (last two digits)
●
%M = month
●
%D = day of month
●
%d = day of year
●
%H = hour (24-hour clock)
●
%h = hour (12-hour clock)
●
%m = minute
●
%s = second
●
%R = random number (between 0 and 9)
●
%P = process or job id
42
For example, the pattern
C:/Test/WF0/failure/%Y/%M/%D/%H/ creates a folder with
path C:/Test/WF0/failure/2006/08/24/20. The folder with the source
name containing failure.log and source files is copied to this
directory.
If the path is not absolute but relative, the folder is created inside the
watched folder.
For more information about file patterns, see Understanding file
patterns.
Stage Folder
The default name for the stage folder inside the watched folder.
Input Folder
The default name for the input folder inside the watched folder.
Preserve On Failure
If true, original files are preserved in the failure folder on failure.
Throttle
Limits the number of watched folder jobs that can be processed at
any given time. The maximum number of jobs is determined by the
Batch Size value. For more information about throttling, see
Understanding how throttling works.
Watched folder endpoint attributes
The following table details the watched folder endpoint attributes.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
Attribute
Description
Name
This attribute is mandatory. The default value is WatchedFolder
Endpoint.
43
Identifies the endpoint.
Description
A description of the endpoint.
Path
This attribute is mandatory.
Specifies the watched folder location.
In a clustered environment, this attribute must point to a shared
network folder that is accessible from every computer in the cluster.
Asynchronous
Identifies the invocation type as asynchronous or synchronous.
Transient and synchronous processes can only be invoked
synchronously.
The default value is asynchronous. Asynchronous is recommended.
Cron Expression
Enter a cron expression if the watched folder must be scheduled using
a cron expression.
For details about configuring the cron expression, see
http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html.
When this attribute is configured, the Repeat Interval is ignored.
Repeat Interval
The interval in seconds for scanning the watched folder for input.
Unless throttling is enabled, the Repeat Interval should be longer than
the time to process an average job, or the system may become
overloaded.
The default value is 5.
Repeat Count
Number of times Watched Folder scans the folder or directory. A value
of -1 indicates indefinite scanning.
The default value is -1.
Throttle
Limits the number of watched folder jobs that can be processed at any
given time. The maximum number of jobs is determined by the Batch
Size value. For more information about throttling, see Understanding
how throttling works.
User Name
This is a mandatory attribute.
The user name used when invoking a target service from the watched
folder.
The default value is SuperAdmin.
Domain Name
This is a mandatory attribute.
The user’s domain.
The default value is DefaultDom.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
Attribute
Description
Batch Size
The number of files or folders to be picked up per scan. Use this
attribute to prevent an overload on the system; scanning too many
files at one time can result in a crash.
44
The default value is 2.
Wait Time
The time in milliseconds to wait before scanning a folder or file after
creation. For example, if wait time is 36,000,000 milliseconds (one
hour) and the file was created one minute ago, this file will be picked
up after 59 or more minutes have passed.
The default value is 0.
This attribute is useful to ensure that a file or folder is completely
copied to the input folder. For example, if you have a large file to
process and the file takes ten minutes to download, set the wait time
to 10*60 *1000 milliseconds. This setting prevents the watched folder
from scanning the file if it is not ten minutes old.
Exclude File Pattern
The pattern that a watched folder uses to determine which files and
folders to scan and pick up. Any file or folder with this pattern will not
be scanned for processing.
This attribute is useful when the input is a folder with multiple files.
The contents of the folder can be copied into a folder with a name that
will be picked up by the watched folder. This prevents the watched
folder from picking up a folder for processing before the folder is
completely copied into the input folder.
For example, if the Exclude File Pattern is data*, all files and folders that
match data* are not picked up. This includes files and folders named
data1, data2, and so on.
Additionally, the pattern can be supplemented with wildcard patterns
to specify file patterns. The watched folder modifies the regular
expression to support wildcard patterns such as *.* and *.pdf. These
wildcard patterns are not supported by regular expressions.
For more information about file patterns, see Understanding file
patterns.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
Attribute
Description
Include File Pattern
This is a mandatory attribute.
45
The pattern that the watched folder uses to determine which folders
and files to scan and pick up.
For example, if the Include File Pattern is input*, all files and folders
that match input* are picked up. This includes files and folders named
input1, input2, and so on.
The default value is *. This indicates all files and folders.
Additionally, the pattern can be supplemented with wildcard patterns
to specify file patterns. The watched folder modifies the regular
expression to support wildcard patterns such as *.* and *.pdf. These
wildcard patterns are not supported by regular expressions.
For more information about file patterns, see Understanding file
patterns.
Result Folder
The folder where the saved results are stored. This value can be an
absolute or relative directory path. If the results do not appear in this
folder, check the failure folder.
Read-only files are not processed and are saved in the failure folder.
The default value is result/%Y/%M/%D/. This is the Result folder inside
the watched folder. For more information about file patterns, see
Understanding file patterns.
Preserve Folder
The location where files are stored after successful scanning and
pickup. This location can be an absolute, a relative, or a null directory
path.
The default value is preserve/%Y/%M/%D/. For more information
about file patterns, see Understanding file patterns.
Failure Folder
The folder where failure files are saved. This location is always relative
to the watched folder.
Read-only files are not processed and are saved in the failure folder.
The default value is failure/%Y/%M/%D/. For more information, see
Understanding file patterns.
Preserve On Failure
Preserve input files in case of failure to execute the operation on a
service.
The default value is true.
Overwrite Duplicate Filenames When set to True, files in the results folder and preserve folder are
overwritten.
When set to False, files and folders with a numeric index suffix are used
for the name.
The default value is False.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Configuring the Watched Folder service
Attribute
Description
Purge Duration
This is a mandatory attribute.
46
Files and folders in the result folder are purged when they are older
than this value. This value is measured in days. This attribute is useful in
ensuring that the result folder does not become full.
A value of -1 days indicates to never delete the results folder.
The default value is -1.
Operation Name
This is a mandatory attribute.
A list of operations that can be assigned to the watched folder
endpoint.
Input Parameter Mappings
Used to configure the inputs required to process the service and
operation. The two types of inputs are literal and variable.
Literal: The watched folder uses the value entered in the field as it is
displayed. All basic Java types are supported. For example, if an API
uses input such as String, long, int, and Boolean, then the string is
converted to the proper type and the service is invoked.
Variable: The value entered is a file pattern that the watched folder
uses to pick up the input. For example, in the case of the encrypt
password service, where the input document has to be a PDF file, the
user can use *.pdf as the file pattern. The watched folder picks up all
files in the watched folder that match this pattern and invokes the
service for each file. When a variable is used, all input files are
converted to documents. Only operations that use Document as the
input type are supported.
Output Parameter Mappings
Used to configure the outputs of the service and operation. The
following options are available:
Single Object: The pattern is Result\%F.ps and the source destination
is Result\sourcefilename.ps.
List: The pattern is Result\%F\ and the source destination is
Result\sourcefilename\source1 (output 1) and
Result\sourcefilename\source2 (output 2).
Map: The pattern is Result\%F\ and the source destination is
Result\sourcefilename\file1 and Result\sourcefilename\file2. If more
than one object is in the map, the pattern is Result\%F.ps and the
source destination is Result\sourcefilename1.ps (output 1) and
Result\sourcefilenam2.ps (output 2).
Understanding file patterns
Administrators can specify the type of file that can invoke a service. Multiple file patterns can be
established for each watched folder. A file pattern can be one of the following file properties:
●
Files with specific file name extensions; for example, *.dat, *.xml, .pdf, *.*
●
Files with specific names; for example, data.*
●
Files with composite expressions in the name and extension, as in these examples:
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
●
Data[0-9][0-9][0-9].[dD][aA][tT]
●
*.[dD][Aa][Tt]
●
*.[Xx][Mm][Ll]
Configuring the Watched Folder service
47
The administrator can define the file pattern of the output folder in which to store the results. For the
output folders (result, preserve, and failure), the administrator can specify any of these file patterns:
●
%Y = year (full),
●
%y = year (last two digits)
●
%M = month,
●
%D = day of month,
●
%d = day of year,
●
%h = hour,
●
%m = minute,
●
%s = second,
●
%R = random number between 0-9
●
%J = Job name
For example, the path to the result folder may be C:\Adobe\LiveCycle\BarcodedForms\%y\%m\%d.
Output parameter mappings can also specify additional patterns, such as these:
●
%F = Source Filename
●
%E = Source Filename Extension
If the output parameter mapping pattern ends with “File.separator”, (which is the path separator), a folder
is created and the content is copied into that folder. If the pattern does not end with “File.separator”, the
content (result file or folder) is created with that name. For more information about output parameter
mappings, see Tips and tricks.
Understanding how throttling works
Throttling is enabled on a watched folder by selecting the Throttling option on a particular watched folder
endpoint. Throttling limits the number of watched folder jobs that can be processed at any given time. The
maximum number of jobs is determined by the Batch Size value, also configurable in the Watched Folder
endpoint. Incoming documents in the input directory of the watched folder will not be polled when the
throttling limit has been reached. The documents will also remain in the input directory until other
watched folder jobs have completed and another poll attempt is made. In the case of synchronous
processing, all jobs processed in a single poll will count towards the throttling limit, even though the jobs
are processed consecutively in a single thread.
Note: Throttling does not scale with a cluster. When throttling is enabled, the cluster as a whole will not
process more than the number of jobs specified in the Batch Size at any given time. This limit is
cluster-wide, and not specific to each node in the cluster. For example, with a Batch Size of 2, the
throttling limit could be reached with a single node processing two jobs, and no other nodes would
poll the input directory until one of the jobs is completed.
Adobe LiveCycle ES
Administrating LiveCycle ES
Using Watched Folders
Performance and scalability
48
How throttling works
Watched Folder scans the input folder at each Repeat Interval, picks up the number of files specified in the
Batch Size, and invokes the target service for each of these files. For example, if the Batch Size is four, at
each scan, Watched Folder will pick up four files, create four invocation requests, and invoke the target
service. Before these requests are completed, if Watched Folder is invoked, it will again start four jobs
regardless of whether the previous four jobs are completed.
Throttling prevents Watched Folder from invoking new jobs when the previous jobs are not completed.
Watched Folder will detect jobs in progress and process new jobs based on the batch size minus jobs in
progress. For example, in the second invocation, if the number of jobs completed is only three and one job
is still in progress, Watched Folder invokes only three more jobs.
Watched Folder relies on the number of files present in the stage folder to find out how many jobs are in
progress. If files remain unprocessed in the stage folder, Watched Folder will not invoke any more jobs. For
example, if the batch size is four and three jobs are stalled, Watched Folder will invoke only one job in
subsequent invocations. There are multiple scenarios that can cause files to remain unprocessed in the
stage folder:
●
When jobs are stalled, the administrator can terminate the process on the Process Management
administration page so that Watched Folder moves the files out of the stage folder.
●
If the LiveCycle ES server goes down before Watched Folder can invoke the jobs, the administrator can
move the files out of the stage folder. For information, see Failure Points and Recovery.
●
If the LiveCycle ES server is running but Watched Folder is not running when the Job Manager service
calls back, which occurs when services do not start in the ordered sequence, the administrator can
move the files out of the stage folder. For information, see Failure Points and Recovery.
Performance and scalability
Watched Folder can serve 100 folders in total on one single node. The performance of Watched Folder is
dependent on the performance of the LiveCycle ES server. For asynchronous invocation, performance is
more dependent on the system load and jobs that are in the Job Manager queue.
Watched Folder performance can be improved by adding nodes to the cluster. Watched Folder jobs are
distributed across the cluster nodes by virtue of the Quartz scheduler and, in the case of asynchronous
requests, by the Job Manager service. All the jobs are persisted in the database.
Watched Folder depends on the Scheduler service for scheduling, unscheduling, and rescheduling the
jobs. Other services, such as Event Management service, User Manager service, and Email Provider service,
are available that share the Scheduler service thread pool. This can affect Watched Folder performance.
The Scheduler service thread pool tuning will be needed when all the services start using it.
Clustering
In a cluster, Watched Folder depends on the Quartz scheduler and the Job Manager service for load
balancing and failover. For more information about Quartz cluster behavior, see
http://www.opensymphony.com/quartz/wikidocs/ConfigJDBCJobStoreClustering.html.
Watched Folder performs these three main tasks at each poll:
●
Scan the folder
●
Invoke the target service
●
Handle the results
Adobe LiveCycle ES
Administrating LiveCycle ES
Using Watched Folders
Performance and scalability
49
The load balancing and failover behavior changes depending on whether the watched folder is configured
for synchronous or asynchronous invocation.
Synchronous watched folder in a cluster
For synchronous invocations, the Quartz load balancer decides which node will get the polling event. The
node that gets the polling event will perform all the tasks: scan the folder, invoke the target service, and
handle the results.
For synchronous invocations, when one node fails, the Quartz scheduler sends new polling events to other
nodes. Invocations that were started on the failed node will be lost. For more information about how to
recover the files associated with the failed job, see Failure Points and Recovery.
Adobe LiveCycle ES
Administrating LiveCycle ES
Using Watched Folders
Performance and scalability
50
Asynchronous watched folder in a cluster
For asynchronous invocations, the Quartz load balancer decides which node will get the polling event. The
node that gets the polling event will scan the input folder and invoke the target service by placing the
request in the Job Manager service queue. The Job Manager service load balancer, in turn, is responsible
for deciding which node will process the invocation request. It is possible that even though node A
created the invocation request, node B ends up processing the request. Or the node that started the
invocation request may also end up processing the request.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Failure Points and Recovery
51
For asynchronous invocations, when one node fails, the Quartz scheduler sends new polling events to
other nodes. Invocation requests that were created on the failed node will be in the Job Manager service
queue and will be sent to other nodes for processing. Files for which invocation requests are not created
will remain in the stage folder. For more information about how to recover the files associated with the
failed job, see Failure Points and Recovery.
Failure Points and Recovery
At each poll event, Watched Folder locks the input folder, moves the files that match the include file
pattern to the stage folder, and then unlocks the input folder. Locking is needed so that two threads do not
pick up the same set of files and process them twice. The chances of this happening increase with a small
repeat interval and a large batch size. After files are moved to the stage folder, the input folder is unlocked
so that other threads can scan the folder. This step helps provide high throughput because other threads
can scan while one thread is processing the files.
After files are moved to the stage folder, invocation requests are created for each file and the target service
is invoked. There may be cases where Watched Folder cannot recover the files in the stage folder:
●
If the server goes down before Watched Folder can create the invocation request, the files in the stage
folder remain in the stage folder and are not recovered.
●
If Watched Folder has successfully created the invocation request for each of the files in the stage folder
and the server crashes, there are two behaviors based on the invocation type:
Synchronous: If Watched Folder is configured to invoke the service synchronously, all the files in
the stage folder remain unprocessed in the stage folder.
Asynchronous: In this case, Watched Folder relies on the Job Manager service. If the Job Manager
Service calls back Watched Folder, the files in the stage folder are moved to the preserve or failure
folder based on the results of the invocation. If the Job Manager service does not call back
Watched Folder, the files will remain unprocessed in the stage folder. This situation happens when
Watched Folder is not running when the Job Manager calls back.
Recovering unprocessed source files in the stage folder
When Watched Folder cannot process the source files in the stage folder, administrators can recover the
unprocessed files.
➤ To recover unprocessed sources files in the stage folder:
1. Restart the application server or node.
2. (Optional) Stop Watched Folder from processing new input files. If you skip this step, it will be much
harder to determine which files are unprocessed in the stage folder. To prevent Watched Folder from
processing new input files, do one of the following tasks:
●
In Archive Administration, change the Include File Pattern parameter for the watched folder
endpoint to something that will not match any of the new input files (for example, enter NOMATCH).
●
Suspend the process that is creating new input files.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Security
52
Wait until LiveCycle ES recovers and processes all of the files. The majority of the files should be
recovered and any new input files processed correctly. The length of time you wait for Watched Folder
to recover and process the files will depend on the length of the operation to invoke and the number of
files to recover.
3. Determine which files cannot be processed. If you waited an appropriate amount of time and
completed the previous step, and there are still unprocessed files left in the stage folder, go to the next
step.
Note: You can look at the date and time stamp of the files in the stage directory. Depending on the
number of files and normal processing time, you can determine which files are old enough to be
considered stuck.
4. Copy the unprocessed files from the stage directory to the input directory.
5. If you prevented Watched Folder from processing new input files in step 2, change the Include File
Pattern to its previous value or re-enable the process that you disabled.
Security
Each watched folder is configured with a user name and password. These credentials are used when
invoking the services. Watched Folder relies on the fact that the shared folder is protected with the
underlying security file system so that only the owner of the watched folder can access the shared folder.
Tips and tricks
Here are some tips and tricks when configuring the Watched Folder endpoint:
●
To specify cron expressions, go to http://quartz.sourceforge.net/javadoc/org/quartz/CronTrigger.html.
If a cron expression is specified, the repeat interval is ignored.
●
The batch size is the number of files or folders that will be picked up in each scan of the watched folder.
If the batch size is set to two and ten files or folders are dropped in the watched folder input folder, only
two will be picked up in each scan. In the next scan, which will happen after the time specified in the
repeat interval, the next two files will be picked up.
●
For file patterns, administrators can specify regular expressions with added support of wild card
patterns to specify file patterns. Watched Folder modifies the regular expression to support wild card
patterns such as *.* or *.pdf. These wild card patterns are not supported by the regular expressions.
●
Watched Folder scans the input folder for the input and does not know if the source file or folder is
completely copied to the input folder before it starts processing the file or folder. To ensure that the
source file or folder is completely copied to the input folder of the watched folder before the file or
folder is picked up, do these tasks:
●
Use Wait time, which is the time in milliseconds that Watched Folder waits from the last modified
time. Use this feature if you have large files to process. For example, if a file takes 10 minutes to
download, specify the wait time as 10*60 *1000 milliseconds. This will prevent Watched Folder from
picking up the file if it is not as old as 10 minutes.
●
Use exclude file pattern and include file pattern. For example, if the exclude file pattern is ex* and
the include file pattern is in*, Watched Folder will pick up the files that start with “in” and will not
pick up the files that start with “ex”. To copy large files or folders, first rename the file or folder so that
the name starts with “ex”. After the file or folder named “ex” is completely copied to the watched
folder, rename it to “in*”.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Tips and tricks
53
●
Use purge duration to keep the result folder clean. Watched Folder cleans up all the files that are older
than the duration mentioned in the purge duration. The duration is in days.
●
When adding a Watched Folder endpoint, after selecting the operation name, the input parameter
mapping is populated. For each input of the operation, one input parameter mapping field is
generated. Here are examples of input parameter mappings:
●
For com.adobe.idp.Document input: If the service operation has an input of type Document,
the administrator can specify the mapping type as Variable. Watched Folder will pick up the
input from the watched folder’s input folder based on the file pattern specified for the input
parameter. If the administrator specifies *.pdf as the parameter, each file that has an extension of
.pdf will be picked up, converted to com.adobe.idp.Document, and the service invoked.
●
For java.util.Map input: If the service operation has an input of type Map, the administrator can
specify the mapping type as Variable and enter a mapping value with a pattern like *.pdf. For
example, a service needs a map of two com.adobe.idp.Document objects that represent two
files in the input folder such as 1.pdf and 2.pdf. Watched Folder will create a map with the key as the
file name and the value as com.adobe.idp.Document.
●
For java.util.List input: If the service operation has an input of type List, the administrator can
specify the mapping type as Variable and enter a mapping value with a pattern like *.pdf.
When PDF files are dropped in the input folder, Watched Folder will create a list of the
com.adobe.idp.Document objects that represents these files and invoke the target service.
●
For java.lang.String: The administrator has two options. First, the administrator can specify
the mapping type as Literal and enter a mapping value as a string, such as hello.
Watched Folder will invoke the service with the string hello. Second, the administrator can specify
the mapping type as a Variable and enter a mapping value with a pattern like *.txt. In the latter
case, files with the .txt extension will be read as a document coerced as a string to invoke the
service.
●
Java primitive type: The administrator can specify the mapping type as Literal and provide the
value. Watched Folder will invoke the service with the value specified.
●
Watched Folder is meant to work with documents. The supported outputs are
com.adobe.idp.Document, org.w3c.Document, org.w3c.Node, as well as a list and map of
these types. Any other type will result in a failure output in the failure folder.
●
If the results are not in the result folder, verify the failure folder to see if a failure has occurred.
●
Watched Folder works best if used in asynchronous mode. In this mode, Watched Folder places the
invocation request into the queue and calls back. The queue is then processed asynchronously. When
the Asynchronous option is not set, Watched Folder invokes the target service synchronously and the
Process Engine waits until the service is done with the request and results are produced. If the target
service takes a long time to process the request, Watched Folder may get time-out errors.
●
The creation of watched folders for import and export operations does not allow file name extension
abstraction. When invoking the Form Data Integration service using watched folders, the file name
extension type for the output file may not match the intended output format for the document object
type. For example, if the input file to a watched folder that invokes the export operation is an XFA form
that contains data, the output should be an XDP data file. To obtain an output file with the correct file
name extension, you can specify it in the output parameter mapping. In this example, you can use
%F.xdp for the output parameter mapping.
●
Watched Folder may process input files before they are completely copied to the folder. File locking is
not mandatory on UNIX as it is on Windows. For this reason, when a file is being copied to a watched
folder, Watched Folder may move the file to stage without waiting for the file copy to complete. This
behavior causes only a portion of the input file to be processed. There are currently two workarounds:
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
●
Service-specific recommendations
54
Workaround 1
1. Specify a pattern for Exclude File Pattern, such as temp*.ps.
2. Copy files that begin with temp (for example, temp1.ps) to the watched folder.
3. After the file has been completely copied to the watched folder, rename the file to correspond
with the pattern specified for Include File Pattern. Watched Folder then moves the completed file to
stage.
●
Workaround 2
If you know the maximum length of time it will take to copy your files to a watched folder, specify
the time in seconds for Wait Time. Watched Folder then waits the specified length of time before
moving the file to stage.
This is not an issue for files on Windows because Windows locks a file when one thread is writing.
However, this is an issue for folders on Windows. For folders, you must follow the steps in
Workaround 1.
●
If the Preserve Folder Name endpoint attribute for Watched Folder is set to a null directory path, the
staging directory is not cleaned out as it should be. The directory still contains the processed file and
temporary folder.
Service-specific recommendations
This section provides service-specific recommendations when configuring watched folders.
For all services, you should adjust the batch size and repeat interval of the watched folder so that the rate
at which Watched Folder picks up new files and folders for processing does not exceed the rate of the jobs
that can be processed by the LiveCycle ES server. The actual parameters to use may vary depending on
how many watched folders are configured, which services are using watched folders, and how intensive
the jobs are on the processor.
Generate PDF service recommendations
For the Generate PDF service, here are additional recommendations:
●
The Generate PDF service can convert only one file at a time for these file types: Microsoft Word,
Microsoft Excel, Microsoft PowerPoint, Microsoft Project, AutoCAD, Adobe Photoshop®, Adobe
FrameMaker®, and Adobe PageMaker®. These are long running jobs; therefore, make sure you keep the
batch size to a low setting. Also increase the repeat interval if there are more nodes in the cluster.
●
For PostScript (PS), Encapsulated PostScript (EPS), and image file types, the Generate PDF service can
process several files in parallel. You should carefully tune the session bean pool size (which governs the
number of conversions that will be done in parallel) depending on the capacity of your server and the
number of nodes in the cluster. Then increase the batch size to a number that is equal to the session
bean pool size for the file types you are trying to convert. The polling frequency should be dictated by
the number of nodes in the cluster; however, because the Generate PDF service processes these kinds
of jobs quite fast, you could configure the repeat interval to a low value such as 5 or 10.
●
Even though the Generate PDF service can convert only one OpenOffice file at a time, the conversion is
quite fast. The above logic for PS, EPS, and image conversions also applies to OpenOffice conversions.
●
To enable uniform load distribution in the cluster, keep the batch size low and increase the repeat
interval.
Adobe LiveCycle ES
Using Watched Folders
Administrating LiveCycle ES
Service-specific recommendations
55
Barcoded Forms service recommendations
For the Barcoded Forms service, here are additional recommendations:
●
For best performance when processing barcoded forms (small files), enter 10 for Batch Size and 2 for
Repeat Interval.
●
When many files are placed in the input folder, errors with hidden files called thumbs.db may occur. It is
therefore recommended that you set the Include File Pattern for the include files to the same value
specified for the input Variable (for example, *.tiff ). This prevents Watched Folder from processing
the DB files.
●
A Batch Size value of 5 and Repeat Interval of 2 is normally sufficient because the Barcoded Forms
service usually takes about .5 seconds to process one barcode.
●
Watched Folder does not wait for the Process Engine to finish the job before it picks up new files or
folders. It keeps scanning the watched folder and invoking the target service. This behavior can
overload the engine, causing resourcing issues and time-outs. Ensure that you use repeat interval and
batch size to throttle the Watched Folder input. You can increase the repeat interval and reduce the
batch size if more watched folders exist or enable throttling on the endpoint. For information about
throttling, see Understanding how throttling works.
●
Watched Folder impersonates the user specified in the user name and domain name. Watched Folder
invokes the service as this user if invoked directly or if the process is short-lived. For a long-lived
process, the process is invoked with the System context. Administrators can set operating system
policies for Watched Folder to determine which user to allow or deny access to.
●
Use patterns as specified in Understanding file patterns to organize result, failure, and preserve folders.
●
Watched Folder relies on the Quartz scheduler for scanning the watched folders. The Quartz scheduler
has a thread pool to scan them. If the repeat interval for the watched folder is very low (< 5 seconds)
and the batch size is high (> 2), a race condition can occur. When this condition occurs, one file is picked
up by two Quartz threads:
●
One of the threads successfully finds the file and invokes the target service with the file.
●
The second thread sees the file but fails when it tries to find out if the file is valid (read or write file),
which causes false failures that indicate that the file cannot be processed because it is read-only.
This happens only with a low repeat interval and a high batch size.
Part II: Maintenance Tasks
This section of the guide describes the maintenance tasks that you need to perform to keep the
LiveCycle ES environment running at peak performance.
56
7
Maintaining LiveCycle ES
This section describes various tasks required by the IT and product administrators, such as accessing
LiveCycle Administration Console and User Management, starting and stopping the LiveCycle ES services,
and patch maintenance.
●
LiveCycle Administration Console
●
Starting and stopping the LiveCycle ES services
●
User Management
●
LiveCycle PDF Generator ES
●
LiveCycle ES Connector for EMC Documentum
●
LiveCycle ES Connector for IBM FileNet
●
LiveCycle Workbench ES
●
LiveCycle Business Activity Monitoring ES
●
Logs
●
Patch maintenance
●
Uninstalling LiveCycle ES
●
Backing up and restoring the LiveCycle ES directory structure
LiveCycle Administration Console
LiveCycle Administration Console is the web-based portal for accessing a variety of configuration pages
where you can set run-time properties that control the way solution components operate. When you log in
to LiveCycle Administration Console, you can access services, settings, and LiveCycle ES web pages. From
those page, you can access attributes for the activated solution components, Archive Administration,
server settings, User Management, and administrative configuration options for the activated LiveCycle ES
services.
Accessing LiveCycle Administration Console
Before you access LiveCycle Administration Console, the LiveCycle ES service must be deployed and
activated on your application server.
The default user name and password for logging in to LiveCycle Administration Console is administrator
and password. For information about using LiveCycle Administration Console, see LiveCycle Administration
Console Help (available on the Home page of the LiveCycle Administration Console).
38
Adobe LiveCycle ES
Maintaining LiveCycle ES
Administrating LiveCycle ES
Starting and stopping the LiveCycle ES services
58
➤ To access LiveCycle Administration Console:
1. Type the following URL in a web browser:
http://[host name]:[port]/adminui
Default ports are as follows:
●
JBoss: 8080
●
WebLogic: 7001 (Use the same port number that you used when creating new managed server.)
●
Web Sphere: 9080
2. In the User Name field, type administrator and, in the Password field, type password.
3. After logging in, you can click Services to access the LiveCycle ES service component pages or
Settings to access the User Management pages.
After you log in the first time, you can access User Management and change the default administrator
password. Changing these default settings will add security to your LiveCycle ES environment.
Starting and stopping the LiveCycle ES services
This section describes the steps required to start and stop the various LiveCycle ES services.
If you installed LiveCycle ES on JBoss by using the turnkey method, the following services will be available
on your system:
●
JBoss for Adobe LiveCycle ES v8.0
●
MySQL for Adobe LiveCycle ES v8.0
These services are accessible through the Windows Administrative Tools > Services panel. Start or stop
these services by selecting them from the list and then clicking the appropriate action button on the
panel.
A complete implementation of LiveCycle ES will include application server and database services to be
installed:
●
[application server] for Adobe LiveCycle ES v8.0
●
[database] for Adobe LiveCycle ES v8.0
In Windows, these services are accessible through the Administrative Tools > Services panel. On UNIX or
Linux, enter the enter the following text from a command line:
ps -A | grep <service name>
where <service name> is the name of the LiveCycle ES service you are verifying.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining LiveCycle ES
User Management
59
User Management
This section outlines information pertinent to getting your LiveCycle ES environment ready for users.
Accessing User Management
User Management allows administrators to maintain a database for all users and groups that are
synchronized with one or more third-party user directories. User Management provides authentication,
authorization, and user management for your activated LiveCycle ES solution components.
User Management allows you to enable single sign-on (SSO) between LiveCycle ES components and
Netegrity SiteMinder protected applications using Security Assertion Markup Language (SAML). When
SSO is implemented, the LiveCycle ES user login pages are not required and are not displayed if the user
has already been authenticated through their company portal.
For information about using User Management, see User Management Help.
➤ To access User Management:
●
From the Home page within LiveCycle Administration Console, click Settings > User Management.
Note: For information about configuring users, click User Management Help in the upper-right
corner of the User Management page.
Configuring User Management for an SSL-enabled LDAP server
If you have an SSL-enabled LDAP server, you must configure User Management to work with it. (See User
Management Help.)
Configuring User Management for dynamic groups
Dynamic groups define its members using an LDAP search. To identify membership of a dynamic group, a
query is initiated and the results are evaluated. Currently, User Management supports normal, static
groups. To enable a dynamic group, the group must contain an attribute that lists the domain names of all
members within the group. This will enable User Management to successfully synchronize a dynamic
group.
User roles and permissions
Two types of roles are available in LiveCycle ES through User Management:
Mutable roles: This type of role can be edited and deleted, and role permissions can be added and
deleted from these role types. Any role that you create is considered a mutable role. You can add or
remove users and groups assigned to mutable roles.
Immutable roles: The default roles that are included with User Management are immutable roles.
These roles cannot be edited or deleted. You can, however, add or remove users and groups assigned
to immutable roles.
For information about the default roles that are included in the User Management database, see
User Management Help. If Rights Management ES is installed, additional default roles are included. For
details about these roles, see LiveCycle Rights Management ES Help. Both mutable and immutable roles can
also be created through the LiveCycle ES APIs.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining LiveCycle ES
Administrator user restrictions
60
Setting user privileges
You must create an administrator user that has the appropriate privileges for creating users and groups. If
your LiveCycle ES environment includes Rights Management ES, you must also grant the privilege to
manage invited and local users to a user who will be the administrator for these users, by enabling these
privileges as well as including this user in the LiveCycle Administration Console User group (thereby giving
this user access to the LiveCycle Administration Console). These privileges must be configured in
User Management before they can be assigned. See User Management Help and
LiveCycle Rights Management ES Help.
To view users and groups in selected domains during policy user searches, a super administrator or policy
set administrator must select and add domains (created in User Management) to the visible user and
group list for each policy set created.
The visible user and group list is visible to the policy set coordinator and is used to restrict which domains
the end user can browse when choosing users or groups to add to policies. If this task is not performed,
the policy set coordinator will not find any users or groups to add to the policy. There can be more than
one policy set coordinator for any given policy set.
Note: Creating domains must be done before any policies can be created.
➤ To set the visible users and groups:
1. After installing and configuring your LiveCycle ES environment with Rights Management ES, set up all
appropriate domains in User Management.
2. In LiveCycle Administration Console, navigate to Services > LiveCycle Rights Management ES >
Policies and then click the Policy Sets tab.
3. Select Global Policy Set and then click the Visible Users and Groups tab.
4. Click Add Domain(s) and add existing domains as required.
5. Navigate to Services > LiveCycle Rights Management ES > Configuration > My Policies and click
the Visible Users and Groups tab.
6. Click Add Domain(s) and add existing domains as required.
Administrator user restrictions
Users with certain types of administrator privileges cannot access the LiveCycle Rights Management ES
end-user web pages for security reasons. Because these web pages can exist outside a firewall, permitting
administration-level tasks could pose a security risk. Only users who have the LiveCycle Rights
Management End User privileges and do not have Administrator privileges can access the
Rights Management ES end-user web pages.
LiveCycle PDF Generator ES
This section describes optional tasks that can be performed to customize PDF Generator ES for your
LiveCycle ES environment.
Adobe LiveCycle ES
Maintaining LiveCycle ES
Administrating LiveCycle ES
Fallback font configurations
61
Fallback font configurations
This section describes how to manually configure the FontManagerResources.properties file to map the
default LiveCycle ES fonts to fallback (or substitute) if the default fonts are not available on the server. This
property file is located in the adobe-fontmanager.jar file.
Note: Fallback font configuration also applies to the assembler service.
➤ To modify the fallback fonts table:
1. Navigate to the adobe-livecycle-[appserver].ear file in the [LiveCycle root]/configurationManager/
export directory, make a backup copy, and unpackage the original.
2. Locate the adobe-fontmanager.jar file and unpackage it.
3. Locate the FontManagerResources.properties file and open it in a text editor.
4. Modify the Generic and Fallback font locations and names as required and save the file.
The font entries in the FontManagerResources.properties file are relative to the [LiveCycleES root]/fonts
directory. If you specify fonts that are not default LiveCycle ES fonts, you must install those fonts within
this directory structure (either within an existing directory or in a newly created one).
Note: If the specified font or default font does not contain a specific unicode character or if it is
unavailable, the character is taken from a fallback font according to the following priority:
●
Locale-specific font
●
ROOT font if locale not set
●
Generic font, searched by order set in the fallback table
5. Repackage the adobe-fontmanager.jar file.
6. Repackage the adobe-livecycle-[appserver].ear file and then redeploy it either manually or by running
LiveCycle Configuration Manager.
Caution: Do not use LiveCycle Configuration Manager to repackage the adobe-livecycle-[appserver].ear
file because it will overwrite your modifications with the LiveCycle ES default values.
Modifying the PDF Export conversion settings
This section describes how to modify the conversion settings for exporting a PDF an EPS, a DOC, a TXT, an
RTF, an XML, or an HTML file. By default, the PDF file uses the default Save As settings configured in Adobe
Acrobat Professional or Acrobat Standard. For example, the default Save As settings in Acrobat for
converting a PDF file to EPS will result in only one page from the PDF file converted to EPS.
Note: After you modify the Save As setting for one file format, it will apply to all conversions of the same
type when they are exported from PDF Generator ES.
➤ To modify the conversion settings:
1. With the PDF file open in Acrobat, select File > Save As.
2. In the Save as type list, select the appropriate format.
3. Click Settings and set the file format settings as required.
4. Click OK and then click Save to export the PDF file.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining LiveCycle ES
LiveCycle ES Connector for EMC Documentum
62
LiveCycle ES Connector for EMC Documentum
This section describes optional tasks that can be performed to customize
LiveCycle ES Connector for EMC Documentum for your LiveCycle ES environment.
Enabling the request for sharing Workspace ES task queues with
Workspace ES Connector for EMC Documentum
Some manual steps are required to ensure that the Request for Sharing of Task Queue feature in
Workspace ES functions properly with Connector for EMC Documentum:
1. After LiveCycle ES is deployed and Workbench ES is installed, log in to Workbench ES and open the
Resources view. You will determine where the QueueSharing.swf file is located from this view.
2. Drag the QueueSharing.swf file from the Resources View to the Windows desktop or an equivalent
location, depending on your operating system.
3. Log in to LiveCycle Administration Console and click Services > LiveCycle ES Connector for EMC
Documentum > Configuration Settings.
4. Under Repository Service Provider Information, change the configured repository provider to EMC
Documentum Repository Provider.
5. Start Workbench ES and copy the QueueSharing.swf file from the location where you originally copied
it to (for example, the Windows desktop or another location) into an existing directory inside the EMC
Documentum repository.
6. In the Workbench ES Processes view, open the Queue Sharing process.
7. In the Variables view, open the properties of the 'theForm' variable and change the URI to match the
path where you placed the QueueSharing.swf file in step 5.
8. Save the process.
9. Migrate the process to the production environment according to your organization's policy.
LiveCycle ES Connector for IBM FileNet
This section describes optional tasks that can be performed to customize LiveCycle Connector for IBM
FileNet for your LiveCycle ES environment.
Enabling the request for sharing Workspace ES task queues with
Workspace ES with Connector for IBM FileNet
Some manual steps are required to ensure that the Request for Sharing of Task Queue feature in
Workspace ES functions properly with Connector for IBM FileNet:
1. After LiveCycle ES is deployed and Workbench ES is installed, open and log into Workbench ES and go
to the Resources view. You will determine where the QueueSharing.swf file is located from this view.
2. Drag the QueueSharing.swf file to the Windows desktop or an equivalent location, depending on your
operating system.
Adobe LiveCycle ES
Maintaining LiveCycle ES
Administrating LiveCycle ES
LiveCycle Workbench ES
63
3. Log in to LiveCycle Administration Console and click Services > LiveCycle ES
Connector for IBM FileNet.
4. Under Repository Service Provider Information, change the configured repository provider to IBM
FileNet Repository Provider.
5. Open Workbench ES and copy the QueueSharing.swf file from the location where you originally copied
it to (for example, the Windows desktop, or another location depending on your operating system) into
an existing directory inside the IBM FileNet repository.
6. In Workbench ES, use the Processes view to open the Queue Sharing process.
7. On the Variables view, open the properties of the 'theForm' variable and change the URI to match the
path where you placed the QueueSharing.swf in step 5.
8. Save the process.
9. Migrate the process to the production environment according to your organization's policy.
LiveCycle Workbench ES
This section describes optional tasks that can be performed to customize Workbench ES for use with your
LiveCycle ES environment.
Configuring assertion validity timeout
The assertion validity timeout setting determines how often Workbench ES requires a user to
reauthenticate or sign in. The default value is 120 minutes; however, your organization’s security policies
may require more or less frequent reauthentication. You can change this setting to 5 minutes or more.
Reauthentication will occur whether Workbench ES is inactive or not. When the Reauthenticate dialog box
is displayed, the user can enter a password to reauthenticate or click Cancel to exit Workbench ES.
➤ To configure the assertion validity timeout setting:
1. In LiveCycle Administration Console, click Services > User Management > Configuration > Import
and export configuration files.
2. Click Export to produce a config.xml file with the existing LiveCycle ES settings.
3. Open the XML file in an editor and locate the following entry:
<entry key="assertionValidityInMinutes" value="120"/>
4. Change the value to any number greater than 5 (in minutes) and save the file.
5. In LiveCycle Administration Console, navigate to the Import and export configuration files page.
6. Enter the path to the modified config.xml file or click Browse to navigate to it.
7. Click Import to upload the modified config.xml file and then click OK.
Adobe LiveCycle ES
Maintaining LiveCycle ES
Administrating LiveCycle ES
LiveCycle Business Activity Monitoring ES
64
LiveCycle Business Activity Monitoring ES
Note: This section applies only if you have installed LiveCycle Business Activity Monitoring ES.
When a process is activated and immediately invoked, the process instance is not registered on the
corresponding BAM Dashboard. BAM Server requires several seconds after a process is activated before it
can monitor the process for activity. After you activate a process, wait several seconds before invoking it.
If you install BAM Server after LiveCycle ES has run a process, you must populate BAM Dashboard, which
initializes BAM Server to begin polling the LiveCycle ES database. When this process is enabled, the
AdobeView can be created from the information gathered from the LiveCycle ES database. In the case of a
clean LiveCycle ES installation, the database will be empty and no view will be created.
➤ To populate BAM Dashboard:
1. Navigate to Workbench > Application Workbench > Events.
2. Find AdobeEvent in the Events list and restart the event, select disable dependencies and then click
enable all.
3. Repeat step 2 for each additional event (other than AdobeEvent or any event that begins with the
letters “VC”) in the event list. Each event must be stopped and restarted individually.
4. Navigate to Workbench > Application Workbench > Views.
5. Find AdobeView in the Views list and restart the view.
6. Click disable dependencies and then click enable all. There will be a delay while the list of existing
processes is populated.
After BAM Dashboard is populated, you can log in to view the LiveCycle ES processes.
➤ To log in to BAM Dashboard:
1. Type the URL to the dashboard in a web browser. For example, type the following line:
http://[host name]:[BAM port]/celequest/login/dashboard.htm
2. Log in as an administrator. The default administrator account for BAM Server uses the following
login ID:
●
Username: system
●
Password: manager
Additional documentation
For more information about Business Activity Monitoring ES, see these documents:
●
For BAM Dashboard, see Using Business Activity Monitoring ES Dashboard
●
For BAM Server, see Business Activity Monitoring ES Server Reference
●
For BAM Workbench, see Using Business Activity Monitoring ES Workbench
Adobe LiveCycle ES
Maintaining LiveCycle ES
Administrating LiveCycle ES
Logs
65
Logs
Events such as run-time or startup errors are recorded to the application server log files. If you have any
problems deploying to the application server, you can use the log files to help you find the problem. You
can open the log files using any text editor.
(JBoss) The following log files are located in the [appserver root]/server/all/log directory:
●
boot.log
●
server.log.[yyyy-mm-dd]
●
server.log
(WebLogic) Domain log files are located in the [appserverdomain] directory, and server log files are located
in the [appserverdomain]/servers/[appserver name]/logs directory:
●
access.log
●
[appserver name].log
●
[appserver name].out.[incremental number]
(WebSphere) The following log files are located in the [appserver root]/profiles/default/logs/[appserver
name] directory:
●
SystemErr.log
●
SystemOut.log
●
StartServer.log
Viewing the error log
If any errors occur during the installation, the installation program creates a log file called log.txt, which
contains the error messages. The log file is located in the [LiveCycleES root] directory.
For information about errors that may occur during installation, see “Troubleshooting” in the Installing and
Deploying LiveCycle ES guide for your application server.
Patch maintenance
To obtain maintenance patches for your LiveCycle ES installation, go to
www.adobe.com/support/products/enterprise/index.html.
Uninstalling LiveCycle ES
The uninstall program located in the [LiveCycleES root] directory does not remove any files that you
deployed to your application server.
Caution: By running the uninstall program, all of the contents within the product installation directory are
subject to removal without further warning. Before proceeding, back up any data you do not
want to lose.
Adobe LiveCycle ES
Maintaining LiveCycle ES
Administrating LiveCycle ES
Backing up and restoring the LiveCycle ES directory structure
66
➤ To remove the files from your computer:
1. Navigate to the [LivecycleES root]/_uninst/server directory and start the uninstall program:
●
(Windows) Double-click the livecycle8_uninstall.exe file. Alternatively, you can use the Add or
Remove Programs function.
●
(Linux and UNIX) From a command line, type ./livecycle8_uninstall.sh
2. Follow the on-screen instructions in the uninstall program, and then click Finish.
Backing up and restoring the LiveCycle ES directory structure
This section describes which files and folders make up the LiveCycle ES directory structure and where a
backup copy exists in case of accidental loss. Although these files are backed up automatically by the
patch installer prior to applying updates, it is the responsibility of the system administrator to back up
these files on a daily basis.
Prior to restoring files from the backup directory to the LiveCycle ES directory, ensure that LiveCycle ES has
been shut down. See “Starting and stopping the LiveCycle ES services” on page 58. When the files are
restored, run LiveCycle Configuration Manager to reconfigure, redeploy and restart any LiveCycle ES and
application server products.
The LiveCycle ES directory structure is as follows:
[LiveCycleES root]deploy
[LiveCycleES root]licenses
[LiveCycleES root]configurationManager
The backup copy of the LiveCycle ES directory structure is as follows:
[LiveCycleES root]patch\SP1\backup_LCESBackupDeploy
[LiveCycleES root]\patch\SP1\backup_LCESBackupLicenses
[LiveCycleES root]\patch\SP1\backup_LCESBackupLCM
8
Maintaining the Application Server
This section describes the basic application server maintenance tasks required to keep LiveCycle ES
running properly.
●
Starting and Stopping your application server
●
Application server websites
●
Global document storage directory
●
Enhancing application server performance
●
Configuring application server data sources
●
Optimizing inline documents and impact on JVM memory
●
WebSphere Application Server enhancements
●
Windows Server 2003 enhancements
Starting and Stopping your application server
Starting and stopping WebLogic Server
Several procedures in this chapter require you to start and stop the instance of WebLogic Server where
you want to deploy LiveCycle ES components. Ensure that WebLogic Server is stopped or running,
depending on the task you are performing.
Activity
Required WebLogic state
Creating a new WebLogic domain
Stopped
Creating a new WebLogic managed server
Running
Increasing the server thread count
Running
Deploying LiveCycle ES products
Running
Note: If you are running WebLogic Server on Red Hat® Enterprise Linux Advanced Server 4.0, you must set
the LD_ASSUME_KERNEL environment variable to 2.4.19 by using the
export LD_ASSUME_KERNEL=2.4.19 command. You must then run WebLogic Server from the
same shell in which you set this environment variable.
➤ To start WebLogic Server:
1. From a command prompt, navigate to BEA_HOME/user_projects/domains/[appserverdomain].
2. Enter the following command:
●
(Windows) startWebLogic.cmd
●
(Linux, UNIX) ./startWebLogic.sh
67
Adobe LiveCycle ES
Maintaining the Application Server
Administrating LiveCycle ES
Starting and stopping WebLogic Server
68
➤ To stop WebLogic Server:
1. With WebLogic Server running, start WebLogic Server Administration Console by typing
http://[host name]:7001/console in the URL line of a web browser.
2. Type the user name and password that was used when creating this WebLogic configuration, and then
click Log In.
3. Under Change Center, click Lock & Edit.
4. Under Domain Structure, click Environment below your domain name and then click Servers.
5. Click AdminServer and, on the Setting for AdminServer pane, click the Control tab.
6. Ensure that AdminServer is selected in the Server Status table and click Shutdown.
7. Select When work completes to gracefully shut down the server or select Force Shutdown Now to
stop the server immediately without completing ongoing tasks.
8. On the Server Life Cycle Assistant pane, click Yes to complete the shutdown.
The WebLogic Server Administration Console will no longer be available, and the command prompt that
you ran the start command from becomes freed up.
➤ To start WebLogic Admin Server:
1. If WebLogic Admin Server is not already running, from a command prompt, navigate to the
BEA_HOME\user_projects\domains\[domainname] directory, and enter the following command:
●
(Windows) startWebLogic.cmd
●
(Linux, UNIX) ./startWebLogic.sh
2. Access WebLogic Server Administration Console by typing
http://[host name]:[Port]/console in the URL line of a web browser, where [Port] is the
non-secure listening port. By default, this port value is 7001.
3. On the login screen, type your administrator user name and password, and click Login.
➤ To start Node Manager:
1. Ensure that WebLogic Server is running.
2. From a new command prompt, navigate to [appserver root]/server/bin.
3. Enter the following command:
●
(Windows) startNodeManager.cmd
●
(Linux, UNIX) ./startNodeManager.sh
➤ To stop Node Manager:
●
After you shut down WebLogic Server (see “To stop WebLogic Server:” on page 68), you can close the
command prompt from which you called Node Manager.
Adobe LiveCycle ES
Maintaining the Application Server
Administrating LiveCycle ES
Starting and stopping WebSphere Application Server
69
➤ To start a WebLogic Managed Server:
Note: This task can be performed only after you have created a WebLogic domain and a Managed Server.
1. Ensure that the WebLogic Server and Node Manager are running.
2. Start WebLogic Server Administration Console by typing http://[host name]:[port]/console
in the URL line of a web browser.
3. Under Change Center, click Lock & Edit.
4. Under Domain Structure, expand the Environment option below your domain name and then click
Servers.
5. In the right pane, below the Servers label, click the managed server, and then click the Control tab.
6. Click the Start button below the managed server you want to start.
➤ To stop a WebLogic Managed Server:
1. Start WebLogic Server Administration Console by typing http://[host name]:[port]/console
in the URL line of a web browser.
2. From the Domain Configurations, click [domain_name] and then click the Control tab.
3. Click the Shutdown button below the managed server you want to stop and select one of the
following options:
Graceful shutdown of all Managed Servers: Initiates a graceful shutdown of the selected server,
causing the Managed Server to notify its subsystems to complete all in-work requests. A graceful
shutdown gives the WebLogic Server subsystems time to complete certain application processing
currently in progress.
Force shutdown of all Managed Servers: Initiates a forced shut down, causing the Managed
Server to instruct subsystems to immediately drop in-work requests.
4. At the WebLogic Server Administration Console prompt, click Yes to confirm the command.
You can verify that the Managed Server has been shut down by viewing the table at the bottom of the
Control tab. The table displays a list of all of the servers and their current state.
Starting and stopping WebSphere Application Server
Several procedures in this chapter require you to stop and start the instance of WebSphere where you
want to deploy LiveCycle ES products. If you are unsure whether or not the application server has been
started, you can first view the WebSphere Application Server’s status.
➤ To view the status of WebSphere Application Server:
1. From a command prompt, navigate to the [appserver root]/bin directory.
2. Enter the following command, replacing server_name with the name of WebSphere Application
Server:
●
(Windows) serverStatus.bat server_name
●
(Linux, UNIX)./serverStatus.sh server_name
Adobe LiveCycle ES
Maintaining the Application Server
Administrating LiveCycle ES
Application server websites
70
➤ To start WebSphere Application Server:
1. From a command prompt, navigate to the [appserver root]/bin directory.
2. Enter the following command, replacing server_name with the name of the WebSphere Application
Server:
●
(Windows) startServer.bat server_name
●
(Linux, UNIX) ./startServer.sh server_name
➤ To stop WebSphere Application Server:
1. From a command prompt, navigate to the [appserver root]/bin directory.
2. Enter the following command, replacing server_name with the name of the WebSphere Application
Server:
●
(Windows) stopServer.bat server_name
●
(Linux, UNIX) ./stopServer.sh server_name
Application server websites
This section presents links to the manufacturer websites for all supported application servers.
●
JBoss: www.jboss.org/products/jbossas
●
BEA WebLogic: www.bea.com/
●
IBM WebSphere: www-306.ibm.com/software/websphere/
Global document storage directory
This section describes the function of the global document storage directory.
About the global document storage directory
The global document storage (GDS) is a directory used to store long-lived files such as PDF files used within a
process or DSC deployment archives. Long-lived files are a critical part of the overall state of the LiveCycle ES
environment. If some or all long-lived documents are lost or corrupted, the LiveCycle ES server may become
unstable. Therefore, it is important that the GDS is stored on the redundant array of independent disks (RAID).
The long-lived files may contain sensitive user information (that is, the information that may require
special credentials when accessed using the LiveCycle ES APIs or user interfaces). It is important that the
GDS is properly secured through the operating system and that only the administrator account used to
run the application server has read/write access to this directory.
Configuring the global document storage directory
The location of the GDS can be configured manually during the LiveCycle ES installation process. If you
leave the location setting empty during installation, the location defaults to a directory under the
application server installation as follows:
●
(JBoss) [appserver root]/server/<server>/svcnative/DocumentStorage
●
(WebLogic) [appserverdomain]/<server>/adobe/LiveCycleServer/DocumentStorage
●
(WebSphere) [appserver root]/installedApps/adobe/<server>/DocumentStorage
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining the Application Server
Cleaning the global document storage directory
71
Changing the default global document storage location
You can change the GDS location in the LiveCycle Administration Console after the LiveCycle ES
installation is complete. You will need to manually relocate the data to complete the process.
Caution: You must migrate the data in the following manner or data loss will occur.
➤ To change the default GDS location:
1. Log in to LiveCycle Administration Console and click Settings > Core System Settings >
Configurations.
2. In the Global document storage directory box, enter the full path to the new GDS directory and then
click OK.
3. Immediately shut down the application server.
4. Move all the files from the old GDS directory to the new location, keeping the internal directory
structure.
5. Restart the application server.
Cleaning the global document storage directory
When a process is executed, temporary files are placed in the GDS directory, but are not deleted when the
process is complete. These files are placed under subdirectories with the name, Session[NNNN], where
NNNN is the process ID. To prevent running out of disk space, you must regularly remove the Session
directories for processes that are not running.
Note: To determine if a process is complete, log in to LiveCycle Administration Console and go to Home >
Services > Process Management ES > Process Search. You can filter the search to return
processes with the status COMPLETE.
If the GDS is not set explicitly in LiveCycle Configuration Manager, the default location of the GDS
directory is [TempDir]/AdobeDocumentStorage/global. If [TempDir] is also not specified by the user in
LiveCycle Configuration Manager, the default location is java.io.tmpdir.
About Deployment Files
LiveCycle ES is made up of two types of deployment files, the service containers and the Java 2 Platform,
Enterprise Edition (J2EE) Enterprise Archive (EAR) files. The EAR files consist of standard J2EE application
bundles that contain the core functionality of LiveCycle ES. The application server specific EARs files are as
follows:
●
adobe-core-[appserver].ear
●
adobe-core-[appserver]-[OS].ear
Implementation of LiveCycle ES involves deploying the assembled EAR files and supporting files to the
application server on which you plan to run your LiveCycle ES solution. If you have configured and
assembled multiple solution components, the deployable components are packaged within the
deployable EAR files. To deploy these files, copy them to the [appserver home]\server\all\deploy directory.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining the Application Server
Enhancing application server performance
72
Components and LiveCycle ES archive files are packaged in JAR files. Because they are not J2EE type files,
they are not deployed to the application server. Instead, they are copied into the GDS directory, and a
reference to their location is stored in the LiveCycle ES database.
Note: Prior to deploying the service containers, ensure that you have created and configured the GDS.
(See “Configuring the global document storage directory” on page 70.)
Enhancing application server performance
This section describes optional settings you can configure to improve the performance of your
LiveCycle ES application server.
Configuring application server data sources
LiveCycle ES uses two data sources, the LiveCycle ES repository and the optional
Business Activity Monitoring ES metadata database. The LiveCycle ES repository stores application assets
and, at run time, services can retrieve assets from the repository as part of completing an automated
business process. The Business Activity Monitoring ES metadata database is used to store the definitions
of the process metrics that the BAM Server monitors, as well as the details of any alerts and object run-time
data that need to be persisted to disk.
Access to these data sources can be significant, depending on the number of LiveCycle ES components
you are running and the number of concurrent users accessing the application. Data source access can be
optimized with connection pooling. Connection pooling is a technique used to avoid the overhead of
making new database connections each time an application or server object requires access to the
database. Connection pooling is usually used in web-based and enterprise applications and is usually
handled by, but not limited to, an application server.
It is important to properly configure your connection pool parameters so that you never run out of
connections because this could reduce application performance.
To properly configure connection pool settings, it is important for the application server administrator to
monitor the connection pool during peak hours of the day to ensure that sufficient connections are
available for applications and users at all times. Most application servers include monitoring tools. For
more information about monitoring and configuring connection pool settings, see the application server
documentation at “Application server websites” on page 70.
When the application server administrator determines the correct connection pool settings, this information
should be communicated to the database administrator as the number of database connections will equal
the number of connections in the connection pool for the data source. Then, complete the steps to
configure the connection pool settings for your application server and data source type as described below.
If you are using both the LiveCycle ES repository and the (BAM) ES metadata database then you must
account for both data source connection pools.
See “Application server considerations” on page 80 for the default connection pool settings.
Configuring connection pool settings for WebLogic for Oracle and MySQL
➤ To configure the connection pool settings:
1. Under Domain Structure, click Services > JDBC > Data Sources and, in the right pane, click IDP_DS.
Adobe LiveCycle ES
Maintaining the Application Server
Administrating LiveCycle ES
Configuring application server data sources
73
2. On the next screen, click the Configuration tab and the Connection Pool tab, and enter a value in the
following boxes:
●
Initial Capacity
●
Maximum Capacity
●
Capacity Increment
●
Statement Cache Size
3. Click Save and then click Activate Changes.
4. Restart WebLogic managed server.
Configuring connection pool settings for WebLogic for SQLServer
➤ To configure the connection pool settings:
1. Under Change Center, click Lock & Edit.
2. Under Domain Structure, click Services > JDBC > Data Sources and, in the right pane, click EDC_DS.
3. On the next screen, click the Configuration and the Connection Pool tab, and enter a value in the
following boxes:
●
Initial Capacity
●
Maximum Capacity
●
Capacity Increment
●
Statement Cache Size
4. Click Save and then click Activate Changes.
5. Restart WebLogic managed server.
Configuring connection pool settings for WebSphere for DB2
➤ To configure IDP_DS connection pools:
1. In the navigation tree, click Resources > JDBC > JDBC Providers and, in the right pane, click the data
source you just created, either DB2 Universal JDBC Driver Provider or LiveCycle - db2 - IDP_DS.
2. Under Additional Properties, click Data sources and then select IDP_DS.
3. On the next screen, under Additional Properties, click Connection Pool Properties and enter a value in
the following boxes:
●
Maximum connections
●
Minimum connections
4. Click OK or Apply, and then click Save directly to master configuration.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining the Application Server
Optimizing inline documents and impact on JVM memory
74
Configuring connection pool settings for WebSphere for Oracle
➤ To configure IDP_DS connection pools:
1. In the navigation tree, click Resources > JDBC > JDBC Providers and, in the right pane, click the
Oracle JDBC Driver data source you just created.
2. Under Additional Properties, click Data sources and then select IDP_DS.
3. On the next screen, under Additional Properties, click Connection Pool Properties and enter a value in
the Maximum connections box.
4. Click OK or Apply, and then click Save directly to master configuration.
Configuring connection pool settings for WebSphere for SqlServer
➤ To configure IDP_DS connection pools:
1. In the navigation tree, click Resources > JDBC > JDBC Providers and, in the right pane, click the
User-defined JDBC Driver data source you just created.
2. In the navigation tree, click Resources > JDBC > JDBC Providers and, in the right pane, click the
User-defined JDBC Driver data source you just created.
3. Under Additional Properties, click Data sources and then select IDP_DS.
4. On the next screen, under Additional Properties, click Connection Pool Properties and enter a value in
the Maximum connections box.
5. Click OK or Apply, and then click Save directly to master configuration.
Optimizing inline documents and impact on JVM memory
If you are typically processing documents of a relatively small size, you can improve the performance
associated with the document transfer speed and storage space by implementing the following
LiveCycle ES product configurations:
●
Increase the (default document) maximum inline size for LiveCycle ES so that it is larger than the size of
most documents.
●
For processing larger files, specify storage directories that are located on a high-speed disk system or a
RAM disk.
The maximum inline size and the storage directories (the LiveCycle ES temporary file directory and the
GDS directory) are configured in the LiveCycle Administration Console.
Document size and maximum inline size
When a document that is sent for processing by LiveCycle ES is less than or equal to the default document
maximum inline size, the document is stored on the server inline and the document is serialized as an
Adobe Document object. Storing documents inline can have significant performance benefits. However, if
you are using Process Management ES, the content may also be stored in the database for tracking
purposes; therefore, increasing the maximum inline size might affect the database size.
A document that is larger than the maximum inline size is stored on the local file system, and the Adobe
Document object that is transferred to and from the server is only a pointer to that file.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining the Application Server
Optimizing inline documents and impact on JVM memory
75
When document content is inlined (that is, less than the maximum inline size), the content is stored in the
database (as part of the document's serialization payload). Therefore, increasing the maximum inline size
might affect the database size.
➤ To change the maximum inline size:
1. Log in to LiveCycle Administration Console and click Settings > Core System Settings >
Configurations.
2. Enter a value in the default document max inline size box.
3. Click OK.
Note: The default maximum inline size is 65536 bytes.
JVM maximum heap size
An increase in the maximum inline size requires more memory for storing the serialized documents and
therefore generally also requires an increase in the JVM maximum heap size. The maximum JVM heap size
should not exceed 2 GB.
A heavily-loaded system that is processing a large number of documents can rapidly saturate the JVM
heap memory. To avoid an OutOfMemoryError, the JVM maximum heap size must be increased by an
amount corresponding to the size of the inline documents multiplied by the number of documents that
are typically executed at any given time.
JVM maximum heap size increase = (inline documents size) x (average number of documents processed).
Example: Calculating the JVM maximum heap size
In this example, the current JVM maximum heap is set to 512 MB and the maximum inline size is 64 KB. The
server needs to be configured for the scenario where 10 jobs are run simultaneously, and each job has 9
input files and 1 result file (a total of 10 files per job and 100 files processed simultaneously). All of the files
are under 512 KB in size.
To store all of the files inline, the maximum inline size must be set to at least 512 KB.
The required increase in the JVM maximum heap size is calculated using the following equation:
(512 KB) x (100) = 51200 KB, or 512 MB
The JVM maximum heap size must be increased by 512 MB for a total of 1GB.
Considering heap fragmentation
Setting the size of inline documents to large values raises the risk of an OutOfMemoryError on systems
that are prone to heap fragmentation. To store a document inline, the JVM heap memory must have
sufficient contiguous space. Some operating systems, JVMs, and garbage collection algorithms are prone
to heap fragmentation. Fragmentation decreases the amount of contiguous heap space and can lead to an
OutOfMemoryError even when sufficient total free space exists.
For example, previous operations on the application server have left the JVM heap in a fragmented state,
and the garbage collector cannot compact the heap sufficiently to regain large blocks of free space. An
OutOfMemoryError can occur even though the JVM maximum heap size has been adjusted for an increase
in maximum inline size.
Adobe LiveCycle ES
Maintaining the Application Server
Administrating LiveCycle ES
WebSphere Application Server enhancements
76
To account for heap fragmentation, the inline document size must not be set higher than 0.1% of the total
heap size. For example, a JVM maximum heap size of 512 MB can support a maximum inline size of 512 MB
x 0.001 = 0.512 MB, or 512 KB.
WebSphere Application Server enhancements
This section describes settings specific to a WebSphere Application Server environment.
Increasing the maximum memory allocated to the JVM
If you are running LiveCycle Configuration Manager or trying to generate Enterprise JavaBeans™ (EJB)
deploy code using the command line utility, ejbdeploy, and an OutOfMemory error occurs, you must
increase the amount of memory allocated to the JVM.
➤ To increase the maximum memory allocated to the JVM:
1. Edit the ejbdeploy script in the [appserver root]/deploytool/itp/ directory:
●
(Windows) ejbdeploy.bat
●
(Linux and UNIX) ejbdeploy.sh
2. Find the -Xmx256M parameter and change it to a higher value, such as -Xmx1024M.
3. Save the file.
4. Run the ejbdeploy command or redeploy using LiveCycle Configuration Manager.
Windows Server 2003 enhancements
This section describes settings specific to a Windows Server 2003 operating system environment.
Improving Windows Server performance with LDAP
Using connection pooling on the search connection can decrease the number of ports needed by as much
as 50% because that connection always uses the same credentials for a given domain, and the context and
related objects are closed explicitly.
➤ To configure your Windows Server for connection pooling:
1. Click Start > Run to start the registry editor and, in the Open box, type regedit and click OK.
2. Navigate to the registry key
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters.
3. In the right pane of the registry editor, find the TcpTimedWaitDelay value name. If the name does not
appear, select Edit > New > DWORD Value from the menu bar to add the name.
4. In the name box, type TcpTimedWaitDelay.
Note: If you do not see a flashing cursor and New Value # inside the box, right-click inside the right
panel, select Rename from the menu and, in the name box, type TcpTimedWaitDelay.
5. Repeat step 4 for the value names MaxUserPort, MaxHashTableSize, and MaxFreeTcbs.
Adobe LiveCycle ES
Administrating LiveCycle ES
Maintaining the Application Server
Windows Server 2003 enhancements
77
6. Double-click inside the right pane to set the TcpTimedWaitDelay value. Under Base, select Decimal
and, in the Value box, type 30.
7. Double-click inside the right pane to set the MaxUserPort value. Under Base, select Decimal and, in
the Value box, type 65534.
8. Double-click inside the right pane to set the MaxHashTableSize value. Under Base, select Decimal
and, in the Value box, type 65536.
9. Double-click inside the right pane to set the MaxFreeTcbs value. Under Base, select Decimal and, in
the Value box, type 16000.
Caution: Serious problems may occur if you modify the registry incorrectly by using Registry Editor or by
using another method. These problems may require that you reinstall your operating system.
Modify the registry at your own risk.
Part III: Troubleshooting LiveCycle ES
This section of the guide describes the troubleshooting methods that you can perform if your LiveCycle ES
environment encounters errors.
78
9
Troubleshooting
This section discusses possible issues with your LiveCycle ES environment, LiveCycle Administration
Console interface issues, and when to contact Adobe Support.
●
Getting help
●
Troubleshooting LiveCycle ES with log files
●
Troubleshooting your application server
●
Troubleshooting your application server with log files
●
Troubleshooting your LiveCycle ES database
●
Troubleshooting output errors
Getting help
This section describes the steps you should take before you contact Adobe Support. If, after reviewing the
LiveCycle ES documentation, you have not resolved your issues, contact Adobe Support. To help expedite
your service, have the following information available:
●
What were you doing when the problem occurred?
●
Can you repeat the problem?
●
Did you see any error message when the problem occurred? Did you see anything else?
●
If you disable the Show friendly HTTP error messages options in Internet Explorer (Tools > Options >
Advanced), do the errors persist?
Installation considerations
If you are having problems installing, configuring, or deploying LiveCycle ES, make sure that you carefully
followed the instructions in these LiveCycle ES documents:
●
Preparing to Install LiveCycle ES
●
Installing and Deploying LiveCycle ES for your application server
●
Administrating LiveCycle ES (this document)
If you have installed and configured everything according to the documentation, review the following
sections for issues similar to those you are experiencing.
79
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Application server considerations
80
Application server considerations
Verify the following application server settings before you contact Adobe Support:
Total transaction lifetime timeout: 300
Initial heap size: 256
Maximum heap size: 1024 Mb
Prepared statement cache: 100
Database connection pool maximum: IDP_DS is 100 and RM_DS is 30
Connection pool maximum connections: 50
Performance considerations
Synchronization issues: If a large number of threads are waiting at the same time in the same part of
the code, obtain a thread dump when the congestion has passed.
Caution: Thread dumps could disable the JVM.
Slow external resources: If a large number of threads are waiting for a return message from an
external source, obtain a thread dump to find threads that are waiting for sources such as databases or
LDAP servers.
Slow GC collection: If verbosegc performs compaction frequently, reduce the amount of “garbage”
generated by the application by introducing object pooling or caching. If the log is showing long
garbage collection cycles in verbosegc, reduce the maximum heap size.
High user CPU: If your CPU is running at 75% or higher, consider these options:
●
Reduce the pool size of web container or ORB threads.
●
Reduce the number of database connections on the database server.
●
Consider adding processing resources if you experience consistently high CPU usage.
●
If the CPU is on the database server, reduce the datasource maximum connection setting.
Bootstrapping considerations
If you are having problems bootstrapping LiveCycle ES, consider the following possibilities:
●
Database instances must contain only alphanumeric characters in their names.
●
(Linux and UNIX) Database instances must not exceed the platform-specific threshold of 8 characters.
If the bootstrapping fails at the beginning of the process, do the following check:
●
(Non-turnkey installation) The LiveCycle ES database has been created and the user has full rights to it.
●
The database server is accessible when you ping it.
●
The database is empty (that is, it has no tables, sequences, views, or index tables).
●
The JNDI name for IDP_DS has been created.
If bootstrapping fails while writing to the registry, check the application server logs for errors that pertain
to the queues and topics. If errors exist, verify that the queues and topics have been configured properly.
(See the Installing and Deploying LiveCycle ES document for your application server.)
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Login issues
81
Login issues
If you cannot access any of the LiveCycle ES web applications (for example, LiveCycle Administration
Console or Workspace ES web pages), check whether these tasks are done:
●
The LiveCycle ES database tables have been created and the user has full rights to the database.
●
The database server is accessible when you ping it.
Note: Only administrators with the appropriate roles can access the Workspace ES application. For
information about roles and permissions, see User Management Help.
If you cannot log in to the LiveCycle Administration Console as a user with administrator privileges, do the
following tasks:
●
Try to log in with Super Administrator (that is, Administrator as user Id). This user always checks into the
local database before going to any other authentication provider.
●
Check the custom SPI issues described below.
●
Check whether the administrator user has all the required roles. If your LDAP tree has an administrator
name, the LiveCycle ES roles could have been overwritten. Contact Adobe Support.
If you cannot log in to the Workspace ES web pages, do the following check:
●
The host file contains the Workspace ES server name.
●
The Workspace ES server is accessible when you ping it.
●
Neither the client nor the Workspace ES server are blocked by a firewall.
●
The QLC file has the correct settings, such as the Workspace ES server name, JNDI, or URL provider port.
If you are using a custom SPI and cannot log in, do the following tasks:
●
Check the config.xml file to ensure that the association between the domain and its authentication
provider is correct. If it is incorrect or absent, login authentication will fail. The domain must be
configured in the config.xml file as follows:
<node name="Domains">
<map/>
<node name="<Domain_Name">
<map>
<entry key="description" value="any suitable discription"/>
<entry key="name" value="<Domain_Name>"/>
<entry key="isLocal" value="true/false"/>
</map>
<node name="AuthConfigs">
<map/>
<node name="<Profile_Name">
<map>
<entry key="authProviderNode"
value="/Adobe/LiveCycle/Config/UM/AuthProviders/<AuthenticationProvider"/>
</map>
</node>
</node>
<node name="DirectoryConfigs">
Adobe LiveCycle ES
Administrating LiveCycle ES
●
Troubleshooting
Troubleshooting LiveCycle ES with log files
82
Every domain keeps a reference of the authentication provider it uses for authentication. The
authentication provider must be configured in the config.xml file as follows:
<root type="system">
<map/>
<node name="Adobe">
<map/>
<node name="LiveCycle">
<map/>
<node name="Config">
<map/>
<node name="UM">
<map/>
<node name="AuthProviders">
<map/>
<node name="Authentication Provider">
<map>
<entry key="configured" value="true"/> SHOULD BE TRUE
<entry key="visibleInUI" value="false"/>
<entry key="enabled" value="true"/>
<entry key="allowMultipleConfigs" value="false"/>
<entry key="className"
value="com.adobe.idp.um.provider.authentication.CertificateAuthProviderImpl"
/> SHOULD BE NON NULL
<entry key="order" value="5"/>
Troubleshooting LiveCycle ES with log files
This section describes how to troubleshoot LiveCycle ES using the log files.
LiveCycle ES log file
By default, the LiveCycle ES log file is located in the [LiveCycleES root] directory and is named log.txt. This
log file is useful for LiveCycle ES failure analysis and may be required when dealing with Adobe Enterprise
Support.
LiveCycle ES log file error messages
OutOfMemoryError
These types of errors are typically caused by one of the following issues:
●
Running out of threads
●
Threads and memory allocations
Adobe LiveCycle ES
Administrating LiveCycle ES
Troubleshooting
LiveCycle ES log file error messages
83
Running out of threads
There are many different types of threads; however, essentially they fall into two categories: Java threads
and native threads. All the threads running within a JVM are Java threads (java.lang.Thread class
inside Java). The native code (C++/C) creates native threads that are scheduled and managed by the
operating system. Here are the key differences between the two types:
●
Operating system tools (such as perfmon or Task Manager) only knows about native threads.
●
Java threads are created and managed by LiveCycle ES code, application server, or the JVM itself.
Because the operating system has no visibility into Java threads, when you monitor threads using
operating system tools such as perfmon, you are only monitoring native threads. The only way to get
details into Java thread is to get a Java thread dump. The process about how to get a Java thread dump will
vary depending on your application server and JVM. Refer to the manufacturer’s documentation.
Incidentally, the implementation of the JVM is done in C/C++ code and that JVM code will map Java
threads to native threads. This mapping can be either 1:1 (1 Java thread to 1 native thread) or N:1 (multiple
Java threads to 1 native thread). The details of how this mapping works will be specific to the JVM vendor,
but 1:1 mapping is a typical default. This means that each Java thread will have a corresponding native
thread. The number of Java threads has no hard limit; however, because 1:1 mapping is typical and the
number of native threads has hard limits, you can run out of Java threads as well. This limit applies *per*
process (JVM being a single process) and will vary on each operating system. You can assume that the limit
will be in the thousands (but less than 10,000). Regardless of this number, having high 100s of threads is a
performance problem because the operating system has to schedule up to that many threads.
Threads and memory allocation
Another common issue for threads pertains to memory allocations. When a new Java thread is allocated, a
fixed amount of memory is required for thread's stack. This thread stack space is a tunable parameter
(-Xss option for Sun™ JVM) and the default is ~512 KB. Therefore, if you have 1000 threads, 500 MB of
memory would be required just for the thread's stacks. This memory will compete with all the other
memory allocations being done in the JVM (for example, what LiveCycle ES allocates) and will create
memory allocation issues.
In practice, when the JVM cannot allocate memory or create threads, it throws an OutOfMemory
exception back to the caller. Along with this exception will be a stack trace and a reason for throwing the
exception. This reason is very important to note; it will give you further clues to what may be wrong.
The following code is an example of a message that displays two errors and their associated reason codes:
"unable to create new native thread: java.lang.OutOfMemoryError: unable to
create new native thread java.lang.OutOfMemoryError: Java heap space"
These errors mean that the JVM could not create more threads for one of these reasons
●
The per-process thread limit has been reached.
●
The thread stack could not be allocated.
Adobe LiveCycle ES
Administrating LiveCycle ES
Troubleshooting
LiveCycle ES log file error messages
84
To determine the exact cause, you need to get a thread dump (also known as Java jump). Thread dump will
typically be called javacore.xxxx.txt and reside under an application server's log directories. A lot of
information will be inside the thread dump, but you can quickly determine the number of threads by
counting the occurrences of the TID: token on the list. A typical entry will look like this:
"Thread-1227" (TID:0x106948F0, sys_thread_t:0x78996DA0, state:R, native
ID:0x191C) prio=5
4XESTACKTRACE at java.net.SocketInputStream.socketRead0(Native Method)
4XESTACKTRACE at
java.net.SocketInputStream.read(SocketInputStream.java(Compiled Code))
4XESTACKTRACE at
java.io.BufferedInputStream.fill(BufferedInputStream.java(Compiled Code))
4XESTACKTRACE at
java.io.BufferedInputStream.read1(BufferedInputStream.java(Compiled Code))
4XESTACKTRACE at
java.io.BufferedInputStream.read(BufferedInputStream.java(Compiled Code))
4XESTACKTRACE at com.sun.jndi.ldap.Connection.run(Connection.java(Compiled
Code))
4XESTACKTRACE at java.lang.Thread.run(Thread.java:567)
If you find thousands of threads, you are probably running out of threads. Developers should be able to
identify obvious culprits by scanning the stack traces of these threads.
Note: Thread dumps are typically intrusive and require that you restart the application server afterwards.
If the thread count is in the hundreds, the reason for the java.lang.OutOfMemory error is not the
thread limit. Reduce the thread stack size (-Xss option mentioned above), rerun LiveCycle ES and see if
the problem disappears.
404 File not found
If you see this error, perform these checks:
●
Confirm the problem in the browser’s access log.
●
Confirm that the EAR file deployed properly and that the application initialized.
●
If the URL is intended for the HTTP server, check that the file exists. Look in the error_log or error.log file
for the full file name that the web server is looking for.
●
(JBoss) Make sure the URL uses the correct case (it is case-sensitive).
●
(JBoss) Does the web application context root (first part of the URL) exist in the
uriworkermap.properties file of the JK plugin configuration?
●
(JBoss) If it is a JSP, does the file exist in the EAR? This option will be confirmed by absence of an entry in
the HTTP server's error log file.
Class not found
If you see this error, check whether any of these problems exist:
●
The class path setting is invalid or missing.
●
The JAR file is obsolete.
●
A compilation problem exists in the class.
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Troubleshooting your application server
85
JNDI name not found
If the symptom is an exception stack trace showing javax.naming.NameNotFoundException:
jdbc/<badName>, check that the expected name is spelled correctly. If it is not, you must fix the code.
To correct most common JNDI exceptions, following this process:
1. Check the JNDI tree on the LiveCycle ES application server. Does the name used appear in the tree?
●
If yes, it is most likely that your code has not properly set up the InitialContext object being
used for the look-up and the look-up is being done on a JNDI tree that is not the one that the
resource is listed in. For the property values to use, see the Installing and Deploying LiveCycle ES
document for your application server.
●
If no, continue to step 2.
2. Does the resource appear in the JNDI tree under a name other than that listed in the look-up?
●
If yes, you are using the incorrect look-up name. Provide the correct name.
●
If no, continue to step 3.
3. Review the application server logs during startup. If the application server has been configured to
make this resource available, but something is going wrong, an exception will appear here. Is there an
exception?
●
If yes, review the exception and stack trace. If the NameNotFoundException is a symptom of
another problem based on your investigation of the server logs, go to the troubleshooting steps for
that problem.
●
If no, continue to step 4.
4. If the resource is not listed in the JNDI tree, and no exception appears at startup to explain why it is not
available, the most probable issue is that the application server has not been configured properly to
make that resource available. Review the application server configuration. Has it been configured to
make this resource available?
●
If no, refer to the Installing and Deploying LiveCycle ES document for your application server.
●
If yes, this problem is not one of the common ones that cause this issue. Contact Adobe Support.
Troubleshooting your application server
This section describes possible issues you may encounter with your application server and how to
troubleshoot possible issues using log files.
Application server does not start
If the server does not start, perform these checks:
●
Check the application server log file.
●
Check whether the server is already running. If so, it will continue to run but fail to initialize. Stop and
restart the application server.
●
Check whether another process is using any of the ports configured for LiveCycle ES.
●
Refer to the manufacturers documentation.
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Troubleshooting your application server with log files
86
Troubleshooting your application server with log files
Information in the application server log files can be used to help troubleshoot problems you are
experiencing with your LiveCycle ES implementation. If the log files do not provide enough information to
help you troubleshoot problems, you can enable verbose logging to increase logging details. Verbose
logging should only be enabled during troubleshooting; otherwise, it will slow system performance and
consume additional disk space for log files.
Note: It is recommended that you work with Adobe Support to troubleshoot problems when using
verbose log files.
JBoss log file
By default, the JBoss log files are located in [LiveCycleES root]\jboss\server\all\log and are named boot.log
and server.log. The log files are useful for JBoss Application Server and LiveCycle ES bootstrapping failure
analysis, and may be required when dealing with Adobe Enterprise Support.
If the log files do not provide enough information to help you troubleshoot problems, you can enable
TRACE logging to increase logging details by modifying the [appserver root]/conf file.
Note: Ensure that you back up the [appserver root]/conf file before you modify it.
➤ To enable TRACE logging in JBoss:
1. From a command prompt, navigate to the [appserver root]/conf directory.
2. Edit the log4j.xml configuration file using a text editor.
3. Locate the <root> logger element in the file and change it as follows:
<root>
<priority value="INFO" />
<appender-ref ref="FILE" />
</root>
4. Above the <root> logger element, enter the following text:
<category name="org.jboss.ejb">
<priority value="TRACE" class="org.jboss.logging.XLevel"/>
<!--Comment the line below if you want to disable tracing -->
<appender-ref ref="TRACE_FILE" />
<appender-ref ref="FILE" />
</category>
5. Locate <appender name="FILE" in the file and change or enter the following line:
<param name="Threadhold" value="DEBUG" />
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Troubleshooting your application server with log files
87
6. Locate <!-- A size based file rolling appender in the file and paste the appender in the
line below:
<appender name="TRACE_FILE"
class="org.jboss.logging.appender.RollingFileAppender">
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.home.dir}/log/trace.log"/>
<param name="Append" value="false"/>
<param name="MaxFileSize" value="5MB"/>
<param name="MaxBackupIndex" value="2"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
</layout>
</appender>
7. Save and close the log4j.xml file.
➤ To disable TRACE logging in JBoss:
1. From a command prompt, navigate to the [appserver root]/conf directory.
2. Edit the log4j.xmlconfiguration file using a text editor.
3. Locate the <root> logger element in the file and change it as follows:
<root>
<priority value="INFO" />
<appender-ref ref="FILE" />
</root>
4. Above the <root> logger element, enter the following text:
<category name="org.jboss.ejb">
<priority value="TRACE" class="org.jboss.logging.XLevel"/>
<!--Comment the line below if you want to disable tracing -->
<appender-ref ref="TRACE_FILE" />
<appender-ref ref="FILE" />
</category>
5. Locate <appender name="FILE" in the file and change or enter the following line:
<param name="Threadhold" value="DEBUG" />
6. Locate <!-- A size based file rolling appender in the file and paste the appender in the
line below:
<appender name="TRACE_FILE"
class="org.jboss.logging.appender.RollingFileAppender">
<errorHandler class="org.jboss.logging.util.OnlyOnceErrorHandler"/>
<param name="File" value="${jboss.server.home.dir}/log/trace.log"/>
<param name="Append" value="false"/>
<param name="MaxFileSize" value="5MB"/>
<param name="MaxBackupIndex" value="2"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value="%d %-5p [%c] %m%n"/>
</layout>
</appender>
7. Save and close the log4j.xml file.
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Troubleshooting your application server with log files
88
WebLogic log file
By default, the WebLogic log file is located in /var/log/httpd/error_log. The log files are useful for
WebLogic Server and LiveCycle ES bootstrapping failure analysis, and may be required when dealing with
Adobe Enterprise Support.
If the log file does not provide enough information to help you troubleshoot problems, you can specify the
level of tracing in the log file to increase logging details. To do this, modify the LogLevel parameter in the
[appserver root]/conf/httpd.conf file. LogLevel sets how verbose the error messages in the error logs are.
LogLevel can be set (from least verbose to most verbose) to emerg, alert, crit, error, warn,
notice, info, or debug. The default LogLevel is warn.
Note: Ensure that you back up the [appserver root]/conf/httpd.conf file before you modify it.
➤ To enable debug LogLevel in WebLogic:
1. From a command prompt, navigate to the [appserver root]/conf directory.
2. Edit the httpd.conf configuration file using a text editor.
3. Locate the LogLevel in the file and change it as follows:
LogLevel debug
4. Save and close the httpd.conf file.
When you have completed troubleshooting, repeat steps 1 to 4 but change the LogLevel to warn.
WebSphere log file
By default, the WebSphere log file is located in [appserver root]/logs/server1/trace.log. The log files are
useful for WebSphere Application Server and LiveCycle ES bootstrapping failure analysis, and may be
required when dealing with Adobe Enterprise Support.
If the log files do not provide enough information to help you troubleshoot problems, in the WebSphere
Administrative Console, you can enable TRACE logging to increase logging details.
➤ To enable TRACE in WebSphere:
1. Log in to WebSphere Administrative Console and, in the navigation tree, click Troubleshooting > Logs
and Trace.
2. In the list of servers, click server1, and then click Change Log Detail Levels.
3. Select Enable Trace and, in the Trace Specification box, type
com.adobe.*=all=enabled:com.adobe.framework.UITools=all=disabled.
Adobe LiveCycle ES
Troubleshooting
Administrating LiveCycle ES
Troubleshooting your LiveCycle ES database
89
➤ To view the JVM system output and error logs:
1. In the WebSphere Administrative Console navigation tree, click Troubleshooting > Logs and Trace.
2. In the list of servers, click the name of the server, and then click JVM Logs.
3. Click the Runtime tab and click View either under System.out (to view the JVM system output log) or
under System.err (to view the error log). If any of the selections are unavailable, you can view them in
the Configuration tab by specifying the SystemOut.log and SystemErr.log file names. By default, the
files are in the following location:
[appserver root]/profiles/[profile_name]/logs/[server name]
Troubleshooting your LiveCycle ES database
This section describes possible issues you may encounter with your LiveCycle ES database and suggests
steps for avoiding or working around them.
If your database is failing to bootstrap, perform the following check:
●
The database has adequate disk space to grow.
●
The database configuration meets minimum database configuration requirements. For configuration
requirements for your database type, see Preparing to Install LiveCycle ES.
●
Refer to the manufacturers documentation.
Note: If your database administrator cannot successfully bootstrap the database after these checks, the
database manufacturer needs to be contacted immediately.
To ensure continuous availability and performance of your LiveCycle ES database, do the tasks:
●
Continuously monitor the database as it is running for performance related problems.
●
Continuously monitor database growth to ensure adequate disk space is available at all times.
●
Consider LiveCycle ES component usage: Intense Process Management ES applications will grow the
database more substantially than intense PDF Generator ES applications.
●
Review manufacturers database performance documentation.
IBM DB2 configuration settings
If you are running LiveCycle ES with a DB2 database and the computer stops responding, check the server
log files for deadlock-related messages. If such messages are in the log files, change your DB2
configuration parameters.:
●
Set the LOCKTIMEOUT parameter to 15.
●
Double the values for the APPLHEAPSZ, STMTHEAP, and SORTHEAP parameters.
You must then restart the database and application server.
Adobe LiveCycle ES
Administrating LiveCycle ES
Troubleshooting
Troubleshooting output errors
90
Troubleshooting output errors
Some output files are not converted from a watched folder
Some LiveCycle ES servers (most commonly those running on UNIX) will invoke the conversion process
before all the associated files have been copied to the watched folder, thereby missing some of the files. To
avoid this issue, create a folder outside of the watched folder hierarchy, copy in all of the required files, and
then copy the entire folder to the watched folder root.
Some output files are lost when a clustered WebSphere Application Server
shuts down
Some expected output files may be lost when one WebSphere Application Server of a cluster shuts down.
One possible cause is that invocation requests from a watched folder cannot access files placed in the
staging folder, for various reasons related to the shutdown.
Perform the following procedure to recover the lost files.
➤ To recover files from a staging folder:
1. Ensure that the node is restarted.
2. Log in to the LiveCycle Administration Console and click on Services > Archive Administration >
Endpoint Management.
3. In the Provider window, select WatchedFolder, then click Filter to display the endpoints for the
watched folder.
4. Select the check box for the service name endpoint, then click Disable. The watched folder is now
disabled from processing new files.
5. Wait for LiveCycle ES to recover and process any files it can access. The waiting time depends on the
time required to process the operation being called and the number of files being recovered.
6. Check the date-time stamp of the files remaining in the staging directory to identify which files are old
enough to be files lost due to the shutdown.
7. Copy the lost files to the input directory.
8. Re-enable the watched folder to process new input files by repeating steps 2 to 4 and selecting Enable.
Password encryption error
When Federal Information Processing Standards (FIPS) mode is enabled in LiveCycle ES (set either during
the LiveCycle ES configuration process or manually in the Core Systems Settings web pages within
LiveCycle Administration Console), password encryption will not be applied to any document. If you
attempt to encrypt the password on a FIPS-enabled document, the error “Password encryption is not
permitted in FIPS mode” is displayed.
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement