Olá, tudo bem?

Esse é um documento completo que fala tudo sobre a integração Robbyson. 

Esperamos que goste! 

Boa leitura! 🤩

Quais os métodos de integração?

API, SFTP - Secure File Transfer Protocol e Integrador.

 

Como funciona o API? 

API é o método mais seguro para o envio de dados. Esse método é realizado diretamente dentro da plataforma Robbyson, sendo de responsabilidade do cliente e sem intervenção da empresa.

Quando se trata da API, existem regras que os clientes devem seguir para enviar dados para a plataforma Robbyson. Essas regras estão em um documento público disponível na internet. Você pode acessá-lo através do seguinte link:

 

https://robbyson-integration-pi.readthedocs.io/en/latest/recursos.html.

O objetivo desta documentação é fornecer orientações aos desenvolvedores que utilizam a API de Integração do Robbyson. Ela descreve o que deve ser enviado, os endereços e métodos utilizados, o fluxo do processo de integração na ferramenta e outros detalhes relevantes.

Ou seja, essas orientações são para os clientes criarem seu próprio código para enviar os dados para o Robbyson.

E para enviar os dados, é necessário ler o código fornecido na documentação e desenvolver a solução que será utilizada para o envio dos dados. Veja na imagem a ilustração da página inicial do site.

 

Imagem ilustrativa da página inicial do site.

No documento "Recursos da API", estão descritos todos os recursos disponíveis, como colaboradores, hierarquia, atributos, indicadores e resultados, juntamente com os detalhes necessários para acessá-los. A imagem abaixo ilustra um exemplo do arquivo "Colaboradores" com as informações detalhadas.

 

Imagem ilustrativa do exemplo do arquivo "Colaboradores" com detalhes de acesso.

O que é necessário para os clientes acessarem a API Robbyson para enviarem seus dados?

Para os clientes acessarem a API Robbyson e enviar dados, é necessário obter uma senha de acesso, como requisito de segurança. Isso pode ser comparado à necessidade de fornecer um login e senha ao acessar uma rede social. A senha de acesso é enviada por e-mail e tem validade de 24 horas.

É importante mencionar que, no painel de integração, é improvável que haja acesso direto aos dados dos clientes para fazer um check nos dados de hierarquia, atributos ou resultados. Isso ocorre devido ao grande volume de dados envolvidos. 

Por que é recomendável os clientes Robbyson utilizarem a API?

Quando lidamos com um grande volume de dados, é altamente recomendado que o cliente utilize a API. Isso porque, um arquivo CSV integrado pode facilmente ter um tamanho mínimo de 3 ou 4 gigabytes, tornando a transferência desses arquivos via SFTP ou integrador extremamente demorada.

Quais os benefícios ao utilizar como método de integração a API?

Os clientes se beneficiam ao utilizar a API, pois ela elimina a necessidade de rotinas estruturadas, como o uso do SFTP. Assim, eles não precisam organizar horários específicos para realizar o envio de dados, pois uma vez enviado, os dados entram em fila de processamento imediatamente. 

No entanto, muitos clientes optam por automatizar o processo de envio de dados, criando suas próprias rotinas. É importante notar que o Robbyson não possui uma rotina específica para a API, sendo essa responsabilidade do cliente.

Existe diferença entre API e os demais métodos de integração?

Sim, a diferença entre a API e os outros métodos de integração está relacionada aos atributos e resultados no contexto do Robbyson. 

Especificamente em relação aos atributos isolados que, quando estão presentes em um arquivo, o peso deve ser definido como zero (0). Exemplos de atributos isolados são: "self", "home office" e atributos específicos.

E, na API, não é permitido atribuir um peso aos atributos isolados. Essas informações devem permanecer em branco, ou seja, não devem ser preenchidas. Se houver preenchimento do peso, o Robbyson não os reconhecerá como atributos isolados.

No caso dos resultados, quando não houver um valor válido, pode-se utilizar zero (0) para indicar a ausência de resultado. No entanto, quando o resultado for nulo, ou seja, não existir, não é necessário enviar nenhum valor. Nesse caso, a ferramenta entenderá que não há resultado para ser registrado.

É importante notar que se um valor vazio for enviado na API para representar um resultado, a plataforma não o reconhecerá e resultará em um erro no painel de integração. Para corrigir essa situação, será necessário enviar o caso para a equipe técnica verificar a causa do erro.

