Introdução ao App Builder - Apêndice B: A camada de negócios no App Builder (Avançado)

Este é o segundo apêndice da série de tutoriais Introdução ao App Builder. Esses apêndices complementam as lições da série e fornecem informações mais detalhadas sobre os conceitos introduzidos.

Nesta lição, vamos explorar mais a fundo a camada de negócios do App Builder, a área onde criamos objetos de negócios ou regras.

Uniões

Uniões, introduzidas na Lição 7, são usadas quando trabalhamos com regras que extraem dados de mais de uma tabela na camada de dados. Elas combinam dados horizontalmente, adicionando colunas de uma segunda tabela ao lado das colunas da primeira.

Uniões funcionam de maneira diferente: em vez de adicionar colunas, elas empilham linhas. Uma união anexa os resultados de uma consulta sobre outra, produzindo uma lista combinada de registros extraídos de mais de uma tabela. Para que uma união funcione, ambas as consultas devem incluir pelo menos uma coluna com o mesmo nome, porque o App Builder usa essa coluna compartilhada como base para empilhar os resultados. É por isso que podemos combinar diretamente as colunas Country de nossas tabelas Customer e Supplier: ambas as colunas compartilham o mesmo nome.

Para demonstrar como uma união funciona, vamos criar manualmente uma união que mostre todos os países que existem na fonte de dados Northwinds. Existem duas tabelas, Supplier e Customer, que contêm uma coluna chamada Country, então vamos combinar as entradas de ambas.

1. Em App Workbench > Rules, clique em + Rule.

2. Quando a tela de criação de regras aparecer:

   1. No campo Name, insira Supplier (Countries for Supplier and Customer).

   2. No campo Propósito, selecione Objeto de Negócio.

   3. Certifique-se de que Fornecedor esteja selecionado no campo Alvo.

   4. Clique em Criar.

3. O App Builder criará a regra. Por padrão, ele adiciona a tabela de destino e seleciona sua chave primária. No entanto, nesta regra, estamos interessados apenas nos países presentes nas tabelas, então desmarque SupplierID, selecione a coluna País e marque-a como chave primária.

4. Precisamos adicionar a outra tabela que contém informações sobre países, então clique em + Tabelas.

5. Encontre a tabela Cliente e clique em Adicionar. O App Builder adicionará a tabela Cliente e você poderá vê-la na aba Tabelas ao lado de Fornecedor.

6. Vá para a aba Junções.

7. O App Builder criou uma junção, mas ajuste-a para torná-la do tipo que você deseja. Certifique-se de que Fornecedor esteja selecionado no campo Esquerda e que o campo Tipo diga União.

8. Clique na aba SQL para ver a sintaxe da sua união:

   

9. Para ver seus resultados, clique no botão Resultados no painel Regra.

10. Observe que os resultados contêm países duplicados. Isso é esperado: vários clientes e fornecedores estão baseados nas mesmas regiões, então cada país aparece uma vez para cada registro em cada tabela. Para produzir uma lista limpa e única de países, usaremos o botão Selecionar Distinto.

11. Navegue de volta para o Construtor de Regras.

12. No painel Regra, clique em Mais > Caso Excepcional. A caixa de diálogo Configurações de Caso Excepcional é aberta. Esta caixa de diálogo fornece controle avançado sobre sua regra. Veja Opções Avançadas na aba Regras do App Workbench para uma descrição completa de todas as opções disponíveis.

13. Marque a caixa de seleção Selecionar Distinto para remover linhas redundantes dos resultados, garantindo que cada registro na lista seja único. Clique em Salvar.

14. Clique no botão Resultados novamente. A regra agora retorna uma lista distinta de todos os países representados nas tabelas Cliente e Fornecedor.

Hora da prática: Use sua regra de união como um controle de lista

Agora, vamos colocar sua nova regra de união em prática. Navegue até as páginas pop-up de Cliente e Fornecedor e mude o tipo de controle do campo País para Lista. Na aba Opções da Lista, selecione o objeto de negócio de união que você acabou de criar e defina tanto a Chave quanto o Título para a coluna País.

Regras CRUD

Introduzimos as regras CRUD na Aula 7, mas agora vamos analisá-las mais de perto.

O acrônimo CRUD significa "Criar, Ler, Atualizar, Excluir". Isso significa que as regras CRUD são o que os desenvolvedores do App Builder usam para inserir, recuperar, alterar ou apagar registros das tabelas presentes na fonte de dados.

Camada alvo: negócios vs. dados

Quando você cria uma regra CRUD, deve selecionar uma camada alvo: a camada de negócios ou a camada de dados. Essa escolha é crítica e tem implicações significativas.

