Error Handlers in Adaptive Forms error-handlers-in-adaptive-form

Adobe recommends using the modern and extensible data capture Core Componentsfor creating new Adaptive Formsor 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 uses-of-error-handler

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

Failure/Error response format failure-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:

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 - if there is SERVER_SIDE_VALIDATION)
        "originMessage" : "<unstructured error message returned by service>" (optional - if there is SERVER_SIDE_VALIDATION)
    }

Where:

Sample error response format sample-error-response-format

Some of the options to display the error responses are:

Prerequisites prerequisites

Before using custom error handler in an Adaptive Forms:

Add error handler using Rule Editor 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-default-errror-handler

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:

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 add-custom-errror-handler

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

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 create-custom-error-message

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

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

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.

Additional information additional-information