You're viewing help content for version:

Introduction

You can prefill the fields of an Adaptive form using existing data. When a user opens a form, the values for those fields are prefilled. You can achieve this with adaptive forms with or without a form template or XML schema as the form model. To accomplish this, the user data should be available as a prefill XML in a specific format that adheres to adaptive forms.

The prefill XML structure

An adaptive form can have mix of bound and unbound fields. bound fields are those which are dragged from the Content Finder tab and contain non-empty bindRef property value in the field edit dialog. unbound fields are dragged directly from the Sidekick and have an empty bindRef value. 

Adaptive forms support prefilling of both bound and unbound fields. To achieve this, the prefill XML can include two sections - afBoundedData and afUnBoundedData. The afBoundedData section contains the prefill data for bound fields and panels. This data has to be compliant with the associated form model schema. 

  • For adaptive forms using the XFA form template, the prefill XML should be compliant with the data schema of the XFA template.
  • For adaptive forms using the XML Schema, the prefill XML should be compliant with the schema structure.
  • For adaptive forms with no Form Model, there is no bound data. Every field is an unbound field and is prefilled using the unbound XML.
A typical prefill XML is shown below that will prefill both bound and unbound fields.
<?xml version="1.0" encoding="UTF-8"?>
<afData>
  <afBoundData>
     <employeeData>
        .
     </employeeData>
  </afBoundData>

  <afUnboundData>
    <data>
      <textbox>Hello World</textbox>
         .
         .
      <numericbox>12</numericbox>
         . 
         .              
    </data>
  </afUnboundData>
</afData>

In case of bound fields with same bindref or unbound fields with same name, data specified in the tag is filled in all the fields. For example, two fields in a form are mapped to the name textbox in the prefill xml. During runtime, if the first text box field contains "A", then "A" is automatically filled in the second text box. This is called live linking of adaptive form fields. 

To prevent live linking:

  1. Open Adobe Experience Manager Web Console Configuration.
    URL: http://<server>:<port>/system/console/configMgr

  2. Search and open Adaptive Form Configuration Service. 

  3. In the Adaptive Form Configuration Service dialog, enable Prevent Sync of Same Mapped Fields. When you prevent sync of same mapped fields, at the runtime, you can fill different values in the fields. But in the submit xml, only one value is retained. For example, you fill "A" and "B" in the two fields in the above example. In the submit xml, you see "B" in the textbox tag of the xml.

Now let's take a closer look at each type of adaptive form.

Adaptive form using XFA form template

  • Prefill XML Structure: The prefill XML for XFA-based adaptive form must be compliant with the data schema of the XFA form template. Optionally, it can be wrapped into /afData/afBoundData tag if you want to prefill unbound fields as well.
  • Submitted XML Structure: if no prefill XML is used, the submitted XML contains data for both bound and unbound fields in afData wrapper tag. If a prefill XML is used, the submitted XML has the same structure as the prefill XML. If the prefill XML starts with the afData root tag, the output XML also has the same format. If the prefill XML does not have afData/afBoundData wrapper and instead starts directly from the schema root tag like employeeData, the submitted XML also starts with the employeeData tag.

Download

Sample containing prefill XMLs and XMLs created by submission

XML schema-based adaptive forms 

  • Prefill XML structure: The prefill XML must be compliant to associated XML Schema. Optionally, it can be wrapped into the /afData/afBoundData tag if you want to prefill unbound fields as well.
  • Submitted XML structure: if no prefill XML is used, the submitted XML contains data for both bound and unbound fields in afData wrapper tag. If the prefill XML is used, the submitted XML has the same structure as the prefill XML. If the prefill XML starts with the afData root tag, the output XML has the same format. If the prefill XML does not have afData/afBoundData wrapper and instead start directly from the schema root tag like employeeData, the submitted XML also starts with the employeeData tag.
