#Evento Antes da Ação

#Introdução

O plugin Evento Antes da Ação oferece um mecanismo de interceptação para ações, que pode ser acionado após a submissão de uma requisição para criar, atualizar ou excluir, mas antes que ela seja processada.

Se um nó "Encerrar fluxo de trabalho" for executado no fluxo de trabalho acionado, ou se qualquer outro nó falhar (devido a um erro ou outra situação de não conclusão), a ação do formulário será interceptada. Caso contrário, a ação pretendida será executada normalmente.

Usá-lo em conjunto com o nó "Mensagem de resposta" permite configurar uma mensagem de resposta para ser retornada ao cliente, fornecendo avisos apropriados. Eventos Antes da Ação podem ser usados para validação de negócios ou verificações lógicas, a fim de aprovar ou interceptar requisições de criação, atualização e exclusão enviadas pelo cliente.

#Configuração do Acionador

#Criar Acionador

Ao criar um fluxo de trabalho, selecione o tipo "Evento Antes da Ação":

#Selecionar Coleção

No acionador de um fluxo de trabalho de interceptação, a primeira coisa a configurar é a coleção correspondente à ação:

Em seguida, selecione o modo de interceptação. Você pode optar por interceptar apenas o botão de ação vinculado a este fluxo de trabalho, ou interceptar todas as ações selecionadas para esta coleção (independentemente do formulário de origem e sem a necessidade de vincular o fluxo de trabalho correspondente):

#Modo de Interceptação

Os tipos de ação atualmente suportados são "Criar", "Atualizar" e "Excluir". Vários tipos de ação podem ser selecionados simultaneamente.

#Configuração da Ação

Se o modo "Acionar interceptação apenas quando um formulário vinculado a este fluxo de trabalho for enviado" for selecionado na configuração do acionador, você também precisará retornar à interface do formulário e vincular este fluxo de trabalho ao botão de ação correspondente:

Na configuração de vínculo do fluxo de trabalho, selecione o fluxo de trabalho correspondente. Geralmente, o contexto padrão para acionar dados, "Dados do formulário inteiro", é suficiente:

#Condições para Interceptação

Em um "Evento Antes da Ação", existem duas condições que farão com que a ação correspondente seja interceptada:

1. O fluxo de trabalho executa até qualquer nó "Encerrar fluxo de trabalho". Similar às instruções anteriores, quando os dados que acionaram o fluxo de trabalho não atendem às condições predefinidas em um nó "Condição", ele entrará no ramo "Não" e executará o nó "Encerrar fluxo de trabalho". Neste ponto, o fluxo de trabalho será encerrado e a ação solicitada será interceptada.
2. Qualquer nó no fluxo de trabalho falha na execução, incluindo erros de execução ou outras exceções. Neste caso, o fluxo de trabalho será encerrado com um status correspondente, e a ação solicitada também será interceptada. Por exemplo, se o fluxo de trabalho chamar dados externos via uma "Requisição HTTP" e a requisição falhar, o fluxo de trabalho terminará com um status de falha e também interceptará a requisição de ação correspondente.

Após as condições de interceptação serem atendidas, a ação correspondente não será mais executada. Por exemplo, se o envio de um pedido for interceptado, os dados do pedido correspondente não serão criados.

#Parâmetros Relacionados para a Ação Correspondente

Em um fluxo de trabalho do tipo "Evento Antes da Ação", diferentes dados do acionador podem ser usados como variáveis no fluxo de trabalho para diferentes ações:

#Mensagem de Resposta de Saída

Após configurar o acionador, você pode personalizar a lógica de decisão relevante no fluxo de trabalho. Tipicamente, você usará o modo de ramificação do nó "Condição" para decidir se deve "Encerrar fluxo de trabalho" e retornar uma "Mensagem de resposta" predefinida com base nos resultados das condições de negócio específicas:

A este ponto, a configuração do fluxo de trabalho correspondente está completa. Agora você pode tentar enviar dados que não atendam às condições configuradas no nó de condição do fluxo de trabalho para acionar a lógica de interceptação do interceptador. Você verá então a mensagem de resposta retornada:

