LiveCycle Tutorial

Adobe LiveCycle ES2 Sample Application

In this tutorial sequence, we will create processes for an enterprise/organization to automate the form design workflows. Workflow involves Designers designing forms; QA testing forms; and Form Requesters approving them. This sample application can act as an infrastructure at an enterprise setting with slight modifications to the configuration settings for the services in the application.

Today, in this short screencast, I will briefly explain the use cases, workflows/processes, tools we employ, and services we use to build the processes. I will follow up this blog with other screencasts explaining in detail about each service used in the application.

LiveCycle Google Documents Connector

LiveCycle ES2 allows developers to build their customized service oriented components extending features beyond their inbuilt components. Using Adobe LiveCycle ES2 Java API, we can build services that are suitable to our business needs. As part of my research work, I created a Google Docs Connector.

This Google Docs Connector will take Four inputs that includes Google User Name, Password, Document you want to upload, and title of the document. Connector validates the user against the credentials supplied and authorizes to upload the file to the Google Documents.

Once the connector service uploads the document, you can see the document by logging on to Google Docs.

Working with Email Start Points

I have been wondering how the Email Startpoint would work for many months now until last Sunday evening after fighting out hangover whole morning. There aren’t many resources or samples out there in the Internet about Email Startpoint. So I thought I could share a sample application that uses Email startpoint and writes a string in tmp directory.

Requirements:

Email Server, LiveCycle Server, Workbench, etc.

Configuration:

Email startpoint requires POP3 and SMTP configuration parameters of your email server. If you do not have access to an Email Server you can download an open source Email Server (http://www.hmailserver.com/) and follow the instructions provided in their documentation to configure your email server. Create an email account for our LiveCycle server to connect to the Email Server using hMailServer Administrator.

To create an email account on hMail Server, log on to the hMailServer Administrator and navigate to Domains section in the hierarchy. Click on Add button and give a domain name “r3tek.com”. Again click on Add button in the Accounts section under the “r3tek.com” domain you created and provide the required details.

After creating an email account, gather the following details for configuring our Email startpoint (Please see the image below):

1) Inbox Host: localhost

2) Inbox Protocol: pop3

3) Inbox Port: 110

4) Inbox Time Out: 60

5) Inbox User: vanam413@r3tek.com

6) Inbox Password: *******

7) SMTP Host: localhost

8) SMTP Port: 25

9) SMTP User: administrator

10) SMTP Password: password

11) Send From: (optional)

12) SMTP SSL Enabled: (optional)

13) POP3/IMAP SSL Enabled: (optional)

Process Design:

Create a LiveCycle application in workbench, TestEmailStartPoint , with a process “EmailSProcess” that has both Email and Programmatic Start points. Double click on the Email start point and provide the details you gathered from the Email Server. Now to write a string to a file in a directory, drag and drop abstract activity and define it with Write String Service Operation. That’s it. We have created a simple application that uses an email start point and writes a string to a file in the file system.

Test:

To test this process, open the hMailServer Administrator and navigate to Server sendout under Utilities and provide the details as shown in the image below. After clicking “Send”, navigate to the file system location that you have provided in the Write String service operation. You can see the File that LC created and the string in it.

Learn Variables Scope in LiveCycle Process Design

In the process design, we define variables for accessing a value within multiple operations. The value can be any data type (String, int, long, boolean, etc). Besides common datatypes, Adobe LiveCycle ES comes with several Service specific data types such as ReaderExtensionsOptionSpec, RenderOptionSpec, PDFOutputOptionSpec, etc.

A variable in LiveCycle process can be defined in two different purposes - a) Process Varibale b) Configuration Parameter.

We will discuss Process Variables in this tutorial. A variable can be input, output or required type to the process. What does it mean when you say INPUT or OUTPUT variable? If a variable is an input then that variable has to be passed to the process when it is invoked through LiveCycle workbench/web browser. And it is the same case with the OUTPUT variable type. The process would respond with a result of that output variable type.

Now, just like the process variables, we need to define variables for each operation within the process design. If we look at the figure renderPDFForm2 Operation, we need to specify input and and output parameters for this operation. These are different from the above image. LiveCycle beginners can get confused easily with the terms Input variables for process and operations.

The parameters for an operation can be passed in serveral ways like a Literal Value, Variable, X-Path Expression, and Templates. If you choose a variable type for either Input or Output parameter, you need to specify the process variable. In the same figure, formData and outTSPDFForm are two process variables and their parameter type is variable but for Input>>Form parameter the type is Literal Value and you can see the value is a String.

Invoking an Orchestration Process through a Servlet

