Regras de validação no Jitterbit App Builder

Validações são uma regra propósito usada para proteger a integridade dos dados. Elas podem ser executadas contra dados que os usuários finais inserem manualmente, rejeitando registros que violam a lógica de negócios (por exemplo, registros duplicados). Se uma regra CRUD for definida para um objeto de negócios, suas validações também serão executadas automaticamente sempre que essa regra CRUD for acionada. As mensagens de validação exibidas aos usuários são configuráveis e suportam substituição dinâmica para uma melhor experiência do usuário.

Como outras regras, uma regra de validação é criada na camada de negócios e só entra em vigor uma vez que está registrada em um evento. Para um guia completo sobre como criar uma regra de validação e registrá-la em um evento intrínseco, consulte Regras de validação em Introdução ao App Builder - Aula 7: Mais sobre regras, e Validações em Apêndice B para um exemplo mais avançado. Esta página cobre os campos do diálogo de Validação em detalhes, juntamente com as melhores práticas a serem lembradas ao trabalhar com regras de validação.

Registrar uma validação em um evento

Uma vez que a cláusula WHERE de uma regra de validação define os dados que ela deve capturar, registre-a em um evento intrínseco ou personalizado para que ela seja executada. No painel de Validações do evento, clique em Registrar para abrir o diálogo de Validação:

O diálogo de Validação inclui os seguintes campos:

• Tipo: Selecione Regra para executar uma regra de negócios como validação, ou Plugin para usar um plugin de validação pré-construído, como o Plugin de Validação Regex.

• Regra: Selecione a regra de validação a ser executada. Mostrado apenas quando Tipo está definido como Regra.

• Vinculação: Selecione Implícita ou Explícita. Veja Vinculação implícita e explícita para decidir qual usar.

• Falha: Selecione Falhar ao retornar dados se a regra for escrita para encontrar dados ruins (a abordagem mais comum). Se a regra for escrita para encontrar dados bons, selecione Falhar ao não retornar dados, de modo que a ausência de dados retornados indique uma falha.

• Severidade: Selecione Erro para bloquear completamente o salvamento, Aviso para permitir que o usuário escolha se deseja prosseguir, ou Informação para exibir uma mensagem sem interromper o fluxo de trabalho.

• Mensagem: Insira a mensagem exibida ao usuário quando a validação é acionada. Este campo suporta substituição dinâmica usando espaços reservados {{ ColumnName }}. Qualquer coluna substituída também deve estar disponível no objeto de negócios no qual o evento está registrado.

• Rótulo: (Opcional) Insira um rótulo a ser exibido no diagrama do evento. Usa o nome da regra se deixado em branco.

• Posição: Defina Ordem para controlar a sequência de execução entre várias validações, e Ativo para habilitar ou desabilitar a validação sem excluí-la.

• Código de Status Http: (App Builder 4.65 e posterior) (Opcional) Insira o código de status HTTP a ser retornado ao chamador quando esta validação falha enquanto é invocada no contexto de uma chamada de webhook. Este campo não tem efeito sobre validações invocadas no contexto de uma chamada de API REST (SNAPI).

  Nota

  Se mais de uma validação na mesma cadeia de eventos falhar com um Código de Status Http configurado, apenas o valor da primeira validação acionada na cadeia é retornado ao chamador. Se o campo for deixado em branco, uma validação falhada normalmente retorna 400 (Solicitação Inválida) por padrão; veja Envelope do corpo da resposta para outros códigos de status padrão.

• Ajuda Técnica: (Opcional) Insira uma descrição da validação para outros desenvolvedores.

Melhores práticas e recomendações

1. Use a vinculação implícita para a maioria das regras de validação, pois ela verifica os dados atualmente na memória na tela do usuário antes de serem salvos. Reserve a vinculação explícita para casos em que a validação precisa verificar dados que já estão salvos no banco de dados, como uma regra de validação de XP que valida dados em uma fonte de dados diferente. Veja Vinculação implícita e explícita para mais informações.

