Add Custom Error Handlers in AEM Adaptive Forms

Adobe recommends using the modern and extensible data capture Core Components for creating new Adaptive Forms or adding Adaptive Forms to AEM Sites pages. These components represent a significant advancement in Adaptive Forms creation, ensuring impressive user experiences. This article describes older approach to author Adaptive Forms using foundation components.

AEM Forms provides out-of-the-box success and error handlers for form submissions. It also provides feature to customize error handler functions. For example, you can invoke a custom workflow in the backend for specific error codes or inform the customer that the service is down. Handlers are client-side functions that execute based on the server response. When an external service is invoked using APIs, the data is transmitted to the server for validation, which returns a response to the client with information about the success or error event for the submission. The information is passed as parameters to the relevant handler to execute the function. An error handler helps to manage and display errors or validation issues encountered.

The Adaptive Form validates the inputs that you provide in fields based on pre-set validation criteria and checks for various errors returned by the REST endpoint configured to invoke an external service. You can set the validation criteria based on the data source that you use with the Adaptive Form. For example, if you use RESTful web services as the data source, you can define the validation criteria in a Swagger definition file.

If the input values meet the validation criteria, the values are submitted to the data source else, the Adaptive Form displays an error message using an error handler. Similar to this approach, Adaptive Forms integrate with custom error handlers to perform data validations. If the input values do not meet the validation criteria, the error messages display at a field level in the Adaptive Form. This occurs when the validation error message returned by the server is in the standard message format.

Uses of error handlers

Error handlers are used for various purposes. Some of the uses of error handler functions are listed below:

• Perform validation: The error handling starts with validating user inputs against predefined rules or criteria. As users fill out an Adaptive Form, the error handler validates the input to ensure it meets the required format, length, or any other constraints.

• Provide real-time feedback: When any error is detected, the error handler displays immediate feedback to the user, such as inline error messages below the corresponding form fields. This feedback helps users to identify and correct errors without having to submit the form and wait for a response.

• Display error messages: When an Adaptive Form submission encounters any validation error, the error handler displays an appropriate error message. The error messages should be clear, concise, and highlight the specific fields that require attention.

• Highlights the erroneous field: To draw the user’s attention to the specific incorrect fields, the error handler highlights or visually differentiates the corresponding fields. It is performed by changing the background color, adding an icon or border, or any other visual cue that helps users quickly locate and address the errors.

Failure/Error response format

An Adaptive Form displays the errors at a field level if the server validation error messages are in the following standard format.
The below code illustrates the existing failure response structure:

   {
    errorCausedBy : "SERVER_SIDE_VALIDATION/SERVICE_INVOCATION_FAILURE"
    errors : [
        {
             somExpression  : <somexpr>
             errorMessage / errorMessages : <validationMsg> / [<validationMsg>, <validationMsg>]
        }
    ]
    originCode : <target error Code>
    originMessage : <unstructured error message returned by service>
    }

Where:

• errorCausedBy describes the reason for failure.
• errors mention the SOM expression of the fields that failed the validation criteria along with the validation error message.
• originCode field added by AEM and contains the http status code returned by the external service.
• originMessage field added by AEM and contains the raw error data returned by the external service.

With the improvements in features and subsequent updates in the versions of AEM Forms, the existing failure response structure changed into new format based on RFC7807, which is backward compatible with the existing failure response structure:

    {
        "type": "SERVER_SIDE_VALIDATION/FORM_SUBMISSION/SERVICE_INVOCATION/FAILURE/VALIDATION_ERROR", (required)
        "title": "Server side validation failed/Third party service invocation failed", (optional)
        "detail": "", (optional)
        "instance": "", (optional)
        "validationErrors" : [ (required)
            {
                "fieldName":"<SOM expression of the field whose data sent is invalid>",
                "dataRef":<JSONPath (or XPath) of the data element which is invalid>
                "details": ["Error Message(s) for the field"] (required)

            }
        ],
        "originCode": <Origin http status code>, (optional - in case of SERVER_SIDE_VALIDATION)
        "originMessage" : "<unstructured error message returned by service>" (optional - in case of SERVER_SIDE_VALIDATION)
    }

Where:

