Plugins

Sumário

1. Conceito

Plugins são uma solução NoCode para usuários de BPM, permitindo a integração dos fluxos na Senior Flowsem necessidade de desenvolvimento.

Com os Plugins, as integrações são simplificadas: basta informar os parâmetros de entrada e saída para que o plugin funcione. Além disso, é possível configurar novos Plugins e monitorar os existentes, verificando versões, logs de chamadas, tempos de resposta e usuários.

2. Utilizando Plugins em Fonte de Dados

Atualmente, existem várias opções de Plugins que podem ser utilizados como Fonte de Dados, o que proporciona uma integração fluida. Para visualizar os plugins recomendados para essa finalidade, acesse: Senior Flow> Plugins, nos filtros por categoria, selecione a opção BPM – FONTE DE DADOS, CRM – FONTE DE DADOS, GLOBALTEC – FONTE DE DADOS, HCM – FONTE DE DADOS, IBGE- FONTE DE DADOS, SENIORX – FONTE DE DADOS ou SOCIAL – FONTE DE DADOS.

2.1 Como realizar a Configuração

Para este exemplo, utilize o plugin Chamada de API HTTP. Por se tratar de um plugin dinâmico, é necessário criar uma configuração prévia antes de sua utilização. Neste caso, a configuração será baseada em uma requisição a uma API que retorna uma lista de colaboradores, contendo os campos: id, nomeColaborador e emailColaborador.

Para criar a configuração com os campos citados, será necessário localizar o plugin Chamada de API HTTP e acessar a aba de configurações, em seguida, clique em Adicionar.

Insira um nome para essa configuração e ative a opção É uma fonte de dados, caso necessário, adicione os parâmetros de entrada, estes geralmente são utilizados como filtros na consulta. Por fim, na aba Campos de Saída, insira os campos retornados pela API: id, nomeColaborador e emailColaborador.

Salve a configuração e, caso necessário, utilize a aba Testar plugin para validar a chamada.

2.2 Configuração no Formulário

Para utilizar um plugin como fonte de dados, é necessário configurá-lo na tela de configuração do processo, através do menu Senior Flow> BPM > Configurações > Fonte de dados. Escolha a aba Plugins e localize o plugin previamente configurado, selecione a configuração desejada e clique em Salvar para concluir.

Após a criação da fonte de dados, retorne ao formulário e adicione os campos mencionados anteriormente: id, nomeColaborador e emailColaborador.

É possível adicionar uma fonte de dados em um campo do formulário, seguindo os seguintes passos:

• Crie ou edite um campo no formulário,neste exemplo, o campo será chamado de Identificação e será referenciado ao campo id configurado no plugin;
• Acesse aba Fonte de Dados/Plugins e defina o tipo da fonte como Consulta;
• Em seguida, localize e selecione a configuração da fonte de dados previamente criada;
• Configure o campo da fonte de dados como id;
• Como estamos utilizando um plugin dinâmico, ou seja, um plugin que permite a definição personalizada de seus campos, é possível configurar valores de entrada específicos para cada campo. Ao selecionar a configuração, a aba Campos da Configuração será exibida para edição.
• No caso do plugin Chamada de API HTTP, é necessário informar dois valores de entrada obrigatórios: a URL do serviço e o método HTTP que será utilizado na requisição.

• Após concluir os passos anteriores, clique em Salvar para registrar a configuração do campo.

Em seguida, é necessário configurar os campos resultantes, para isso, abra novamente a tela de configuração do campo, desta vez, selecionando um dos campos resultantes e na configuração, defina o tipo de fonte como Resultante.

No campo do formulário com a fonte de dados de consulta, selecione o campo previamente criado como origem da consulta. Neste exemplo, será o campo Identificação.

Por fim, no campo resultante do plugin, selecione o campo que fará referência ao campo do formulário.

Após concluir, salve a configuração do campo e, em seguida, salve o formulário para aplicar as alterações.

2.3 Testando Fonte de Dados

Para realizar o teste da fonte de dados, basta iniciar a solicitação do processo previamente configurado. A consulta à fonte de dados pode ser feita a partir do campo Identificação, de duas maneiras:

1. Inserindo manualmente o valor no campo. Se houver correspondência, o resultado será carregado automaticamente;
2. Clicando no ícone de lupa ao lado do campo. Isso abrirá uma janela modal que executa a consulta na fonte de dados. A modal exibirá todos os resultados retornados pela API, permitindo a seleção do item desejado.

