Hinzufügen von benutzerdefinierten Fehler-Handlern in adaptiven Formularen

Adobe empfiehlt die Verwendung der modernen und erweiterbaren Kernkomponenten zur Datenerfassung für das Erstellen neuer adaptiver Formulare oder das Hinzufügen von adaptiven Formularen zu AEM Sites-Seiten. Diese Komponenten stellen einen bedeutenden Fortschritt bei der Erstellung adaptiver Formulare dar und sorgen für beeindruckende Benutzererlebnisse. In diesem Artikel wird der ältere Ansatz zum Erstellen von adaptiven Formularen mithilfe von Foundation-Komponenten beschrieben.

AEM Forms bietet sofort einsetzbare Erfolgs- und Fehler-Handler für Formularübermittlungen. Es bietet außerdem die Möglichkeit zum Anpassen von Fehler-Handler-Funktionen. Sie können beispielsweise einen benutzerdefinierten Workflow im Back-End für bestimmte Fehler-Codes aufrufen oder die Kundin bzw. den Kunden darüber informieren, dass der Dienst nicht verfügbar ist. Handler sind Client-seitige Funktionen, die basierend auf der Server-Antwort ausgeführt werden. Wenn ein externer Dienst mithilfe von APIs aufgerufen wird, werden die Daten zur Validierung an den Server übertragen, der eine Antwort mit Informationen zum Erfolgs- oder Fehlerereignis für die Übermittlung an den Client zurückgibt. Die Informationen werden als Parameter an den relevanten Handler übergeben, um die Funktion auszuführen. Ein Fehler-Handler hilft bei der Verwaltung und Anzeige von Fehlern oder aufgetretenen Validierungsproblemen.

Das adaptive Formular validiert die Eingaben, die Sie in Feldern angeben, basierend auf voreingestellten Validierungskriterien und prüft auf verschiedene Fehler, die vom REST-Endpunkt zurückgegeben werden können, der zum Aufrufen eines externen Dienstes konfiguriert ist. Sie können die Validierungskriterien auf Grundlage der Datenquelle festlegen, die Sie mit dem adaptiven Formular verwenden. Wenn Sie beispielsweise RESTful-Web-Services als Datenquelle verwenden, können Sie die Validierungskriterien in einer Swagger-Definitionsdatei definieren.

Wenn die Eingabewerte die Validierungskriterien erfüllen und die Werte an die Datenquelle gesendet werden, zeigt das adaptive Formular eine Fehlermeldung mit einem Fehler-Handler an. Ähnlich wie bei diesem Ansatz können adaptive Formulare jetzt in benutzerdefinierte Fehler-Handler integriert werden, um Datenvalidierungen durchzuführen. Wenn die Eingabewerte die Validierungskriterien nicht erfüllen, werden die Fehlermeldungen auf Feldebene im adaptiven Formular angezeigt. Dies tritt auf, wenn die vom Server zurückgegebene Meldung über einen Validierungsfehler im standardmäßigen Nachrichtenformat vorliegt.

Verwendung von Fehler-Handlern

Fehler-Handler werden für verschiedene Zwecke verwendet. Einige der Verwendungen von Fehler-Handler-Funktionen sind unten aufgeführt:

• Durchführung einer Validierung: Die Fehlerbehebung beginnt mit der Validierung von Benutzereingaben anhand vordefinierter Regeln oder Kriterien. Während Benutzende ein adaptives Formular ausfüllen, validiert der Fehler-Handler die Eingabe, um sicherzustellen, dass sie das erforderliche Format, die Länge oder andere Einschränkungen erfüllt.

• Echtzeit-Feedback geben: Wenn ein Fehler erkannt wird, zeigt der Fehler-Handler den Benutzenden sofortiges Feedback an, z. B. durch Inline-Fehlermeldungen unter den entsprechenden Formularfeldern. Dieses Feedback hilft Benutzenden, Fehler zu identifizieren und zu korrigieren, ohne das Formular senden und auf eine Antwort warten zu müssen.

• Fehlermeldungen anzeigen: Wenn bei der Übermittlung eines adaptiven Formulars ein Überprüfungsfehler auftritt, zeigt der Fehler-Handler eine entsprechende Fehlermeldung an. Die Fehlermeldungen sollten klar und deutlich sein und die spezifischen Felder hervorheben, die beachtet werden müssen.