In this tutorial, we will be primarily focusing on invoking a Short-Lived or Orchestration LiveCycle process through a servlet. To be able to understand the tutorial, one should be familiar with J2EE and LiveCycle Processes. This tutorial gives you the step-by-step procedure that one should follow in order to invoke a short lived process. It starts with the Software/Tools, Orchestration Process Design, introduction of Adobe's proprietary Application Programming Interface, LiveCycle Integration Types, and Invocation steps.

Software/Tools: For the purpose of this tutorial, I used Netbeans, Glassfish 3.0 server, LiveCycle ES2, JBoss server hosting LiveCycle, JDK 1.6, etc.

Orchestration Process Design: Orchestration process is also referred to as Short-lived process. As the name suggests, the purpose of orchestration process is to orchestrate a business process. Generally, it is used to render PDF forms or deliver data to the PDF Form upon user interaction. For extreme simplicity, we will design a process that will take two input strings and returns an out string. Click here to know more about this orchestration process design.

Adobe's Application Programming Interface: Adobe provides API to program with LiveCycle ES2 services. The API is categorized into two types -- a) Java Client Library b) Java Invocation API.

1. Java Client Library serves the purpose to invoke LiveCycle ES2 Services such as Assembler Service API for assembling multiple PDF documents into one file, Forms Service API to render interactive/dynamic/static PDF documents, etc.
2. Java Invocation API would be used to invoke Short-Lived or Human-Centric processes.

LiveCycle Integration Types: Invoking a LiveCycle from a web application can be done in several ways (Remoting for Flex, Java API for J2EE, and WebService API for .net applications).
In this tutorial, we will discuss about Java API Invocation API.

Invocation Steps: We will be using SOAP connection mode.

1. Create a web project and include the following jar files (adobe-livecycle-client, adobe-usermanager-client, adobe-utilities, activation, axis, commons-codec-1.3, commons-discovery, commons-logging, dom3-xml-apis-2.5.0, jaxen-1.1, jaxrpc, log4j, mail, wsdl4j, xalan, xbean, xercesImpl)
2. Create a servlet in your project. In the servlet, define ServiceClientFactory to hold connection properties; create ServiceClient object to establish a connection with LiveCycle server; Create an InvocationRequest object to send an invocation request to livecycle process and retrieving invocation response;

Copy the following code into your servlet and be sure to change the connection properties appropriate to your server settings.


package com.r3tek;

import com.adobe.idp.dsc.DSCException;
import com.adobe.idp.dsc.InvocationRequest;
import com.adobe.idp.dsc.InvocationResponse;
import com.adobe.idp.dsc.clientsdk.ServiceClient;
import com.adobe.idp.dsc.clientsdk.ServiceClientFactory;
import com.adobe.idp.dsc.clientsdk.ServiceClientFactoryProperties;
import java.io.IOException;
import java.io.PrintWriter;
import java.util.HashMap;
import java.util.Map;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class JavaServlet extends HttpServlet {
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
doPost(request, response);
}

protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.setContentType("text/html;charset=UTF-8");
PrintWriter out = response.getWriter();
try {
Properties connectionProps = new Properties();
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_DEFAULT_SOAP_ENDPOINT, "http://192.168.1.37:8080");
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_TRANSPORT_PROTOCOL, ServiceClientFactoryProperties.DSC_SOAP_PROTOCOL);
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_SERVER_TYPE, ServiceClientFactoryProperties.DSC_JBOSS_SERVER_TYPE);
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_USERNAME, "administrator");
connectionProps.setProperty(ServiceClientFactoryProperties.DSC_CREDENTIAL_PASSWORD, "password");
Map params = new HashMap();

params.put("lname", "vanam");
params.put("fname", "Naveen");

ServiceClientFactory factory = ServiceClientFactory.createInstance(connectionProps);
ServiceClient myServiceClient = factory.getServiceClient();
InvocationRequest requestInv = factory.createInvocationRequest(
"TimeSheets/getEmployeeID",
"invoke",
params,
true);
InvocationResponse responseInv = myServiceClient.invoke(requestInv);
String outPut = (String) responseInv.getOutputParameter("employeeID");

out.println("");
out.println("");
out.println("");
out.println("");
out.println("");
out.println("

The Output value " + outPut + "

");
out.println("");
out.println("");

} catch (DSCException ex) {
Logger.getLogger(JavaServlet.class.getName()).log(Level.SEVERE, null, ex);
} finally {
out.close();
}
}
}

In the next tutorial, we will see how to invoke Human-Centric Process. Good Luck!