• type (required) specifies the type of failure. It can be one of the following values:

  • SERVER_SIDE_VALIDATION indicates a failure due to server-side validation.
  • FORM_SUBMISSION indicates a failure during form submission
  • SERVICE_INVOCATION indicates a failure during a third-party service invocation.
  • FAILURE indicates a general failure.
  • VALIDATION_ERROR indicates a failure due to a validation error.

• title (optional) provides a title or brief description of the failure.

• detail (optional) provides additional details about the failure if necessary.

• instance (optional) represents an instance or identifier associated with the failure and helps in tracking or identifying the specific occurrence of the failure.

• validationErrors (required) contains information about validation errors. It includes the following fields:

  • fieldname mentions the SOM expression of the fields that failed the validation criteria.
  • dataRef represents the JSON path or XPath of the fields that failed the validation.
  • details contain the validation error message with the erroneous field.

• originCode (optional) field added by AEM and contains the http status code returned by the external service

• originMessage (optional) field added by AEM and contains the raw error data returned by the external service.

Sample error response format

Some of the options to display the error responses are:

Add error handler using Rule Editor

Using the Rule Editor’s Invoke Service action, you define the validation criteria based on the data source that you use with the Adaptive Form. In case, you use RESTful web services as the data source, you can define the validation criteria in a Swagger definition file. By using the error handler functions and Rule Editor in Adaptive Forms, you can effectively manage and customize error handling. You define the conditions using Rule Editor and configure the desired actions to be performed when the rule is triggered. Adaptive Form validates the inputs that you enter in fields based on pre-set validation criteria. In case, the input values do not meet the validation criteria, the error messages are displayed at the field level in an Adaptive Form.

Using Rule Editor, you can:

• Add default error handler function
• Add custom error handler function

Add default error handler function

A default error handler is supported to display error messages on fields if the error response is in standard schema or in server-side validation failure.
To understand how to use a default error handler using the Rule Editor’s Invoke Service action, take an example of a simple Adaptive Form with two fields, Pet ID and Pet Name and use a default error handler at the Pet ID field to check for various errors returned by the REST endpoint configured to invoke an external service, for example, 200 - OK,404 - Not Found, 400 - Bad Request. To add a default error handler using the Rule Editor’s Invoke Service action, execute the following steps:

1. Open an Adaptive Form in authoring mode, select a form component and tap Rule Editor to open the rule editor.
2. Tap Create.
3. Create a condition in the When section of the rule. For example, When[Name of Pet ID field] is changed. Select is changed from the Select State drop-down list.
4. In the Then section, select Invoke Service from the Select Action drop-down list.
5. Select a Post service and its corresponding data bindings from the Input section. For example, to validate Pet ID, select a Post service as GET /pet/{petId} and select Pet ID in the Input section.
6. Select the data bindings from the Output section. Select Pet Name in the Output section.
7. Select Default Error Handler from the Error Handler section.
8. Click Done.

As a result of this rule, the values you enter for Pet ID checks validation for Pet Name using external service invoked by REST endpoint. If the validation criteria based on the data source fail, the error messages are displayed at the field level.

Add custom error handler function

You can add a custom error handler function to perform some of the actions like:

• handle error responses that use non-standard or standard error responses. It is important to note that these non-standard error responses do not comply with the standard schema of error responses.
• send analytics events to any analytics platforms. For example, Adobe Analytics.
• display modal dialog with error messages.

In addition to the mentioned actions, the custom error handlers can be used to execute customized functions that meet specific user requirements.

The custom error handler is a function (Client Library) designed to respond to errors returned by an external service and deliver a customized response to end users. Any Client Library with annotation @errorHandler is considered as a custom error handler function. This annotation helps to identify the error handler function specified in the .js file.
To understand how to create and use a custom error handler using the Rule Editor’s Invoke service action, let’s take an example of Adaptive Form with two fields, Pet ID and Pet Name and use a custom error handler at the Pet ID field to check for various errors returned by the REST endpoint configured to invoke an external service, for example, 200 - OK,404 - Not Found, 400 - Bad Request.

To add and use a custom error handler in an Adaptive Form, perform the following steps:

1. Create a custom error handler
2. Use the Rule Editor to configure custom error handler

1. Create a custom error handler

To create a custom error function, perform the following steps:

1. Clone your AEM Forms as a Cloud Service Repository.

2. Create a folder under the [AEM Forms as a Cloud Service repository folder]/apps/ folder. For example, create a folder named as experience-league