• Markiert das fehlerhafte Feld: Um die Aufmerksamkeit der Benutzenden auf bestimmte falsche Felder zu lenken, hebt der Fehler-Handler die entsprechenden Felder hervor oder unterscheidet sie visuell. Dies geschieht durch Ändern der Hintergrundfarbe, Hinzufügen eines Symbols oder Rahmens oder eines anderen visuellen Hinweises, der Benutzenden beim schnellen Auffinden und Beheben der Fehler hilft.

Format der Fehlschlag-/Fehlerreaktion

Ein adaptives Formular zeigt die Fehler auf Feldebene an, wenn die Fehlermeldungen zur Server-Validierung im folgenden Standardformat vorliegen.
Der folgende Code veranschaulicht die vorhandene Struktur der Fehlerreaktion:

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

Dabei gilt:

• errorCausedBy beschreibt den Grund für das Fehlschlagen.
• errors geben den SOM-Ausdruck der Felder an, die die Überprüfungskriterien nicht erfüllt haben, zusammen mit der Validierungsfehlermeldung.
• originCode Feld, das von AEM hinzugefügt wurde und den vom externen Dienst zurückgegebenen HTTP-Status-Code enthält.
• originMessage Feld, das von AEM hinzugefügt wurde und die vom externen Dienst zurückgegebenen Rohfehlerdaten enthält.

Mit den Verbesserungen bei den Funktionen und den nachfolgenden Updates in den Versionen von AEM Forms wurde die bestehende Fehlerreaktionsstruktur in ein neues Format auf der Grundlage von RFC7807 geändert, das mit der bestehenden Fehlerreaktionsstruktur abwärtskompatibel ist:

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

Dabei gilt:

• type (required) gibt den Fehlertyp an. Es kann einer der folgenden Werte sein:

  • SERVER_SIDE_VALIDATION weist auf einen Fehler aufgrund der Server-seitigen Validierung hin.
  • FORM_SUBMISSION weist auf einen Fehler während der Formularübermittlung hin.
  • SERVICE_INVOCATION weist auf einen Fehler während des Aufrufs eines Drittanbieter-Dienstes hin.
  • FAILURE weist auf einen allgemeinen Fehler hin.
  • VALIDATION_ERROR weist auf einen Fehler aufgrund eines Validierungsfehlers hin.

• title (optional) enthält einen Titel oder eine kurze Beschreibung des Fehlers.

• detail (optional) enthält bei Bedarf weitere Details zum Fehler.

• instance (optional) stellt eine Instanz oder eine Kennung dar, die mit dem Fehler verknüpft ist, und hilft beim Tracking oder Identifizieren des spezifischen Auftretens des Fehlers.

• validationErrors (required) enthält Informationen zu Validierungsfehlern. Dazu gehören folgende Felder:

  • fieldname erwähnt den SOM-Ausdruck der Felder, die die Validierungskriterien nicht erfüllt haben.
  • dataRef stellt den JSON-Pfad oder XPath der Felder dar, bei denen die Überprüfung fehlgeschlagen ist.
  • details enthält die Validierungsfehlermeldung mit dem fehlerhaften Feld.

• originCode (optional) Feld, das von AEM hinzugefügt wurde und den vom externen Dienst zurückgegebenen HTTP-Status-Code enthält.

• originMessage (optional) Feld, das von AEM hinzugefügt wurde und die vom externen Dienst zurückgegebenen Rohfehlerdaten enthält.

Beispiel für das Format einer Fehlerantwort

Einige der Optionen zur Anzeige der Fehlerantworten sind:

Hinzufügen eines Fehler-Handlers mithilfe des Regeleditors

Mithilfe der Aktion Aufrufdienst des Regeleditors definieren Sie die Validierungskriterien basierend auf der Datenquelle, die Sie mit dem adaptiven Formular verwenden. Wenn Sie beispielsweise RESTful-Web-Services als Datenquelle verwenden, können Sie die Validierungskriterien in einer Swagger-Definitionsdatei definieren. Durch die Verwendung der Funktionen des Fehler-Handlers und des Regeleditors in adaptiven Formularen können Sie die Fehlerbehandlung effektiv verwalten und anpassen. Sie definieren die Bedingungen mithilfe des Regeleditors und konfigurieren die gewünschten Aktionen, die ausgeführt werden sollen, wenn die Regel ausgelöst wird. Adaptive Formulare validieren die Eingaben, die Sie in Felder eingeben, auf der Grundlage von voreingestellten Validierungskriterien. Falls die Eingabewerte die Validierungskriterien nicht erfüllen, werden die Fehlermeldungen auf Feldebene in einem adaptiven Formular angezeigt.