2. Escolha o alvo certo para a validação, dependendo de onde você deseja que ela seja executada:

   • Direcione a tabela e registre a validação em seu Detalhe do Evento da Tabela se você quiser que ela seja executada sempre que qualquer registro for salvo através de qualquer objeto de negócios que aponte para essa tabela.

   • Direcione o objeto de negócios e registre a validação em seu Detalhe do Evento da Regra se você quiser que ela seja executada apenas quando aquele objeto de negócios específico for utilizado.

   Veja Onde os eventos são configurados e Tabela vs. objeto de negócios para mais informações.

3. Quando uma regra de validação usa vinculação implícita, o objeto de negócios em que está registrada deve conter todas as colunas referenciadas na regra. O App Builder precisa que essas colunas estejam presentes para substituir com sucesso seus valores em memória. Veja o exemplo de validação de e-mail duplicado abaixo para uma configuração de exemplo.

4. A severidade de Aviso de uma validação só funciona quando a validação é acionada diretamente pelo painel ou evento da interface do usuário. Quando uma regra contendo a validação é executada como uma ação dentro da execução de outro evento (por exemplo, de uma regra pai mais acima em uma cadeia de eventos), não há interface disponível naquele momento para mostrar ao usuário um prompt de prosseguir ou cancelar, então a severidade da validação é elevada para Erro.

5. Use substituição dinâmica para tornar as mensagens de validação mais úteis para os usuários finais. Adicione o valor a ser substituído como uma coluna no objeto de negócios em que o evento está registrado, e então faça referência a ele no campo Mensagem da validação usando a sintaxe {{ ColumnName }}.

6. Se você estiver criando uma regra de validação que faz referência a uma tabela, ou a vários objetos de negócios construídos na mesma tabela, mais de uma vez, como uma regra que verifica se o endereço de e-mail de um novo registro duplica um já salvo nessa tabela (como no exemplo abaixo), adicione a tabela alvo à regra uma segunda vez. Faça isso na aba Tabelas da regra, enquanto constrói a regra no construtor de regras. Isso garante que o novo registro realmente seja validado, pois a vinculação implícita do App Builder substitui automaticamente apenas a primeira instância dessa tabela pelo registro em memória que está sendo editado. Sem uma segunda instância deixada intocada, a regra não teria dados reais salvos para comparar com o novo registro, e a validação nunca capturaria a duplicata que deveria detectar.

   Nota

   O mesmo risco aparece quando uma regra de validação usa mais de um objeto de negócios que todos visam a mesma tabela que o painel ou evento que aciona a validação. Ao contrário de uma tabela adicionada duas vezes, onde apenas a primeira instância é substituída, cada um desses objetos de negócios é substituído pelo registro em memória, uma vez que o App Builder não tem como distinguir entre eles. Se você precisar que um deles continue refletindo os dados reais salvos, por exemplo, para executar o mesmo tipo de verificação de duplicatas, direcione uma tabela diferente daquela usada pelo painel ou evento; porque não corresponderá, o App Builder nunca a substitui.

Exemplo: Regra de validação de e-mail duplicado

Este exemplo mostra uma regra de validação que usa a abordagem "em memória" descrita acima, verificando um endereço de e-mail inserido pelo usuário em relação aos valores já salvos na tabela para outras contas. Como a regra usa vinculação implícita, todas as suas colunas referenciadas devem existir no objeto de negócios em que está registrada para que o App Builder coloque os valores em memória na lógica da regra:

1. Uma regra de validação chamada tcAccount (Validation) (Duplicate Email) é criada na aba Regras do App Workbench.

2. A regra de validação direciona a tabela tcAccount duas vezes: uma vez como TA (o registro em memória, que é substituído) e uma vez como TA2 (os registros salvos existentes para comparação).

   

3. A cláusula WHERE da regra de validação é configurada para comparar as colunas Email e AccountTypeID entre as duas instâncias da tabela para detectar um duplicado.

   

4. Na aba Joins da regra, as duas instâncias de tcAccount são unidas pelo AccountID, excluindo correspondências entre um registro e ele mesmo.

   

5. Finalmente, a regra é anexada a um evento usando vinculação implícita, com a severidade definida como erro.