February 2009 Archives

If you are looking for a simple way to provide feedback to those users who have disabled JavaScript in Adobe Reader, here’s a simple approach. This works best on a flowed form as the text and space you are going to display to the user should ideally appear when script is disabled and disappear when script is enabled. Technically if a user has script disabled you can’t use script to have a section of text appear or disappear so you need to have the text appear by default and then use script to have the object disappear.

In this example, the “JavaScript is Disabled…” message appears to the user only when JavaScript has been disabled. When script is enabled the text is not displayed as the initialize code “this.presence = "hidden";” causes the text itself to disappear. If your form is Flowed then the space that the text appeared in will also be removed. With a positional page, the text will disappear but the blank space will remain.

To download the sample: http://my.adobe.acrobat.com/checkforjavascriptpdfsample/

LiveCycle ES Update 1 can be downloaded on a trial basis from here (need a freely obtainable Adobe ID). The downloads are between 2 and 3.5 GB. Depending on your Internet bandwidth, you should expect to get a throughput of about 1 GB/hour from the Akamai download. Longer download times increase the risk of corrupt or incomplete downloads. To help you verify that the downloaded file is not corrupt, Adobe provides the MD5 (Message Digest algorithm version 5) checksums here (PDF).

It is a very good idea to verify the integrity of the downloaded file before running the install.

1) Login with your free Adobe ID
2) Agree to the EULA (End User License Agreement)
3) Choose the appropriate download option
4) Also download the checksum file

Once the download is complete, download an MD5 checksum generator such as md5deep
1) Run it against the downloaded LiveCycle zip file with the following command:
md5deep -ze C:\TEMP\JBoss_EFGJ_DVD.zip

You should get an output such as this:
2923744940 60da1ec0664f014aad93f9d99e94350c C:\TEMP\JBoss_EFGJ_DVD.zip

The middle number is the MD5 checksum (60da1ec0664f014aad93f9d99e94350c). Compare it against the value in the Adobe Checksum PDF file. If they match exactly, you have a downloaded file that is not corrupt.

md5deep usage instructions are available here. You can also use the following command to get the command line arguments:
md5deep -help

If you are curious to learn more about LiveCycle activity at the system level (file open/close/read/write, registry access, thread create/delete, network activity etc), there is an excellent tool available (only) on Windows. It is Microsoft's own Process Monitor.

1) Download and run it.

2) Run Windows Task Manager and determine the Process ID of the java.exe process that represents the appserver instance that hosts LiveCycle. You also would want to do the same for LiveCycle processes that run outside the JVM such as XMLForm.exe as well as pdfgen.exe.

3) Apply filters so that only events related to these processes are captured and displayed.

Here's a very detailed video about Process Monitor by Mark Russinovich, one of its creators. You need Microsoft Silverlight to view it.

LiveCycle Process Management ES is essentially LiveCycle's workflow management component. After installing LiveCycle, it is a very good idea to verify that workflow functions correctly in your environment.

1) Install Sample Orchestrations
Ensure that you choose to deploy 'Samples' which is the last major step during configuration by LiveCycle Configuration Manager (LCM).

2) Login using Workbench ES

3) In the Processes view, navigate to Samples - LiveCycle ES, then MortgageLoan - Prebuilt. Open the orchestration (MortgageLoan - Prebuilt - 1.0) for view. It is a simple 2-step mortgage loan application workflow. Any user can initiate the workflow. If the requested amount is $500,000 or more, the workitem will be routed to a (senior) Bank Manager. It the amount is less than $500,000, it will be routed to a Loan Officer. The 'Bank Manager' role is mapped to the built-in user Tony Blue. The 'Loan Officer' role is mapped to the built-in user Alex Pink.

Tony Blue or Alex Pink can approve or deny the loan application. At this point, the workflow is completed. These two users along with Kel Varsen and Rye Woodard are four built-in users belonging to the LiveCycle user domain called 'Sample Organization, Finance Corp' which gets installed when you choose to deploy 'Samples' using LCM.

4) Login to LiveCycle Workspace (http://server:port/workspace) as user 'rwoodard' with password 'password'. Click on the 'Start Process' icon. On the left pane, click on 'Samples'. Click on the 'MortgageLoan - Prebuilt' icon. This will open up a PDF form. Type in values for 'Property Price' and 'Downpayment' so that the Mortgage amount is more than 500,000. Type in values for other fileds also. Do not check 'Approved' or 'Declined'. Click the 'Complete' button at the bottom right. Logout.

5) Wait about 2 minutes. Log back in to Workspace as user 'tblue' with password 'password'. Click on the 'To Do' icon. You should now see an icon representing a new workitem (task). Click it. The previous PDF form should now open up with the values you typed in. Check the checkbox for 'Approve' and click the the 'Complete' button at the bottom right. Logout.