Mit dem Regeleditor können Sie folgende Aktionen durchführen:

• Hinzufügen einer benutzerdefinierten Fehler-Handler-Funktion
• Hinzufügen einer benutzerdefinierten Fehler-Handler-Funktion

Hinzufügen einer benutzerdefinierten Fehler-Handler-Funktion

Ein Standard-Fehler-Handler wird unterstützt, um Fehlermeldungen zu Feldern anzuzeigen, wenn sich die Fehlerantwort im Standardschema befindet oder es sich um Server-seitige Validierungsfehler handelt.
Um zu verstehen, wie man einen Standard-Fehler-Handler mit der Aktion Aufrufdienst des Regeleditors verwendet, nehmen wir das Beispiel eines einfachen adaptiven Formulars mit zwei Feldern, Haustier-ID und Haustiername. Verwenden Sie einen Standard-Fehler-Handler für das Feld Haustier-ID, um verschiedene Fehler zu überprüfen, die vom REST-Endpunkt zurückgegeben werden können, der zum Aufrufen eines externen Dienstes konfiguriert ist, z. B. 200 - OK, 404 - Not Found, 400 - Bad Request. Führen Sie die folgenden Schritte aus, um mithilfe der Aktion „Aufrufdienst des Regeleditors“ einen Standard-Fehler-Handler hinzuzufügen:

1. Öffnen Sie ein adaptives Formular im Authoring-Modus, wählen Sie eine Formularkomponente und wählen Sie Regeleditor , um den Regeleditor zu öffnen.
2. Wählen Sie Erstellen aus.
3. Definieren Sie eine Bedingung im Abschnitt Wann der Regel. Beispiel: Wann[Name des Felds "Haustier-ID"] geändert. Wählen Sie die Option aus. Status auswählen Dropdown-Liste.
4. Im Abschnitt Dann wählen Sie Dienst aufrufen aus der Dropdown-Liste Aktion auswählen.
5. Wählen Sie einen Post-Service und die zugehörigen Datenbindungen aus dem Abschnitt Eingabe. Beispiel: Um Haustier-ID zu validieren, wählen Sie einen Post-Service als GET /pet/{petId} und wählen Sie Haustier-ID im Abschnitt Eingabe.
6. Wählen Sie die Datenbindungen aus dem Abschnitt Ausgabe. Wählen Sie Haustiername im Abschnitt Ausgabe aus.
7. Wählen Sie Standard-Fehler-Handler im Abschnitt Fehler-Handler aus.
8. Klicken Sie auf Fertig.

Aufgrund dieser Regel werden die Werte, die Sie für Haustier-ID eingeben, bei der Validierung von Haustiername über einen externen Dienst überprüft, der vom REST-Endpunkt aufgerufen wird. Wenn die auf der Datenquelle basierenden Validierungskriterien fehlschlagen, werden die Fehlermeldungen auf Feldebene angezeigt.

Hinzufügen einer benutzerdefinierten Fehler-Handler-Funktion

Sie können eine benutzerdefinierte Fehler-Handler-Funktion hinzufügen, um einige Aktionen auszuführen, wie z. B.:

• Behandlung von Fehlerantworten, die nicht standardmäßige oder Standardfehlerantworten verwenden. Beachten Sie, dass diese nicht standardmäßigen Fehlerantworten nicht mit dem Standardschema von Fehlerantworten übereinstimmen.
• Senden von Analyseereignissen an beliebige Analyse-Plattformen. Zum Beispiel Adobe Analytics.
• Anzeigen eines modalen Dialogfelds mit Fehlermeldungen.

Zusätzlich zu den genannten Aktionen können die benutzerdefinierten Fehler-Handler verwendet werden, um benutzerdefinierte Funktionen auszuführen, die bestimmten Benutzeranforderungen entsprechen.

