Aggiungere gestori di errori personalizzati nel Forms adattivo dell’AEM error-handlers-in-adaptive-form

Adobe consiglia di utilizzare l'acquisizione dati moderna ed estensibile Componenti coreper la creazione di un nuovo Forms adattivoo l'aggiunta di Forms adattivo alle pagine AEM Sites. Questi componenti rappresentano un progresso significativo nella creazione di Forms adattivi, garantendo esperienze utente straordinarie. Questo articolo descrive un approccio precedente all’authoring di Forms adattivi utilizzando i componenti di base.

AEM Forms fornisce gestori predefiniti di successo e di errori per l’invio di moduli. Fornisce inoltre funzionalità per personalizzare le funzioni del gestore degli errori. Ad esempio, puoi richiamare un flusso di lavoro personalizzato nel backend per codici di errore specifici o informare il cliente che il servizio non è disponibile. I gestori sono funzioni lato client che vengono eseguite in base alla risposta del server. Quando un servizio esterno viene richiamato utilizzando le API, i dati vengono trasmessi al server per la convalida, che restituisce una risposta al client con informazioni sull’evento di successo o errore per l’invio. Le informazioni vengono passate come parametri al gestore pertinente per eseguire la funzione. Un gestore degli errori consente di gestire e visualizzare gli errori o i problemi di convalida rilevati.

Il modulo adattivo convalida gli input forniti nei campi in base a criteri di convalida predefiniti e verifica la presenza di vari errori restituiti dall’endpoint REST configurato per richiamare un servizio esterno. È possibile impostare i criteri di convalida in base all’origine dati utilizzata con il modulo adattivo. Ad esempio, se utilizzi i servizi web RESTful come origine dati, puoi definire i criteri di convalida in un file di definizione Swagger.

Se i valori di input soddisfano i criteri di convalida, vengono inviati all’origine dati, altrimenti nel modulo adattivo viene visualizzato un messaggio di errore tramite un gestore degli errori. Simile a questo approccio, Forms adattivo si integra con gestori di errori personalizzati per eseguire le convalide dei dati. Se i valori di input non soddisfano i criteri di convalida, i messaggi di errore vengono visualizzati a livello di campo nel modulo adattivo. Ciò si verifica quando il messaggio di errore di convalida restituito dal server è nel formato di messaggio standard.

Utilizzo dei gestori di errori uses-of-error-handler

I gestori di errori vengono utilizzati per vari scopi. Di seguito sono elencati alcuni degli utilizzi delle funzioni di gestione degli errori:

Formato della risposta di errore/errore failure-response-format

Un modulo adattivo visualizza gli errori a livello di campo se i messaggi di errore di convalida del server sono nel seguente formato standard.
Il codice riportato di seguito illustra la struttura di risposta dei guasti esistente:

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

Dove:

Con i miglioramenti delle funzioni e i successivi aggiornamenti delle versioni di AEM Forms, la struttura di risposta dei guasti esistente è stata modificata in un nuovo formato basato su RFC7807, compatibile con le versioni precedenti della struttura di risposta dei guasti esistente:

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

Dove:

Formato risposta errore di esempio sample-error-response-format

Alcune delle opzioni per visualizzare le risposte di errore sono:

Aggiungi gestore errori tramite l’Editor regole add-error-handler-using-rule-editor

Utilizzando l'azione Invoke Service🔗 dell'editor di regole , puoi definire i criteri di convalida in base all'origine dati utilizzata con il modulo adattivo. Se si utilizzano i servizi Web RESTful come origine dati, è possibile definire i criteri di convalida in un file di definizione Swagger. Utilizzando le funzioni di gestore degli errori e l’editor di regole in Adaptive Forms, puoi gestire e personalizzare in modo efficace la gestione degli errori. Definisci le condizioni utilizzando l’Editor regole e configura le azioni da eseguire quando la regola viene attivata. Il modulo adattivo convalida gli input immessi nei campi in base a criteri di convalida predefiniti. Se i valori di input non soddisfano i criteri di convalida, i messaggi di errore vengono visualizzati a livello di campo in un modulo adattivo.

Utilizzando l’editor di regole, puoi:

Aggiungi funzione gestore errori predefinita add-default-errror-handler

