| Passo a passo: | A integração entre o Protheus e Feedz ocorre para envio dos dados abaixo:
- Filiais (SM0)
- Funcionários (SRA)
- Participantes (também conhecido como Pessoas - RD0 e RDZ)
- Cargos (SQ3)
- Departamentos (SQB)
- Grupos de Contrato (SX5 - Tabela 1C)
- Líder dos Funcionários (utilizado quando o cliente tem controle de Hierarquia por uso do App MEU RH ou Portal GCH - SRA + RD0 + RDZ)
As informações enviadas do Protheus para a Feedz, estarão presentes em uma tabela chamada REF, e os dados integrados (com falha ou sucesso) via rotina de Carga Inicial ou Schedule, podem ser visualizados na rotina de Consulta de Lotes.
Para que os Funcionários possam ser integrados, é obrigatório que exista na SRA:
> Email
> Cargo
> Departamento
> CPF
Dicas:
→ Nos casos em que o cliente nos procura com erros na integração que não sejam do lado do Protheus ou dúvidas sobre a plataforma Feedz de modo geral, devemos orientar que ele procure o seu Agente de Sucesso Feedz.
→ Existem casos em que o cliente acaba tendo falhas cadastrais na Integração, como por exemplo, foi enviado um funcionário com email incorreto ou email de outra pessoa. Nestes casos, podemos orientar que ele ajuste manualmente os registros na Feedz e processe novamente a integração do Funcionário pela rotina do Protheus, mas se mesmo assim o problema persistir e chegarmos à um nível que não temos mais o que avaliar/orientar da nossa parte, devemos entrar em contato com o time de Suporte da Feedz via chat. Para que eles consigam ser assertivos nas análises, devemos ter em mãos o ProcessID do lote integrado pelo cliente. Essa informação pode ser coletada no Log de Ocorrências gerado em tela ao final da integração OU pela rotina de Consulta aos Lotes de Integração.
→ Os clientes possuem ambiente Teste chamado 'Sandbox' e a Produção. Caso ocorram falhas na integração relacionadas à URL ou token, é legal orientar que ele valide se está utilizando os dados do ambiente correto. Outro erro que costuma acontecer envolvendo URL e token, é que os clientes tentam utilizar os exemplos listados na nossa documentação. Cada cliente tem o seu ambiente, então caso não saiba como coletar os dados da URL e gerar o token, deve procurar o seu Agente de Sucesso Feedz.
→ A Feedz não trabalha com múltiplos vínculos, então nestes casos, devemos orientar o cliente a integrar somente um dos registros do funcionário.
OBS: para facilitar o entendimento, foram inseridos prints dos processos em todo o passo a passo. Todas as palavras em 'azul', representam uma imagem, para abri-la, basta clicar em cima da palavra com o hiperlink.
Exemplo da uma imagem anexada a nossa documentação aqui.
| Deck of Cards |
|---|
| | Card |
|---|
| Para que a integração aconteça, é necessário que exista um ambiente criado na plataforma Feedz + token de acesso. O cliente conseguirá esses dados através do seu Agente de Sucesso Feedz, ou seja, no momento de configurar a implantação no Protheus, ele já terá estes dados em mãos.
A URL utilizada pelo cliente, vai depender se ele está utilizando um ambiente teste ou produção.
Para ambiente TESTE (Sandbox), a URL utilizada deve ser https://integrations.feedz.dev/protheus-feedz-etl/
Para ambiente PRODUÇÃO, a URL utilizada deve ser https://integrations.feedz.com.br/protheus-feedz-etl/
O token pode ser gerado dentro da Feedz em Configurações - Integrações.
Para os testes do time de Suporte, serão utilizados os dados do ambiente TESTE abaixo:
> URL da Plataforma: https://integrations.feedz.dev/protheus-feedz-etl/
> Token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwcm9maWxlX2lkIjo3MjM2MiwiY29tcGFueV9pZCI6MTAyLCJ0aW1lc3RhbXAiOjE3MTA3ODc3MjZ9.8Pb8BM_t2hQ9fNPdL-BUnAgMTMnAqbh8xj3vStEGRg0
Os parâmetros que devem ser preenchidos com estes dados são:
→ MV_APIFEE1
→ MV_APIFEE2 |
| Card |
|---|
| Para que seja possível o envio dos dados, configuração da amarração dos Cargos e Departamentos (explicaremos mais adiante sobre isso) e consulta das informações integradas com sucesso ou não, é necessária a inclusão de algumas rotinas no meu menu do SIGAGPE.
Para isso, acesse o Configurador - Ambiente - Cadastros - Menus - desmarque todos os menus e selecione apenas o 'Gestão de Pessoal' - clique em OK.
Adicione todos os menus do SIGAGPE à direita da tela para que não tenhamos problema com as demais rotinas existentes no módulo.
Para melhor visualização, optei por criar uma nova 'pasta' de menu, chamada Feedz. Você pode definir onde ela será criada, no meu exemplo, criei esta pasta dentro da opção 'Atualizações'. Para isso, basta posicionar em cima do menu já existente e clicar em 'Novo Grupo'. Será aberta uma nova janela, onde você deve informar o nome da nova pasta, após isso, dê um ok.
Após ter criado a nova pasta, posicione sobre ela e clique em 'Novo Item' para iniciarmos a criação dos menus.
Vamos criar quatro novas rotinas, que são:
→ De x Para de Cargos (GPEA944B)
→ De x Para de Departamentos (GPEA944C)
→ Integração (GPEM939)
→ Consulta (GPEM939B)
Quando finalizar a inserção dos quatro menus, clique em 'Gerar' - Informe o Arquivo SIGAGPE e Gerar novamente. Após finalizar, os menus já estatão estarão disponíveis no SIGAGPE.
OBS: faça esta etapa com o Protheus fechado, utilize apenas o Configurador nesta etapa.
Caso tenha dificuldades na criação da nova pasta e menus, veja este vídeo: . |
| Card |
|---|
| label | 3. Manutenção Tabelas |
|---|
| Dentro do SIGAGPE, teremos que ajustar dados nas tabelas auxiliares S043 e S049, no menu Atualizações - Definições de Cálculo - Manutenção Tabelas.
Na S043, devemos preencher a coluna 'Tipo P&M/Feedz'.
Na S049, devemos preencher a coluna 'Agrupador P&M/Feedz'.
OBS: em ambos casos, o cliente deve decidir sobre qual a forma que considera mais adequada para preenchimento das tabelas. |
| Card |
|---|
| label | 3. Criação dos Menus |
|---|
| Para que seja possível a integração de dados do Protheus para o Quirons, bem como cadastro de usuário, senha e acesso à rotina de Monitor de Integração que possibilita que o usuário confira se o dado foi ou não integrado corretamente, será necessária a inclusão de três rotinas no menu do SIGAGPE através do Configurador, que são:
• Carga Inicial - GPEM925
• Parâmetros - GPEM926
• Monitor - GPEM924
Para inclusão das rotinas no menu, é necessário acesso em modo exclusivo. Com isso, acesse o Configurador - Ambiente - Cadastro - Menus - selecione o módulo Gestão de Pessoal e Confirme:
Posicione na primeira opção com o nome do módulo SIGAGPE e clique na opção Adicionar para que todos os menus existentes fiquem no painel à direita da nossa tela conforme exemplo:
Os três novos menus podem ser adicionados em qualquer menu que já existe, mas também é possível criar um novo sub menu.
No exemplo abaixo, decidi incluir um novo sub menu dentro do menu Atualizações. Para isso, posiciono no menu Atualizações e clico na opção Novo Grupo.
Inseri como exemplo, o nome Quirons e com isso, o sub menu já fica visível para que consigamos incluir as rotinas.
As rotinas devem ser incluídas com o nome de sua preferência, sendo importante apenas se atentar ao informar o nome do Programa (o fonte da rotina que está sendo incluída), Módulo que será o Gestão de Pessoal e Tipo que será Função Protheus, conforme este exemplo.
Após finalizar as três inclusões, elas deverão aparecer no novo sub menu. Para confirmar os ajustes, basta clicar em Gerar - informar SIGAGPE e Gerar novamente.
Caso não tenha conseguido incluir os menus, veja este vídeo: Incluindo Menus
| Card |
|---|
| label | 4. Parâmetro envolvido na integração |
|---|
| Para habilitar a integração no Protheus, é necessário configurarmos o parâmetro MV_RHNG com conteúdo .T. |
| 4. De x Para de Cargos e Departamentos |
| O De x Para de Cargos (GPEA944B) é utilizado quando o cliente utiliza a tabela SQ3 com algum nível de exclusividade.
A Feedz não aceita a integração de dois Cargos com o mesmo nome/código em Filiais diferentes, ou até de códigos diferentes mas que tenham o mesmo nome, por este motivo, devemos utilizar esta rotina para 'amarrar' estes dados, de modo que uma única informação seja integrada para a Feedz.
No exemplo a seguir, tenho um Cargo com descrição 'Analista de Suporte' nas filiais M SP 01 e M SP 02.
Neste caso, os Cargos tem o mesmo nível/são exatamente iguais, portanto, antes de processar a integração farei a amarração destes dados.
Acessando a rotina De x Para de Cargos, clique em Incluir para iniciar o vínculo entre os dados.
Insira o código e descrição como preferir, e clique em Outras Ações - Vincular Cargos. Selecione os Cargos que são equivalentes e clique em Salvar.
Após isso, será demonstrada na parte inferior os Cargos vinculados a este cadastro de De x Para, e você pode vincular quantos cargos forem necessários. Finalizando a seleção, basta clicar em Confirmar.
Com isso, teremos nosso cadastro de De x Para do Cargo 'Analista de Suporte' criado e pronto para ser integrado.
A mesma regra é utilizada para os cadastros de Departamentos da tabela SQB, ou seja, caso exista qualquer nível de exclusividade ou cadastros de mesmo nome, se faz obrigatório o cadastro de De x Para de Departamentos (GPEA944C).
No exemplo a seguir, tenho um Departamento com descrição 'Suporte' nas filiais M SP 01 e M SP 02.
Neste caso, os Departamentos tem o mesmo nível/são exatamente iguais, portanto, antes de processar a integração farei a amarração destes dados.
Acessando a rotina De x Para de Departamentos, clique em Incluir para iniciar o vínculo entre os dados.
Insira o código e descrição como preferir, e clique em Outras Ações - Vincular Departamentos. Selecione os Departamentos que são equivalentes e clique em Salvar.
Após isso, será demonstrada na parte inferior os Departamentos vinculados a este cadastro de De x Para, e você pode vincular quantos departamentos forem necessários. Finalizando a seleção, basta clicar em Confirmar.
Com isso, teremos nosso cadastro de De x Para do Departamento 'Suporte' criado e pronto para ser integrado.
OBS: o De x Para de Cargos e Departamentos só é obrigatório se as tabelas SQ3 ou SQB tiverem algum nível de exclusividade. Caso alguma das tabelas seja totalmente Compartilhada, não é necessário nenhum tipo de cadastro de De x Para, por exemplo: se a SQ3 for CCC e a SQB for EEE, não é necessário o De x Para de Cargos, apenas o de Departamentos.
OBS2: se alguma das tabelas for totalmente compartilhada mas o cliente tiver Cargos ou Departamentos com mesmo nome, será necessário orientá-lo para que ajuste o nome de um dos registros. |
| Card |
|---|
| Agora estamos prontos para iniciar nossas integrações \õ/
Para isso, vamos acessar a rotina Integração (GPEM939) - Avançar até o passo 2 - Configuração.
Nos parâmetros, teremos:
→ Verificação registro ativo: caso NÃO queira integrar demitidos, selecione a opção 'Somente pelo campo MSBLQL (se houver)'. Se quiser integrar demitidos, selecione então a opção 'Campo MSBLQL (se houver) + vínculo com registro ativo da SRA', com isso, será habilitada a pergunta 'Data de corte demissão'. As demissões anteriores à data informada nesta pergunta não serão integradas para a Feedz.
→ Verificação retorno da integração: caso queira visualizar o log de integração em tela, selecione a opção 'Aguardar o retorno da integração', com isso, será habilitada a pergunta 'Tempo limite (em minutos)'. Nela devemos informar o tempo que queremos aguardar para que seja gerado o log em tela. Caso NÃO queira aguardar o retorno da integração e consultar os dados enviados posteriormente na rotina de Consulta, basta deixar selecionada a opção 'Não aguardar o retorno da integração'.
Avançando para o passo 3 - Opções, teremos a listagem dos dados que podemos integrar para a Feedz.
É extremamente importante que a ordem de integração seja respeitada conforme consta na rotina, caso contrário, não será possível mais a frente a integração de Funcionários e Líderes.
Inicialmente, podemos selecionar as opções Filiais, Cargos, Departamentos e Grupos de Contrato e Avançar.
No passo 4 - Filtro, devemos obrigatoriamente selecionar pelo menos uma Filial para conseguir avançar.
Por fim, no passo 5 - Processamento, efetue a integração com a Feedz.
Ao finalizar a integração, será gerado o Log de Ocorrências em tela (caso tenha optado por aguardar o retorno), onde é possível consultar quais filtros foram utilizados e se os dados foram integrados corretamente ou não.
Se todos os itens listados anteriormente foram integrados com sucesso, na sequência você pode integrar os Funcionários.
Para isso, retorne na rotina de Integração, no passo 3 - Opções, selecione 'Funcionários', no passo 4 - Filtro, selecione a Filial que o funcionário pertence e a matrícula se necessário (caso não seja uma integração geral da Filial) e conclua a integração. Se o cadastro do Funcionário tiver todos os dados necessários, no Log de Ocorrências será possível verificar a integração concluída com sucesso.
Por fim, temos a opção de integração de Líderes dos Funcionários. A hierarquia é montada/enviada para a Feedz de acordo com o parâmetro MV_ORGCFG.
Caso o cliente utilize o parâmetro como 1 ou 2, no passo 2 - Configuração, será demonstrada a pergunta 'Código da Visão', onde deverá ser selecionado qual cadastro de Visão existente no módulo 70 - Arquitetura Organizacional, será utilizado.
No passo 3 - Opções, selecione 'Líder dos Funcionários', e no passo 4 - Filtro, selecione a Filial e no filtro de Líderes, devem ser selecionados os Funcionários (subordinados) e não os Líderes, pois desta forma, a rotina valida a qual Departamento o Funcionário está vinculado, consulta qual o responsável (líder) daquele Departamento, e faz a amarração entre Líder x Subordinado. Caso seja selecionado o próprio líder, o retorno do log será de que o Funcionário foi desprezado pois não possui líder.
OBS: caso a tabela SQ3 ou SQB sejam totalmente compartilhadas, na rotina de Integração - passo 2 - Configuração, será demonstrada a pergunta 'Descrição Cargo/Departamento' com duas opções:
→ Somente Descrição: será integrada apenas a descrição do cadastro, por exemplo: Analista de RH (Cargo) ou Recursos Humanos (Departamento).
→ Descrição + Código: será integrado o código do Grupo de Empresas + descrição do cadastro, por exemplo: 01 - Analista de RH (Cargo) ou 01 - 00000001 - Recursos Humanos (Departamento). |
| Card |
|---|
| label | 6. Consulta das Integrações |
|---|
| A rotina de Consulta das Integrações (GPEM939B) é extremamente necessária quando:
- o cliente utiliza Schedule para integração diária dos dados entre Protheus x Feedz
- para integrações manuais de registros que ainda estão com status 'Pendente', devido o Schedule ainda não ter sido executado, através da opção 'Consultar Status'
- quando não é esperado o retorno da integração com o Log de Ocorrências em tela.
Para consultar uma integração feita, clique nos três pontinhos - Visualizar. Será aberta uma tela contendo os dados do ID do lote, status, data/hora da integração, qual a API e o arquivo JSON que foi enviado + o retorno da Feedz.
Para lotes com status 'Não Iniciado', você deve selecionar a opção 'Consultar', para que seja atualizado o status do envio, ou se os dados já foram integrados.
Importante: cada lote de integração para a Feedz possui 100 registros, então se por exemplo, você estiver integrando 150 Funcionários, serão gerados dois lotes/dois IDs.
Para solicitar apoio ao time Feedz em casos de falha na integração, é importante ter print da opção Visualizar da consulta do lote OU print do log de ocorrências ao término da integração, pois temos que passar o ID do lote para que eles consigam visualizar o que provocou falha no recebimento dos dados. |
| Card |
|---|
| A utilização de Schedule na integração entre Protheus x Feedz é completamente opcional, ficando a critério do cliente utilizar ou não.
Para utilização, será necessário cadastro do agendamento do job GPEM939D para integração dos dados e do job GPEM939C para atualização do status da integração dos dados | | Card |
|---|
| label | 5. Configurando nossa URL para simular o envio do Protheus para Quirons |
|---|
| Como não temos um ambiente Quirons para receber os dados, vamos utilizar a ferramenta Webhook para simular o Quirons, através do endereço https://webhook.site/#!/view
Ao acessar o Webhook, será gerada uma URL única, e ela será usada nos cadastros do Protheus.
No SIGAGPE, vamos acessar a rotina de Parâmetros que criamos no passo 3, e faremos o preenchimento desta forma:
• URI = nossa URL única gerada no Webhook
• Usuário e Senha = você pode informar seu email e qualquer senha, pois como estamos usando o Webhook, estes dados não serão validados efetivamente.| Card |
|---|
| label | 6. Cadastro do Schedule |
|---|
| A última etapa cadastral, se trata do Schedule da rotina GPEM923, para que os dados enviados através da nossa rotina de Carga Inicial, sejam gravados na tabela RJP, e com isso, o Schedule envie os dados da RJP para o Quirons através do nosso arquivo JSON.
Para cadastrar o Schedule, será necessário acessar o Configurador - Ambiente - Schedule - Schedule.
Devemos inicialmente cadastrar um Agent na opção de mesmo nome, levando em consideração:
• IP = como faremos apenas testes em ambiente interno, podemos informar localhost
• Porta = se trata da nossa porta TCP, contida no arquivo appserver.ini do nosso ambiente
Após o cadastro, nosso Agent deve ficar com status Habilitado para o correto funcionamento.
OBS: cadastre o Agent vinculado ao Grupo de Empresas em que a integração foi toda configurada.
Por fim
Na sequência, vamos cadastrar o Job da rotina GPEM923, que será a responsável pelo envio dos dados da tabela RJP para o Quirons.
• Para isso, vamos na opção Agendamentos e faremos a inclusão com a rotina GPEM923
• Na primeira parte do cadastro, informaremos a recorrência, ou seja, de quanto em quanto tempo queremos que o Job seja executado. Neste exemplo, estamos deixando como Sempre Ativo, ou seja, o Job sempre fará buscas na tabela por qualquer dado novo gravado, para que o envio ao Quirons seja feito em tempo real, porém, o cliente pode definir isso da melhor forma pra ele
• Na segunda parte do cadastro, informaremos os dados do Grupo de Empresa, Filial e Módulo
• Por fim, vamos conferir nosso cadastro para Concluir.
Após o cadastro, o Job aparecerá com status Habilitado.
Caso tenha dificuldade no cadastro de Agent e Job, veja este vídeo: Configuração do Schedule
| | Card |
|---|
| label | 7. Integrando dados do Protheus para o Quirons |
|---|
| Com todos os cadastros necessários, estamos prontos para fazer nossa integração funcionar \õ/
No Protheus, vamos acessar a rotina de Carga Inicial e vamos selecionar os dados que queremos integrar para o Quirons.
Após a confirmação de execução da rotina, ao consultar nossa tabela RJP, teremos o dado gravado corretamente, o que significa que podemos conferir o status do envio através da rotina de Monitor de Integração - GPEM924. Para isso, basta buscar o registro que tentamos integrar e clicar em Visualizar.
No Webhook, assim que o Job do Schedule processar o envio, podemos conferir a estrutura do arquivo JSON com os dados integrados.
Caso tenha dúvidas sobre o processo, veja este vídeo: Integrando Protheus x Quirons
| Card |
|---|
| O Postman é uma ferramenta de mercado, onde conseguimos simular o envio de arquivos XML/JSON na integração via Mensagem Única (EAI), simulando integrações com o Protheus, ou seja, ao invés de termos que instalar o outro sistema e aprender como fazer o processo nele, usamos o Postman para simular os testes e validações necessárias. Link para baixar o Postman: https://www.postman.com/downloads/ Cabe ressaltar que usaremos o Postman apenas nos casos onde precisamos simular o consumo de dados no Quirons, por exemplo, se precisamos consumir os dados de um novo Centro de Custo cadastrado. | Dica |
|---|
| - A API RESTful é uma interface que dois sistemas usam para trocar informações de forma segura pela internet.
- Os Métodos existentes em uma API são como as ações que esta API permite que sejam realizadas através dela:
- DELETE: Método específico para remoção de dados, ou seja, permite deletar dados através da API;
- GET: Método para uma requisição que busca dados, ou seja, ele é usado para consultar dados através da API, não altera informações, apenas as carrega;
- POST: Método para uma requisição que envia dados, ou seja, é usado para inserir informações através da API;
- PUT: Método para atualização de dados, pode ser utilizado quando se deseja atualizar uma informação já existente.
|
|
| Card |
|---|
| | label | 9. Fazendo um GET no Postman para simular o consumo de dados no Quirons |
|---|
| Neste teste, usaremos o Postman para simular o consumo de dados no Quirons, por exemplo: nos casos onde foi cadastrado um novo Centro de Custo no Protheus, o usuário precisa acessar o Quirons, e através dele fazer o consumo deste dado, para que ele também exista no Quirons.
Para isso, usaremos o método GET no Postman e também usaremos esta documentação para sabermos quais parâmetros são chave para que seja feita a requisição dos dados na nossa API.
Simulando o consumo dos dados de um Centro de Custo:
• devemos buscar na documentação os parâmetros que serão usados no nosso GET
• acessar nosso REST, e procurar pela API informada na documentação, neste caso, a de nome payrollcostcenter. Ao localizá-la, clicar na opção For More Details. Aqui, vamos guardar os dados contidos no GET para usarmos na sequência no Postman
• com o Postman aberto, criaremos um novo File e vamos iniciar o preenchimento do nosso GET. Primeiro, vamos informar o endereço do nosso REST + os dados copiados do GET do nosso REST
• agora, vamos preencher os parâmetros conforme nossa documentação, informando manualmente um a um e contendo os dados do código de Filial e Grupo de Empresas. Com isso, poderemos ver que a barrinha do nosso GET ficará com todos estes parâmetros também
• por fim, vamos clicar na opção Body - deixar marcada a opção None e clicar no Send
Protinho, agora conseguimos visualizar o arquivo JSON contendo os dados do Centro de Custo de código 01, de nome Suporte. Seu teste funcionou certinho =D
Se tiver dúvidas, você pode assistir esse vídeo com o processo: Simulação via Postman x Protheusnossos jobs através da opção Agendamentos - Novo.
Faça a inclusão de um novo registro para a rotina GPEM939D, configure a recorrência para no máximo 2x ao dia, depois configure o Grupo de Empresas e Filiais, e por fim, salve o registro.
Faça o cadastro para o job da rotina GPEM939C, lembrando de configurar o horário de execução após o GPEM939D.
OBS: a integração com a Feedz pode não acontecer em tempo real, pois eles trabalham com fila de recebimento de dados. Caso tenham vários clientes integrando dados no mesmo momento, os lotes podem ficar com status 'Não Iniciado' por este motivo, ou seja, eles já entraram na fila, mas ainda não puderam ser processados. Esse processamento pode levar algum tempo, considerando o volume de dados integrados pelo cliente ou lotes que a Feedz esteja recebendo de vários clientes naquele momento, não se tratando de falha ou erro na integração. |
|
