AEM 6.4 has reached the end of extended support and this documentation is no longer updated. For further details, see our technical support periods. Find the supported versions here.
Web-based applications that enable a user to fill in interactive forms require the data to be submitted back to the server. Using the Forms service, you can retrieve the data that the user entered into an interactive form. After you retrieve the data, you can process the data to meet your business requirements. For example, you can store the data in a database, send the data to another application, send the data to another service, merge the data in a form design, display the data in a web browser, and so on.
Form data is submitted to the Forms service as either XML or PDF data, which is an option that is set in Designer. A form that is submitted as XML enables you to extract individual field data values. That is, you can extract the value of each form field that the user entered into the form. A form that is submitted as PDF data is binary data, not XML data. You can save the form as a PDF file, or send the form to another service. If you want to extract data from a form submitted as XML and then use the form data to create a PDF document, invoke another AEM Forms operation. (See Creating PDF Documents with Submitted XML Data)
The following diagram shows data being submitted to a Java Servlet named HandleData
from an interactive form displayed in a web browser.
The following table explains the steps in the diagram.
Step |
Description |
---|---|
1 |
A user fills in an interactive form and clicks the form’s Submit button. |
2 |
Data is submitted to the |
3 |
The |
When form data is submitted as XML, you can retrieve XML data that represents the submitted data. All form fields appear as nodes in an XML schema. The node values correspond to the values that the user filled in. Consider a loan form where each field in the form appears as a node within the XML data. The value of each node corresponds to the value that a user fills in. Assume a user fills the loan form with data shown in the following form.
The following illustration shows corresponding XML data that is retrieved by using the Forms service Client API.
The fields in the loan form. These values can be retrieved
using Java XML classes.
The form design must be configured correctly in Designer for data to be submitted as XML data. To properly configure the form design to submit XML data, ensure that the Submit button that is located on the form design is set to submit XML data. For information about setting the Submit button to submit XML data, see AEM Forms Designer.
Consider a web application that invokes the Forms service. After the Forms service renders an interactive PDF form to a client web browser, the user fills in the form and submits it back as PDF data. When the Forms service receives the PDF data, it can send the PDF data to another service or save it as a PDF file. The following diagram shows the application’s logic flow.
The following table describes the steps in this diagram.
Step |
Description |
---|---|
1 |
A web page contains a link that accesses a Java Servlet that invokes the Forms service. |
2 |
The Forms service renders an interactive PDF form to the client web browser. |
3 |
The user fills in an interactive form and clicks a submit button. The form is submitted back to the Forms service as PDF data. This option is set in Designer. |
4 |
The Forms service saves the PDF data as a PDF file. |
If form data is submitted as URL UTF-16 data, the client computer requires Adobe Reader or Acrobat 8.1 or later. Also if the form design contains a submit button that has URL-encoded Data (HTTP Post) and the data encoding option is UTF-16, the form design must be modified in a text editor such as Notepad. You can set the encoding option to either UTF-16LE
or UTF-16BE
for the submit button. Designer does not provide this functionality.
For more information about the Forms service, see Services Reference for AEM Forms.
To handle submitted forms, perform the following tasks:
Include project files
Include necessary files into your development project. If you are creating a client application using Java, include the necessary JAR files. If you are using web services, ensure that you include the proxy files.
Create a Forms Client API object
Before you can programmatically perform a Forms service Client API operation, you must create a Forms service client. If you are using the Java API, create a FormsServiceClient
object. If you are using the Forms web service API, create a FormsService
object.
Retrieve form data
To retrieve submitted form data, you invoke the FormsServiceClient
object’s processFormSubmission
method. When invoking this method, you have to specify the submitted form’s content type. When data is submitted from a client web browser to the Forms service, it can be submitted as either XML or PDF data. To retrieve the data that is entered into form fields, the data can be submitted as XML data.
You can also retrieve form fields from a form submitted as PDF data by setting the following run-time options:
processFormSubmission
method as the content type parameter: CONTENT_TYPE=application/pdf
.RenderOptionsSpec
object’s PDFToXDP
value to true
RenderOptionsSpec
object’s ExportDataFormat
value to XMLData
You specify the content type of the submitted form when you invoke the processFormSubmission
method. The following list specifies applicable content type values:
You will notice that there are three corresponding quick starts associated with the Handling Submitted Forms section. The Handling PDF forms submitted as PDF using the Java API quick start demonstrates how to handle submitted PDF data. The content type specified in this quick start is application/pdf
. The Handling PDF forms submitted as XML using the Java API quick start demonstrates how to handle submitted XML data that is submitted from a PDF form. The content type specified in this quick start is text/xml
. Likewise, the Handling HTML forms submitted as XML using the Java API quick start demonstrates how to handle submitted XML data that is submitted from an HTML form. The content type specified in this quick start is application/x-www-form-urlencoded.
You retrieve form data that was posted to the Forms service and determine its processing state. That is, when data is submitted to the Forms service, it does not necessarily mean that the Forms service is finished processing the data and the data is ready to be processed. For example, data can be submitted to the Forms service so that a calculation can be performed. When the calculation is complete, the form is rendered back to the user with the calculation results displayed. Before you process submitted data, it is recommended that you determine whether the Forms service has finished processing the data.
The Forms service returns the following values to indicate whether it has finished processing the data:
Calculations and validations must be rendered back to the user. (See Calculating Form Data.)
Determine if the form submission contains file attachments
Forms submitted to the Forms service can contain file attachments. For example, using Acrobat’s built-in attachment pane, a user can select file attachments to submit along with the form. As well, a user can also select file attachments using an HTML toolbar that is rendered with an HTML file.
After you determine if a form contains file attachments, you can process the data. For example, you can save the file attachment to the local file system.
The form must be submitted as PDF data in order to retrieve file attachments. If the form is submitted as XML data, file attachments are not submitted.
Process the submitted data
Depending on the content type of the submitted data, you can extract individual form field values from the submitted XML data or save the submitted PDF data as a PDF file (or send it to another service). To extract individual form fields, convert submitted XML data to an XML data source and then retrieve XML data source values by using org.w3c.dom
classes.
See also
Including AEM Forms Java library files
Forms Service API Quick Starts
Passing Documents to the Forms Service
Creating Web Applications that Renders Forms
Handle a submitted form by using the Forms API (Java):
Include project files
Include client JAR files, such as adobe-forms-client.jar, in your Java project’s class path.
Create a Forms Client API object
ServiceClientFactory
object that contains connection properties.FormsServiceClient
object by using its constructor and passing the ServiceClientFactory
object.Retrieve form data
com.adobe.idp.Document
object by using its constructor and invoking the javax.servlet.http.HttpServletResponse
object’s getInputStream
method from within the constructor.RenderOptionsSpec
object by using its constructor. Set the locale value by invoking the RenderOptionsSpec
object’s setLocale
method and passing a string value that specifies the locale value.You can instruct the Forms service to create XDP or XML data from submitted PDF content by invoking the RenderOptionsSpec
object’s setPDF2XDP
method and passing true
and also calling setXMLData
and passing true
. You can then invoke the FormsResult
object’s getOutputXML
method to retrieve the XML data that corresponds to the XDP/XML data. (The FormsResult
object is returned by the processFormSubmission
* method, which is explained in the next sub-step.)*
Invoke the FormsServiceClient
object’s processFormSubmission
method and pass the following values:
com.adobe.idp.Document
object that contains the form data.CONTENT_TYPE=text/xml
. To handle PDF data, specify the following string value for this parameter: CONTENT_TYPE=application/pdf
.HTTP_USER_AGENT
header value, for example, . Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)
. This parameter value is optional.RenderOptionsSpec
object that stores run-time options.The processFormSubmission
method returns a FormsResult
object containing the results of the form submission.
Determine whether the Forms service is finished processing the form data by invoking the FormsResult
object’s getAction
method. If this method returns the value 0
, the data is ready to be processed.
Determine if the form submission contains file attachments
FormsResult
object’s getAttachments
method. This method returns a java.util.List
object that contains files that were submitted with the form.java.util.List
object to determine if there are file attachments. If there are file attachments, each element is a com.adobe.idp.Document
instance. You can save the file attachments by invoking the com.adobe.idp.Document
object’s copyToFile
method and passing a java.io.File
object.This step is only applicable if the form is submitted as PDF.
Process the submitted data
If the data content type is application/vnd.adobe.xdp+xml
or text/xml
, create application logic to retrieve XML data values.
com.adobe.idp.Document
object by invoking the FormsResult
object’s getOutputContent
method.java.io.InputStream
object by invoking the java.io.DataInputStream
constructor and passing the com.adobe.idp.Document
object.org.w3c.dom.DocumentBuilderFactory
object by calling the static org.w3c.dom.DocumentBuilderFactory
object’s newInstance
method.org.w3c.dom.DocumentBuilder
object by invoking the org.w3c.dom.DocumentBuilderFactory
object’s newDocumentBuilder
method.org.w3c.dom.Document
object by invoking the org.w3c.dom.DocumentBuilder
object’s parse
method and passing the java.io.InputStream
object.org.w3c.dom.Document
object and the name of the node whose value you want to retrieve. This method returns a string value representing the value of the node. In the code example that follows this process, this custom method is called getNodeText
. The body of this method is shown.If the data content type is application/pdf
, create application logic to save the submitted PDF data as a PDF file.
com.adobe.idp.Document
object by invoking the FormsResult
object’s getOutputContent
method.java.io.File
object by using its public constructor. Be sure to specify PDF as the file name extension.com.adobe.idp.Document
object’s copyToFile
method and passing the java.io.File
object.See also
Quick Start (SOAP mode): Handling PDF forms submitted as XML using the Java API
Quick Start (SOAP mode): Handling HTML forms submitted as XML using the Java API
Quick Start (SOAP mode): Handling PDF forms submitted as PDF using the Java API
Including AEM Forms Java library files
Handle a submitted form by using the Forms API (web service):
Include project files
Create a Forms Client API object
Create a FormsService
object and set authentication values.
Retrieve form data
To retrieve form data that was posted to a Java Servlet, create a BLOB
object by using its constructor.
Create a java.io.InputStream
object by invoking the javax.servlet.http.HttpServletResponse
object’s getInputStream
method.
Create a java.io.ByteArrayOutputStream
object by using its constructor and passing the length of the java.io.InputStream
object.
Copy the contents of the java.io.InputStream
object into the java.io.ByteArrayOutputStream
object.
Create a byte array by invoking the java.io.ByteArrayOutputStream
object’s toByteArray
method.
Populate the BLOB
object by invoking its setBinaryData
method and passing the byte array as an argument.
Create a RenderOptionsSpec
object by using its constructor. Set the locale value by invoking the RenderOptionsSpec
object’s setLocale
method and passing a string value that specifies the locale value.
Invoke the FormsService
object’s processFormSubmission
method and pass the following values:
BLOB
object that contains the form data.CONTENT_TYPE=text/xml
. To handle PDF data, specify the following string value for this parameter: CONTENT_TYPE=application/pdf
.HTTP_USER_AGENT
header value; for example, Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)
.RenderOptionsSpec
object that stores run-time options.BLOBHolder
object that is populated by the method.javax.xml.rpc.holders.StringHolder
object that is populated by the method.BLOBHolder
object that is populated by the method.BLOBHolder
object that is populated by the method.javax.xml.rpc.holders.ShortHolder
object that is populated by the method.MyArrayOf_xsd_anyTypeHolder
object that is populated by the method. This parameter is used to store file attachments that are submitted along with the form.FormsResultHolder
object that is populated by the method with the form that is submitted.The processFormSubmission
method populates the FormsResultHolder
parameter with the results of the form submission.
Determine whether the Forms service is finished processing the form data by invoking the FormsResult
object’s getAction
method. If this method returns the value 0
, the form data is ready to be processed. You can get a FormsResult
object by getting the value of the FormsResultHolder
object’s value
data member.
Determine if the form submission contains file attachments
Get the value of the MyArrayOf_xsd_anyTypeHolder
object’s value
data member (the MyArrayOf_xsd_anyTypeHolder
object was passed to the processFormSubmission
method). This data member returns an array of Objects
. Each element within the Object
array is an Object
that corresponds to the files that were submitted along with the form. You can get each element within the array and cast it to a BLOB
object.
Process the submitted data
If the data content type is application/vnd.adobe.xdp+xml
or text/xml
, create application logic to retrieve XML data values.
BLOB
object by invoking the FormsResult
object’s getOutputContent
method.BLOB
object’s getBinaryData
method.java.io.InputStream
object by invoking the java.io.ByteArrayInputStream
constructor and passing the byte array.org.w3c.dom.DocumentBuilderFactory
object by calling the static org.w3c.dom.DocumentBuilderFactory
object’s newInstance
method.org.w3c.dom.DocumentBuilder
object by invoking the org.w3c.dom.DocumentBuilderFactory
object’s newDocumentBuilder
method.org.w3c.dom.Document
object by invoking the org.w3c.dom.DocumentBuilder
object’s parse
method and passing the java.io.InputStream
object.org.w3c.dom.Document
object and the name of the node whose value you want to retrieve. This method returns a string value representing the value of the node. In the code example that follows this process, this custom method is called getNodeText
. The body of this method is shown.If the data content type is application/pdf
, create application logic to save the submitted PDF data as a PDF file.
BLOB
object by invoking the FormsResult
object’s getOutputContent
method.BLOB
object’s getBinaryData
method.java.io.File
object by using its public constructor. Be sure to specify PDF as the file name extension.java.io.FileOutputStream
object by using its constructor and passing the java.io.File
object.java.io.FileOutputStream
object’s write
method and passing the byte array.See also
Invoking AEM Forms using Base64 encoding