Gestionnaires d’erreurs dans Adaptive Forms

Adobe recommande d’utiliser la capture de données moderne et extensible. Composants principaux pour création d’un Forms adaptatif ou Ajout de Forms adaptatif à des pages AEM Sites. Ces composants représentent une avancée significative dans la création de Forms adaptatif, ce qui garantit des expériences utilisateur impressionnantes. Cet article décrit l’approche plus ancienne de la création de Forms adaptatif à l’aide de composants de base.

AEM Forms fournit des gestionnaires de succès et d’erreur prêts à l’emploi pour les envois de formulaires. Il fournit également une fonctionnalité pour personnaliser les fonctions du gestionnaire d’erreurs. Par exemple, vous pouvez appeler un workflow personnalisé dans le serveur principal pour des codes d’erreur spécifiques ou informer le client que le service est hors service. Les gestionnaires sont des fonctions côté client qui s’exécutent en fonction de la réponse du serveur. Lorsqu’un service externe est appelé à l’aide d’API, les données sont transmises au serveur pour validation, qui renvoie une réponse au client avec des informations sur l’événement de succès ou d’erreur pour l’envoi. Les informations sont transmises comme paramètres au gestionnaire approprié pour exécuter la fonction. Un gestionnaire d’erreurs permet de gérer et d’afficher les erreurs ou les problèmes de validation rencontrés.

Le formulaire adaptatif valide les entrées que vous fournissez dans les champs en fonction de critères de validation prédéfinis et vérifie diverses erreurs renvoyées par le point de terminaison REST configuré pour appeler un service externe. Vous pouvez définir les critères de validation en fonction de la source de données utilisée avec le formulaire adaptatif. Par exemple, si vous utilisez des services web RESTful comme source de données, vous pouvez définir les critères de validation dans un fichier de définition Swagger.

Si les valeurs d’entrée répondent aux critères de validation, les valeurs sont envoyées à la source de données, sinon le formulaire adaptatif affiche un message d’erreur à l’aide d’un gestionnaire d’erreurs. De la même manière que cette approche, Adaptive Forms s’intègre aux gestionnaires d’erreurs personnalisés pour effectuer des validations de données. Si les valeurs d’entrée ne répondent pas aux critères de validation, les messages d’erreur s’affichent au niveau du champ dans le formulaire adaptatif. Cela se produit lorsque le message d’erreur de validation renvoyé par le serveur est au format standard du message.

Utilisation des gestionnaires d’erreurs

Les gestionnaires d’erreurs sont utilisés à diverses fins. Certaines des utilisations des fonctions de gestionnaire d’erreurs sont répertoriées ci-dessous :

• Validation: la gestion des erreurs commence par la validation des entrées utilisateur par rapport à des règles ou critères prédéfinis. Lorsque les utilisateurs remplissent un formulaire adaptatif, le gestionnaire d’erreurs valide l’entrée afin de s’assurer qu’elle respecte le format, la longueur ou toute autre contrainte requis.

• Fournir des commentaires en temps réel: lorsqu’une erreur est détectée, le gestionnaire d’erreurs affiche des commentaires immédiats à l’utilisateur, tels que des messages d’erreur intégrés sous les champs de formulaire correspondants. Ces commentaires permettent aux utilisateurs d’identifier et de corriger les erreurs sans avoir à envoyer le formulaire et attendre une réponse.

• Affichage des messages d’erreur: lorsqu’un envoi de formulaire adaptatif rencontre une erreur de validation, le gestionnaire d’erreurs affiche un message d’erreur approprié. Les messages d’erreur doivent être clairs, concis et mettre en évidence les champs spécifiques qui nécessitent une attention particulière.

• Met en surbrillance le champ erroné: pour attirer l’attention de l’utilisateur sur les champs spécifiques incorrects, le gestionnaire d’erreurs surligne ou distingue visuellement les champs correspondants. Il est effectué en modifiant la couleur d’arrière-plan, en ajoutant une icône ou une bordure, ou tout autre indice visuel qui aide les utilisateurs à localiser et à corriger rapidement les erreurs.

Format de réponse échec/erreur

Un formulaire adaptatif affiche les erreurs au niveau du champ si les messages d’erreur de validation du serveur sont au format standard suivant.
Le code ci-dessous illustre la structure de réponse d’échec existante :

   {
    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>
    }

Où :

