Pular para conteúdo

N8N Workflows

Objetivo

Explicar como podemos utilizar Quoti Workflows para realizar customizações dentro de uma organização do Quoti, além de explicar como as ferramentas nativas da plataforma funcionam.

O que é

Uma ferramenta no code / low code para criação de fluxos e aplicações. Existe uma documentação extensa sobre todas as funcionalidades disponíveis na ferramenta de workflows chamada n8n, que foi utilizada como base para implementação dos Quoti Workflows: https://docs.n8n.io/

Recomendamos se familiarizar com as seguintes seções antes de continuar a utilizar essa documentação.

Caveat

A documentação do n8n está considerando a versão > 1.0 dele, a versão do n8n usada no Quoti é a 0.237.x, então algumas funcionalidades podem não estar disponíveis.

Como acessar workflows

Na sua plataforma do Quoti navegue para quoti.cloud/suaOrgSlug/app/workflow. Segue um print da tela na organização interna da Beyond no Quoti: É possível que o seu domínio seja diferente de quoti.cloud, mas para utilizar essa ferramenta será necessário acessar por lá. Não se preocupe, apesar do link ser diferente, a plataforma é a mesma.

Nós do Quoti

O Quoti fornece nós customizados para facilitar a integração a plataforma. Especificamente para validar tokens de autenticação (Bearer) e gerenciar Quoti Databases.

Credencial Quoti API

Existe um tipo de credencial específico para utilizar os nós do Quoti, com dois tipos de tokens.

Service Account Token: (Também chamado de BearerStatic) É um token estático para um usuário específico. Todas as operações realizadas com ele ficam associadas ao usuário em questão, geralmente uma conta de serviço. Para criar uma basta acessar /serviceaccounts, clicar no botão de (+) com um token seguro e aleatório:

API Key: Token com acesso mais abrangente, permitindo atribuições de permissões para autenticação via API do Quoti. Para obter uma é necessário solicitá-la diretamente ao time do Quoti.

  • Depois de conseguir os tokens, basta criar uma nova credencial do tipo Quoti API Você não precisa dos dois tokens para criar uma credencial, porém, cada um deles serve um propósito: a API Key serve para o nó de Quoti Auth e o Service Account Token serve para o nó de Quoti Databases.

Nó Quoti Auth

Geralmente utilizado em conjunto com um nó de Webhook para verificar se um token não está expirado e pertence a um usuário da sua organização. Quando o token é valido, o nó retorna as informações do usuário dono do token.

Por padrão o token é buscado nos dados de input do nó, dentro de um objeto chamado "headers", para facilitar a criação de endpoint autenticados com o nó de Webhook.

Caso necessário, também é possível especificar o token utilizando a opção chamada User's Token (geralmente utilizando uma expressão)

Também é possível verificar se o usuário identificado pelo token tem um conjunto de permissões utilizando o campo de Permissions. A sintaxe dele é de um array de objetos, permitindo fazer a verificação de múltiplas permissões como explicado aqui: https://www.npmjs.com/package/quoti-auth na secção de Checking user permissions.

O nó possui duas saídas, uma para quando a autenticação e autorização dão certo (pass) e outra para quando falham (fail).

Nó Quoti Databases

Permite fazer CRUD em qualquer database da plataforma. Basta selecionar o Database, uma Operação e preencher os campos necessários para a operação.

Operação de Create

Permite adicionar linhas a um Quoti Database. É possível adicionar as colunas e seus valores. O nó já traz as colunas que existem no database automaticamente.

Operação de Update

Bem parecida com a operação de Create mas é necessário especificar o ID da linha que será atualizada.

Operação de Delete

Apaga uma linha pelo ID dela.

Operação List

Permite listar uma ou mais linhas do Quoti Database. Permite realizar filtros nos valores das colunas, limitar a quantidade de itens que é retornada e agregar os resultados em um só item do n8n ou em vários.

Pro-tip

Neste nó existe uma propriedade de "Filter" que permite a utilização de um JSON para aplicar filtros complexos. Por exemplo: fazer comparação de maior que e menor que com datas e números, fazer lógicas de AND e OR e filtrar por linhas nas quais uma coluna possui uma substring específica (operador LIKE no SQL).

Para saber como usar o nó de filter, verifique a documentação do parâmetro where API de Quoti Databases aqui

Operação Get

Permite buscar uma linha do database pelo ID dela.

Um exemplo prático do uso de workflows