Direcionar para a camada de negócios é a abordagem recomendada para a maioria das operações. Quando sua regra CRUD direciona para a camada de negócios (por exemplo, o objeto de negócio Pedido (Fonte)), ela age como um usuário interagindo com o aplicativo. Isso aciona todos os eventos intrínsecos (Salvar, Atualizar, etc.) associados a esse objeto de negócio. Isso significa que todas as suas regras de validação configuradas, ações personalizadas e rastreamento de auditoria leve serão executados automaticamente. Essa abordagem garante a integridade e a consistência dos dados com a lógica do seu aplicativo. Também permite que você use manipuladores de sucesso, falha e reversão para o evento.

Direcionar para a camada de dados ignora toda a lógica de negócios. Quando você direciona para a camada de dados (por exemplo, a tabela Pedido), sua regra interage diretamente com o banco de dados. Ela não acionará nenhum evento intrínseco, validações ou rastreamento de auditoria configurados no objeto de negócio. Essa é uma abordagem de "porta dos fundos", útil para operações em massa de alto desempenho onde você deseja intencionalmente ignorar a lógica de negócios.

Você pode ver essa diferença visualmente no fluxo de trabalho visual; uma regra que visa a camada de negócios mostrará subprocessos para sua lógica de eventos, enquanto uma que visa a camada de dados não mostrará.

Atualização CRUD

Primeiro, vamos ver como criar uma regra de atualização CRUD. Isso significa modificar registros existentes em uma tabela. Para demonstrar, vamos criar uma regra que aumenta todas as quantidades dos produtos pedidos.

1. Em App Workbench > Regras, clique em + Regra.

2. No campo Nome, insira OrderDetail (Quantidade + 1).

3. No campo Propósito, selecione CRUD.

4. No campo Ação, selecione Atualizar.

5. Em Camada Alvo, selecione Camada de Dados. (Para esta atualização em massa simples, vamos ignorar a lógica de negócios).

6. No campo Alvo, selecione OrderDetail.

7. Clique em Criar. O App Builder levará alguns segundos para criar a regra.

8. Na aba Tabelas, a tabela OrderDetail aparecerá, com sua chave primária, OrderDetailID, selecionada. Selecione também a coluna Quantidade clicando na sua caixa de seleção.

9. Vamos adicionar uma nova coluna com um alias para nos ajudar a visualizar que a regra está funcionando. Vá para a aba Colunas e clique em + Coluna. Quando a caixa de diálogo Coluna - Adicionar Coluna abrir, insira as seguintes informações:

   1. No campo Coluna ou Expressão, insira OD.Quantity + 1.

   2. No campo Alias, insira um nome legível. Usaremos QuantidadePlus.

   3. No campo Alvo, selecione Quantidade. Isso informa ao App Builder para gravar o resultado dessa expressão na coluna Quantidade.

   4. Clique em Salvar.

10. Na aba Colunas, você verá agora tanto Quantidade quanto QuantidadePlus. A coluna original OD.Quantity também será direcionada para Quantidade por padrão. Precisamos desmarcá-la para evitar ambiguidade:

    1. Encontre a linha OD.Quantity na lista de Colunas.

    2. Clique no dropdown Target. Um botão X aparece ao lado. Clique nele para desmarcar a coluna.

       Isso garante que apenas nossa expressão QuantityPlus seja usada para atualizar a coluna Quantity. Se ambas fossem marcadas, a que tivesse o índice mais alto "vencería", levando a um comportamento imprevisível.

11. A regra está pronta. No painel Rule, clique no painel Results para vê-la funcionando. Note que a coluna extra que você adicionou aumenta todas as quantidades em um:

    

Copiar Regra

Pense em como você criaria uma regra de atualização CRUD semelhante à que criamos acima, mas com o efeito oposto, ou seja, uma regra que modifica todas as entradas na coluna Quantity da tabela OrderDetail subtraindo um. No entanto, em vez de construir essa regra do zero, vamos usar o recurso Copiar Regra do App Builder, que duplica uma regra existente para que você possa usá-la como ponto de partida, economizando tempo ao criar regras que são semelhantes às que você já construiu.

1. Em App Workbench > Rules, localize a regra OrderDetail (Quantity + 1) e clique em Mais > Copiar Regra.

2. Clique em Copiar.

3. O App Builder cria a nova regra, nomeando-a OrderDetail (Quantity + 1) (New). Você é levado diretamente para a tela de edição. No painel Rule, atualize o campo Name para OrderDetail (Quantity - 1), em seguida, navegue até a aba Columns.

4. Encontre a expressão OD.Quantity + 1 e edite-a. Altere a expressão para OD.Quantity - 1 e atualize o Alias de QuantityPlus para QuantityMinus. Clique em Salvar.

5. Verifique se a regra está funcionando corretamente clicando em Results no painel Rule.

Hora da prática: Adicionar controles de quantidade