6) Log in to the LiveCycle Admin Console (http://server:port/adminui). Navigate to Services->LiveCycle Process Management ES->Task Search. In the search field for User Name, type in 'Tony Blue', check 'Show Completed Task' and click the 'Search' button. You should see a task listed with a status of 'Completed'. Click on the Task ID and verify the timestamp and date.

7) You can now repeat this for a mortgage amount less than 500,000 and verify that the workitem (task) gets routed to Alex Pink (user 'apink with password 'password').

If this does not work for you, Process Management is not functional in your environment. Look in the appserver instance's log for clues on what might be wrong.

LiveCycle Product Management confirms that general support for Solaris 10 Zones has been added with LiveCycle ES Update 1 Service Pack 1 (version 8.2.1.1) and subsequent releases.

Adobe will support LiveCycle ES being deployed into both the Global Zone and into non-Global Zones on Solaris 10. The application server binaries can be installed into the Global zone with the WebSphere profile, WebLogic domain being resident in a non-Global Zone, LiveCycle ES can subsequently be deployed into the non-Global Zone. This is subject to the Application Servers restrictions on Zone configuration.

Note: Non-Global Zones on WebSphere require the following:
Create a new JVM custom property "adobeidp.RootDirectory" to point to the path where the Adobe native files are to be extracted (example /profiles//installedApps)

VMware allows organizations of all sizes to save a great deal on the costs associated with hardware and operational expenses. Following the VM trend, as of the release of Adobe LiveCycle ES Update 1 Service Pack 1 (also known as 8.2.1.1) LiveCycle Product Management confirms that Adobe now supports the following operating systems running under VMWare ESX 3.0 and 3.5 or GSX 1.0 (now known as VMWare Server):
• Red Hat Enterprise Linux 4 (AS and ES) 32-Bit
• Red Hat Enterprise Linux 5 (Advanced Platform and Server) 64-Bit
• Novell SUSE Linux Enterprise Server 9 32-Bit
• Novell SUSE Linux Enterprise Server 10 64-Bit

If you have any questions related to supported platforms and configurations, please refer to the support matrix documents posted here:

http://www.adobe.com/products/livecycle/pdfs/lces_update1_sysreqs.pdf
http://www.adobe.com/support/products/enterprise/knowledgecenter/softcomp2_0_1.pdf

*At the time of this blog post the above mentioned VMWare configurations were not yet mentioned in these documents.

Many LiveCycle enterprise customers prefer to integrate LiveCycle with their corporate LDAP directory to avoid the hassle of maintaining an additional user directory. Here is a procedure you can follow to configure your corporate LDAP with LiveCycle ES. This has been developed based on multiple customer engagements.

TOOLING
-----------

Download and install one of the following free tools to browse the corporate LDAP Directory :
- Apache Directory Studio
- Microsoft Active Directory Explorer
- Softerra LDAP Browser

UNDERSTAND YOUR LDAP SCHEMA
--------------------------------------------

2) Work with the LDAP Administrator and get Softerra/Apache Directory Studio working
At the very least, you would need the IP address or name of your LDAP server(s), the port (usually 389), a userID, its password as well as the Base Distinguished Name (DN).

3) Familiarize Yourself with the LDAP Schema
Integrating LiveCycle essentially involves the mapping of LiveCycle's user attributes to the LDAP users' attributes. In most cases, the directory is organized into Organizational Units (OUs) at the highest levels. Working twith the LDAP Administrator as well as the LiveCycle Business User, determine the lowest OU that would contain ALL of LiveCycle's users. Using the Softerra LDAP Browser or Apache Directory Studio, determine its DN.

BACKUP LIVECYCLE'S DATABASE
-------------------------------------------

In practical terms, integration of LiveCycle with the corporate LDAP is a trial and error effort. In many cases, it takes at least three diffferent tries before we get it right. In case the first few attempts go awry, and you feel like you need to start from a clean baseline, it is a good idea to backup your database.

INTEGRATE LIVECYCLE
------------------------------

3) Connect to the Directory from the LiveCycle AdminUI
Login to the LiveCycle Admin Console.
Navigate to Settings->User Management->Domain Management.
Click on 'New Enterprise Domain'. Type in an ID and Name (description)
Cick on 'Add Authentication'
In most cases, you'd choose 'LDAP'. Click OK.
Click on 'Add Directory'
Type in a Profile name (eg. "My_Company_Directory") and click 'Next'.
Type in the server name or IP address
Type in the port number
If only SSL connections are allowed to the LDAP Directory servers, choose SSL. Otherwise, choose No.
If binding (connecting) requires authentication (required in most cases), type in the userID that can access it and the associated password.
In the 'Populate Page With' dropdownlst, choose the type of your LDAP Directory. This will populate your user mapping fields with the most appropriate values. However, in most cases, some of these require changes.
Check the checkbox for 'Retrieve Base DNs'
Click on the button 'Test'. If the connection succeeded, the page will say "The server test was successful." (in gray, at the top - it's very easy to miss). If the test is successful, click 'Next'

The user attribute mapping field will load next.

4) Integrate Users
In the Softerra LDAP Browser, locate the entry for a user with whom you are familiar. It can be you, the LDAP Administrator, or the LiveCycle business user. Examine the user's attributes. The LiveCycle user attributes that need to be mapped to your LDAP user attributes are as follows (only some are required, others are optional). The choices you make here are VERY IMPORTANT:

