Invoking AEM Forms using REST Requests invoking-aem-forms-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 Forms 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 Forms 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 AJAX client that is written in JavaScript. The second client is 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 Forms 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 AEM forms user name and password. However, if you do not want to specify a user name and password, you can disable service security.

To invoke a Forms service (a process becomes a service when the process is activated) using REST, configure a REST endpoint. (See “Managing Endpoints” in administration help.)

After a REST endpoint is configured, you can invoke a Forms service by using an HTTP GET method or a POST method.

 action="https://hiro-xp:8080/rest/services/[ServiceName]/[OperationName]:[ServiceVersion]" method="post" enctype="multipart/form-data"

The mandatory ServiceName value is the name of the Forms 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 supported-data-types

The following data types are supported when invoking AEM Forms services using REST requests:

Asynchronous invocations asynchronous-invocations

Some AEM Forms 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.)

An AEM Forms 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.)

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.

Error reporting error-reporting

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

Security and authentication security-and-authentication

To provide REST invocations with a secure transport, a AEM forms administrator can enable the HTTPS protocol on the J2EE application server hosting AEM Forms. This configuration is specific to the J2EE application server; it is not part of the forms server configuration.

AEM Forms services that support REST invocation aem-forms-services-that-support-rest-invocation

Although it is recommended that you invoke processes created using Workbench as opposed to services directly, there are some AEM Forms 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 AEM Forms services that support direct REST invocation.

REST invocation examples 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 an AEM Forms 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.

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

Passing date values to a process

The following HTML example passes a date value to an AEM Forms process named SOAPEchoService. The name of the invocation method is echoCalendar. Notice that the HTML Post method is used.

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

Passing documents to a process

The following HTML example invokes an AEM Forms process named MyApplication/EncryptDocument that requires a PDF document. For information about this process, see Invoking AEM Forms using MTOM.

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

Passing document and text values to a process

The following HTML example invokes an AEM Forms process named RestTest3 that requires a document and two text values. Notice that the HTML Post method is used.

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

Passing enumeration values to a process

The following HTML example invokes an AEM Forms process named SOAPEchoService that requires an enumeration value. Notice that the HTML Post method is used.

 <html>
 <body>

 <form name="input" action="https://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>

Invoking the MyApplication/EncryptDocument process using REST

You can invoke an AEM Forms short-lived process named MyApplication/EncryptDocument by using REST.

When this process is invoked, it performs the following actions:

Invoking the MyApplication/EncryptDocument process from Acrobat

You can invoke a Forms process from Acrobat by using a REST request. For example, you can invoke the MyApplication/EncryptDocument process. To invoke a Forms process from Acrobat, place a submit button on a XDP file within Designer. (See Designer Help.)

Specify the 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 https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.

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

You can also submit form data as XML to a Forms 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.