Agora que você tem ambas as regras de quantidade, conecte-as ao painel Order Details na página Orders.

1. Abra o objeto de negócios OrderDetail (Fonte) e crie um evento personalizado para a regra OrderDetail (Quantidade + 1). Na caixa de diálogo de criação de evento, insira Quantidade Mais no campo Nome e defina Escopo de Atualização como Linha. Isso garante que, quando o evento for acionado, apenas a linha afetada seja atualizada, em vez de todo o painel.

2. Repita o passo 1 para criar um segundo evento chamado Quantidade Menos, anexando a regra OrderDetail (Quantidade - 1) e também definindo Escopo de Atualização como Linha.

3. Navegue até a tela de edição da página Pedidos. No painel Detalhes do Pedido, adicione dois controles de Botão: um que executa o evento Quantidade Mais e um que executa o evento Quantidade Menos.

4. Visite a pré-visualização da página Pedidos e teste os novos botões.

CRUD excluir

As regras de exclusão CRUD são usadas para apagar registros das tabelas. No entanto, como é fácil usar elementos de interface do usuário para excluir registros individuais, as regras de exclusão CRUD são tipicamente usadas apenas para excluir muitos registros de uma vez. Para demonstrar, vamos criar uma regra de exclusão CRUD que exclui todos os detalhes do pedido associados a um pedido individual, a fim de eliminar a necessidade de excluir todos os detalhes do pedido separadamente quando um pedido é cancelado.

1. Em App Workbench > Regras, clique em + Regra.

2. No campo Nome, insira OrderDetail (Excluir OrderDetail para Pedido).

3. No campo Finalidade, selecione CRUD.

4. No campo Ação, selecione Excluir.

5. Em Camada de Destino, selecione Camada de Dados.

6. No campo Destino, selecione OrderDetail.

7. Clique em Criar.

8. Na aba Tabelas, o App Builder adicionou a tabela OrderDetail e selecionou sua chave primária, OrderDetailID. Mantenha isso selecionado, pois direcionar a chave primária é a maneira mais eficiente e segura de realizar uma operação de exclusão. Selecione também a coluna OrderID; usaremos esta coluna na próxima seção para vincular a regra a um pedido específico.

Events

As regras CRUD só podem ser usadas quando estão anexadas a eventos, que são processos incorporados em tabelas ou objetos de negócios que são executados em resposta a certas ações, como salvar um registro. Todas as tabelas e objetos de negócios possuem intrinsecamente quatro eventos: salvar, atualizar, excluir e inserir, que são executados à medida que você altera registros no App Builder.

Vamos ativar as regras CRUD que criamos. Para isso, vamos criar nossos próprios eventos personalizados. Ao contrário dos eventos intrínsecos, os eventos personalizados devem ser anexados a um controle para serem executados. As regras CRUD que estamos criando exigem eventos personalizados para serem executados quando desejamos.

Primeiro, vamos criar um evento personalizado para associar à nossa regra de exclusão CRUD, para que, quando um pedido for excluído, os detalhes do pedido relacionado também sejam excluídos.

1. Em App Workbench > Regras, localize e abra a regra Pedido (Fonte).

2. No painel Regra, clique em Eventos. A página Todos os Eventos (Pedido (Fonte)) é aberta. Ela lista os quatro eventos intrínsecos que o App Builder inclui para cada tabela e objeto de negócios: Inserir, Salvar, Atualizar e Excluir. Para uma descrição completa desta página e suas opções, veja Configurar um evento.

3. Como estamos criando um evento personalizado, clique em + Evento de Regra. A página Evento é aberta, onde você pode adicionar os detalhes do novo evento (veja Opções de detalhes do evento para uma descrição completa de todos os campos):

   1. Em Informações do Evento, no campo Nome, insira Excluir Detalhes do Pedido.

   2. Em Mensagens, no campo Confirmação, insira uma mensagem que será exibida aos usuários antes da execução do evento, pedindo que confirmem se desejam prosseguir. A mensagem deve deixar claro o que acontecerá se o usuário continuar, ajudando a prevenir ações acidentais. Veja Configurar um evento para aprender sobre os outros tipos de mensagens.

      

   3. Na seção Propriedades de Execução, marque a caixa de seleção Transação. Isso garante que o evento seja uma execução tudo ou nada: como nossa regra de exclusão afeta vários itens de linha, uma transação garante que, se um erro ocorrer no meio do processo, o App Builder reverte todas as alterações. Isso previne um cenário onde alguns registros são excluídos enquanto outros permanecem, deixando os dados em um estado inconsistente. Veja Propriedades de execução para uma descrição completa de todas as opções nesta seção.

   4. Deixe os outros campos com suas seleções padrão e clique em Salvar. O App Builder criará o evento.

      Nota

      Para cenários de acesso concorrente onde a integridade dos dados pode ser comprometida, o App Builder também fornece Bloqueio de Evento, que força a execução serial e pode ser limitado a registros individuais. Deixe isso desmarcado para o evento atual, mas tenha em mente para ambientes de alto tráfego ou fluxos de trabalho complexos onde a sincronização em nível de registro é um requisito.

