Create a custom Submit Action for Adaptive Forms writing-custom-submit-action-for-adaptive-forms

Version
Article link
AEM 6.5
Click here
AEM as a Cloud Service
This article

An Adaptive Form provides multiple Submit Actions out-of-the-box (OOTB). A Submit Action specifies details of the actions to be performed on the data collected via the Adaptive Form. For example, sending data on an email.

You can create a custom Submit Action to add functionality not included in out-of-the-box Submit Actions or not supported via a single OOTB Submit Action. For example, submitting data to a workflow, saving the data on a data store, sending email notification to the person submitting the form, and sending an email to person responsible for processing the submitted form for approvals and rejections through a single Submit Action.

XML data format xml-data-format

The XML data is sent to the servlet using the jcr:data request parameter. Submit Actions can access the parameter to process the data. The following code describes the format of the XML data. The fields that are bound to the Form model appear in the afBoundData section. Unbound fields appear in the afUnoundDatasection.

<?xml ?>
<afData>
<afUnboundData>
<data>
<field1>value</field2>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
</data>
</afUnboundData>
<afBoundData>
<!-- xml corresponding to the Form Model /XML Schema -->
</afBoundData>
</afData>

Action fields action-fields

A Submit Action can add hidden input fields (using the HTML input tag) to the rendered form HTML. These hidden fields can contain values that it needs while processing form submission. When submitting the form, these field values are posted back as request parameters that the Submit Action can use during submission handling. The input fields are called action fields.

For example, a Submit Action that also captures the time taken to fill a form can add the hidden input fields startTime and endTime.

A script can supply the values of the startTime and endTime fields when the form renders and before form submission, respectively. The Submit Action script post.jsp can then access these fields using request parameters and compute the total time required to fill the form.

File attachments file-attachments

Submit Actions can also use the file attachments you upload using the File Attachment component. Submit Action scripts can access these files using the sling RequestParameter API. The isFormField method of the API helps identify whether the request parameter is a file or a form field. You can iterate over the Request parameters in a Submit Action to identify File Attachment parameters.

The following sample code identifies the file attachments in the request. Next, it reads the data into the file using the Get API. Finally, it creates a Document object using the data and appends it to a list.

RequestParameterMap requestParameterMap = slingRequest.getRequestParameterMap();
for (Map.Entry<String, RequestParameter[]> param : requestParameterMap.entrySet()) {
    RequestParameter rpm = param.getValue()[0];
    if(!rpm.isFormField()) {
        fileAttachments.add(new Document(rpm.get()));
    }
}

When you attach files to the Adaptive Form, the server validates the file attachments after Adaptive Form submission and returns an error message if:

  • File attachments include a filename that starts with (.) character, contains \ / : * ? " < > | ; % $ characters, or contains special filenames reserved for Windows operating system such as nul, prn, con, lpt, or com.

  • Size of the file attachment is 0 bytes.

  • The format of the file attachment is not defined in the Supported File Types section while configuring the File Attachment component in an Adaptive Form.

Forward path and Redirect URL forward-path-and-redirect-url

After performing the required action, the Submit servlet forwards the request to the forward path. An action uses the setForwardPath API to set the forward path in the Guide Submit servlet.

If the action does not provide a forward path, the Submit servlet redirects the browser using the Redirect URL. The author configures the Redirect URL using the Thank You Page configuration in the Adaptive Form Edit dialog. You can also configure the Redirect URL through the Submit Action or the setRedirectUrl API in the Guide Submit servlet. You can also configure the Request parameters sent to the Redirect URL using the setRedirectParameters API in the Guide Submit servlet.

NOTE
An author provides the Redirect URL (using the Thank You Page Configuration). OOTB Submit Actions use the Redirect URL to redirect the browser from the resource that the forward path references.
You can write a custom Submit Action that forwards a request to a resource or servlet. Adobe recommends that the script that performs resource handling for the forward path redirect the request to the Redirect URL when the processing completes.

Submit Action submit-action

A Submit Action is a sling:Folder that includes the following:

  • addfields.jsp: This script provides the action fields that are added to the HTML file during rendition. Use this script to add hidden input parameters required during submission in the post.POST.jsp script.

  • dialog.xml: This script is similar to the CQ Component dialog. It provides configuration information that the author customizes. The fields are displayed in the Submit Actions Tab in the Adaptive Form Edit dialog when you select the Submit Action.

  • post.POST.jsp: The Submit servlet calls this script with the data that you submit and the additional data in the previous sections. Any mention of running an action in this page implies running the post.POST.jsp script. To register the Submit Action with the Adaptive Forms to display in the Adaptive Form Edit dialog, add these properties to the sling:Folder:

    • guideComponentType of type String and value fd/af/components/guidesubmittype

    • guideDataModel of type String that specifies the type of Adaptive Form for which the Submit Action is applicable. xsd is supported for XSD-based Adaptive Forms. basic is supported for Adaptive Forms that do not use XDP or XSD. To display the action on multiple types of Adaptive Forms, add the corresponding strings. Separate each string by a comma. For example, to make an action visible on XSD-based Adaptive Forms, specify the value as xsd.

    • jcr:description of type String. The value of this property is displayed in the Submit Action list in the Submit Actions Tab of the Adaptive Form Edit dialog. The OOTB actions are present in the CRX repository at the location /libs/fd/af/components/guidesubmittype.

    • submitService of type String. For more information, see Schedule Adaptive Form submission for custom actions.

Creating a custom Submit Action creating-a-custom-submit-action