- Unique Identifier
- Description
- Full Name
- Login ID
- Last Name
- Given Name
- Initials
- Business Calendar
- Organization
- Primary Email
- Secondary Email
- Telephone
- Postal Address
- Locale
- Time Zone

The most important is the Unique Identifier. You have to absolutely make sure that this is indeed unique among users in your entire directory.

The search filter field is very important also. You will need the asistance of your LDAP Administrator in coming up with a filter that brings in only those users who need to use LiveCycle and not more. If you bring in ALL of your users, the daily LDAP Synch operation will take too long to complete. Here is a sample search filter:
(&(objectclass=inetOrgPerson)(!(employeetype=0))(activestatus=y))

A very common mistake is mapping 'Locale' to an LDAP user attribute that contains the name of a city. This will cause errors such as this:
Can not persist Principal with User Id: your_LDAP_auth_login and your_domain ID: your_profile_name because one of the field's size exceeds database column length
This is because the corresponding database table column is not big enough to accomodate some of the city names (eg: San Francisco won't work). To verify, check the definition of the EDCPRINCIPALUSERENTITY. The LOCALE column is VARCHAR (20)

Click the 'Test' button. LiveCycle will query your LDAP Directory with these settings and return some results. Verify that the returned resultset is correct. pay special attention and ensure that all of the columns in the resultset are properly populated with the correct values.

Click 'Close' and then 'Next'. This will load the Group Settings page.

5) Integrate Groups
In the Softerra LDAP Browser, locate the entry for a group with whom you are familiar. It can be a group you or the LDAP Administrator is a member of.

The LiveCycle group attributes that need to be mapped to your LDAP group attributes are as follows (only some are required, others are optional). The choices you make here are VERY IMPORTANT:

- Unique Identifier
- Base DN
- Search Filter
- Description
- Full Name
- Member DN
- Member Unique Identifier
- Organization
- Primary Email
- Secondary Email

The most important is the Unique Identifier. You have to absolutely make sure that this is indeed unique among groups in your entire directory.

The search filter field is very important also. You will need the asistance of your LDAP Administrator in coming up with a filter that brings in only those users who need to use LiveCycle and not more. If you bring in ALL of your users, the daily LDAP Synch operation will take too long to complete. Here is a sample search filter:
(|(ou:dn:=Groups1)(ou:dn:=Groups2)).

Click the 'Test' button. LiveCycle will query your LDAP Directory with these settings and return some results. Verify that the returned resultset is correct. pay special attention and ensure that all of the columns in the resultset are properly populated with the correct values.

Click 'Close' and then 'Finish'.
Click OK in the 'New Enterprise Domain' page.
Click 'Save' in the 'Domain Management' page. This is CRITICAL. If you don't perform the sequence of these last three steps, your configuration changes will NOT get saved.

6) Synchronize
Check the checkbox against the domain you just configured and click 'Sync Now' to start syncnronizing the LiveCycle User Manager tables (EDC...) with information from the corporate LDAP. To determine the progress, check the appserver instance's server log or keep querying the EDCPRINCIPALENTITY table every couple of minutes using this SQL query:
SELECT COUNT(*) FROM your_schema_name.EDCPRINCIPALENTITY

While the synchronization is in progress, you will see this count going up.

7) Configuring Daily Synchronization
The default CRON expression for daily synchronization at 3 am is this:
0 00 3 ? * *

For more details on the Quartz open-source job scheduling system (version 1.4.0), see here.

VERIFY
----------

Login to the LiveCycle Admin Console.
Navigate to Settings->User Management->Domain Management.
Ensure that the 'Current Sync State' is shown as "Completed".

Ensure that you are able to login to the LiveCycle Admin Console using your LAN (LDAP) userID and password.

Here are some additional instructions on verifying a LiveCycle LDAP Synch.

EXPORT CONFIGURATION
----------------------------------

Once you are satisfied that you have a working configuration, it is a good idea to export the configuration. This will enable you to quickly import this configuration into your TEST, STAGING and PRODUCTION environments.

To do the export and import, login to the LiveCycle Admin Console and navigate to Settings->User Management->Configuration->Import and export configuration files. Please note that the exported config.xml file will not contain the password of the user configured to authenticate LiveCycle against the LDAP directory. After each import, you need to add it back and save the configuration before initiating a synch.