Invoking LiveCycle using REST Requests

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

  These data types are commonly accepted as input values to processes created in Workbench.

  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.

  If 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 object.

  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.

  Lists 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.

  If 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:

  attributesColor=red

  attributesShape=box

  attributesWidth=5

  This translates into a map of three records: Color=red, Shape=box, and Width=5.

  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)

  The following example is an XML message returned by a service that has a single output parameter named list, which is a list of integers.

  <result>  
      <list>12345</list>  
      . . . 
      <list>67890</list> 
  </result>

  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.

  <result>  
      <A>http://localhost:8080/DocumentManager/docm123/4567</A>  
      . . .  
      <Z>http://localhost:8080/DocumentManager/docm987/6543</Z> 
  </result> 
  

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.

http://localhost:8080/rest/async_invoke/SomeService. SomeOperation?integer_input_variable=123&string_input_variable=abc

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:

http://localhost:8080/rest/async_status/SomeService.SomeOperation?job_id=2345353443366564

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:

http://localhost:8080/rest/async_dispose/SomeService.SomeOperation?job_id=2345353443366564

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.

<exception> 
      <exception_class_name>[ 
      <DSCError> 
         <componentUID>component_UUD</componentUID> 
        <errorCode>error_code</errorCode> 
        <minorCode>minor_code</minorCode> 
        <message>error_message</message> 
      </DSCError> 
]  
      <message>exception_message</message> 
    <stackTrace>exception_stack_trace</stackTrace> 
      </exception_class_name> 
    <exception> 
      </exception> 
</exception>

The DSCError element is optional and present only if the exception is an instance of com.adobe.idp.dsc.DSCException.

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.

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 lease period.

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.

• Distiller service

• Rights Management service

• GeneratePDF service

• Generate3dPDF service

• FormDataIntegration

The following REST invocation examples are provided:

• Passing Boolean values to a process

• Passing date values to a process

• Passing documents to a process

• Passing document and text values to a process

• Passing enumeration values to a process

• Invoking the MyApplication/EncryptDocument process using REST

• Invoking the MyApplication/EncryptDocument process from Acrobat

  Each example demonstrates passing different data types to a LiveCycle process

<html> 
<body> 
 
<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"> 
 
</form> 
 
</body> 
</html>

<html> 
<body> 
 
<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"> 
 
</form> 
 
</body> 
</html>

<html> 
<body> 
 
<form name="input" action="http://localhost:9080/rest/services/MyApplication/EncryptDocument/invoke" method="post"  
         enctype="multipart/form-data"> 
 
File: <input type="file" name="value-to-echo"> 
<input type="submit" value="Submit"/> 
 
</form> 
 
</body> 
</html>

<html> 
<body> 
 
<form name="input" action="http://localhost:9080/rest/services/RestTest3" method="post"  
         enctype="multipart/form-data"> 
 
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"/> 
 
</form> 
 
</body> 
</html>

<html> 
<body> 
 
<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"> 
 
</form> 
 
</body> 
</html>