3. Navigate to [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/ and create a ClientLibraryFolder as clientlibs.

4. Create a folder named js.

5. Navigate to the [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js folder.

6. Add a JavaScript file, for example function.js. The file comprises the code for custom error handler.
   Let’s add the following code to the JavaScript file to display the response and headers, received from the REST service endpoint, in the browser console.

       /**
       * Custom Error handler
       * @name customErrorHandler Custom Error Handler Function
       * @errorHandler
       */
       function customErrorHandler(response, headers)
       {
           console.log("Custom Error Handler processing start...");
           console.log("response:"+JSON.stringify(response));
           console.log("headers:"+JSON.stringify(headers));
           guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers);
           console.log("Custom Error Handler processing end...");
       }
   

   To call the default error handler from your custom error handler, the following line of the sample code is used:
   guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers)

   NOTE

   In the .content.xml file, add the allowProxy and categories properties.

   • allowProxy = [Boolean]true
   • categories= customfunctionsdemo
     For example, in this case, [custom-errorhandler-name] is provided as customfunctionsdemo.

7. Save the function.js file.

8. Navigate to the [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js folder.

9. Add a text file as js.txt. The file contains:

       #base=js
       functions.js
   

10. Save the js.txt file.
    The created folder structure looks like:

    

    NOTE

    To learn more about how to create custom functions, click custom functions in the Rule Editor.

11. Add, commit, and push the changes in the repository using the below commands:

    
        git add .
        git commit -a -m "Adding error handling files"
        git push
    

12. Run the pipeline.

Once the pipeline is executed successfully, the custom error handler becomes available in your Adaptive Form rule editor. Now, let’s understand how to configure and use a custom error handler using the Rule Editor’s Invoke service in AEM Forms.

2. Use the Rule Editor to configure custom error handler

Before implementing the custom error handler in an Adaptive Form, ensure that the client library name in the Client Library Category aligns with the name specified in the categories option of the .content.xml file.

In this case, the client library name is provided as customfunctionsdemo in the .content.xml file.

To use a custom error handler using the Rule Editor’s Invoke Service action:

1. Open an Adaptive Form in authoring mode, select a form component and tap Rule Editor to open the rule editor.
2. Tap Create.
3. Create a condition in the When section of the rule. For example, When [Name of Pet ID field] is changed, select is changed from the Select State drop-down list.
4. In the Then section, select **Invoke Service ** from the Select Action drop-down list.
5. Select a Post service and its corresponding data bindings from the Input section. For example, to validate Pet ID, select a Post service as GET /pet/{petId} and select Pet ID in the Input section.
6. Select the data bindings from the Output section. For example, Select Pet Name in the Output section.
7. Select Custom Error Handler from the Error Handler section.
8. Click Done.

As a result of this rule, the values you enter for Pet ID checks validation for Pet Name using external service invoked by REST endpoint. If the validation criteria based on the data source fail, the error messages are displayed at the field level.

Open the browser console and check the response and header, received from the REST service endpoint, for the validation error message.

The custom error handler function is responsible for executing additional actions such as displaying a modal dialog or sending an analytics event, based on the error response. A custom error handler function provides the flexibility to tailor error handling to the specific user requirements.

See Also

• Create an AEM Adaptive Form
• Add an AEM Adaptive Form to AEM Sites page
• Apply themes to an AEM Adaptive Form
• Add components to an AEM Adaptive Form
• Use CAPTCHA in an AEM Adaptive Form
• Generate PDF version (DoR) of an AEM Adaptive Form
• Translate an AEM Adaptive Form
• Enable Adobe Analytics for an Adaptive Form to track form usage
• Connect Adaptive Form to Microsoft SharePoint
• Connect Adaptive Form to Microsoft Power Automate
• Connect Adaptive Form to Microsoft OneDrive
• Connect Adaptive Form to Microsoft Azure Blob Storage
• Connect Adaptive Form to Salesforce
• Use Adobe Sign in an AEM Adaptive Form
• Add a new locale for an Adaptive Form
• Send Adaptive Form data to a database
• Send Adaptive Form data to a REST endpoint
• Send Adaptive Form data to AEM Workflow
• Use Forms Portal to list AEM Adaptive Forms on an AEM website
• Create and use custom error handlers in Adaptive Forms (Core Components)