Como funciona o SFTP - Secure File Transfer Protocol? 

No nosso sistema de rede, utilizamos o SFTP para acesso às pastas, que requer autenticação por meio de login e senha, seguindo um processo similar ao acesso via API. Cada cliente possui sua própria pasta para armazenar os dados necessários para alimentar o Robbyson, incluindo arquivos de colaborador, atributos, resultados, hierarquia e indicadores.

Com esse método, é necessário estabelecer uma rotina de envio de dados, com dias e horários programados, para garantir a sincronização com o cliente e permitir o processamento das informações no Robbyson.

Mas, para que a rotina funcione corretamente, é importante garantir que os arquivos sejam nomeados corretamente. Exemplo: se a rotina espera processar um arquivo chamado "ATRIBUTOS", é necessário que o arquivo esteja nomeado exatamente dessa forma. Caso contrário, o arquivo não será reconhecido pela rotina e não será processado.

Portanto, é essencial ter cuidado ao fazer o upload dos arquivos e garantir que eles estejam nomeados de acordo com as especificações da rotina de busca. Isso ajudará a evitar problemas e assegurará que os arquivos corretos sejam lidos e processados adequadamente pela plataforma.

Além do envio dos dados via SFTP para a pasta designada, há uma janela de tempo a cada 10 minutos que realiza uma simples cópia dos arquivos da pasta para o servidor da Robbyson. No entanto, essa ação não constitui uma integração completa, apenas uma duplicação dos arquivos. 

Portanto, quando executamos a integração, o arquivo que será integrado é o mais recente a ser copiado. Por exemplo, se estabelecermos uma rotina de integração às 13h, os dados que serão integrados e posteriormente processados serão aqueles copiados às 12h50. 

Esse processo envolve três etapas de integração, que vamos falar mais adiante, porém, se uma etapa se sobressair sobre a outra, os dados podem ser processados com erros. 

Uma observação é que, além da cópia dos arquivos a cada 10 minutos, podem existir arquivos na pasta que não devem ser processados pela rotina de integração. Esses arquivos são logs ou registros de informações sobre o envio e processamento dos arquivos.

Falando sobre os dados do arquivo, a Robbyson, conforme mencionado, é uma ferramenta passiva em relação aos dados enviados, ou seja, ela não realiza nenhuma modificação nos arquivos. Isso significa que qualquer palavra com acentuação será mantida com o acento original. 

Como funciona o método integrador? 

Esse método é realizado dentro do próprio Robbyson sendo responsabilidade do cliente integrar sem nenhuma intervenção da Robbyson.

No método integrador, o cliente tem a liberdade de processar os dados quando desejar, conforme oferecido pela API, além de lidar com o manuseio dos arquivos necessários, semelhante ao SFTP. Para garantir que não ocorra nenhum erro durante o envio dos dados, é fundamental que o arquivo enviado esteja totalmente correto, caso contrário, ele não será processado. 

O que acontece se durante o processamento de integração ocorre algum erro?

Durante o processo de integração, se houver algum erro no arquivo, uma mensagem de erro será exibida, indicando que o processamento não foi realizado com sucesso. É importante garantir a integridade e a validade dos dados antes de enviá-los para a plataforma, a fim de evitar erros e problemas no processamento.

Nesse método, o processo de integração ainda segue as três etapas mencionadas anteriormente (Envio dos dados, Integração dos dados no banco e Processamento dos dados), porém, essas etapas são executadas pelo orquestrador presente na plataforma Robbyson. 

O que é o orquestrador existente na plataforma Robbyson?

O orquestrador é responsável por organizar a entrada dos dados e seu processamento dentro do sistema. Ele coordena e gerencia as etapas de integração, garantindo que os dados sejam corretamente recebidos, processados e utilizados na plataforma.

Em resumo, o orquestrador desempenha um papel crucial na execução e controle das etapas de integração, assegurando a ordem adequada de entrada e processamento dos dados no ambiente do Robbyson.

Existe uma sequência para o envio de dados no método integrador?

No método proposto, é necessário ter cuidado ao enviar ou atualizar os dados, seguindo a seguinte sequência: colaborador, indicador, hierarquia, atributo e resultado. 