• errorCausedBy décrit le motif de l’échec…
• errors mentionnez l’expression SOM des champs qui ont échoué aux critères de validation avec le message d’erreur de validation.
• originCode champ ajouté par AEM et contient le code d’état http renvoyé par le service externe.
• originMessage champ ajouté par AEM et contient les données d’erreur brutes renvoyées par le service externe.

Avec les améliorations des fonctionnalités et les mises à jour ultérieures dans les versions d’AEM Forms, la structure de réponse aux échecs existante a été changée en nouveau format basé sur RFC7807, qui est rétrocompatible avec la structure de réponse aux échecs existante :

    {
        "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)
    }

Où :

• type (required) spécifie le type d’échec. Il peut s’agir de l’une des valeurs suivantes :

  • SERVER_SIDE_VALIDATION indique un échec en raison de la validation côté serveur.
  • FORM_SUBMISSION indique un échec lors de l’envoi du formulaire
  • SERVICE_INVOCATION indique un échec lors d’un appel de service tiers.
  • FAILURE indique un échec général.
  • VALIDATION_ERROR indique un échec en raison d’une erreur de validation.

• title (optional) fournit un titre ou une brève description de l’échec.

• detail (optional) fournit des détails supplémentaires sur l’échec, si nécessaire.

• instance (optional) représente une instance ou un identifiant associé à l’échec et permet de suivre ou d’identifier l’occurrence spécifique de l’échec.

• validationErrors (required) contient des informations sur les erreurs de validation. Il comprend les champs suivants :

  • fieldname mentionne l’expression SOM des champs qui ont échoué aux critères de validation.
  • dataRef représente le chemin JSON ou XPath des champs qui ont échoué à la validation.
  • details contiennent le message d’erreur de validation avec le champ en erreur.

• originCode (optional) champ ajouté par AEM et contient le code d’état http renvoyé par le service externe

• originMessage (optional) champ ajouté par AEM et contient les données d’erreur brutes renvoyées par le service externe.

Exemple de format de réponse d’erreur

Voici quelques options pour afficher les réponses d’erreur :

Conditions préalables requises

Avant d’utiliser un gestionnaire d’erreurs personnalisé dans une Forms adaptative :

• Connaissances de base en créer une fonction personnalisée.
• Installez la dernière version de Apache Maven.

Ajout d’un gestionnaire d’erreurs à l’aide de l’éditeur de règles

En utilisant la variable Service d’appel de l’éditeur de règles , vous définissez les critères de validation en fonction de la source de données que vous utilisez avec le formulaire adaptatif. Si vous utilisez des services web RESTful comme source de données, vous pouvez définir les critères de validation dans un fichier de définition Swagger. En utilisant les fonctions de gestionnaire d’erreurs et l’éditeur de règles dans Adaptive Forms, vous pouvez gérer et personnaliser efficacement la gestion des erreurs. Vous définissez les conditions à l’aide de l’éditeur de règles et configurez les actions à effectuer lorsque la règle est déclenchée. Le formulaire adaptatif valide les entrées que vous saisissez dans les champs en fonction de critères de validation prédéfinis. Si les valeurs d’entrée ne répondent pas aux critères de validation, les messages d’erreur s’affichent au niveau du champ dans un formulaire adaptatif.

L’éditeur de règles vous permet d’effectuer les opérations suivantes :

• Ajouter la fonction de gestionnaire d’erreurs par défaut
• Ajout d’une fonction de gestionnaire d’erreurs personnalisée

Ajouter la fonction de gestionnaire d’erreurs par défaut

Un gestionnaire d’erreurs par défaut est pris en charge pour afficher les messages d’erreur sur les champs si la réponse d’erreur se trouve dans le schéma standard ou dans un échec de validation côté serveur.
Pour comprendre comment utiliser un gestionnaire d’erreurs par défaut à l’aide de la méthode Service d’appel de l’éditeur de règles , prenez un exemple de formulaire adaptatif simple avec deux champs, Identifiant de paramètre prédéfini et Nom du paramètre prédéfini et utilisez un gestionnaire d’erreurs par défaut au niveau de l’événement Identifiant de paramètre prédéfini pour vérifier les différentes erreurs renvoyées par le point de terminaison REST configuré pour appeler un service externe, par exemple : 200 - OK,404 - Not Found, 400 - Bad Request. Pour ajouter un gestionnaire d’erreurs par défaut à l’aide de l’action Invoke Service de l’éditeur de règles, procédez comme suit :