Der benutzerdefinierte Fehler-Handler ist eine Funktion (Client-Bibliothek), die auf von einem externen Dienst zurückgegebene Fehler reagiert und Endbenutzenden eine benutzerdefinierte Antwort bereitstellt. Jede Client-Bibliothek mit Anmerkungen @errorHandler wird als benutzerdefinierte Fehler-Handler-Funktion betrachtet. Diese Anmerkung hilft, die in der .js-Datei angegebene Fehler-Handler-Funktion zu identifizieren.
Um zu verstehen, wie man einen benutzerdefinierten Fehler-Handler mit der Aktion Aufrufdienst des Regeleditors erstellt und verwendet, nehmen wir ein Beispiel für ein adaptives Formular mit zwei Feldern, Haustier-ID und Haustiername und verwenden einen benutzerdefinierten Fehler-Handler für das Feld Haustier-ID, um verschiedene Fehler zu überprüfen, die vom REST-Endpunkt zurückgegeben werden, der zum Aufrufen eines externen Dienstes konfiguriert ist, z. B. 200 - OK, 404 - Not Found, 400 - Bad Request.

Um einen benutzerdefinierten Fehler-Handler in einem adaptiven Formular hinzuzufügen und zu verwenden, führen Sie die folgenden Schritte aus:

1. Erstellen eines benutzerdefinierten Fehler-Handlers
2. Verwenden des Regeleditors zum Konfigurieren des benutzerdefinierten Fehler-Handlers

1. Erstellen Sie einen benutzerdefinierten Fehler-Handler

Um eine benutzerdefinierte Fehlerfunktion zu erstellen, führen Sie die folgenden Schritte aus:

1. Klonen Sie Ihr AEM Forms as a Cloud Service-Repository.

2. Erstellen Sie einen Ordner unter dem Ordner [AEM Forms as a Cloud Service repository folder]/apps/. Erstellen Sie beispielsweise einen Ordner mit dem Namen experience-league