#Status da Mensagem de Resposta

Se o nó "Encerrar fluxo de trabalho" for configurado para sair com um status de "Sucesso", a requisição da ação ainda será interceptada quando este nó for executado, mas a mensagem de resposta retornada será exibida com um status de "Sucesso" (em vez de "Erro"):

#Exemplo

Combinando as instruções básicas acima, vamos usar um cenário de "Envio de Pedido" como exemplo. Suponha que precisamos verificar o estoque de todos os produtos selecionados pelo usuário ao enviar um pedido. Se o estoque de qualquer produto selecionado for insuficiente, o envio do pedido será interceptado e uma mensagem de aviso correspondente será retornada. O fluxo de trabalho fará um loop e verificará cada produto até que o estoque de todos os produtos seja suficiente, momento em que prosseguirá e criará os dados do pedido para o usuário.

Outras etapas são as mesmas das instruções. No entanto, como um pedido envolve vários produtos, além de adicionar um relacionamento muitos-para-muitos "Pedido" <-- M:1 -- "Item do Pedido" -- 1:M --> "Produto" no modelo de dados, você também precisa adicionar um nó "Loop" no fluxo de trabalho "Evento Antes da Ação" para verificar iterativamente se o estoque de cada produto é suficiente:

O objeto para o loop é selecionado como o array "Item do Pedido" dos dados do pedido enviados:

O nó de condição dentro do loop é usado para determinar se o estoque do objeto do produto atual no loop é suficiente:

Outras configurações são as mesmas do uso básico. Quando o pedido é finalmente enviado, se qualquer produto tiver estoque insuficiente, o envio do pedido será interceptado e uma mensagem de aviso correspondente será retornada. Durante o teste, tente enviar um pedido com vários produtos, onde um tem estoque insuficiente e outro tem estoque suficiente. Você pode ver a mensagem de resposta retornada:

Como você pode ver, a mensagem de resposta não indica que o primeiro produto, "iPhone 15 pro", está fora de estoque, mas apenas que o segundo produto, "iPhone 14 pro", está. Isso ocorre porque, no loop, o primeiro produto tem estoque suficiente, então não é interceptado, enquanto o segundo produto tem estoque insuficiente, o que intercepta o envio do pedido.

#Invocação Externa

O Evento Antes da Ação é injetado durante a fase de processamento da requisição, portanto, também suporta ser acionado por chamadas de API HTTP.

Para fluxos de trabalho que estão vinculados localmente a um botão de ação, você pode chamá-los assim (usando o botão de criação da coleção posts como exemplo):

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

O parâmetro de URL triggerWorkflows é a chave do fluxo de trabalho; várias chaves de fluxo de trabalho são separadas por vírgulas. Essa chave pode ser obtida passando o mouse sobre o nome do fluxo de trabalho na parte superior da tela do fluxo de trabalho:

Após a chamada acima ser feita, o Evento Antes da Ação para a coleção posts correspondente será acionado. Após o fluxo de trabalho correspondente ser processado de forma síncrona, os dados serão criados e retornados normalmente.

Se o fluxo de trabalho configurado atingir um "nó de término", a lógica é a mesma de uma ação de interface: a requisição será interceptada e nenhum dado será criado. Se o status do nó de término for configurado como falha, o código de status da resposta retornada será 400; se for sucesso, será 200.

Se um nó "Mensagem de resposta" também for configurado antes do nó de término, a mensagem gerada também será retornada no resultado da resposta. A estrutura para um erro é:

{
  "errors": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

A estrutura da mensagem quando o "nó de término" é configurado para sucesso é:

{
  "messages": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

Se o Evento Antes da Ação for configurado no modo global, você não precisará usar o parâmetro de URL triggerWorkflows para especificar o fluxo de trabalho correspondente ao chamar a API HTTP. Basta chamar a ação da coleção correspondente para acioná-lo.

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create"