4. O evento foi criado, e o App Builder mostra a tela de configuração:

   

   Você está atualmente na Visualização em Grade (mostrada na captura de tela acima), que fornece uma lista de alto nível de todas as ações e validações registradas neste evento. Uma visão alternativa do evento pode ser vista no Editor de Fluxo Visual, que mostra a ordem de execução e a relação entre eventos herdados. Para vê-lo, clique no ícone no painel Evento. Para retornar à Visualização em Grade a qualquer momento, clique no ícone que o substitui.

   O Editor de Fluxo Visual transforma seus eventos em diagramas de fluxo interativos, facilitando a visualização do caminho que seus dados percorrem enquanto se movem pelo sistema. Cada evento é mapeado como um processo com pontos de início e fim distintos, e subprocessos marcados com um ícone de mais podem ser clicados duas vezes para aprofundar em camadas mais profundas de lógica. Você pode usar os botões dedicados para adicionar novas ações ou validações diretamente na sequência e selecionar qualquer nó para editar seus detalhes, excluí-lo ou reordená-lo dentro da cadeia lógica. Veja Editor de Fluxo Visual para uma descrição completa de seus recursos.

5. O evento ainda não tem nenhuma ação anexada a ele. Se você estiver na Visualização em Grade, observe que o painel Ações está vazio e clique no botão Registrar. Se você estiver no Editor de Fluxo Visual, clique no botão + Ação na parte superior do painel Diagrama de Evento. Isso abrirá a caixa de diálogo Ação:

   1. No campo Tipo, selecione Regra.

   2. No campo Regra, selecione OrderDetail (Excluir OrderDetail para Pedido), a regra de exclusão CRUD que criamos anteriormente.

   3. Deixe os outros campos com suas seleções padrão. Isso inclui as configurações de Posição que controlam a ordem e o tempo de execução. Veja Tipos de ação de evento para uma descrição completa. Clique em Salvar. O diálogo para a ação mostrará mais detalhes:

      

   4. No painel Vinculações, clique em + Vinculação. Selecione OrderID como a Coluna de Origem e OrderID como a Coluna da Regra.

      Nota

      Este passo de vinculação é crítico, pois filtra os resultados da sua regra pelo registro do painel contra o qual você executou o evento. Se deixado "não vinculado", a regra de exclusão afetaria todos os registros na tabela OrderDetail. Ao vincular a Coluna de Origem (OrderID do registro do painel Pedido (Origem)) à Coluna da Regra (OrderID em nossa regra de exclusão), adicionamos um filtro implícito (por exemplo, WHERE OrderID = 10248).

      Isso garante que apenas os registros OrderDetail correspondentes a esse OrderID específico sejam excluídos. Se essa vinculação fosse omitida, acionar o evento excluiria todos os registros da tabela OrderDetail.

   5. Clique em Salvar.

6. O evento personalizado agora está pronto para ser implementado.

Hora da prática: Adicione um controle de exclusão

Agora que sua regra de exclusão e evento estão prontos, vamos colocá-los para funcionar na interface do usuário. Adicione um botão Excluir Detalhes do Pedido ao painel Pedidos e vincule-o ao evento Excluir Detalhes do Pedido que você acabou de configurar. Isso permite que seus usuários limpem todos os detalhes de um pedido com um único clique.

Regras de subconsulta

Uma regra de subconsulta atua como um intermediário lógico, calculando ou ajustando dados antes de passá-los para outro objeto. Ao contrário das regras padrão que interagem diretamente com um registro, as subconsultas não gravam de volta nas tabelas. Em vez disso, elas realizam uma operação específica, como uma agregação, para gerar um valor para uso em outro lugar em sua aplicação.

Vamos demonstrar criando uma regra de subconsulta. Ela será usada para encontrar o máximo OrderNumber da tabela Order e, em seguida, adicionar um a ele. Mais tarde, criaremos uma regra CRUD com o propósito de copiar um pedido, e ela dependerá dessa subconsulta para funcionar.

1. Em App Workbench > Regras, clique em + Regra.

2. No campo Nome, insira Pedido (OrderNumber + 1).

3. No campo Propósito, selecione Subconsulta.

4. No campo Alvo, selecione Pedido.

5. Clique em Criar. O App Builder criará a nova regra.