Perform the following steps to create a custom Submit Action that saves the data in the CRX repository and then sends you an email. The Adaptive Form contains the OOTB Submit Action Store Content (deprecated) that saves the data in the CRX repository. In addition, AEM provides a Mail API that can be used to send emails. Before using the Mail API, configure the Day CQ Mail service through the system console. You can reuse the Store Content (deprecated) action to store the data in the repository. The Store Content (deprecated) action is available at the location /libs/fd/af/components/guidesubmittype/store in the CRX repository.

  1. Log in to CRXDE Lite at the URL https://<server>:<port>/crx/de/index.jsp. Create a node with the property sling:Folder and name store_and_mail in the /apps/custom_submit_action folder. Create the custom_submit_action folder if it does not exist already.

    Screenshot depicting the creation of a node with the property sling:Folder

  2. Provide the mandatory configuration fields.

    Add the configuration the Store action requires. Copy the cq:dialog node of the Store action from /libs/fd/af/components/guidesubmittype/store to the action folder at /apps/custom_submit_action/store_and_email.

    Screenshot showing the copying of the dialog node to the action folder

  3. Provide configuration fields to prompt the author for email configuration.

    The Adaptive Form also provides an Email action that sends emails to users. Customize this action based on your requirements. Navigate to /libs/fd/af/components/guidesubmittype/email/dialog. Copy the nodes within the cq:dialog node to cq:dialog node of your Submit Action (https://experienceleague.adobe.com/apps/custom_submit_action/store_and_email/dialog?lang=en).

    Customizing the email action

  4. Make the action available in the Adaptive Form Edit dialog.

    Add the following properties in the store_and_email node:

    • guideComponentType of type String and value fd/af/components/guidesubmittype

    • guideDataModel of type String and value xsd, basic

    • jcr:description of type String and value Store and Email Action

    • submitService of type String and value Store and Email. For more information, see Schedule Adaptive Form submission for custom actions.

  5. Open any Adaptive Form. Click the Edit button next to Start to open the Edit dialog of the Adaptive Form container. The new action is displayed in the Submit Actions Tab. Selecting the Store and Email Action displays the configuration added in the dialog node.

    Submit Action configuration dialog

  6. Use the action to complete a task.

    Add the post.POST.jsp script to your action. (https://experienceleague.adobe.com/apps/custom_submit_action/store_and_mail/?lang=en).

    Run the OOTB Store action (post.POST.jsp script). Use the FormsHelper.runAction(java.lang.String, java.lang.String, org.apache.sling.api.resource.Resource, org.apache.sling.api.SlingHttpServletRequest, org.apache.sling.api.SlingHttpServletResponse)) API that CQ provides in your code to run the Store action. Add the following code in your JSP file:

    FormsHelper.runAction("/libs/fd/af/components/guidesubmittype/store", "post", resource, slingRequest, slingResponse);

    To send the email, the code reads the recipient’s email address from the configuration. To fetch the configuration value in the action’s script, read the properties of the current resource using the following code. Similarly you can read the other configuration files.

    ValueMap properties = ResourceUtil.getValueMap(resource);

    String mailTo = properties.get("mailTo");

    Finally, use the CQ Mail API to send the email. Use the SimpleEmail class to create the Email Object as depicted below:

    note note
    NOTE
    Ensure that the JSP file has the name post.POST.jsp.
    code language-java
    <%@include file="/libs/fd/af/components/guidesglobal.jsp" %>
    <%@page import="com.day.cq.wcm.foundation.forms.FormsHelper,
           org.apache.sling.api.resource.ResourceUtil,
           org.apache.sling.api.resource.ValueMap,
                    com.day.cq.mailer.MessageGatewayService,
      com.day.cq.mailer.MessageGateway,
      org.apache.commons.mail.Email,
                    org.apache.commons.mail.SimpleEmail" %>
    <%@taglib prefix="sling"
                    uri="https://sling.apache.org/taglibs/sling/1.0" %>
    <%@taglib prefix="cq"
                    uri="https://www.day.com/taglibs/cq/1.0"
    %>
    <cq:defineObjects/>
    <sling:defineObjects/>
    <%
            String storeContent =
                        "/libs/fd/af/components/guidesubmittype/store";
            FormsHelper.runAction(storeContent, "post", resource,
                                    slingRequest, slingResponse);
     ValueMap props = ResourceUtil.getValueMap(resource);
     Email email = new SimpleEmail();
     String[] mailTo = props.get("mailto", new String[0]);
     email.setFrom((String)props.get("from"));
            for (String toAddr : mailTo) {
                email.addTo(toAddr);
       }
     email.setMsg((String)props.get("template"));
     email.setSubject((String)props.get("subject"));
     MessageGatewayService messageGatewayService =
                        sling.getService(MessageGatewayService.class);
     MessageGateway messageGateway =
                    messageGatewayService.getGateway(SimpleEmail.class);
     messageGateway.send(email);
    %>
    

    Select the action in the Adaptive Form. The action sends an email and stores the data.

Use submitService property for custom Submit Actions submitservice-property

When you set the custom Submit Action, which includes the submitService property, the form triggers the FormSubmitActionService on submission. The FormSubmitActionService uses the getServiceName method to retrieve the value for the submitService property. Based on the value of the submitService property, the service invokes the appropriate submit method. Include the FormSubmitActionService to the custom bundle that you upload to the AEM Forms server.

Add the submitService property of type string to the sling:Folder of your custom Submit Action to enable Adobe Sign for the Adaptive Form. You can select the Enable Adobe Sign option in the Electronic Signature section of the Adaptive Form container properties only after setting the value for the submitService property of your custom Submit Action.

Submit service property

recommendation-more-help
fbcff2a9-b6fe-4574-b04a-21e75df764ab