3. Navigieren Sie zu [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/ und erstellen Sie einen ClientLibraryFolder als clientlibs.

4. Erstellen Sie einen Ordner mit dem Namen js.

5. Navigieren Sie zum Ordner [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js.

6. Fügen Sie eine JavaScript-Datei hinzu, beispielsweise function.js. Die Datei enthält den Code für den benutzerdefinierten Fehler-Handler.
   Fügen wir den folgenden Code zur JavaScript-Datei hinzu, um die Antwort und die Kopfzeilen, die wir vom Endpunkt des REST-Dienstes erhalten haben, in der Browser-Konsole anzuzeigen.

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

   Zum Aufrufen des Standard-Fehler-Handlers über Ihren benutzerdefinierten Fehler-Handler wird folgende Zeile des Beispiel-Codes verwendet:
   guidelib.dataIntegrationUtils.defaultErrorHandler(response, headers)

   HINWEIS

   Fügen Sie in der Datei .content.xml die Eigenschaften allowProxy und categories hinzu.

   • allowProxy = [Boolean]true
   • categories= customfunctionsdemo
     Beispiel: In diesem Fall wird [custom-errorhandler-name] als customfunctionsdemo bereitgestellt.

7. Speichern Sie die Datei function.js.

8. Navigieren Sie zum Ordner [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js.

9. Hinzufügen einer Textdatei als js.txt. Die Datei enthält:

       #base=js
       functions.js
   

10. Speichern Sie die Datei js.txt.
    Die erstellte Ordnerstruktur sieht wie folgt aus:

    

    HINWEIS

    Um mehr über das Erstellen benutzerdefinierter Funktionen zu erfahren, klicken Sie auf benutzerdefinierte Funktionen im Regeleditor.

11. Fügen Sie die Änderungen mit den folgenden Befehlen hinzu, übertragen Sie sie und pushen Sie sie in das Repository:

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

12. Ausführen der Pipeline.

Sobald die Pipeline erfolgreich ausgeführt wurde, steht der benutzerdefinierte Fehler-Handler im Regeleditor für adaptive Formulare zur Verfügung. Im Folgenden erfahren Sie, wie Sie einen benutzerdefinierten Fehler-Handler mit dem Aufrufdienst des Regeleditors in AEM Forms konfigurieren und verwenden.

2. Verwenden Sie den Regeleditor, um den benutzerdefinierten Fehler-Handler zu konfigurieren

Bevor Sie den benutzerdefinierten Fehler-Handler in einem adaptiven Formular implementieren, stellen Sie sicher, dass der Name der Client-Bibliothek in der Client-Bibliothekskategorie dem Namen entspricht, der in der Kategorieoption der Datei .content.xml angegeben ist.

In diesem Fall wird der Name der Client-Bibliothek als customfunctionsdemo in der Datei .content.xml angegeben.

Um einen benutzerdefinierten Fehler-Handler zu verwenden, verwenden Sie die Aktion Aufrufdienst des Regeleditors:

1. Öffnen Sie ein adaptives Formular im Authoring-Modus, wählen Sie eine Formularkomponente und wählen Sie Regeleditor , um den Regeleditor zu öffnen.
2. Wählen Sie Erstellen aus.
3. Definieren Sie eine Bedingung im Abschnitt Wann der Regel. Beispiel: Wenn der [Name des Felds „Haustier-ID“] geändert wird, wählen Sie Geändert aus der Dropdown-Liste Status auswählen.
4. Im Abschnitt Dann wählen Sie Dienst aufrufen aus der Dropdown-Liste Aktion auswählen.
5. Wählen Sie einen Post-Service und die zugehörigen Datenbindungen aus dem Abschnitt Eingabe. Beispiel: Um Haustier-ID zu validieren, wählen Sie einen Post-Service als GET /pet/{petId} und wählen Sie Haustier-ID im Abschnitt Eingabe.
6. Wählen Sie die Datenbindungen aus dem Abschnitt Ausgabe. Wählen Sie beispielsweise Haustiername im Abschnitt Ausgabe.
7. Wählen Sie Benutzerdefinierter Fehler-Handler aus dem Abschnitt Fehler-Handler.
8. Klicken Sie auf Fertig.

Aufgrund dieser Regel werden die Werte, die Sie für Haustier-ID eingeben, bei der Validierung von Haustiername über einen externen Dienst überprüft, der vom REST-Endpunkt aufgerufen wird. Wenn die auf der Datenquelle basierenden Validierungskriterien fehlschlagen, werden die Fehlermeldungen auf Feldebene angezeigt.

Öffnen Sie die Browser-Konsole und überprüfen Sie die Antwort und die Kopfzeile, die vom REST-Dienstendpunkt empfangen wurden, auf die Überprüfungsfehlermeldung.

Die benutzerdefinierte Fehler-Handler-Funktion ist für die Ausführung zusätzlicher Aktionen verantwortlich, z. B. für die Anzeige eines modalen Dialogfelds oder das Senden eines Analytics-Ereignisses basierend auf der Fehlerantwort. Eine benutzerdefinierte Fehler-Handler-Funktion bietet die Flexibilität, die Fehlerbehandlung an die spezifischen Benutzeranforderungen anzupassen.

Siehe auch

• Erstellen eines adaptiven AEM-Formulars
• Hinzufügen eines adaptiven AEM-Formulars zu einer AEM Sites-Seite
• Anwenden von Designs auf ein adaptives AEM-Formular
• Hinzufügen von Komponenten zu einem adaptiven AEM-Formular
• Verwenden von CAPTCHA in einem adaptiven AEM-Formular
• Generieren der PDF-Version (DoR) eines adaptiven AEM-Formulars
• Übersetzen eines adaptiven AEM-Formulars
• Aktivieren von Adobe Analytics für ein adaptives Formular, um die Formularnutzung zu verfolgen.
• Verbinden eines adaptiven Formulars mit Microsoft SharePoint
• Verbinden eines adaptiven Formulars mit Microsoft Power Automate
• Verbinden eines adaptiven Formulars mit Microsoft OneDrive
• Verbinden eines adaptiven Formulars mit Microsoft Azure Blob Storage
• Verbinden eines adaptiven Formulars mit Salesforce
• Verwenden von Adobe Sign in einem adaptiven AEM-Formular
• Hinzufügen eines neuen Gebietsschemas für ein adaptives Formular
• Senden von Daten adaptiver Formulare an eine Datenbank
• Senden von Daten adaptiver Formulare an einen REST-Endpunkt
• Senden von Daten adaptiver Formulare an einen AEM-Workflow
• Verwenden des Formularportals zur Auflistung von adaptiven AEM-Formularen auf einer AEM-Website
• Erstellen und Verwenden benutzerdefinierter Fehler-Handler in Adaptive Forms (Kernkomponenten)