6. O App Builder selecionará automaticamente a chave primária da tabela Order, mas não precisaremos dela para esta regra. Desmarque-a na aba Tabelas.

   Por que desmarcar OrderID?

   Ao usar uma função de agregação como faremos aqui, adicionar qualquer outra coluna à consulta (como OrderID) fará com que o banco de dados aplique uma cláusula GROUP BY para essa coluna.

   Se incluíssemos OrderID, a expressão encontraria o máximo OrderNumber por OrderID. Isso retornaria apenas o OrderNumber para cada pedido, o que não é o que queremos.

   Para encontrar o único máximo OrderNumber em toda a tabela, não devemos incluir outras colunas em nossa consulta. É por isso que usamos uma subconsulta: para realizar esse cálculo agregado primeiro, para que possa ser usado em outra regra.

7. Na aba Colunas, clique em + Coluna. O diálogo Coluna - Adicionar Coluna será aberto.

8. No campo Coluna ou Expressão, insira a expressão Max(O.OrderNumber) + 1. A sintaxe Max() invoca a função Max(), que encontra o maior valor na coluna O.OrderNumber. Em seguida, um é adicionado a ele.

9. No campo Alias e Destino, insira um alias apropriado para esta coluna, como MaxOrderNumber.

10. No campo Tipo de Dado Lógico, selecione Número, pois OrderNumber não é um valor UUID, mas um número natural.

11. Clique em Salvar.

12. Verifique se a regra está funcionando corretamente clicando no botão Resultados. Deve haver apenas uma linha com um número de pedido, que deve ser um número maior do que o maior número de pedido atualmente presente na tabela Order.

Agora, vamos criar uma regra CRUD capaz de copiar um pedido. Esta regra CRUD dependerá da regra de subconsulta que acabamos de criar para funcionar.

1. Em App Workbench > Regras, clique em + Regra.

2. No campo Nome, insira Pedido (Copiar Pedido).

3. No campo Finalidade, selecione CRUD.

4. No campo Ação, selecione Inserir.

5. No campo Camada de Destino, selecione Camada Lógica.

6. No campo Destino, selecione Pedido.

7. Clique em Criar. O App Builder criará a regra.

Uma vez que a regra é criada, configure suas colunas e destinos:

1. Na aba Tabelas, o App Builder adicionou automaticamente a tabela Pedido, mas precisaremos de mais. Clique em + Tabelas.

2. Selecione a regra de subconsulta que criamos para este propósito, Pedido (OrderNumber + 1). Clique em Adicionar.

3. Na aba Tabelas, marque a caixa de seleção ao lado da barra de pesquisa no topo da lista de colunas. Isso seleciona todas as colunas existentes da tabela Pedido de uma vez.

4. Clique no nome da tabela Pedido. O diálogo Tabela será aberto. Em Selecionar todas as Colunas, habilite a caixa de seleção. Isso garante que quaisquer novas colunas adicionadas à tabela Pedido no futuro sejam automaticamente incluídas nesta regra. Feche o diálogo.

5. Da tabela de subconsulta Order (OrderNumber + 1), selecione sua única coluna, MaxOrderNumber.

6. Na aba Columns, refine o mapeamento de dados da regra da seguinte forma:

   • Remova o alvo para OrderID. Como esta é uma chave primária gerada automaticamente, a camada de negócios atribuirá automaticamente um valor único quando a regra for executada.
   • OrderNumber: Confirme que a linha OON.MaxOrderNumber tem como alvo OrderNumber, mapeando o novo valor incrementado para a coluna correta.
   • OrderDate: Clique no campo Column or Expression para esta coluna e substitua seu valor atual por Now() para definir a data do pedido copiado como hoje.
   • Nem todas as colunas são necessárias nesta regra. Remova as seguintes:
     • RequiredDate, ShippedDate e Freight: Esses detalhes devem ser inseridos manualmente para o novo pedido, em vez de serem duplicados do original.
     • AddedOn, AddedBy, ChangedOn, ChangedBy e IsActive: O App Builder gera automaticamente esses valores na criação.

   Leitura adicional

   Aprenda mais sobre este conceito em Target in business object rules.

7. Clique em Results no painel Rule para verificar se a regra está funcionando corretamente.

Agora vamos criar uma segunda regra CRUD para copiar os itens de linha do pedido. Esta regra será registrada como um manipulador de sucesso no evento Copy Order, garantindo que as linhas de detalhes sejam criadas apenas uma vez que o novo registro de pedido exista.

1. Em App Workbench > Rules, clique em + Rule.

2. No campo Name, insira OrderDetail (Insert) Copy Order Detail.

3. No campo Purpose, selecione CRUD.

4. No campo Action, selecione Insert.

5. No campo Target Layer, selecione Logic Layer.

6. No campo Target, selecione OrderDetail.

7. Clique em Create.