Uma particularidade importante desse método é que os arquivos de hierarquia e atributos devem ser enviados juntos no Robbyson, ou seja, eles não podem ser enviados separadamente. 

Como realizar o processo de integração dos arquivos?

Inicialmente acesse o Robbyson ADM pelo link: https://app.robbyson.com/administracao/

Logo em seguida, clique em “Configurações” e depois em “Integração por Arquivos”. Na tela de “Integração por Arquivos” clique em “+novo arquivo”. Veja o passo a passo:

1° passo: na tela do “ Painel de Administração” no menu lateral clique em “Configurações”.

2° passo: na tela de “Configurações” no campo CONFIGURAÇÃO clique em “Integração por arquivos”.

3° passo: na tela de “Integrações” clique em “+NOVO ARQUIVO”.

Como exemplo, vamos realizar o input dos arquivos de hierarquia e atributos. A ordem entre esses dois arquivos não importa, desde que ambos sejam enviados juntos.

No nosso exemplo, começaremos com o input do arquivo de hierarquia. Após o envio desse arquivo, o status será definido como "aguardando pendência". Somente nesse momento será possível realizar o input do arquivo de atributos.

Essa restrição garante que a plataforma Robbyson tenha os dados necessários da hierarquia antes de processar os atributos relacionados.

4° passo: input do arquivo hierarquia. 

- Selecione o arquivo de hierarquia e preencha com o período desejado. 

- Você não precisa preencher o ID transação, pois esse código ainda não foi gerado pela plataforma. 

Mas, o que é ID transação? O ID transação é normalmente atribuído pela plataforma Robbyson após o processamento do arquivo e é utilizado para rastrear e identificar de forma única a transação relacionada ao envio do arquivo.

 

5° passo: agora que já realizamos o input do arquivo hierarquia, vamos para o input do arquivo atributo.

- Na tela de “Integrações” clique em “+Novo Arquivo”.

- Logo após, selecione o arquivo do input, no nosso exemplo será o arquivo atributos.

- Preencha com o mesmo período do arquivo hierarquia.

- Preencha com o ID que foi gerado quando realizado o input do arquivo hierarquia.

Para isso devemos voltar para tela de “Integrações”.

 

- No campo ID Transação copie e cole o código gerado pelo input do arquivo hierarquia e clique em “enviar”.

 

Portanto, ao realizar o upload dos dados no Robbyson, é essencial assegurar que os arquivos de hierarquia e atributos sejam enviados de forma conjunta, seguindo a ordem especificada, a fim de garantir uma integração correta e sem erros no sistema. 

Na imagem temos um exemplo de como visualizamos os arquivos que foram integrados juntos pelo Robbyson no Painel de Integração.

 

 

Imagem ilustrativa do exemplo da tela de uma pasta SFTP na rede Robbyson.

Vamos falar sobre como garantir uma rotina de integração bem-sucedida com as três etapas do processo de integração:

1.    Envio dos dados: nesta etapa, os arquivos contendo os dados relevantes são enviados para a pasta específica na rede, utilizando o protocolo SFTP. É importante que os arquivos sejam nomeados corretamente, como discutimos anteriormente, para que sejam reconhecidos pela rotina.

2.    Integração dos dados no banco: após o envio dos arquivos, a rotina de integração deve ser projetada para realizar a leitura e a integração desses dados. 

3.    Processamento dos dados: uma vez que os dados foram integrados ao banco, a rotina pode prosseguir com o processamento das informações. Isso pode envolver cálculos, análises, geração de relatórios ou qualquer outra tarefa relacionada aos dados específicos e aos requisitos do Robbyson.

É importante garantir que cada etapa seja adequadamente configurada e implementada na rotina de integração, a fim de garantir um fluxo de dados consistente.

O que é e para que serve o painel de integração? 

O Painel de Integração de Dados no Robbyson é uma função que permite aos administradores acompanhar, de forma independente e sem a necessidade de assistência direta da equipe Robbyson, o andamento e o status dos passos da integração de dados.

Na coluna “Passos”, fica o registro que representa um processo de integração de dados, abrangendo desde o processo inicial, envio de dados, até a etapa de processamento desses dados. Esses registros fornecem uma visão geral dos passos envolvidos e permitem que acompanhem o progresso e o estado de cada etapa do processo.