Outro ponto importante desta modal é que é possível aplicar filtros com base nos campos da fonte de dados, conforme exemplo:

3. Usando Plugins em Serviço de Integração

O uso de Plugins como Serviço de Integração proporcionam a inserção de dados na integração com outras APIs de maneira NoCode diretamente no BPM. Para explicar como configurar os Plugins para esse cenário, vamos utilizar o mesmo contexto usado na criação da fonte de dados: anteriormente, realizamos uma consulta de colaboradores; agora, vamos usar um resultado dessa consulta para realizar a inserção de dados.

3.1 Criação da Configuração

Para criar uma configuração que funcione como um serviço de integração, os mesmos passos usados na criação de uma configuração para fonte de dados podem ser seguidos — com a diferença de que a opção É uma fonte de dados não deve ser habilitada.

Para seguirmos com o exemplo, vamos criar uma configuração responsável por cadastrar um colaborador via BPM e, com o uso do plugin, persistir os dados em uma API externa.

Nesse caso, foi configurado um parâmetro de saída, que seria o id gerado para o colaborador:

3.2 Configuração no Fluxo

Para configurar o fluxo com o serviço de integração usando o plugin, vamos criar um processo usando formulário ECM que possua os campos que configuramos no plugin:

No fluxo do processo, configure o serviço de integração clicando em Adicionar Serviço e, em seguida, em Configurar.

Selecione a opção Plugin e escolha o plugin utilizado na configuração criada.

Após selecionar o plugin, escolha a configuração correspondente e preencha os campos disponíveis. Veja o exemplo abaixo:

Concluída a configuração, salve e publique o processo.

3.3 Testando Serviço de Integração

Para realizar o teste com o Serviço de Integração criado, inicie uma solicitação com o processo configurado e preencha os campos:

Em seguida, basta enviar a solicitação. O plugin irá enviar os dados para a API e o retorno da API estará disponível como resposta.

4.Objetos Raiz

O parâmetro Objeto Raiz refere-se ao objeto que contém os dados a serem retornados na resposta da requisição. Quando especificado, ele permite que o usuário defina qual parte da resposta deve ser considerada como a origem dos dados. Por exemplo, ao solicitar a lista de "tasks", o Objeto Raiz seria o objeto imediatamente acima dessa lista na estrutura da resposta, que, neste caso, também se chama "tasks".

Se o parâmetro não for informado, o sistema utilizará automaticamente a raiz da resposta, conhecida como "root".

Dessa forma, a definição do Objeto Raiz é opcional, mas sua utilização pode proporcionar uma maneira mais clara e precisa de acessar os dados desejados.

5. Filtros por Campo

A parametrização inicial, incluindo os valores nos campos da tela de configuração, funciona de forma estática. Para tornar o filtro dinâmico, deixe os campos na tela de configuração em branco e monte o filtro na tela Filtros para validação dos dados. Por exemplo:

6. Visualizar Log e Payload

Através do menu Senior Flow > Plugins, está disponível a funcionalidade visualizar detalhes avançados de erros do plugin. Para visualizar a mensagem de erro, basta selecionar um plugin e, na guia Histórico de execução, clicar no botão Ver mensagem.

Uma mensagem de erro será exibida:

Além disso, o plugin é compatível com o Dataset de API, permitindo acesso ao payload do plugin através de Senior Flow > Plugins. Para visualizar as informações, selecione um plugin e clique na guia Payload. As informações estarão disponíveis para visualização.

7. Múltiplos Plugins por Tarefa

Funcionalidade pensada no vínculo de mais de um serviço externo e/ou plugin a uma etapa do processo, proporcionando uma maior flexibilidade para personalizar o fluxo de acordo com diferentes cenários.

No processo que desejar configurar, siga o caminho:Senior Flow > Lista de processos > Processo desejado > Editar >Fluxo.

No fluxo, abra o menu de engrenagem.

Aba lateral direita, clique em Serviço de integração e clique em Adicionar Serviço.

Após isso podem ser inserido diversos serviços externos.

8. Plugins Dinâmicos e Assíncronos

Atualmente, os plugins podem ser classificados em três tipos distintos:

• Plugin Padrão: Possui parâmetros de entrada e saída pré-definidos. O usuário deve utilizá-los conforme especificado, não sendo possível adicionar ou remover campos. Essa configuração garante padronização e simplicidade de uso;
• Plugin Dinâmico: Permite ao usuário criar configurações personalizadas, possibilitando a definição de campos de entrada e saída conforme a necessidade do processo. Essa flexibilidade torna o plugin adaptável a diferentes cenários.
• Plugin Assíncrono: Similar ao plugin padrão, porém funciona de forma assíncrona. O BPM apenas envia os dados para a URL configurada, sem aguardar uma resposta imediata. Esse modelo é ideal para integrações que não exigem retorno imediato ou para comunicações unidirecionais.

