September 2008 Archives

If you have a fully configured installation of LiveCycle ES and would like to add the IBM FileNet Connector to it, here are high level steps you need to follow:

- Re-run the install.
- Provide the new serial number for the IBM FileNet Connector for LIveCycle ES.
- On completion, run LiveCycle Configuration Manager (LCM).
- LCM will remmeber your previous choices but the IBM FileNet Connector will now be active. Check its checkbox.
- Re-build the EAR files.
- Undeploy the LiveCycle EAR file from your appserver.
- Deploy the new one. No need to replace the native EAR or the other EAR files.
- No need to initialize the database tables but check the checkbox to deploy Components (crucial step).

- Follow LiveCycle documentation for your respective appserver.

You need to read and follow instructions in two separate documents, namely the 'Preparing to Install LiveCycle ES' guide as well as the 'Installing and Deploying LiveCycle ES' guide.

- Copy the FileNet client library JAR files to all nodes on the server.
- Create an adobe-component-ext.properties file and copy it to the recommended location.

For IBM WebSphere, this is the root folder of the appserver profile which hosts LiveCycle. The file's contents should look something like this (should be all in one line, unlike what is shown below):
com.adobe.livecycle.ConnectorforIBMFileNet.ext=
/opt/adobe/livecycle8.2was/FileNet_client_libs/activation.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/connector.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/javaapi.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/listener.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/log4j-1.2.8.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/mailapi.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/p8cjares.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/soap.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/xercesImpl.jar,
/opt/adobe/livecycle8.2was/FileNet_client_libs/xml-apis.jar

There is an additional JAR file that is needed that is not listed above, only if you plan to integrate LiveCycle with the FileNet Process Engine.

- Re-start the appserver.
- Login to the LiveCycle AdminUI.
- In the 'Services' panel, there should now be a new option (link) for 'LiveCycle ES Connector for IBM FileNet'.
- Click it and configure the options. You will require the assistance of your FileNet system administrator for this.

The Process Engine configuration fields can be left empty if you don't plan to integrate LiveCycle with it. If you plan to keep your forms in the FileNet ObjectStore, choose the radiobuton for 'IBM FileNet Repository Provider'. However, if you only plan to archive your documents (end of business process) in FileNet but keep the source forms in the LiveCycle repository, choose the radiobutton 'LiveCycle ES Repository Provider'.

- Click Save and make sure there are no errors.
- Navigate to Home->Services->Applications and Services->Service Management.
- Choose the Category 'Connector for IBM FileNet' and click 'Filter'.
- Start the services
: IBMFileNetAuthProviderService
: IBMFileNetContentRepositoryConnector
: IBMFileNetRepositoryProvider

Start the service 'IBMFileNetProcessEngineConnector' only if you plan to integrate with the IBM FileNet Process Engine.

- Verify that the services now display a status of 'Running'. If you get an error at this point, the configuration is not correct.
- Login to Workbench. In the Services window, verify that a new category for the IBM FileNet Connector is displayed.

We recently posted a document on translating forms that I'd like to call you attention to. The LiveCyle ES Update 1 Designer (aka 8.2) provides a method of generating unique ids in the form template to identify text strings . The strings can then be extracted using an XSLT into a common tranlsation format know as XLIFF , translated and then inserted into a new copy of the template using another XSLT. This type of automation allows you to quickly produce multiple languages of a form from a single source without manually maintaining multiple versions. There are sample XSLTs provided as attachments to the document along with full instructions on how to use the feature.

Once you have finished installing, configuring and integrating LiveCycle ES in your DEV, TEST, STAGING or PROD environments, here are some of the things you can quickly do to validate that you have a working configuration:

ADMINISTRATION
---------------------