<?xml version="1.0" encoding="utf-8" ?> 
<xs:schema targetNamespace="http://adobe.com/sample.xsd"
            xmlns="http://adobe.com/sample.xsd"
            xmlns:xs="http://www.w3.org/2001/XMLSchema">
 
    <xs:element name="sample" type="SampleType"/>
         
    <xs:complexType name="SampleType">
        <xs:sequence>
            <xs:element name="noOfProjectsAssigned" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>
</xs:schema>

For fields whose model is XML schema, the data is prefilled in the afBoundedData tag as shown in the sample schema below. It can be used for authoring an adaptive form with one or more unbound text fields.

<?xml version="1.0" encoding="UTF-8"?><afData>
  <afUnboundData>
    <data>
      <textbox>Ignorance is bliss :) </textbox>
    </data>
  </afUnboundData>
  <afBoundData>
    <data>
      <noOfProjectsAssigned>twelve</noOfProjectsAssigned>
    </data>
  </afBoundData>
</afData>

Note:

It is recommended not to use unbound fields in bound panels (panels with non-empty bindRef that has been created by dragging components from Sidekick). It may cause loss of data of these unbound fields. Also, it is recommended that the names of the fields are unique across the form, specially for unbound fields.

<?xml version="1.0" encoding="UTF-8"?><config>
 <assignmentDetails descriptionOfAssignment="Some Science Project" durationOfAssignment="34" financeRelatedProject="1" name="Lisa" numberOfMentees="1"/>
 <assignmentDetails descriptionOfAssignment="Kidding, right?" durationOfAssignment="4" financeRelatedProject="1" name="House" numberOfMentees="3"/>
</config>

Adaptive Form with no Form Model

For adaptive forms with no form model,  the data for all the fields will be under the <data> tag of whose parent is <afUnboundData>.

Also, take note of the following:

  1. The XML tags for the user data submitted for various fields are generated using the name of the fields. Therefore, the field names must be unique.

  2. unbound fields are written in the folder created on submission and in the XML in the jcr:data property of that folder.

<?xml version="1.0" encoding="UTF-8"?><afData>
  <afUnboundData>
    <data>
      <radiobutton>2</radiobutton>
      <repeatable_panel_no_form_model>
        <numericbox>12</numericbox>
      </repeatable_panel_no_form_model>
      <repeatable_panel_no_form_model>
        <numericbox>21</numericbox>
      </repeatable_panel_no_form_model>
      <checkbox>2</checkbox>
      <textbox>Nopes</textbox>
    </data>
  </afUnboundData>
  <afBoundData/>
</afData>

Configuring Prefill Service using Configuration Manager

In order to enable prefill service, you need to specify the Default Prefill Service Configuration in the AEM Web Console Configuration. Use the following steps to configure the Prefill service:

 

  1. Open Adobe Experience Manager Web Console Configuration by using the URL:
    http://<server>:<port>/system/console/configMgr

  2. Search and open Default Prefill Service Configuration

    Prefill_config
  3. Enter the data location or a regex (regular expression) for the Data files locations. Examples of valid Data file locations are:

    • file:///C:/Users/public/Document/Prefill/.*
    • http://localhost:8000/somesamplexmlfile.xml

    Note:

    By default, prefill is allowed through crx files for all types of Adaptive Forms (none, XSD, and XDP). Prefill is allowed only with XML files.

  4. The prefill service is now configured for your form.

    Note:

    The crx protocol takes care of prefilled data security and hence, is allowed by default. Prefilling via other protocols using generic regex might cause vulnerability.  A very secure URL must be specified in the configuration for protecting your data.

The curious case of repeatable panels

Generally, bound (from form template or XML schema) and unbound fields or subforms are authored in the same adaptive form, but the following are a few exceptions in case the bound subforms are repeatable:

  • unbound repeatable panels are not supported for adaptive forms using the XFA form template or XSD.
  • Do not use unbound fields in bound repeatable panels.

Note:

As a rule of thumb, you should not mix bound and unbound fields if they are intersected in data filled by the end user in unbound fields. If possible, you should modify the XML schema or the XFA form template and add an entry for unbided fields, so that it also becomes bound and its data is available like other fields in the XML.

Supported protocols for prefilling user data