8. Na aba Tables, marque a caixa de seleção ao lado da barra de pesquisa para selecionar todas as colunas existentes de uma vez. Em seguida, clique no nome da tabela OrderDetail, ative Select all Columns na caixa de diálogo Table e feche a caixa de diálogo.

9. Na aba Colunas, faça as seguintes alterações:

   • Exclua as colunas de auditoria leve e selecionáveis pelo usuário (AddedOn, AddedBy, ChangedOn, ChangedBy, IsActive). Estas serão preenchidas automaticamente ao serem criadas.
   • Atualize a expressão para OrderDetailID para NewUUID(). Isso garante que cada item de linha copiado receba seu próprio identificador exclusivo.
   • Remova o alvo para OrderID e defina seu alias como BindOrderID. Este valor representa o ID do pedido original, que usaremos para vinculação durante o evento.
   • Adicione uma nova expressão usando Generated() direcionada a OrderID. A função Generated() recupera um valor criado durante a execução do evento atual e aceita dois argumentos: o valor e o tipo de dado. Insira Generated('OrderID', 'UUID') como a expressão.

10. Clique em Resultados para verificar a regra.

Agora criamos ambas as regras de cópia. Vamos anexar a regra Copiar Pedido a um evento personalizado e conectar a regra Copiar Linhas do Pedido para ser acionada automaticamente em seu sucesso.

1. Em App Workbench > Regras, localize e abra a regra Pedido (Fonte).

2. No painel Regra, clique em Eventos. A página Todos os Eventos (Pedido (Fonte)) é aberta.

3. Clique em + Evento de Regra. A página Evento é aberta:

   1. Em Informações do Evento, no campo Nome, insira Copiar Pedido.

   2. No campo Atualizar Escopo, selecione Atualização do Painel. Isso garante que o painel seja atualizado imediatamente após a conclusão da cópia, para que o novo pedido apareça sem uma atualização manual.

   3. Em Mensagens, configure uma mensagem de confirmação, sucesso e falha usando substituição dinâmica. Ao usar chaves duplas, você pode puxar dados em tempo real da regra subjacente e injetá-los no texto. Como este evento está registrado na regra Pedido (Fonte), você tem acesso a todas as suas colunas. Por exemplo:

      • Confirmação: Você tem certeza de que deseja duplicar o pedido {{OrderNumber}}?
      • Sucesso: Pedido {{OrderNumber}} foi copiado com sucesso!
      • Falha: Erro: O pedido {{OrderNumber}} falhou ao copiar!

   4. Na seção Propriedades de Execução, marque a caixa de seleção Transação para garantir a integridade dos dados revertendo todo o processo se qualquer parte da duplicação falhar.

   5. Deixe os outros campos com suas seleções padrão e clique em Salvar.

      Nota

      Veja Opções de detalhes do evento para uma descrição completa de todos os campos.

4. O evento foi criado. No painel Ações, clique em Registrar. A caixa de diálogo Ação é aberta:

   1. No campo Tipo, selecione Regra.
   2. No campo Regra, selecione Pedido (Copiar Pedido).
   3. No painel Vinculações, clique em + Vinculação. Selecione OrderID como a Coluna de Origem e OrderID como a Coluna da Regra. Usar OrderID para vinculação é mais confiável do que OrderNumber, que pode não ser único.
   4. Salve.

5. No painel Ações, há um campo Manipuladores que mostra três botões: Sucesso, Falha e Rollback:

   • Manipulador de Sucesso: Aciona apenas quando a regra pai é concluída com sucesso. Use isso para encadear lógica, como copiar os detalhes do nosso pedido, que depende da existência do registro pai primeiro.
   • Manipulador de Falha: Aciona apenas se a regra pai encontrar um erro. Use-o para enviar alertas, registrar erros ou acionar ações compensatórias.
   • Manipulador de Rollback: Usado ao trabalhar com sistemas que não suportam transações padrão de banco de dados, como uma API REST de terceiros. Ele executa ações em ordem cronológica reversa para desfazer manualmente a execução da regra até aquele ponto.

   Clique em Sucesso. A caixa de diálogo Manipuladores de Sucesso é aberta. Clique em Criar. A caixa de diálogo Ação é aberta:

   1. No campo Tipo, selecione Regra.
   2. No campo Regra, selecione OrderDetail (Inserir) Copiar Detalhe do Pedido.
   3. Salve.
   4. No painel Vinculações, clique em + Vinculação e mapeie o seguinte:
      • Coluna de Origem: Selecione OrderID (o ID único do pedido que está sendo copiado atualmente).
      • Coluna da Regra: Selecione BindOrderID (o alias que criamos na regra para identificar o registro de origem).
   5. Salve.