È supportato un gestore degli errori predefinito per visualizzare i messaggi di errore sui campi se la risposta di errore si trova nello schema standard o in un errore di convalida lato server.
Per informazioni su come utilizzare un gestore di errori predefinito utilizzando l'azione Richiama servizio🔗 dell'editor di regole, utilizzare un modulo adattivo semplice con due campi, ID animale domestico e Nome animale e utilizzare un gestore di errori predefinito nel campo ID animale per verificare la presenza di vari errori restituiti dall'endpoint REST configurato per richiamare un servizio esterno, ad esempio 200 - OK,404 - Not Found, 400 - Bad Request. Per aggiungere un gestore degli errori predefinito tramite l’azione Richiama servizio dell’editor di regole, esegui i passaggi seguenti:

Come risultato di questa regola, i valori immessi per ID animale controllano la convalida per Nome animale utilizzando il servizio esterno richiamato dall'endpoint REST. Se i criteri di convalida basati sull’origine dati non riescono, i messaggi di errore vengono visualizzati a livello di campo.

Aggiungi funzione di gestione degli errori personalizzata add-custom-errror-handler

È possibile aggiungere una funzione di gestione degli errori personalizzata per eseguire alcune delle azioni seguenti:

Oltre alle azioni citate, i gestori degli errori personalizzati possono essere utilizzati per eseguire funzioni personalizzate che soddisfano requisiti utente specifici.

Il gestore degli errori personalizzati è una funzione (libreria client) progettata per rispondere agli errori restituiti da un servizio esterno e fornire una risposta personalizzata agli utenti finali. Qualsiasi libreria client con annotazione @errorHandler è considerata una funzione di gestore degli errori personalizzata. Questa annotazione consente di identificare la funzione di gestione degli errori specificata nel file .js.
Per capire come creare e utilizzare un gestore di errori personalizzato utilizzando l'azione Richiama servizio🔗 dell'editor di regole, prendiamo ad esempio il modulo adattivo con due campi, ID animale domestico e Nome animale, e utilizziamo un gestore di errori personalizzato nel campo ID animale per verificare la presenza di vari errori restituiti dall'endpoint REST configurato per richiamare un servizio esterno, ad esempio 200 - OK,404 - Not Found, 400 - Bad Request.

Per aggiungere e utilizzare un gestore di errori personalizzato in un modulo adattivo, effettua le seguenti operazioni:

1. Creare un gestore degli errori personalizzato create-custom-error-message

Per creare una funzione di errore personalizzata, effettuare le seguenti operazioni:

Una volta eseguita correttamente la pipeline, il gestore degli errori personalizzato diventa disponibile nell’editor di regole del modulo adattivo. Ora vediamo come configurare e utilizzare un gestore di errori personalizzato utilizzando il servizio Invoke dell’editor di regole in AEM Forms.

2. Utilizza l’Editor regole per configurare un gestore degli errori personalizzato use-custom-error-handler

Prima di implementare il gestore di errori personalizzato in un modulo adattivo, accertati che il nome della libreria client nella Categoria libreria client sia allineato al nome specificato nell'opzione delle categorie del file .content.xml.

In questo caso, il nome della libreria client viene fornito come customfunctionsdemo nel file .content.xml.

Per utilizzare un gestore degli errori personalizzato utilizzando l'azione Richiama servizio dell'editor di regole:

Come risultato di questa regola, i valori immessi per ID animale controllano la convalida per Nome animale utilizzando il servizio esterno richiamato dall'endpoint REST. Se i criteri di convalida basati sull’origine dati non riescono, i messaggi di errore vengono visualizzati a livello di campo.

Apri la console del browser e controlla la risposta e l’intestazione, ricevute dall’endpoint del servizio REST, per il messaggio di errore di convalida.

La funzione del gestore degli errori personalizzato è responsabile dell’esecuzione di azioni aggiuntive, ad esempio la visualizzazione di una finestra di dialogo modale o l’invio di un evento di analisi, in base alla risposta all’errore. Una funzione di gestione degli errori personalizzata offre la flessibilità necessaria per adattare la gestione degli errori ai requisiti utente specifici.

Consulta anche see-also