- Load the LiveCycle AdminUI Login page (http://server_name:port_name/adminui) and login as the Super Administrator user (Administrator) with the default password (password). If you can successfully login, the connection from the J2EE appserver to the database is working.

- Navigate to Services->Applications and Services->Service Management. Make sure that all of the services listed are in the 'Running' state. If at least one is not in the 'Running' state, you have problems. If you get an error instead of a list of services, your Global Storage Folder is probably not accessible.

PDF GENERATOR ES
-------------------------

- If you licensed PDF Generator ES, navigate to Services->LiveCycle PDF Generator ES->HTML to PDF. In the 'Specify URL' field, type in the URL of a well-known website (http://slashdot.org) and click 'Create'. If you get a URL for the new PDF, click on it and verify its contents. If it looks like the webpage at http://slashdot.org, PDF Generator is working.

READER EXTENSIONS ES
------------------------------

- If you licensed Reader Extensions ES, load the ReaderExtensions sample application (http://server_name:port_name/readerextensions), login as the Super Administrator user, browse to a PDF document and apply Reader Extensions rights to it. If this is successful, Reader Extensions ES is working.

WORKBENCH
----------------

- Using Workbench, login as the Super Administrator user. Verify that all of the services you have licensed are listed.

FORMS ES
-------------

- Deploy the FormsIVS sample application. You can find it at $LIVECYCLE_INSTALL_ROOT/deploy/adobe-forms-ivs-your_appserver.ear Access it at http://server_name:port_name/FormsIVS. Choose a form template and its associated data XML and render it via EJB. Try the same using Web Services. If these are successful, Forms ES is working.

OUTPUT ES
--------------

- Deploy the OutputIVS sample application. You can find it at $LIVECYCLE_INSTALL_ROOT/deploy/adobe-output-ivs-your_appserver.ear. Access it at http://server_name:port_name/OutputIVS. Choose a form template and its associated data XML. Choose an appropriate record level (2) and render it via EJB. Try the same using Web Services. If these are successful, Output ES is working.

ASSEMBLER
----------------

- Also, an IVS sample application is available for Assembler (adobe-assembler-ivs.ear - http://server_name:port_name/Assembler). Here's a blog entry from Kathy Stony providing details on using AssemblerIVS to validate a LiveCycle install.

IVS is an acronym for Installation Verification Sample.

PROCESS MANAGEMENT ES
----------------------------------

- If you licensed Process Management ES, load Workspace (http://server_name:port_name/workspace) and verify that you can successfully login as the Super Administrator user. For additional verification, follow instructions here.

For multi-server clusters (vertical or horizontal), shut down all cluster members except one and repeat the above tests for each server in the cluster. To verify that load-balancing across the cluster is working, you would need a load generator tool. Most load-balancers do not evenly split the load until there is consistent heavy load on the cluster.

A quick note to our readers who have been following the recent posts on Solution Accelerators: We have created a new LiveCycle Solution Accelerators blog dedicated entirely to these new product development kits from Adobe. Future SA-related articles will be posted there.

The need to clean up an install of Adobe LiveCycle on IBM WebSphere occurs at various times during an application's development life cycle. Steps to achieve this are provided here. The interface is the WebSphere Admin Console, usually available via HTTP on port 9060 by default.

LiveCycle touches various parts of the J2EE feature set, including JMS, JDBC, and J2C. Even if you don't intend to clean up an install, this provides an outline of the various parts of WebSphere that LiveCycle touches.

Undeploy the EAR files
---------------------------
Three EAR files are usually involved. Since system administrators are free to name them whatever they want, likely names would include terms such as LiveCycle, LiveCycle Native, LiveCycle Workspace. In addition, depending on the LiveCycle features you have licensed, there could also additional EARs to un-deploy like Content Services, and Lava. Also, if LiveCycle was configured using LiveCycle Configuration Manager (LCM), there will be an additional EAR file called 'adobe-lcm-lcvalidator' that need to be undeployed.

Service Integration Bus (SIB)
-----------------------------------
LiveCycle requires a Service Integration Bus. Navigate to Service Integration->Buses and delete the bus that was defined for LiveCucle. It is named "IDP_JMS_Bus".

QueueConnectionFactories
---------------------------------
Navigate to Resources->JMS->Queue connection factories. Delete two queue connection factories, namely 'JobManagerQueueConnectionFactory' and 'QueueConnectionFactory'.

TopicConnectionFactories
-------------------------------
Navigate to Resources->JMS->Topic connection factories. Delete the topic connection factory named 'TopicConnectionFactory'.

Queues
----------
LiveCycle uses four queues for JMS point-to-point messaging. Navigate to Resources->JMS->Queues. Make sure the scope is set to 'All scopes'. Delete the queues 'adobe_JobManagerQueue', 'adobe_PECommandQueue', 'adobe_PEDCommandQueue' and 'adobe_PEInteractionQueue'.

Topics
-------
LiveCycle uses one topic for JMS publish-subscribe (pub-sub) messaging. Navigate to Resources->JMS->Topics. Make sure the scope is set to 'All scopes'. Delete the topic 'adobe_TaskEventTopic'.

Activation Specifications
------------------------------
LiveCycle uses four activation specifications for its queues and topics. Navigate to Resources->JMS->Activation specifications. Make sure the scope is set to 'All scopes'. Delete the activation specifications named 'JobManager_AS', 'PECommand_AS', 'PEDCommand_AS' and 'Task_Event_AS'.

Queue Destinations
-----------------------
Deleting the Service Integration Bus will delete the Queue Destinations defined for LiveCycle. For the record, these queue destinations are named 'adobe_JobManagerQueue', 'adobe_PECommandQueue', 'adobe_PEDCommandQueue' and 'adobe_PEInteractionQueue'. To see them listed, navigate to Service Integration->Buses->IDP_JMS_Bus->Destinations.

Topic Destinations
---------------------
Deleting the Service Integration Bus will delete the single Topic Destination defined for LiveCycle. For the record, this topic destination is named 'adobe_TaskEventTopic'. To see it listed, navigate to Service Integration->Buses->IDP_JMS_Bus->Destinations.

JDBC Provider
------------------
Navigate to Resources->JDBC->JDBC Providers. Make sure the scope is set to 'All scopes'. Delete the JDBC Providers (usually three) defined for LiveCycle. They will have names that include terms like IDP_DS, EDC_DS and JMS_DS.

JDBC Data Sources
------------------------
Deleting the JDBC Provider usually deletes the Dtaa Sources defined using that Provider. However, if you would like to keep the JDBC Provider, you can delete the Data Sources. Navigate to Resources->JDBC->Data Sources. Make sure the scope is set to 'All scopes'. Delete the Data Sources (usually three) defined for LiveCycle. They will have names that include terms like IDP_DS, EDC_DS and JMS_DS.

Replication Domain
-----------------------
LiveCycle requires a data replication domain to be defined for HTTP session replication amongst members of a cluster. Navigate to Environment->Replication Domains. Delete the data replication domain defined for LiveCycle (LCM would have named it "livecycle").

J2C Authentication Alias
-----------------------------
In the WebSphere Admin Console, navigate to Security->Secure administration, applications, and infrastructure->Java Authentication and Authorization Service->J2C authentication data and delete all (usually three) entries for LIveCycle database access. Names can include terms such as IDP_DS, EDC_DS and JMS_DS.

Virtual Host
--------------
If a virtual host has been defined exclusively for LiveCycle, delete it.

Transaction Log
-------------------
On each node in the cluster, navigate to $WAS_INSTALL_ROOT/profiles/your_WAS_profile_name/tranlog/your_WAS_cell_name/your_WAS_node_name/your_WAS_server_name/transaction/ and delete everything below it.

SSL Repertoires
---------------------
If you had defined any SSL repertoires exclusively for LiveCycle, delete them.

Clusters
----------
If you decide to delete the two clusters created for LIveCycle, also remember to delete the corresponding log folders for the member servers on each of the nodes.

Also, remember to drop the tables, views and sequences on the database side, whether it be IBM DB2, Oracle, or Microsoft SQL Server.

Re-start the LiveCycle cluster as well as the LIveCycle JMS cluster afterwards.

A colleague asked me an interesting question the other day as he was building another solution with the CM Aug 20 PDK: "How do I make sure this paragraph is included in my letter only if the user selects this other paragraph?"

The answer is quite simple, actually: Assuming the "other" paragraph is optional, just make the dependent paragraph conditional (by including the cmConditionalContent object in its CM Content subform) and set its condition to evaluate to "true" when the "other" paragraph's cmOptionalContent object is checked (it's a check box).

For example, if the "other" paragraph is sitting in a CM Content subform named "TheOtherParagraph", the condition script would look like this:

cmUtils.ConditionalContentInclusion(this, this.parent.parent.TheOtherParagraph.cmOptionalContent, "==", 1);

To make it work in your letter template, you should just need to replace "TheOtherParagraph" with the name of your CM Content subform.

When Reader Extending a document be sure you select only the rights that you have licensed and that those rights are included in the credential file that you are referencing in your process.

If your extending process fails you may find that you are attempting to apply a right that does not exist.

A common mistake is including the 2D right. Developers select all the rights availalbe and receive the "ALC-RES-001-015: The requested usage right, [BarcodeDecoding], is not allowed by the credential, [CERT]." error which simply means that there was an attempt to include the 2D Barcode Decoding right in the extension process and it has not been licensed (in this case the certificate with the alias "CERT" does not have this right).

As promised, here is the Letter Building Tutorial based on the August 20, 2008, release of the Correspondence Management Solution Accelerator PDK. I had previously indicated I was going to reveal this over a series of posts but I already had it all written-up in a nice document complete with screen shots and converting it to multiple posts just seemed like make-work. I'm sure you'll appreciate having the entire tutorial in a single, searchable document.

Software Requirements

To get started with Correspondence Management (CM), you will need the following (or better):

• CM PDK released on August 20, 2008
• AIR 1.0
• Flash Player 9.0.124.0
• LiveCycle Workbench ES 8.2
• LiveCycle Designer ES 8.2
• Acrobat 9.0 Pro
• Access to a LiveCycle ES Update 1 server running Forms and Workspace, along with any other LC services you may need for your own CM solutions

Tutorial

Download the tutorial [pdf]

Videos

Since videos can reveal even more details, here is a list of links to videos covering the following sections of the tutorial:

1. Installing the kit.
2. Installing and running the Custom Communications sample provided in the kit.
3. Setting-up for building the letter template.
4. Building the letter content (i.e. paragraphs) using the Content Creator tool.
5. Inspecting the base letter template and using it to create a new letter template for a specific solution.
6. Adding content to the letter template.
7. Testing the letter template using the debugging tools.
8. Building and running the Letter Filling Experience (a form guide designed to allow the user to choose content based on inclusion rules specified in the letter template).
9. Troubleshooting some common problems.

Note: In the videos, I point-out a possible bug in Workbench 8.2 related to broken fragment references in the cmBaseTemplate.xdp file. Upon further investigation, it looks like Workbench may not be the culprit after all (sorry guys!). This issue is still under investigation by the CM Team. Please use the workaround provided in the document/videos in the mean time.