1. Ouvrez un formulaire adaptatif en mode création, sélectionnez un composant de formulaire et appuyez sur Éditeur de règles pour ouvrir l’éditeur de règles.
2. Appuyez sur Créer.
3. Définissez une condition dans la section Lorsque de la règle. Par exemple : When[Nom du champ Identifiant de l’animal domestique] est modifiée. L’option Sélectionner est modifiée à partir du Sélectionner un état liste déroulante.
4. Dans la section Then (Alors), sélectionnez Invoke Service (Appeler un service) dans la liste déroulante Select Action (Sélectionner une action).
5. Sélectionnez une Post service et ses liaisons de données correspondantes depuis la variable Entrée . Par exemple, pour valider Identifiant de paramètre prédéfini, sélectionnez une Post service as GET /pet/{petId} et sélectionnez Identifiant de paramètre prédéfini dans le Entrée .
6. Sélectionnez les liaisons de données dans la Sortie . Sélectionner Nom du paramètre prédéfini dans le Sortie .
7. Sélectionner Gestionnaire d’erreurs par défaut de la Gestionnaire d’erreurs .
8. Cliquez sur Terminé.

À la suite de cette règle, les valeurs que vous saisissez pour Identifiant de paramètre prédéfini vérifie la validation Nom du paramètre prédéfini utilisation du service externe appelé par le point de terminaison REST. Si les critères de validation basés sur la source de données échouent, les messages d’erreur s’affichent au niveau du champ.

Ajout d’une fonction de gestionnaire d’erreurs personnalisée

Vous pouvez ajouter une fonction de gestionnaire d’erreurs personnalisée pour effectuer certaines des actions suivantes :

• gérer les réponses d’erreur qui utilisent des réponses d’erreur non standard ou standard. Il est important de noter que ces réponses d’erreur non standard ne sont pas conformes au schéma standard des réponses d’erreur.
• envoyer des événements analytics à n’importe quelle plate-forme analytics ; Par exemple, Adobe Analytics.
• afficher la boîte de dialogue modale avec les messages d’erreur.

Outre les actions mentionnées, les gestionnaires d’erreurs personnalisés peuvent être utilisés pour exécuter des fonctions personnalisées répondant à des besoins spécifiques de l’utilisateur.

Le gestionnaire d’erreurs personnalisé est une fonction (bibliothèque cliente) conçue pour répondre aux erreurs renvoyées par un service externe et fournir une réponse personnalisée aux utilisateurs finaux. Toute bibliothèque cliente avec annotation @errorHandler est considérée comme une fonction de gestionnaire d’erreurs personnalisée. Cette annotation permet d’identifier la fonction de gestionnaire d’erreurs spécifiée dans la variable .js fichier .

Pour comprendre comment créer et utiliser un gestionnaire d’erreurs personnalisé à l’aide de la méthode Service Invoke de l’éditeur de règles action, prenons un exemple de formulaire adaptatif avec deux champs, Identifiant de paramètre prédéfini et Nom du paramètre prédéfini et utilisez un gestionnaire d’erreurs personnalisé à l’adresse Identifiant de paramètre prédéfini pour vérifier les différentes erreurs renvoyées par le point de terminaison REST configuré pour appeler un service externe, par exemple : 200 - OK,404 - Not Found, 400 - Bad Request.

Pour ajouter et utiliser un gestionnaire d’erreurs personnalisé dans un formulaire adaptatif, procédez comme suit :

1. Création d’un gestionnaire d’erreurs personnalisé
2. Utilisation de l’éditeur de règles pour configurer le gestionnaire d’erreurs personnalisé

1. Création d’un gestionnaire d’erreurs personnalisé

Pour créer une fonction d’erreur personnalisée, procédez comme suit :

1. Se connecter http://server:port/crx/de/index.jsp#.

2. Créez un dossier sous le /apps dossier. Par exemple, créez un dossier nommé comme experience-league.

3. Enregistrez vos modifications.

4. Accédez au dossier créé et créez un noeud de type cq:ClientLibraryFolder as clientlibs.

5. Accédez au clientlibs et ajoutez le dossier allowProxy et categories properties:

   

   REMARQUE

   Vous pouvez indiquer n’importe quel nom à la place de customfunctionsdemo.