Adaptive form can be prefilled using the user data in XML format via the following protocols:

The file:// protocol 

http://localhost:4502/content/forms/af/someAF.html?wcmmode=disabled&dataRef=file:///C:/Users/form-user/Downloads/somesamplexml.xml

The referred file must be on the same server.

The crx:// protocol

http://localhost:4502/content/forms/af/xml.html?wcmmode=disabled&dataRef=crx:///tmp/fd/af/myassets/sample.xml

The specified node must have a property called jcr:data and hold the XML data.

The http:// protocol

http://localhost:4502/content/forms/af/xml.html?wcmmode=disabled&dataRef=http://localhost:8000/somesamplexmlfile.xml

The service:// protocol

http://localhost:4502/content/forms/af/abc.html?wcmmode=disabled&dataRef=service://[SERVICE_NAME]/[IDENTIFIER]
  • SERVICE_NAME refers to the name of the OSGI prefill service. Refer Create and run a prefill service.
  • IDENTIFIER refers to any meta data required by the OSGI prefill service to fetch the prefill data. An example of meta-data could be an identifer to the logged-in user.

Note:

Passing authentication parameters is not supported.

Setting data attribute in slingRequest

You can also set the data attribute in slingRequest, where the data attribute is a string containing XML tags, as shown in the sample code below.

<%
           String dataXML="<afData>" +
                            "<afUnboundData>" +
                                "<dataRoot>" +
                                    "<first_name>"+ "Tyler" + "</first_name>" +
                                    "<last_name>"+ "Durden " + "</last_name>" +
                                    "<gender>"+ "Male" + "</gender>" +
                                    "<location>"+ "Texas" + "</location>" +
                                    "</dataRoot>" +
                            "</afUnboundData>" +
                        "</afData>";
        slingRequest.setAttribute("data", dataXML);
%>

You can write a simple XML string containing all your data and set it in slingRequest. This can easily be done in your renderer JSP for any component, which you want to include in the page where you can set the slingRequest data attribute.

Let's take an example where you want a specific design for your page with a specific type of header. To achieve this, you can write your own header.jsp, which you can include in your page component and set the data attribute. 

Another good example is a use case where you'd like to prefill data on login through social accounts like Facebook, Twitter, or LinkedIn. In this case, you can include a simple JSP in header.jsp, which fetches data from the user account and sets the data parameter.

Download

Sample prefill.jsp in page component

AEM Forms prefill service

You can use the prefill service for the scenarios, where you constantly read data from a pre-defined data xml (prefill XML). The prefill service reads a data xml (prefill XML) file stored in crx-repository and prefills the fields of the adaptive form with the content of the prefill XML file. It also helps you permanently associate a prefill XML with an adaptive form.  

Create and run a prefill service

The prefill service is an OSGi bundle. You create the OSGi bundle, upload, and install it to AEM Forms bundles. Before you get started with creating the bundle:

Create a prefill service

The boilerplate package (sample prefill service package) contains sample implementation of AEM Forms prefill service. Open the boilerplate package in a code editor. For example, open the boilerplate project in Eclipse for editing. After you open the boilerplate package in a code editor, perform the following steps to create the service.

  1. Open the src\main\java\com\adobe\test\Prefill.java file for editing.

  2. In the code, set value of:

    • nodePath: The nodepath variable crx-repository contains path of the data xml (prefill XML) file. For example, /content/prefillservice.xml
    • label: The label parameter specifies display name of the service
  3. Save and close the Prefill.java file.

  4. Add the AEM 6.2 Forms Client SDK package to the build path of the boilerplate project.

  5. Compile the project and create the .jar for the bundle.

Start and use the prefill service

To start the prefill service, upload the JAR file to AEM Forms Web Console, and activate the service. Now, the service start appearing in adaptive forms editor. To associate a prefill service to an adaptive form:

  1. Open the adaptive form in forms editor and open properties panel for Form Container.

  2. In the properties console, navigate to AEM Forms container > Basic > prefill service.

  3. Select the prefill service and click save. The service is associated to the form.

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy