Manipuladores de erros para o formulário adaptável com base nos Componentes principais

O AEM Forms fornece manipuladores de sucesso e erro prontos para uso para envios de formulários. Ele também fornece recursos para personalizar funções do manipulador de erros. Por exemplo, você pode chamar um fluxo de trabalho personalizado no backend para códigos de erro específicos ou informar ao cliente que o serviço está inativo. Os manipuladores são funções do lado do cliente executadas com base na resposta do servidor. Quando um serviço externo é chamado usando APIs, os dados são transmitidos ao servidor para validação, o que retorna uma resposta ao cliente com informações sobre o evento bem-sucedido ou com erro para o envio. As informações são passadas como parâmetros para o manipulador relevante para executar a função. Um manipulador de erros ajuda a gerenciar e exibir erros ou problemas de validação encontrados.

O Formulário adaptável valida as entradas que você fornece nos campos com base em critérios de validação predefinidos e verifica vários erros retornados pelo endpoint REST configurado para chamar um serviço externo. Você pode definir os critérios de validação com base na fonte de dados usada com o Formulário adaptável. Por exemplo, se você usar os serviços Web RESTful como fonte de dados, poderá definir os critérios de validação em um arquivo de definição do Swagger.

Se os valores de entrada atenderem aos critérios de validação, os valores serão enviados para a fonte de dados ou então, o Formulário adaptável exibirá uma mensagem de erro usando um manipulador de erros. Semelhante a essa abordagem, o Adaptive Forms é integrado a manipuladores de erro personalizados para executar validações de dados. Se os valores de entrada não atenderem aos critérios de validação, as mensagens de erro serão exibidas em nível de campo no Formulário adaptável. Isso ocorre quando a mensagem de erro de validação retornada pelo servidor está no formato de mensagem padrão.

Usos de manipuladores de erros

Os manipuladores de erros são usados para vários propósitos. Alguns dos usos das funções do manipulador de erros estão listados abaixo:

• Executar validação: o tratamento de erros começa com a validação das entradas do usuário em relação a regras ou critérios predefinidos. À medida que os usuários preenchem um Formulário adaptável, o manipulador de erros valida a entrada para garantir que ela atenda ao formato, ao comprimento ou a qualquer outra restrição necessária.

• Fornecer feedback em tempo real: quando qualquer erro é detectado, o manipulador de erros exibe um feedback imediato do usuário, como mensagens de erro em linha abaixo dos campos de formulário correspondentes. Este feedback ajuda os usuários a identificar e corrigir erros sem precisar enviar o formulário e aguardar uma resposta.

• Exibir mensagens de erro: quando um envio de Formulário adaptável encontra qualquer erro de validação, o manipulador de erros exibe uma mensagem de erro apropriada. As mensagens de erro devem ser claras, concisas e destacar os campos específicos que exigem atenção.

• Realça o campo incorreto: para chamar a atenção do usuário para os campos incorretos específicos, o manipulador de erros destaca ou diferencia visualmente os campos correspondentes. Ela é executada alterando a cor do plano de fundo, adicionando um ícone ou uma borda ou qualquer outra dica visual que ajude os usuários a localizar e corrigir os erros rapidamente.

Formato de resposta de falha/erro

Um Formulário adaptável exibe os erros em um nível de campo se as mensagens de erro de validação do servidor estiverem no seguinte formato padrão.
O código abaixo ilustra a estrutura de resposta de falha existente:

   {
    errorCausedBy : "SERVER_SIDE_VALIDATION/SERVICE_INVOCATION_FAILURE"
    errors : [
        {
             errorMessage / errorMessages : <validationMsg> / [<validationMsg>, <validationMsg>]
        }
    ]
    originCode : <target error Code>
    originMessage : <unstructured error message returned by service>
    }

Em que:

• errorCausedBy descreve o motivo da falha.
• errors mencione a expressão dos campos que falharam nos critérios de validação junto com a mensagem de erro de validação.
• originCode campo adicionado pelo AEM e contém o código de status http retornado pelo serviço externo.
• originMessage campo adicionado pelo AEM e contém os dados de erro brutos retornados pelo serviço externo.

Com as melhorias nos recursos e atualizações subsequentes nas versões do AEM Forms, a estrutura de resposta a falhas existente mudou para um novo formato com base no RFC7807, que é compatível com versões anteriores com a estrutura de resposta a falhas existente:

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

Em que:

• type (required) especifica o tipo de falha. Pode ser um dos seguintes valores:

  • SERVER_SIDE_VALIDATION indica uma falha devido à validação do lado do servidor.
  • FORM_SUBMISSION indica uma falha durante o envio do formulário
  • SERVICE_INVOCATION indica uma falha durante uma invocação de serviço de terceiros.
  • FAILURE indica uma falha geral.
  • VALIDATION_ERROR indica uma falha devido a um erro de validação.

• title (optional) fornece um título ou uma breve descrição da falha.

• detail (optional) A seção fornece detalhes adicionais sobre a falha, se necessário.

• instance (optional) representa uma instância ou identificador associado à falha e ajuda a rastrear ou identificar a ocorrência específica da falha.

• validationErrors (required) contém informações sobre erros de validação. Inclui os seguintes campos:

  • fieldname menciona o nome do campo qualificado dos campos que falharam nos critérios de validação.
  • dataRef representa o caminho JSON ou XPath dos campos que falharam na validação.
  • details contém a mensagem de erro de validação com o campo errado.

• originCode (optional) campo adicionado pelo AEM e contém o código de status http retornado pelo serviço externo

• originMessage (optional) campo adicionado pelo AEM e contém os dados de erro brutos retornados pelo serviço externo.

Formato de resposta de erro de exemplo

Algumas das opções para exibir as respostas de erro são:

Requisitos para adicionar manipulador de erros usando o serviço Chamar do Editor de regras

Antes de adicionar um manipulador de erros usando o serviço Chamar do Editor de regras:

• Ativar os Componentes principais adaptáveis do Forms para o ambiente do AEM Cloud Service.

• Saiba como criar funções personalizadas.

Adicionar manipulador de erros usando o Editor de regras

Usar o Serviço de chamada do editor de regras , você define os critérios de validação com base na fonte de dados usada com o Formulário adaptável. Caso você use os serviços Web RESTful como fonte de dados, é possível definir os critérios de validação em um arquivo de definição do Swagger. Ao usar as funções do manipulador de erros e o Editor de regras no Adaptive Forms, você pode gerenciar e personalizar com eficiência a manipulação de erros. Você define as condições usando o Editor de regras e configura as ações desejadas a serem executadas quando a regra for acionada. O Formulário adaptável valida as entradas inseridas nos campos com base em critérios de validação predefinidos. Caso os valores de entrada não atendam aos critérios de validação, as mensagens de erro serão exibidas no nível do campo em um Formulário adaptável.

Usando o Editor de regras, você pode:

• Adicionar função de manipulador de erros padrão
• Adicionar função de manipulador de erro personalizada

Adicionar função de manipulador de erros padrão

Um manipulador de erros padrão é compatível com a exibição de mensagens de erro em campos se a resposta do erro estiver no esquema padrão ou na falha de validação do lado do servidor.
Para entender como usar um manipulador de erros padrão usando o Serviço de chamada do editor de regras , confira um exemplo de um Formulário adaptável simples com dois campos, ID do animal de estimação e Nome do animal de estimação e use um manipulador de erros padrão no ID do animal de estimação para verificar vários erros retornados pelo endpoint REST configurado para chamar um serviço externo, por exemplo, 200 - OK,404 - Not Found, 400 - Bad Request. Para adicionar um manipulador de erros padrão usando a ação Chamar serviço do Editor de regras, execute as seguintes etapas:

1. Abra um formulário adaptável no modo de criação, selecione um componente de formulário e Editor de regras para abrir o editor de regras.
2. Selecione Criar.
3. Crie uma condição no Quando seção da regra. Por exemplo, Quando[Nome do campo de ID do animal de estimação] foi alterado. Selecione é alterado de Selecionar Estado lista suspensa.
4. No Depois , selecione Chamar serviço do Selecionar ação lista suspensa.
5. Selecione um Pós-serviço e as vinculações de dados correspondentes do Entrada seção. Por exemplo, para validar ID do animal de estimação, selecione um Pós-serviço as GET /pet/{petId} e selecione ID do animal de estimação no Entrada seção.
6. Selecione as associações de dados na Output seção. Selecionar Nome do animal de estimação no Output seção.
7. Selecionar Manipulador de erro padrão do Manipulador de erros seção.
8. Clique em Concluído.

Como resultado dessa regra, os valores inseridos para ID do animal de estimação verifica a validação de Nome do animal de estimação usando serviço externo chamado pelo ponto de extremidade REST. Se os critérios de validação com base na fonte de dados falharem, as mensagens de erro serão exibidas no nível do campo.

Adicionar função de manipulador de erro personalizada

Você pode adicionar uma função de manipulador de erros personalizada para executar algumas das ações, como:

• lidam com respostas de erro que usam respostas de erro não padrão ou padrão. É importante observar que essas respostas de erro não padrão não estão em conformidade com as esquema padrão de respostas de erro.
• envie eventos do analytics para qualquer plataforma do analytics. Por exemplo, Adobe Analytics.
• exibir caixa de diálogo modal com mensagens de erro.

Além das ações mencionadas, os manipuladores de erros personalizados podem ser usados para executar funções personalizadas que atendam a requisitos específicos do usuário.

O manipulador de erros personalizado é uma função (Biblioteca do cliente) criada para responder aos erros retornados por um serviço externo e fornecer uma resposta personalizada aos usuários finais. Qualquer biblioteca do cliente com anotação @errorHandler é considerada uma função de manipulador de erros personalizada. Essa anotação ajuda a identificar a função do manipulador de erros especificada no .js arquivo.
Para entender como criar e usar um manipulador de erros personalizado usando o Serviço Chamar do editor de regras vamos ver um exemplo de Formulário adaptável com dois campos, ID do animal de estimação e Nome do animal de estimação e use um manipulador de erros personalizado no ID do animal de estimação para verificar vários erros retornados pelo endpoint REST configurado para chamar um serviço externo, por exemplo, 200 - OK,404 - Not Found, 400 - Bad Request.

Para adicionar e usar um manipulador de erros personalizado em um Formulário adaptável, execute as seguintes etapas:

1. Criar um manipulador de erros personalizado
2. Usar o Editor de regras para configurar o manipulador de erros personalizado

1. Criar um manipulador de erros personalizado

Para criar uma função de erro personalizada, execute as seguintes etapas:

Para criar uma função de erro personalizada, execute as seguintes etapas:

1. Clonar o Repositório as a Cloud Service do AEM Forms..

2. Crie uma pasta em [AEM Forms as a Cloud Service repository folder]/apps/ pasta. Por exemplo, crie uma pasta chamada como experience-league

3. Navegue até [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/experience-league/ e criar um ClientLibraryFolder as clientlibs.

4. Crie uma pasta chamada js.

5. Navegue até a [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js pasta.

6. Adicione um arquivo JavaScript, por exemplo, function.js. O arquivo compreende o código do manipulador de erros personalizado.
   Vamos adicionar o seguinte código ao arquivo JavaScript para exibir a resposta e os cabeçalhos, recebidos do endpoint do serviço REST, no console do navegador.

       /**
       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.")
           globals.invoke('defaultErrorHandler',response, headers)
           console.log("Custom Error Handler processing end...");
       }
   

   Para chamar o manipulador de erros padrão a partir do manipulador de erros personalizado, a seguinte linha do código de amostra é usada:
   globals.invoke('defaultErrorHandler',response, headers)

   OBSERVAÇÃO

   No .content.xml arquivo, adicionar categories = [custom-errorhandler-name]. Por exemplo, neste caso, [custom-errorhandler-name] é fornecido como customfunctionsdemoV2.

7. Salve o function.js arquivo.

8. Navegue até a [AEM Forms as a Cloud Service repository folder]/apps/[AEM Project Folder]/clientlibs/js pasta.

9. Adicionar um arquivo de texto como js.txt. O arquivo contém:

       #base=js
       functions.js
   

10. Salve o js.txt arquivo.
    A estrutura de pastas criada é semelhante a:

    

    OBSERVAÇÃO

    Para saber mais sobre como criar funções personalizadas, clique em funções personalizadas no Editor de regras.

11. Adicione, confirme e envie as alterações no repositório usando os comandos abaixo:

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

12. Execute o pipeline.

Depois que o pipeline é executado com êxito, o manipulador de erros personalizado fica disponível em seu editor de regras do Formulário adaptável. Agora, vamos entender como configurar e usar um manipulador de erros personalizado usando o serviço Chamar do editor de regras no AEM Forms.

2. Use o Editor de regras para configurar o manipulador de erros personalizado

Antes de implementar o manipulador de erros personalizado em um Formulário adaptável, verifique se o nome da biblioteca do cliente no Categoria da biblioteca cliente alinha com o nome especificado na opção categories do .content.xml arquivo.

Para usar um manipulador de erros personalizado usando o Serviço de chamada do editor de regras ação:

1. Abra um formulário adaptável no modo de criação, selecione um componente de formulário e Editor de regras para abrir o editor de regras.
2. Selecione Criar.
3. Crie uma condição no Quando seção da regra. Por exemplo, Quando [Nome do campo de ID do animal de estimação] for alterado, selecione foi alterado do Selecionar Estado lista suspensa.
4. No Depois , selecione Chamar serviço do Selecionar ação lista suspensa.
5. Selecione um Pós-serviço e as vinculações de dados correspondentes do Entrada seção. Por exemplo, para validar ID do animal de estimação, selecione um Pós-serviço as GET /pet/{petId} e selecione ID do animal de estimação no Entrada seção.
6. Selecione as associações de dados na Output seção. Por exemplo, selecione Nome do animal de estimação no Output seção.
7. Selecionar Manipulador de erro personalizado do Manipulador de erros seção.
8. Clique em Concluído.

s

Como resultado dessa regra, os valores inseridos para ID do animal de estimação verifica a validação de Nome do animal de estimação usando serviço externo chamado pelo ponto de extremidade REST. Se os critérios de validação com base na fonte de dados falharem, as mensagens de erro serão exibidas no nível do campo.

Abra o console do navegador e verifique a mensagem de erro de validação na resposta e no cabeçalho, recebidos do ponto de acesso do serviço REST.

A função de manipulador de erros personalizada é responsável por executar ações adicionais, como exibir uma caixa de diálogo modal ou enviar um evento de análise, com base na resposta do erro. Uma função de manipulador de erros personalizada oferece a flexibilidade para adaptar o tratamento de erros aos requisitos específicos do usuário.

Informações adicionais

• Criar um formulário adaptável independente baseado nos Componentes principais
• Criar estilo ou temas para seus formulários
• Criar ou adicionar um formulário adaptável à página do AEM Sites

Consulte também

• Criar um formulário adaptável de AEM
• Adicionar um formulário adaptável de AEM à página do AEM Sites
• Aplicar temas a um formulário adaptável de AEM
• Adicionar componentes a um formulário adaptável de AEM
• Usar CAPTCHA em um formulário adaptável de AEM
• Gerar versão do PDF (DoR) de um formulário adaptável AEM
• Traduzir um formulário adaptável de AEM
• Ativar o Adobe Analytics para um formulário adaptável para rastrear o uso do formulário
• Conectar o formulário adaptável ao Microsoft SharePoint
• Conectar o formulário adaptável ao Microsoft Power Automate
• Conectar o formulário adaptável ao Microsoft OneDrive
• Conectar o formulário adaptável ao armazenamento de blobs do Microsoft Azure
• Conectar o formulário adaptável ao Salesforce
• Usar o Adobe Sign em um formulário adaptável AEM
• Adicionar uma nova localidade para um Formulário adaptável
• Enviar dados do Formulário adaptável a um banco de dados
• Enviar dados do formulário adaptável para um endpoint REST
• Enviar dados do formulário adaptável para o fluxo de trabalho do AEM
• Usar o Forms Portal para listar AEM Adaptive Forms em um site de AEM