6. Enregistrez vos modifications.

7. Créez un dossier appelé js sous le clientlibs dossier.

8. Créez un fichier JavaScript appelé functions.js sous le js folder

9. Créez un fichier appelé js.txt sous le clientlibs dossier.

10. Enregistrez vos modifications.
    La structure de dossiers créée ressemble à ce qui suit :

    

11. Double-cliquez sur le functions.js pour ouvrir l’éditeur. Le fichier comprend le code du gestionnaire d’erreurs personnalisé.
    Ajoutons le code suivant au fichier JavaScript pour afficher la réponse et les en-têtes, reçus du point d’entrée du service REST, dans la console du navigateur.

        /**
        * 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...");
        }
    

    Pour appeler le gestionnaire d’erreurs par défaut à partir de votre gestionnaire d’erreurs personnalisé, la ligne suivante de l’exemple de code est utilisée :
    guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers)

12. Enregistrer function.js.

13. Accédez à js.txt et ajoutez le code suivant :

        #base=js
        functions.js
    

14. Enregistrez le fichier js.txt.

Maintenant, comprenons comment configurer et utiliser un gestionnaire d’erreurs personnalisé à l’aide du service Invoke de l’éditeur de règles dans AEM Forms.

2. Utilisez l’éditeur de règles pour configurer le gestionnaire d’erreurs personnalisé

Avant d’implémenter le gestionnaire d’erreurs personnalisé dans un formulaire adaptatif, assurez-vous que le nom de la bibliothèque cliente dans la variable Catégorie de bibliothèque cliente s’aligne sur le nom spécifié dans l’option categories de la variable .content.xml fichier .

Dans ce cas, le nom de la bibliothèque cliente est fourni comme suit : customfunctionsdemo dans le .content.xml fichier .

Pour utiliser un gestionnaire d’erreurs personnalisé à l’aide de la méthode Service d’appel de l’éditeur de règles action :

1. Ouvrez un formulaire adaptatif en mode création, sélectionnez un composant de formulaire et appuyez sur Éditeur de règles pour ouvrir l’éditeur de règles.
2. Appuyez sur Créer.
3. Définissez une condition dans la section Lorsque de la règle. Par exemple, Lorsque [Nom du champ Identifiant de l’animal domestique] est modifié, sélectionnez est modifié de la Sélectionner un état liste déroulante.
4. Dans la section Then (Alors), sélectionnez Invoke Service (Appeler un service) dans la liste déroulante Select Action (Sélectionner une action).
5. Sélectionnez une Post service et ses liaisons de données correspondantes depuis la variable Entrée . Par exemple, pour valider Identifiant de paramètre prédéfini, sélectionnez une Post service as GET /pet/{petId} et sélectionnez Identifiant de paramètre prédéfini dans le Entrée .
6. Sélectionnez les liaisons de données dans la Sortie . Par exemple, Sélectionner Nom du paramètre prédéfini dans le Sortie .
7. Sélectionner Gestionnaire d’erreurs personnalisé de la Gestionnaire d’erreurs .
8. Cliquez sur Terminé.

À la suite de cette règle, les valeurs que vous saisissez pour Identifiant de paramètre prédéfini vérifie la validation Nom du paramètre prédéfini utilisation du service externe appelé par le point de terminaison REST. Si les critères de validation basés sur la source de données échouent, les messages d’erreur s’affichent au niveau du champ.

Ouvrez la console du navigateur et vérifiez le message d’erreur de validation de la réponse et de l’en-tête reçus du point d’entrée du service REST.

La fonction de gestionnaire d’erreurs personnalisée est responsable de l’exécution d’actions supplémentaires, telles que l’affichage d’une boîte de dialogue modale ou l’envoi d’un événement d’analyse, en fonction de la réponse d’erreur. Une fonction de gestionnaire d’erreurs personnalisée offre la possibilité de personnaliser la gestion des erreurs en fonction des besoins spécifiques de l’utilisateur.

Informations complémentaires

• Création d’un formulaire adaptatif basé sur des composants principaux autonomes
• Créer un style ou des thèmes pour vos formulaires
• Créer ou ajouter un formulaire adaptatif à une page AEM Sites

Ressources Business.Adobe.com

Auto Form Fill Targeted Content Asset Collections Web Content Management Digital Rights Management Digital Asset Management