Error Handlers for Adaptive Form based on Core Components error-handlers-in-adaptive-form
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:
-
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 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 : [
{
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 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":"<qualified fieldname 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)
}
- Ensure that the error response structure includes either fieldName or dataRef.
- Ensure that the ContentType header is application/problem+json.
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 submissionSERVICE_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 qualified fieldname 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 sample-error-response-format
Some of the options to display the error responses are:
-
Header:
content-type:application/problem+json
-
Response:
code language-javascript { "type": "VALIDATION_ERROR", "validationErrors": [ { "fieldName": "$form.PetId", "dataRef": "", "details": [ "Invalid ID supplied. Provided value is not correct!" ] } ]}
-
Header:
content-type:application/problem+json
-
Response:
code language-javascript { "type": "VALIDATION_ERROR", "validationErrors": [ { "fieldName": "", "dataRef": "$.Pet.id", "details": [ "Invalid ID supplied. Provided value is not correct!" ] } ]}
You can view the value of dataRef in the Properties window of a form component.
Requirements to add error handler using Rule Editor’s Invoke service before-you-start-to-add-error-handler
Before you add an error handler using the Rule Editor’s Invoke service:
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.
- To use error handlers with the Rule Editor’s Invoke service action, configure Adaptive Forms with a form data model (FDM).
- A default error handler is provided to display error messages on fields if the error response is in the standard schema. You can also call the default error handler from the custom error handler function.
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:
- Open an Adaptive Form in authoring mode, select a form component and select Rule Editor to open the rule editor.
- Select Create.
- 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.
- In the Then section, select Invoke Service from the Select Action drop-down list.
- 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.
- Select the data bindings from the Output section. Select Pet Name in the Output section.
- Select Default Error Handler from the Error Handler section.
- 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 add-custom-errror-handler
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 create-custom-error-message
To create a custom error function, perform the following steps:
To create a custom error function, perform the following steps:
-
Create a folder under the
[AEM Forms as a Cloud Service repository folder]/apps/
folder. For example, create a folder named asexperience-league
-
Navigate to
[AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/
and create aClientLibraryFolder
asclientlibs
. -
Create a folder named
js
. -
Navigate to the
[AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js
folder. -
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.code language-javascript /** Custom Error handler * @name customErrorHandler Custom Error Handler Function * @errorHandler */ function customErrorHandler(response, headers, globals) { console.log("Custom Error Handler processing start..."); console.log("response:"+JSON.stringify(response)); console.log("headers:"+JSON.stringify(headers)); alert("CustomErrorHandler - Enter valid PetId.") console.log("Custom Error Handler processing end..."); return true; // true - call default error handler, false - don't call default error handler. }
In the code above,
return true
invokes the default error handler automatically. To prevent the default error handler from being called by default, includereturn false
.note note NOTE In the .content.xml
file, addcategories = [custom-errorhandler-name]
. For example, in this case, [custom-errorhandler-name] is provided ascustomfunctionsdemoV2
. -
Save the
function.js
file. -
Navigate to the
[AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js
folder. -
Add a text file as
js.txt
. The file contains:code language-javascript #base=js functions.js
-
Save the
js.txt
file.
The created folder structure looks like:note note NOTE To learn more about how to create custom functions, click custom functions in the Rule Editor. -
Add, commit, and push the changes in the repository using the below commands:
code language-javascript git add . git commit -a -m "Adding error handling files" git push
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 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.
To use a custom error handler using the Rule Editor’s Invoke Service action:
- Open an Adaptive Form in authoring mode, select a form component and select Rule Editor to open the rule editor.
- Select Create.
- 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.
- In the Then section, select **Invoke Service ** from the Select Action drop-down list.
- 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.
- Select the data bindings from the Output section. For example, Select Pet Name in the Output section.
- Select Custom Error Handler from the Error Handler section.
- Click Done.
s
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
See Also see-also
- Create an AEM Adaptive Form
- Add an AEM Adaptive Form to the 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 a 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
- Add versionings, comments, and annotations to an Adaptive Form
- Compare Adaptive Forms