Introduction

Adobe LiveCycle workflow allows you to invoke Processes (human-centric workflows) or Orchestrations (straight-through processing) in a number of ways:

• By completing a form in LiveCycle Workspace
• Via a Watch Folder
• Via Web Services/SOAP
• Using Java code

However, sometimes you need something a little simpler, like:

• Start the process when I click this link on a web page
• Start the process when I hit a Submit button in a PDF that is opened from a web page or a file system

The Avoka Process Invoker is a web application that allows an Adobe LiveCycle ES process to be started via a URL or PDF Form Submission.

The result of the process invocation can be sent back to the user who initiated it, and may be an HTML page, or a PDF, or any other type of content a browser can display. It can also be configured to display a simple web page indicating whether the process was started successfully or not.

Basic operation

The URL for launching the process, whether invoked via a URL in a web page, or a URL in a Submit button on a form, always follows the same format:

http://livecycleserver:8080/processinvoker?fixedparameter=xxx&passedparameter=yyy&etc

Fixed Parameters 

There are a number of "fixed" parameters that are interpreted by the servlet itself. Fixed parameters include:

Passed parameters

All other parameters are assumed to be parameters that are passed directly to input parameters of the process being invoked. No checking is done that the parameters in your URL match those of the process - you must verify this.

All parameters are simple strings. Usage of non-string input parameters will rely on the implicit type coercion facilities within workflow, and behaviour could be different to what is expected.

Response

By default, the Process Invoker will display a simple web page indicating the status of the request. This will provide the end-user some simple information on whether their request was successful or not (and why), as well as some simple data that can be used to track the process (the process-id).

It is possible to modify the look and feel of the default pages by simple modifying the response.jsp file within the ProcessInvoker .war file.

Alternately, the process designer can return an HTML or PDF document as the output from the invoked process. In this case, the resulting document/page will be displayed in the user's browser or Reader.

Audit Trail feature

 If you have userid set to "enabled" than a userid parameter is required to be part of each request. Example usage: If you have Process Invoker sitting between an existing application and your LiveCycle workflow, each time a user from the existing system requests a process to be invoked, their user id is logged so you can find out who made the request by reviewing the logs. The userId will also be used to determine identical requests so the same user can't accidentally call the same process multiple times (used along with delay seconds).

 Configuration

The operation of the process invoker is controlled via a simple configuration file. This ensures that only those processes specifically designated to be started via Process Invoker are allowed. It also provides for some simple denial-of-service-attack prevention.

You must include a separate <service> section for each service that you want to be able to invoke.

The configuration file is read in once on startup. Any changes to the configuration file require a restart of the application.

Sample Config File 

<?xml version="1.0" encoding="utf-8"?>

<host name="localhost" type="JBoss">
	<licensekey></licensekey>
	<licenseorganization></licenseorganization>
	<endpoint>http://localhost:8080/</endpoint>
	<protocol>SOAP</protocol>
	<username>administrator</username>
	<password>password</password>
	<delayseconds>60</delayseconds>
	<maxrequests>10</maxrequests>
	<userid>disabled</userid>
	<service>
		<name>SampleProcess</name>
		<operation>invoke</operation>
		<synchronous>true</synchronous>
		<authcode></authcode>
		<requestvar>inputDoc</requestvar>
		<responsevar>outputDoc</responsevar>
		<responsemimetype></responsemimetype>
	</service>
	<service>
		<name>TestProcess</name>
		<operation>invoke</operation>
		<synchronous>true</synchronous>
		<authcode>secret</authcode>
	</service>
</host>

 Explanation of config tags

Installation

You will probably need to replace the Adobe libraries that come with Process Invoker with the ones from your install of LiveCycle. See Common Issues section.

For JBoss, simply drop the ProcessInvoker .war file into your JBoss deploy directory. For other supported application servers, deploy using the Application-server tools.

You may also run the Process Invoker on any Servlet container, such as Tomcat.

You must configure the configuration file within the .war file before deploying the .war file to the application server - you can use WinZip or similar to extract the default configuration file, make changes, and then re-zip it.

Alternately, you can deploy the .war file as an unzipped .war - in this case, the directory in the JBoss deploy directory must have the .war extension. This allows you to update the configuration file at any time, without needing to unzip/zip it.

Common Issues

Invalid Class Exception: local class incompatible

The Process Invoker application may have worked for you in the past but you've updated LiveCycle and now get the following error or similar

This is caused by the LiveCycle ES API being used by the client (Process Invoker) being different to the version on the server. To resolve, replace the following JAR files:

• adobe-livecycle-client.jar

• adobe-usermanager-client.jar 
  

These can be found on your server here: [LiveCycle ES Home]\LiveCycle_ES_SDK\client-libs\common

To replace the ones in Process Invoker here: processinvoker.war\WEB-INF\lib

Proxy Related Issues

The Process Invoker will use the proxy settings of the underlining JVM. See Sun documentation on this here:  Java Networking and Proxies.

Key options are:

-Dhttp.proxyHost=proxy-server
-Dhttp.proxyPort=80
-Dhttp.nonProxyHosts="test-lces|localhost"