9. Pontos Importantes em Plugins XT

Com o objetivo de simplificar a integração, foram desenvolvidos plugins para facilitar a interação entre a plataforma e os sistemas XT da Senior, que incluem:

• Gestão Empresarial | ERP
• Gestão Empresarial PME | GOUP
• Gestão de Pessoas | HCM
• Ronda Senior.

Os plugins XT tem como principal função inserir e consultar dados disponíveis por API na XT.

Para mais informações referente ao Plugin XT, acesse a documentação completa.

9.1 Configuração de Firewall

Um problema muito recorrente em relação à plugins XT é por conta de bloqueios que muitas vezes acontecem por meio do Firewall ou outras tecnologias que acabam bloqueando o plugin de acessar a máquina do XT.

Geralmente, os tipos de erros que retornam quando alguém barra a consulta vinda do plugin são os seguintes:

• Timeout (Tempo esgotado)
  • Erro: ETIMEDOUT, 408 Request Timeout, Connection timed out
• Conexão Recusada
  • Erro: ECONNREFUSED, Connection refused, ERR_CONNECTION_REFUSED
• Host Inalcançável
  • Erro: ENETUNREACH, EHOSTUNREACH, Destination Host Unreachable
• Forbidden / Acesso negado
  • Erro: 403 Forbidden, Permission denied
• Service Unavailable / Gateway Errors
  • Erro: 502 Bad Gateway, 503 Service Unavailable, 504 Gateway Timeout
• Erro de SSL/TLS
  • Erro: SSL handshake failed, ERR_SSL_PROTOCOL_ERROR
• Bloqueio por IP ou país
  • Erro: Varia, mas muitas vezes apresenta como “acesso negado”, 403, ou até redirecionamento para páginas de erro personalizadas.
• ICMP bloqueado
  • Erro: Ping não retorna, Request timed out

Para evitar que tais erros aconteçam nesse tipo de integração, é necessário liberar o IP externo 34.230.148.169 na sua rede interna. Esse tipo de configuração geralmente precisa ser feito nas seguintes camadas da infraestrutura de rede e segurança:

• Firewall da rede (perimetral)
• Firewall do sistema operacional (host)
• Balanceador de carga ou proxy reverso (se houver)
• Sistema de segurança de aplicações (WAF)
• Middleware ou aplicações com controle de IP

9.2 Configuração do Parâmetro de Criptografia

O parâmetro Encryption depende do tipo de autenticação que está sendo realizada. Verifique as opções:

• 0: Autenticação com usuário XT diretamente.
• 3: Autenticação com usuário X, integrando com XT.

10. Criando seu Plugin

Para disponibilizar um novo plugin, é necessário abrir um Merge Request neste repositório no GitLab. É importante lembrar que este processo é voltado para desenvolvedores.

Para começar, é necessário clonar o repositório e instalar o Node 18. Em seguida, execute os seguintes comandos:

1. "npm install -g serveless" em qualquer diretório;
2. "npm install" na pasta do projeto.

O Merge Request deve conter três arquivos para ser aceito e o novo plugin entrar em operação: swagger.yaml, index.ts e handler.ts.

No arquivo swagger.yaml, devem estar contidas as informações sobre parâmetros, título e descrição do plugin, que serão exibidos dentro da Senior X. Já no arquivo index.ts, deve ser definida a forma de chamada do plugin, seja ela um POST, GET, PUT ou DELETE, bem como o caminho da requisição. Por fim, no arquivo handler.ts, deve existir um método chamado handler, no qual serão implementadas todas as funções que o plugin deve realizar.

Ao criar os arquivos, é importante seguir alguns padrões:

• Todos eles devem estar dentro da pasta Plugin;
• Deve-se criar uma subpasta contendo o nome do plugin, que deve ser o mesmo utilizado no swagger e no caminho dentro do index.ts. Por exemplo, se a pasta se chama obter-cep, o swagger deve conter um item /obter-cep na opção paths, e o atributo path do index.ts deve ser obter-cep.

Antes de realizar o commit e tornar o plugin disponível, é possível testá-lo localmente usando o comando sls offline, sem a necessidade da infraestrutura da AWS.