Invoking LiveCycle using REST Requests
Processes created in Workbench can be configured so that
you can invoke them through Representational State Transfer (REST)
requests. REST requests are sent from HTML pages. That is, you can
invoke a LiveCycle process directly from a web page using
a REST request. For example, you can open a new instance of a web
page. Then you can invoke a LiveCycle process and load a
rendered PDF document with data that was sent in an HTTP POST request.
Two types of HTML clients exist. The first HTML client is an
an HTML form that contains a submit button. An HTML-based client
application is not the only possible REST client. Any client application
that supports HTTP requests can invoke a service using a REST invocation.
For example, you can invoke a service by using a REST invocation
from a PDF form. (See Invoking the MyApplication/EncryptDocument process from Acrobat.)
When using REST requests, it is recommended that you do not invoke LiveCycle services directly. Instead, invoke processes that were
created in Workbench. When creating a process that is meant for
REST invocation, use a programmatic start point. In this situation,
the REST endpoint is added automatically. For information about
creating processes in Workbench, see Using Workbench.
When you invoke a service using REST, you are prompted for a
LiveCycle user name and password. However, if you do not
want to specify a user name and password, you can disable service
security. (See Disabling Service Security.)
To invoke a LiveCycle service (a process becomes a service
when the process is activated) using REST, configure a REST endpoint.
(See “Managing Endpoints” in LiveCycle Administration Help.)
After a REST endpoint is configured, you can invoke a LiveCycle service by using an HTTP GET method or a POST method.
action="http://hiro-xp:8080/rest/services/[ServiceName]/[OperationName]:[ServiceVersion]" method="post" enctype="multipart/form-data"
The mandatory ServiceName value is the name
of the LiveCycle service to invoke. The optional OperationName value
is the name of the service’s operation. If this value is not specified,
this name defaults to invoke, which is the operation
name that starts the process. The optional ServiceVersion value
is the version encoded in the X.Y format. If this value is not specified,
the most current version is used. The enctype value
can also be application/x-www-form-urlencoded.
Supported data types
The following data types are supported when invoking LiveCycle services using REST requests:
Java primitive data types, such as Strings and integers
com.adobe.idp.Document data type
XML data types such as org.w3c.Document and org.w3c.Element
Collection objects such as java.util.List and java.util.Map
data types are commonly accepted as input values to processes created
If a LiveCycle service is invoked with
the HTTP POST method, the arguments are passed inside the HTTP request
body. If the LiveCycle service’s signature has a string
input parameter, the request body can contain the text value of
the input parameter. If the service’s signature defines multiple
string parameters, the request can follow the HTTP’s application/x-www-form-urlencoded notation
with the parameter’s names used as the form’s field names.
a LiveCycle service returns a string parameter, the result
is a textual representation of the output parameter. If a service
returns multiple string parameters, the result is an XML document
encoding the output parameters in the following format:
<result> <output-paramater1>output-parameter-value-as-string</output-paramater1> . . . <output-paramaterN>output-parameter-value-as-string</output-paramaterN> </result>
Note: The output-paramater1 value represents
the output parameter name.
If a LiveCycle service
requires a com.adobe.idp.Document parameter, the
service can only be invoked using the HTTP POST method. If the service
requires one com.adobe.idp.Document parameter,
the HTTP request body becomes the content of the input Document
If a LiveCycle service requires multiple input
parameters, the HTTP request body must be a multipart MIME message
as defined by RFC 1867. (RFC 1867 is a standard used by web browsers
to upload files to websites.) Each input parameter must be sent
as a separate part of the multipart message and encoded in the multipart/form-data format.
The name of each part must match the parameter’s name.
and maps are also used as input values to LiveCycle processes
created in Workbench. As a result, you can use these data types when
using a REST request. Java arrays are not supported because they
are not used as an input value to a LiveCycle process.
an input parameter is a list, a REST client can send it by specifying
the parameter multiple times (once for each item in the list). For
example, if A is a list of documents, the input must be a multipart
message consisting of multiple parts named A. In this case, each
part named A becomes an item in the input list. If B is a list of
strings, the input can be an application/x-www-form-urlencoded message
consisting of multiple fields named B. In this case, each form field named
B becomes an item in the input list.
If an input parameter
is a map and it is the services only input parameter, then every
part/field of the input message becomes a key/value record in the map.
The name of each part/field becomes the record’s key. The content
of each part/field becomes the record’s value.
If an input
map is not the services only input parameter, then each key/value
record that belongs to the map can be sent using a parameter named
as a concatenation of the parameter name and the record’s key. For example,
an input map called attributes can be sent with
a list of the following key/values pairs:
translates into a map of three records: Color=red, Shape=box,
The output parameters of the
list and map types become part of the resultant XML message. The
output list is represented in XML as a series of XML elements with
one element for each item in the list. Every element is given the same
name as the output list parameter. The value of each XML element
is one of two things:
A text representation of the item in the list (if the list
consists of string types)
A URL that points to the content of Document (if the list
consists of com.adobe.idp.Document objects)
following example is an XML message returned by a service that has a
single output parameter named list, which is a list of integers.
. . .
An output map parameter is represented
in the resultant XML message as a series of XML elements with one
element for each record in the map. Every element is given the same
name as the map record’s key. The value of each element is either
a text representation of the map record’s value (if the map consists
of records with a string value) or a URL pointing to the Document’s content
(if the map consists of records with the com.adobe.idp.Document value).
Below is an example of an XML message returned by a service that
has a single output parameter named map. This parameter
value is a map consisting of records that associate letters with com.adobe.idp.Document objects.
. . .
Some LiveCycle services, such as human-centric
long-lived processes, require a long time to complete. These services
can be invoked asynchronously in a non-blocking manner. (See Invoking Human-Centric Long-Lived Processes.)
A LiveCycle service can be invoked asynchronously by
substituting services with async_invoke in
the invocation URL, as shown in the following example.
This URL returns the identifier value (in “text/plain” format)
of the job responsible for this invocation.
The status of the asynchronous invocation can be retrieved by
using an invocation URL with services substituted
with async_status. The URL must contain a job_id parameter
specifying the identifier value of the job associated with this
invocation. For example:
This URL returns an integer value (in “text/plain” format) encoding
the job status according to the Job Manager’s specification (for
example, 2 means running, 3 means completed, 4 means failed, and
so on.) (See Retrieving the Status of a LiveCycle Job.)
If the job is completed, the URL returns the same result as if
the service was invoked synchronously.
Once the job is completed and the result is retrieved, the job
can disposed of by using an invocation URL with services is
substituted with async_dispose. The URL should
also contain a job_id parameter specifying the
identifier value of the job. For example:
If the job is successfully disposed of, this URL returns an empty message.
If a synchronous or asynchronous invocation request cannot
be completed due to an exception being thrown on the server, the
exception is reported as part of the HTTP response message. If the
invocation URL (or the async_result URL in the
case of an asynchronous invocation) does not have an .xml suffix,
the REST Provider returns the HTTP code 500 Internal Server Error followed
by an exception message.
If the invocation URL (or the async_result URL
in the case of an asynchronous invocation) does have an .xml suffix,
the REST Provider returns the HTTP code 200 OK followed
by an XML document describing the exception in the following format.
The DSCError element is optional and present
only if the exception is an instance of com.adobe.idp.dsc.DSCException.
Security and authentication
To provide REST invocations with a secure transport, a
LiveCycle administrator can enable the HTTPS protocol on
the J2EE application server hosting LiveCycle. This configuration
is specific to the J2EE application server; it is not part of the
LiveCycle server configuration.
Note: As a Workbench developer that wants to expose
your processes through a REST endpoint, keep in mind the XSS vulnerability
issue. XSS vulnerabilities can be used to steal or manipulate cookies,
modify presentation of content, and compromise confidential information.
It is recommended that you extend the process logic with the additional
input and output data validation rules if XSS vulnerability is an
LiveCycle services that support REST invocation
Although it is recommended that you invoke processes created using
Workbench as opposed to services directly, there are some LiveCycle services that do support REST invocation. The reason why it is recommended
that you invoke a process as opposed to a service directly is because
it is more efficient to invoke a process. Consider the following
scenario. Assume that you want to create a policy from a REST client.
That is, you want the REST client to define values such as the policy
name, the offline lease period.
To create a policy, you have to define complex data types such
as a PolicyEntry object. A PolicyEntry object
defines attributes such as permissions associated with the policy.
(See Creating Policies.)
Instead of sending a REST request to create a policy (which would
include defining complex data types such as a PolicyEntry object),
create a process that creates a policy using Workbench. Define the process
to accept primitive input variables such as a string value that
defines the process name or an integer that defines the offline
This way, you do not have to create a REST invocation request
that includes complex data types that required by the operation.
The process defines the complex data types and all you do from the
REST client is invoke the process and pass primitive data types.
For information about invoking a process using REST, see Invoking the MyApplication/EncryptDocument process using REST.
The following lists specifies those LiveCycle services
that support direct REST invocation.
REST invocation examples
The following REST invocation examples are provided:
Passing Boolean values to a process
The following HTML example
passes two Boolean values to a LiveCycle
process named RestTest2. The name of the invocation
method is invoke and the version is 1.0. Notice
that the HTML Post method is used.
<form name="input" action="http://localhost:9080/rest/services/RestTest2/invoke/1.0" method="post">
Boolean 1: <input type="text" name="inBooleanList" value="true">
Boolean 2: <input type="text" name="inBooleanList" value="false">
<input type="submit" value="Submit">
Passing date values to a process
The following HTML example passes
a date value to a LiveCycle process named SOAPEchoService.
The name of the invocation method is echoCalendar.
Notice that the HTML Post method is used.
<form name="input" action="http://localhost:9080/rest/services/SOAPEchoService/echoCalendar" method="post">
Date: <input type="text" name="value-to-echo" value="2009-01-02T12:15:30Z">
<input type="submit" value="Submit">
Passing documents to a process
The following HTML example invokes
a LiveCycle process named MyApplication/EncryptDocument that
requires a PDF document. For information about this process, see Invoking LiveCycle using MTOM.
<form name="input" action="http://localhost:9080/rest/services/MyApplication/EncryptDocument/invoke" method="post"
File: <input type="file" name="value-to-echo">
<input type="submit" value="Submit"/>
Passing document and text values to a process
The following HTML
example invokes a LiveCycle process named RestTest3 that
requires a document and two text values. Notice that the HTML Post
method is used.
<form name="input" action="http://localhost:9080/rest/services/RestTest3" method="post"
Doc: <input type="file" name="inDoc">
String 1: <input type="text" name="inListOfStrings" value="hello">
String 2: <input type="text" name="inListOfStrings" value="privet">
<input type="submit" value="Submit"/>
Passing enumeration values to a process
The following HTML example
invokes a LiveCycle process named SOAPEchoService that
requires an enumeration value. Notice that the HTML Post method
<form name="input" action="http://hiro-xp:8080/rest/services/SOAPEchoService/echoEnum" method="post">
Color Enum Value: <input type="text" name="value-to-echo" value="green">
<input type="submit" value="Submit">
Invoking the MyApplication/EncryptDocument process using REST
can invoke a LiveCycle short-lived process named MyApplication/EncryptDocument by
This process is not based on
an existing LiveCycle process. To follow along with the
code example, create a process named MyApplication/EncryptDocument
LiveCycle Workbench. (See Using Workbench
process is invoked, it performs the following actions:
Obtains the unsecured PDF document that is passed to the process.
This action is based on the SetValue operation.
The input parameter for this process is a document process
variable named inDoc.
Encrypts the PDF document with a password. This action is
based on the PasswordEncryptPDF operation. The
password encrypted PDF document is returned in a process variable
When this process is invoked
using a REST request, the encrypted PDF document is displayed in
the web browser. Before you view the PDF document, you specify the
password (unless security is disabled). The following HTML code
represents a REST invocation request to the MyApplication/EncryptDocument process.
<form action="http://hiro-xp:8080/rest/services/MyApplication/EncryptDocument" method="post" enctype="multipart/form-data">
<p>Chose a PDF file (.pdf) to send to the EncryptDocument process.</p>
<input type="file" name="inDoc" />
Invoking the MyApplication/EncryptDocument process from Acrobat
can invoke a LiveCycle process from Acrobat by using a REST request.
For example, you can invoke the MyApplication/EncryptDocument process.
To invoke a LiveCycle process from Acrobat, place a submit
button on a XDP file within Designer. (See Designer Help.)
URL to invoke the process within the button’s Submit to URL field,
as shown in the following illustration.
The complete URL
to invoke the process is http://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.
the process requires a PDF document as an input value, ensure that
you submit the form as PDF, as shown in the previous illustration.
Also, to successfully invoke a process, the process must return
a PDF document. Otherwise Acroabt cannot handle the return value
and an error occurs. You do not have to specify the name of the
input process variable. For example, the MyApplication/EncryptDocument process
has an input variable named inDoc. You do not have
to specify inDoc, as long as the form is submited as PDF.
can also submit form data as XML to a a LiveCycle process,
To submit XML data, ensure that the Submit As drop
down specifies XML. Because the return value of the process must
be a PDF document, the PDF document is displayed in Acrobat.