6. Saia dos diálogos abertos e navegue até o Editor de Fluxo de Trabalho Visual clicando no ícone . O diagrama de eventos agora é mais complexo do que o evento Excluir Detalhes do Pedido que revisamos anteriormente. Observe o seguinte:

   • Camada de Lógica: Tanto as regras Copiar Pedido quanto Copiar Itens do Pedido passam pela camada de negócios, razão pela qual ambos os blocos de regras mostram o ícone +. Clique duas vezes em qualquer bloco para navegar diretamente para os eventos pai que ele aciona.
   • Caminhos condicionais: Você pode ver os caminhos ramificados para Sucesso e Falha. O caminho Sucesso mostra a regra Copiar Itens do Pedido sendo acionada, enquanto o caminho Falha não mostra eventos subsequentes, confirmando que o processo para se a cópia principal falhar.

Hora da prática: Adicione um controle de cópia

Agora que suas regras de cópia e evento estão prontas, vamos colocá-las em funcionamento na interface do usuário. Adicione um botão Copiar ao painel Pedidos e vincule-o ao evento Copiar Pedido que você acabou de criar. Uma vez que o botão seja adicionado, teste-o: você deve ver a mensagem de confirmação com o número do pedido dinâmico e, ao ter sucesso, um novo pedido aparecerá usando o próximo número de pedido disponível.

Validações

As regras de validação são usadas para garantir que os dados inseridos no App Builder sejam válidos antes de serem salvos. Na Aula 7, cobrimos uma validação simples de "campo obrigatório". Agora, vamos explorar um cenário de validação mais complexo, incluindo lógica personalizada e mensagens de erro dinâmicas.

Como outras regras, as regras de validação devem estar anexadas a um evento para serem usadas. A escolha do evento depende do caso de uso:

• Evento intrínseco: Use isso quando quiser que a validação seja executada automaticamente durante operações padrão (por exemplo, impedir um salvamento se os dados forem inválidos).

• Evento personalizado: Use isso quando quiser acionar a validação sob demanda a partir de um controle específico (por exemplo, um clique em botão).

Vamos criar uma regra de validação para garantir que um desconto em um pedido nunca seja superior a 10%. Queremos que isso seja executado toda vez que um registro OrderDetail for salvo, então o anexaremos ao evento de salvamento intrínseco.

1. Em App Workbench > Regras, clique em + Regra.

2. No campo Nome, insira OrderDetail (Validar Desconto).

3. No campo Propósito, selecione Validação.

4. No campo Alvo, selecione OrderDetail.

5. Clique em Criar.

6. Na aba Tabelas, selecione a coluna Desconto (você pode desmarcar OrderDetailID).

7. Na aba Onde, clique em + Cláusula Where. Um diálogo se abre onde você pode criar cláusulas WHERE:

   

   1. No campo Expressão Esquerda, insira OD.Desconto.

   2. No campo Operador, selecione >.

   3. No campo Expressão Direita, insira 0.1.

8. Clique em Salvar.

A regra agora está criada. Ela foi projetada para encontrar dados "ruins" (registros onde o desconto é superior a 10%).

Limite dinâmico

Na última etapa, definimos um limite fixo de 10%. Agora, vamos torná-lo configurável: vamos armazenar o limite como um parâmetro de aplicativo para que o negócio possa atualizá-lo pela interface do usuário sem tocar na própria regra. Aplique os seguintes passos usando habilidades de lições anteriores:

1. Adicione uma coluna DiscountMaximum à tabela Parâmetro. Defina o Tipo de Dado Lógico como Percentual e a escala como 4 para capturar valores precisos como 12,25%.

2. Navegue até a página Parâmetro. Na tela de edição da tabela, o botão Páginas fornece um atalho: ele lista todas as páginas que atualmente usam esta tabela, permitindo que você vá diretamente para a página certa.

3. Adicione DiscountMaximum como um controle numérico à página e preencha com um valor como .3 para permitir descontos de até 30%.

4. Retorne a App Workbench > Regras e abra a regra OrderDetail (Validar Desconto).

5. Na aba Tabelas, clique em + Tabelas e adicione a tabela Parâmetro. Selecione a coluna DiscountMaximum.

6. Na aba Onde, clique no ícone de lápis para editar a cláusula WHERE. No campo Expressão Direita, substitua 0.1 por P.DiscountMaximum.

Qualquer valor definido na página Parâmetro agora controla o limite para esta validação.

Anexar a regra de validação

Agora, vamos anexar a regra de validação ao evento de salvamento intrínseco para OrderDetail.

1. Em App Workbench > Regras, encontre o objeto de negócios OrderDetail (Fonte) e abra-o.

2. No painel Regra, clique em Eventos. A página Todos os Eventos (OrderDetail (Fonte)) é aberta.

