# Floui Conectores Personalizados
## Introdução
A ferramenta de conectores personalizados permite que usuários com conhecimentos avançados em programação possam implementar conectores personalizados de acordo com as necessidades da sua operação. Esta ferramenta é especialmente poderosa para atender regras de negócio específicas ou integrações com outros sistemas externos.
Neste artigo será apresentado como gerenciar estes conectores personalizados, como utilizá-los em fluxos, além de apresentar informações relevantes para a implementação destes conectores. Adicionalmente, será listados algumas boas práticas para uso da ferramenta, visando o aumento do conhecimento para implementar conectores complexos.
## Gerenciamento de conectores personalizados
Para acessar o gerenciamento de conectores personalizados, acesse o menu lateral e, em Construção, clique em Conectores Personalizados. A partir desta tela de gerenciamento, é possível visualizar informações gerais dos conectores. Por esta tela, também haverá as seguintes opções:
* Acessar a criação de novos conectores.
* Acessar a edição de conectores.
* Buscar por conectores.
* Duplicar conectores existentes.
Listagem e gerenciamento de conectores personalizados
## Criação de conectores personalizados
Para criar um novo conector personalizado, clique em Criar Conector. Em seguida preencha as informações básicas do conector. Abaixo estão a descrição das configurações disponíveis:
* **Nome**: Identificação do conector personalizado;
* **Descrição**: Informações gerais sobre o conector;
* **Imagem do conector**: Ícone usado na apresentação do conector. Recomenda-se utilizar imagens de 128x128px com tamanho máximo de 100 KB;
* **Nome do serviço**: Nome utilizado para identificar e categorizar conectores relacionados a um mesmo serviço.
Parâmetros de Configuração
* **Código do campo**: Identificação única do campo, usada na implementação do conector;
* **Label**: Nome ou rótulo exibido para o campo;
* **Tipo**: Formato de entrada de dados. As opções disponíveis são:
* **Texto**: Campo para texto;
* **Texto longo**: Campo para textos extensos;
* **Dropdown**: Seletor com múltiplas opções, permitindo apenas uma escolha;
* **Editor de código**: Campo para edição de código;
* **Tabela de parâmetros**: Tabela estruturada em formato chave e valor.
* **Duplicar**: Cria uma cópia do campo configurado;
* **Opções**: Disponíveis ao selecionar o tipo Dropdown, permitindo configurar as opções do seletor;
* **Colunas**: Disponível ao selecionar o tipo Tabela de Parâmetros, permitindo definir as colunas da tabela.
Funções do conector
* Tipo de execução: Permite selecionar o tipo a forma em que o conector será executado. No momento permite apenas a opção **Executar código customizado;**
* Bloco de código: Permite implementar sobre o conector customizado. Acesse a seção [Observações Gerais da Implementação de Conectores Personalizados](#observacoes-gerais-da-implementacao-de-conectores-personalizados).
Criação/edição de conectores
## Importação e exportação de conectores personalizados
Pela tela de edição do conector personalizado, é disponibilizado ao usuário para que possa exportar toda a estrutura do conector criado em formato JSON. Assim como também permite importar uma estrutura de conector personalizado.
Acesse a tela de edição ou criação do conector e clique em **Exportar Conector** para exportar a estrutura em JSON, ou clique em **Importar Conector**, e selecione um arquivo JSON válido de conector para importar a estrutura.
## Observações Gerais da Implementação de Conectores Personalizados
Após configurar o conector personalizado, parametrizando os campos necessários, deve-se implementar a lógica para atender às necessidades específicas da operação. Clique em **Funções do Conector** para acessar a aba de implementação do conector.
A implementação de conectores personalizados é feita utilizando a linguagem de programação **JavaScript**, por meio da função assíncrona `handler(msg, params)`. Toda a lógica do conector deve ser desenvolvida com base nessa função.
Implementação de conector personalizado
### Bibliotecas disponíveis
O Floui disponibiliza algumas funções reservadas para os conectores personalizados, responsáveis por manipular no contexto de execução o objeto msg. Estas funções permitem ao conector personalizado aplicar bibliotecas já instaladas no workspace ou manipular informações em tempo de execução.
**handler(msg, params)**
Função utilizada para acessar os campos do conector e manipular o objeto msg, que é gerado no contexto da execução do fluxo. Esse objeto contém informações relevantes sobre o estado ou dados processados durante a execução.
Com handler, é possível realizar alterações, validações ou transformações no conteúdo de msg, permitindo personalizar seu comportamento de acordo com as necessidades do fluxo.
Parâmetros
msg (objeto): o objeto gerado pelo contexto do fluxo, que será manipulado ou transformado. Contém dados estruturados que podem variar conforme o fluxo ou integração.
params (campo): Campo do conector personalizado que será manipulado ou transformado. Contém os dados parametrizados pelo usuário.
***
**await getVar("chave")**
Recupera o valor associado a uma variável definida no painel de configuração do fluxo ou uma variável global do Workspace, caso a variável global e do fluxo possuem o mesmo nome, irá capturar a variável do fluxo. Através do nome da variável fornecido, `getVar` permite acessar valores configurados, facilitando a reutilização de dados dentro do fluxo.
Parâmetros
nomeDaVariavel (string): o nome da variável a ser buscada. Deve ser uma string que corresponda exatamente ao nome utilizado no momento da definição da variável.
Variáveis padrões
* `current_date`
* `current_datetime`
* `current_time`
* `timestamp`
## Uso do conector personalizado em fluxo
Após ter criado o conector personalizado, ele ficará disponível para uso em qualquer fluxo dentro daquele Workspace Floui. Para utilizá-lo, siga estes passos:
1. Acesse a edição ou criação de um fluxo.
2. Abra a **Biblioteca de Componentes**.
3. Navegue até a categoria **Conectores Personalizados** ou use a barra de busca para localizar o conector pelo seu nome.
4. Clique no conector criado para adicioná-lo ao fluxo.
## Boas práticas
O conector personalizado disponibiliza aos usuários as ferramentas necessárias para criar seus próprios conectores de acordo com a necessidade da operação. Seguir boas práticas na criação destes conectores diminui casos de manutenção destes conectores, o que também pode implicar na manutenção em todos os fluxos que utilizam estes conectores. Seguem alguns exemplos de boas práticas na criação de conectores personalizados:
* Documente o uso do conector personalizado criado. Explique seus campos, APIs utilizadas, funções e demais detalhes da implementação.
* Siga boas práticas de implementação na criação dos conectores personalizados, facilitando a sua leitura e manutenções futuras.
* Teste os seus conectores personalizados.
* Defina o escopo e casos de uso daquele conector, quais são e não são suas responsabilidades, Isto irá tornar o seu conector mais objetivo, claro e com menos manutenção, logo reduzindo possibilidades de quebras ao utilizá-lo em vários fluxos.