Suponha que estamos montando uma aplicação para registrar apostas relacionada às olimpíadas. Especificamente permitiremos que usuários possam criar apostas para disputas que vão acontecer. Também deve ser possível editar as apostas, mas apenas até o momento que as disputas começarem, depois não fica mais permitido editar as apostas.

Vamos utilizar dois Quoti Databases para guardar os dados, o primeiro irá guardar o calendário de disputas, com 3 colunas: Descrição, Esporte, A data e horário de início da disputa

O segundo irá guardar as apostas, com 2 colunas: A disputa (ID de uma linha do banco de dados anterior) e o País que irá ganhar o ouro:

Agora ainda é possível criar apostas até mesmo para disputas que já passaram, como é possível ver no print anterior, então vamos resolver esse problema com um workflow seguindo o passo a passo: 1. Primeiro, vamos criar o workflow e adicionar um nó de webhook nele, acessando a página de workflow do Quoti, vamos adicionar um novo: 2. Agora vamos dar um nome a dele e adicionar um nó de webhook:

  1. Seremos levados imediatamente para a interface de configuração do webhook:

  2. Vamos dar uma boa URL, utilizar o método POST para o webhook e escolher responder ele com um nó de "Respond To Webhook" (isso vai ser bem útil em alguns passos)

  3. Agora vamos copiar a URL de produção do webhook (https://workflow.quoti.cloud/webhook/validar-apostas) e ativar o workflow:

  4. Com o workflow criado vamos criar um hook no quoti database para o evento beforeUpdate, para que possamos abortar a operação caso necessário:

  5. Com o hook criado, vamos tentar editar uma aposta apenas para verificar quais dados vamos receber no workflow

  6. No workflow, se formos na aba de execução poderemos ver a execução em questão e quais dados teremos Podemos ver que temos vários dados do usuário (escondidos no print), e que realizamos uma requisição mudando país para Colômbia. Além disso é possível verificar que antes o país era Austrália.

  7. Vamos copiar os dados do webhook na execução e pinar no nosso editor para criar as nossas regras no workflow!

  8. Agora que temos dados podemos criar um workflow para validar se ainda é permitido editar uma aposta. A primeira coisa que precisamos fazer é conectar o nosso nó de Webhook a um novo nó de Quoti Databases e usar a coluna "dispute_id" para buscar os dados : Os nós devem ficar conectados, assim:

  9. Agora podemos adicionar um nó de IF e verificar se a data da disputa é maior que a data atual: Usamos uma expressão para gerar uma data do momento atual com new Date(). No caso do exemplo, a data da disputa não ocorre depois da data atual, então precisaríamos bloquear essa operação.

  10. Para tal vamos conectar um nó de Respond To Webhook para retornar um erro e abortar a operação: Retornamos um JSON com { "aborted": true, "message": "Você não pode mais editar a aposta!" } e um código HTTP 403, indicando que o usuário não tem permissão para realizar a operação.

  11. Agora já temos um workflow que bloqueia operações de edição de apostas quando a disputa em questão já começou! Vamos salvar o workflow e tentar editar a aposta para a disputa com id 1610 novamente!

  12. Dessa vez vemos a mensagem de erro na interface! E se recarregarmos a página podemos verificar que nada foi alterado!

  13. Assim, nossas apostas agora estão seguras! É importante ressaltar que essa validação é feita pela API do Quoti, então mesmo que utilizássemos a API diretamente e não a interface (frontend) a validação ainda seria feita e o mesmo erro iria acontecer!

Outros Exemplos de Casos de Uso

Mais alguns dos casos de uso de workflows:

  • Sincronização de dados
    • No passado, já precisamos garantir que todas as pessoas que tem um certo perfil também participem de um grupo específico.
  • Enriquecimento de Dados
    • Seria possível utilizar hooks para preencher campos de um banco de dados com base em outros campos. Por exemplo: dado um campo de "CEP", utilizar uma API para buscar informações do CEP e preencher outros campos como "Nome da Rua", "Cidade" e "Bairro".
  • Bots do Telegram
    • É possível usar o nó de Trigger do Telegram para criar bots usando workflows.
  • Cron jobs
    • É possível usar o nó de Schedule para executar workflows periodicamente. Por exemplo, para verificar integridade de dados e que regras de negócio estão sendo cumpridas.
  • Integrações com outros sistemas
    • Facilitar a comunicação entre APIs que não foram feitas para "conversarem". Pode-se utilizar um workflow para mapear dados vindos de uma API para outro formato que uma segunda API entenda.