Essa funcionalidade no Painel de Integração é projetada para fornecer maior transparência e autonomia aos administradores, permitindo que eles monitorem o fluxo de integração de dados de forma eficiente e façam ajustes ou tomem ações necessárias, caso surjam problemas ou obstáculos no processo.

Quais são as falhas que podem aparecer no painel de integração?

Quando falamos de problemas ou obstáculos, existem duas falhas que podem ocorrer dentro dos arquivos durante o processo de integração de dados no Robbyson: falhas estruturais e falhas qualitativas.

As falhas estruturais são aquelas que impedem o processamento dos arquivos devido a problemas na sua estrutura. Por exemplo, pode haver uma coluna adicional que não corresponde ao esperado, uma coluna com valores invertidos, ou uma data com formato incorreto. Essas falhas estruturais estão relacionadas à criação ou formatação inadequada dos arquivos e podem impedir que os dados sejam corretamente processados pela plataforma.

Já as falhas qualitativas estão relacionadas à integridade ou consistência dos dados em relação aos registros existentes. Por exemplo, um usuário pode estar presente no arquivo de atributos, mas não constar no arquivo de hierarquia correspondente. Além disso, pode haver erros nas matrículas ou IDs dos usuários, ou ausência de resultados para determinados registros. Essas falhas qualitativas podem afetar a correta associação e análise dos dados, resultando em resultados imprecisos ou incompletos.

Tanto as falhas estruturais quanto as falhas qualitativas podem levar a erros no processamento dos dados. É importante realizar uma validação cuidadosa dos arquivos antes do envio, garantindo que eles estejam corretos e completos, a fim de evitar problemas durante a integração.

Na imagem abaixo é possível visualizar um exemplo de falha no processo de integração, onde os registros afetados pelas falhas não apareceriam ou seriam marcados de forma distinta, indicando que não foram processados corretamente.

 Como identificar quais foram os erros identificados no processo?

Para verificar os erros identificados no processo de integração, siga os passos abaixo:

1° passo: no Painel de Integração do Robbyson, localize o ícone do olho relacionado à integração específica que deseja verificar os erros. Clique neste ícone para obter mais detalhes.

2° passo: na tela de detalhes da integração, navegue pela barra de navegação ou pelos menus disponíveis e procure a opção ou guia rotulada como "API". Clique nessa opção para acessar a página que exibe os erros identificados.

3° passo: na página de erros, você poderá visualizar uma lista dos erros encontrados durante o processamento da integração. 

Cada erro geralmente é acompanhado de informações relevantes, como a descrição do erro, a identificação do registro afetado. Clique em um erro específico para visualizar os detalhes.

4° passo: Após identificar o erro clique em “Fechar”.

 

Quais os significados dos erros mais comuns?

Abaixo temos alguns erros já identificados e seus significados. 

1.    Cannot encode object: JSONDecodeError('Expecting value: line 1 column 1 (char 0)') - Falta de campo obrigatório para integração.

2.    'utf-8' codec can't decode byte 0xc3 in position 74192: invalid continuation byte - Encode incorreto.

3.    'utf-8' codec can't decode byte 0x82 in position 16: invalid start byte - 

Posição de coluna.

Pode ser causado por falta de coluna ou coluna invertida.

4.    Erro no campo RESULTADO_RESULTADO com o valor 0+C311333:C311338

Envio de resultado incorreto.

Exemplo: a coluna e configurado para ser do tipo 'Inteiro' e o cliente está enviando como 'string'

5.    Esta linha não tem todos os campos necessários. Talvez o separador dos campos está incorreto?

Separador incorreto.

6.    {"Atributo n\u00e3o encontrado ": {"identification": "10908108", "date": "2023-04-01"}}

O arquivo de hierarquia não possui dependência, o usuário está no arquivo de hierarquia porém não está no arquivo de atributo, como esses dois arquivos são dependentes o painel apresenta esses erros.

Arquivo de hierarquia tem data início e Fim e o de atributo somente data, quando existe a dependência é obrigatório o nome ser igual.

Agora chegamos ao final do nosso conteúdo! Ficou com alguma dúvida? Mande para suporte@robbyson.zohodesk.com que vamos atrás da informação para incluir aqui.