3. Encontre a linha Salvar. Note que há dois botões de designer: Detalhe do Evento da Tabela e Detalhe do Evento da Regra. Queremos registrar essa validação usando Detalhe do Evento da Regra. Esta é uma distinção importante: garante que a validação se aplique apenas quando esta regra de negócios específica for utilizada, em vez de impor uma restrição global em toda a tabela OrderDetail. Isso mantém o aplicativo flexível. Por exemplo, você poderia posteriormente construir uma página de Aprovação do Gerente. Ao usar um objeto de negócios diferente lá, um supervisor poderia autorizar descontos maiores sem ser bloqueado pela regra padrão que estamos construindo aqui. Clique em Detalhe do Evento da Regra para o evento Salvar.

4. No painel Validações, clique em Registrar. A caixa de diálogo Validação é aberta:

   

5. No campo Tipo, selecione Regra.

6. No campo Regra, selecione OrderDetail (Validar Desconto), a regra de validação que acabamos de criar.

7. No campo Vinculação, selecione Implícita.

   Nota

   Vinculação implícita valida os dados que estão atualmente "em memória" na tela do usuário. Este é o valor que o usuário digitou, antes de ser salvo no banco de dados. Usamos a vinculação implícita aqui porque queremos impedir que o usuário salve um novo registro enquanto o valor do Desconto é inválido (ou seja, maior do que o limite configurado). Por outro lado, Vinculação explícita valida os dados que já estão salvos no banco de dados.

   Para ilustrar, imagine que um registro foi salvo com um desconto inválido de 50%. Um usuário abre esse registro, corrige o campo Desconto para um valor válido como 7% e o envia. Se o evento de validação usar vinculação explícita, ele verificará o banco de dados, verá o valor original de 50% e falhará na validação. No entanto, se o evento de validação usar vinculação implícita, ele verificará o valor em memória (7%), verá que não é maior do que o limite e passará na validação, permitindo o salvamento.

   Leia mais em Vinculação implícita e explícita.

8. No campo Falha, selecione Falhar ao retornar dados.

   Nota

   As validações do App Builder podem ser configuradas de duas maneiras. O padrão, que estamos usando, é Falhar ao retornar dados. Isso significa que a regra de validação é escrita para encontrar os dados ruins (por exemplo, Desconto é maior que o limite). Se a regra encontrar algum registro que corresponda a esse critério "ruim", ela falha e exibe a mensagem de erro. A alternativa é Falhar ao não retornar dados, que é usada quando uma regra é escrita para encontrar dados bons.

9. No campo Severidade, selecione Erro.

   Nota

   O campo Severidade determina quão fortemente o App Builder interage com o usuário quando uma validação é acionada:

   • Erro: O nível mais crítico. Indica um problema maior e impede completamente o salvamento. O usuário vê uma notificação vermelha e deve corrigir os dados antes de prosseguir.
   • Aviso: Um bloqueio suave. Alerta o usuário sobre um potencial problema com uma notificação amarela, mas dá a ele a escolha de cancelar e corrigir ou prosseguir e salvar o registro mesmo assim.
   • Informação: Puramente informativa. Fornece uma notificação azul após a execução do evento para dar ao usuário um contexto útil, mas nunca para ou interrompe o fluxo de trabalho.

10. No campo Mensagem, insira: Desconto não pode ser maior que {{ DiscountMaximum }}. Usar substituição dinâmica aqui garante que a mensagem de erro reflita automaticamente qualquer limite que esteja atualmente definido na página Parâmetro.

11. Clique em Salvar para sair da caixa de diálogo.

A validação está anexada. Para testá-la, vá para a visualização da página Pedidos, selecione um pedido e tente editar um item Detalhe do Pedido para ter um desconto maior que o limite que você definiu. Quando você clicar para salvar, deverá ver a mensagem de erro dinâmica.

Para que o espaço reservado {{ DiscountMaximum }} seja resolvido corretamente, a coluna deve estar disponível no objeto de negócios Detalhe do Pedido (Fonte). Como DiscountMaximum está em uma tabela Parâmetro separada, você precisa adicioná-lo explicitamente:

1. Retorne para App Workbench > Regras e abra a regra OrderDetail (Fonte).

2. Na aba Tabelas, clique em + Tabelas e adicione a tabela Parâmetro. Selecione a coluna DiscountMaximum.

O nome da coluna na regra deve corresponder exatamente ao espaço reservado na sua mensagem de validação. Se você tivesse usado um nome diferente na mensagem (por exemplo, {{ MaxDiscount }}), seria necessário criar um alias para a coluna na regra para que correspondesse.

Aprendizado adicional

Isso conclui esta imersão nos detalhes da camada de negócios do App Builder. Veja Apêndice A para uma análise mais detalhada da camada de dados, ou Apêndice C para a camada de interface do usuário.