Histórico da Página
ÍNDICE
...
Índice
...
- Parametrização
- Cadastro do Relógio Carol
- Schedule\Menu
- Detalhes do PONAPI01
...
exclude ÍNDICE
01. OBJETIVO
Apresentar ao usuário final, que faça uso da plataforma Carol para marcações de ponto dos colaboradores, como configurar o Protheus para habilitar a integração automática de marcações.
...
Aviso | ||
---|---|---|
| ||
ESTE DOCUMENTO SOMENTE TERÁ UTILIDADE PARA CLIENTES QUE JÁ UTILIZAM A PLATAFORMA CAROL, CASO CONTRÁRIO NÃO SERÁ POSSÍVEL A REALIZAÇÃO DESTA CONFIGURAÇÃO. |
02.
...
FLUXO DO AMBIENTE
03. VISÃO GERAL
A configuração da integração entre a Carol e Protheus se baseia na configuração de um Schedule que será executado em intervalos previamente definidos, acionando as API's da Carol ou a rotina cadastrada em Menu:
...
Informações | ||
---|---|---|
| ||
O CAMPO PISCODE NA PLATAFORMA CAROL É OBRIGATÓRIO PARA A INTEGRAÇÃO CORRETA COM O PROTHEUS, POIS SE TRATA DE UMA INFORMAÇÃO CHAVE PARA O SISTEMA. |
...
04. EXEMPLO DE UTILIZAÇÃO
O cliente utiliza a Carol para as marcações de ponto dentro da empresa, esta empresa possui diversos dispositivos espalhados pela organização.
O Protheus será o responsável por acionar a plataforma Carol, buscar as informações contidas em cada dispositivo e armazenar os registros dentro do módulo SIGAPON. Nos próximos tópicos, os passos serão detalhados:
...
4.1. PARAMETRIZAÇÃO
Para que haja a devida integração entre os dois sistemas, se faz necessário preencher os parâmetros abaixo:
Parâmetro | Descrição do Parâmetro | Tipo | Exemplo de utilização |
---|---|---|---|
MV_APICLO0 | Clock In da Carol - Utiliza integração com Carol Clock in? | Lógico | Exemplo: .T. |
MV_APICLO1 | Clock In da Carol - Endereço de Acesso ao EndPoint | Caractere | |
MV_APICLO2 | Clock In da Carol - Patch de Acesso ao EndPoint. | Caractere | api/v2/oauth2/token |
MV_APICLO3 | Clock In da Carol - ID de Conexão de Acesso. | Caractere | clockinmobile |
MV_APICLO4 | Clock In da Carol - Username de Acesso ao EndPoint. | Caractere | username@totvs.com.br |
MV_APICLO5 | Clock In da Carol - Password de Acesso ao EndPoint. | Caractere | senha1 |
MV_APICLO6 | Clock In da Carol - Domain Name de Acesso EndPoint. | Caractere | domínioCliente |
MV_APICLO7 | Clock In da Carol - Path do EndPoint DeviceList - Clock In Carol. | Caractere | api/v2/queries/named/deviceList |
MV_APICLO8 | Clock In da Carol - Path EndPoint clockinrecordsList - Clock In Carol. | Caractere | api/v2/queries/named/clockinrecordsList |
MV_APICLO9 | Clock In da Carol - Nome da Organização de acesso EndPoint | Caractere | ambiente |
MV_APICLOA | Clock In da Carol - Codigo do API Token (Connector Token) | Caractere | 00a00a0a000007e597b39b8a07qw5f60 |
Informações | ||
---|---|---|
| ||
A criação destes parâmetros estará disponível apenas na 12.1.27 e caso o cliente possua a plataforma Carol e versão inferior a citada e deseja integrar com o módulo SIGAPON no Protheus, deverá criar manualmente os parâmetros. |
Aviso | ||
---|---|---|
| ||
1. Após a criação do parâmetro MV_APICLOA, o sistema sempre irá realizar a primeira tentativa de autenticação utilizando o API Token (MV_APICLOA). Caso o Token esteja inválido, será realizada uma tentativa de autenticação por usuário e senha. O Log de erro de integração só será exibido se ambas as tentativas de autenticação falharem. |
b. Cadastro do Relógio Carol
Para cadastro do relógio, basta acessar no SIGAPON/CADASTRO DO PONTO/RELÓGIOS e preencher os dados da aba geral com atenção especial para os campos:
- Controle (P0_CONTROL) = "P" //Relógio de Ponto
- Tipo Arquivo (P0_TIPOARQ) = "R" //Integração com Carol ou TSA
- Rep (P0_REP) = "" //Se o relógio for da Carol este campo não deve ser preenchido
Informações | ||
---|---|---|
| ||
Somente será permitido deixar o campo Rep em branco se o parâmetro MV_APICLO0 estiver como .T. . |
c. Schedule\Menu
A rotina desenvolvida para a realização de todo o fluxo de requisição para a Carol foi nomeada de PONAPI01, esta rotina não estará disponibilizada em Menu ou pré-carregada no Schedule.
O Processo de Cadastramento será o mesmo utilizado por outras rotinas:
Preenchimento do Schedule:
- Acessar o módulo SIGACFG - Configurador;
- Acessar o caminho do menu AMBIENTE/SCHEDULE/SCHEDULE;
- Clicar na opção Cadastro no calendário de agendamentos, conforme imagem1 da tela no Tópico 04;
- O preenchimento é simples e intuitivo para o preenchimento correto do schedule (leia o item 5 abaixo, antes de confirmar o cadastro);
- Clique o ícone cinza ao lado do botão de confirmar, pois lá se encontra as informações de periodicidade de acionamento da rotina cadastrada (Imagem 2 do Tópico 04);
- Após a confirmação do cadastramento, será necessário habilitar os agents (Imagem 3 do Tópico 04 ), onde você pode cadastrar manualmente ou pressionar o ícone de radar verde no canto superior direito e os agents serão incluídos automaticamente;
- Com os agents devidamente cadastrados, o usuário deve pressionar o ícone de pasta do lado esquerdo e ligar Task Manager e Queue Manager (São os gerenciadores da fila de acionamento dos agents) (Imagem 4 do Tópico 04 ).
Preenchimento do Cadastro da Rotina MENU.
- Acessar o módulo SIGACFG - Configurador;
- Acessar o caminho do menu AMBIENTE/CADASTROS/MENU;
- Selecione o módulo\Menu que deseja realizar a inclusão da rotina, conforme imagem 1 do Tópico 05;
- Quando clicar em "OK" será aberta uma tela semelhante a imagem 2 do Tópico 05 e você deverá pressionar o primeiro botão central "Adicionar>>" e o menu inteiro será transferido para o lado direito da tela;
- Clique na pasta azul que desejar incluir o item da rotina e pressione o botão Novo Item conforme imagem 3 do Tópico 05, desta forma será exibida uma nova tela para inclusão da rotina conforme imagem 4;
- Preencha o nome que deseja que apareça no menu e digite o nome da rotina citada no início deste documento PONAPI01, conforme imagem 4;
- Confirme o cadastro e clique no botão central de Gerar;
- O Sistema exibirá uma mensagem solicitando o nome do xnu que será gerado, sugerimos manter o mesmo nome do xnu padrão ex.
d. Detalhes do PONAPI01
Para eventual manutenção na rotina de leitura dos marcações da Carol, é possível utilizar os parâmetros abaixo afim de realizar alguns filtros específicos. Estes parâmetros não são obrigatórios. Caso não sejam informados, a rotina utilizará a sequência de marcações para realização da importação dos dados. Os parâmetros opcionais são:
...
Parâmetro
...
Observação
...
Obrigatório
...
Tipo
...
Exemplo
...
38b0dc89a20aaf49
...
Obs.: O parâmetro nCodNSR somente deverá ser utilizado quando for necessário realizar buscar uma marcação específica, pois o Protheus já busca todas as marcações atuais.
Aviso | ||
---|---|---|
| ||
Ao configurar a rotina para execução automática (Schedule), os parâmetros (lWork, dInicio, dFinal, cCoDisp e nCodNSR) não deverão ser informados. |
Card documentos | ||||
---|---|---|---|---|
|
04. CONFIGURAÇÃO SSL
Para realizar requisições para a Carol, será necessária a configuração do SSL no Appserver. Atualmente a Carol utiliza a versão SSL 1.3 e por este motivo é necessária a configuração do SSL por parte do Protheus. Segue abaixo um exemplo da configuração:
Para mais informações de como realizar a configuração do SSL no AppServer, no final da desta documentação, em anexos, estará disponível o link do passo a passo de como realizar a configuração.
05. TELA DE CADASTRO DE SCHEDULE
...
Cadastro de Rotina
Preenchimento da periodicidade dos acionamentos:
Interface de Agents.
Gerenciamento da fila e execução dos agents.
06. TELA DE CADASTRO DE MENU
...
Tela de listagem de menus
Tela de configuração do menu escolhido
...
MV_APICLOB | Clock In da Carol - Define se na integração com Carol Clock In será efetuada pesquisa por lacuna na numeração do NSR (.T.) ou se será efetuado pesquisa a partir do último NSR gravado (.F.) | Lógico | Exemplo: .T. |
MV_APICLOC | Define se será gerado o log de integração com a Carol. .T. = Gera o log; .F. = Não gera o log | Lógico | Exemplo: .T. |
MV_APICLOD | Define se a integração utilizará a tabela RR1 ou MSA_CONTROL_MARCAC. .T. = RR1 .F. = MSA | Lógico | Exemplo: .T. |
Informações | ||
---|---|---|
| ||
A criação destes parâmetros estará disponível apenas na 12.1.27 e caso o cliente possua a plataforma Carol e versão inferior a citada e deseja integrar com o módulo SIGAPON no Protheus, deverá criar manualmente os parâmetros. |
Aviso | ||
---|---|---|
| ||
1. Após a criação do parâmetro MV_APICLOA, o sistema sempre irá realizar a primeira tentativa de autenticação utilizando o API Token (MV_APICLOA). Caso o Token esteja inválido, será realizada uma tentativa de autenticação por usuário e senha. O Log de erro de integração só será exibido se ambas as tentativas de autenticação falharem. |
Informações | ||
---|---|---|
| ||
Quando o MV_APICLOB estiver com o conteúdo com .T. o sistema irá verificar na tabela RR1/MSA se há uma lacuna na numeração dos NSR e assim efetuar a leitura a partir desse número. Ao executar a rotina de Leitura e Apontamento (PONM010) o sistema irá realizar a leitura independentemente do NSR, assim uma marcação com NSR inferior será processada normalmente e essa marcação será salva na tabela SP8. |
4.2. CADASTRO DO RELÓGIO CAROL
Aviso | ||
---|---|---|
| ||
A partir da aplicação do pacote de Expedição Contínua RH com data 18/03/2024 ou superior não será mais necessário realizar o compartilhamento da tabela de relógios (SP0) para utilização da leitura e apontamento das marcações do Clock In. Consulte o documento técnico da melhoria para a execução da leitura das marcações dos funcionários: DT Leitura das marcações do Clock In quando o relógio estiver exclusivo |
Para cadastro do relógio, basta acessar no SIGAPON/CADASTRO DO PONTO/RELÓGIOS e preencher os dados da aba geral com atenção especial para os campos:
- Controle (P0_CONTROL) = "P" //Relógio de Ponto
- Tipo Arquivo (P0_TIPOARQ) = "R" //Integração com Carol ou TSA
- Rep (P0_REP) = "" //Se o relógio for da Carol este campo não deve ser preenchido
- Com a portaria 671 é necessário informar o tipo do REP (1510, REP-A, REP-C e REP-P). Para um relógio do Clock In teremos apenas duas opções, 1510 e REP-A, em ambos os tipos os sistema irá identificar o funcionário pelo PIS ou CPF da marcação por ser um relógio do Clock In, por este motivo qualquer uma das opções são válidas no cadastro do relógio, porém é necessário verificar qual o tipo do REP do Clock In e preencher corretamente o cadastro do relógio.
Informações | ||
---|---|---|
| ||
Somente será permitido deixar o campo Rep em branco se o parâmetro MV_APICLO0 estiver como .T. . |
4.3. SCHEDULE\MENU
A rotina desenvolvida para a realização de todo o fluxo de requisição para a Carol foi nomeada de PONAPI01, esta rotina não estará disponibilizada em Menu ou pré-carregada no Schedule.
O Processo de Cadastramento será o mesmo utilizado por outras rotinas:
4.3.1. PREENCHIMENTO DO SCHEDULE
- Acessar o módulo SIGACFG - Configurador;
- Acessar o caminho do menu AMBIENTE/SCHEDULE/SCHEDULE;
- Clicar na opção Cadastro no calendário de agendamentos, conforme imagem1 da tela no Tópico 06;
- O preenchimento é simples e intuitivo para o preenchimento correto do schedule (leia o item 5 abaixo, antes de confirmar o cadastro);
- Clique o ícone cinza ao lado do botão de confirmar, pois lá se encontra as informações de periodicidade de acionamento da rotina cadastrada (Imagem 2 do Tópico 06);
- Após a confirmação do cadastramento, será necessário habilitar os agents (Imagem 3 do Tópico 06 ), onde você pode cadastrar manualmente ou pressionar o ícone de radar verde no canto superior direito e os agents serão incluídos automaticamente;
- Com os agents devidamente cadastrados, o usuário deve pressionar o ícone de pasta do lado esquerdo e ligar Task Manager e Queue Manager (São os gerenciadores da fila de acionamento dos agents) (Imagem 4 do Tópico 06 ).
4.3.2. PREENCHIMENTO DO CADASTRO DA ROTINA NO MENU
- Acessar o módulo SIGACFG - Configurador;
- Acessar o caminho do menu AMBIENTE/CADASTROS/MENU;
- Selecione o módulo\Menu que deseja realizar a inclusão da rotina, conforme imagem 1 do Tópico 06;
- Quando clicar em "OK" será aberta uma tela semelhante a imagem 2 do Tópico 06 e você deverá pressionar o primeiro botão central "Adicionar>>" e o menu inteiro será transferido para o lado direito da tela;
- Clique na pasta azul que desejar incluir o item da rotina e pressione o botão Novo Item conforme imagem 3 do Tópico 06, desta forma será exibida uma nova tela para inclusão da rotina conforme imagem 4;
- Preencha o nome que deseja que apareça no menu e digite o nome da rotina citada no início deste documento PONAPI01, conforme imagem 4;
- Confirme o cadastro e clique no botão central de Gerar;
- O Sistema exibirá uma mensagem solicitando o nome do xnu que será gerado, sugerimos manter o mesmo nome do xnu padrão ex.
Dica | ||
---|---|---|
| ||
Devido ao tamanho da string trafegada entre os sistemas, pode haver estouro de string caso os parâmetros citados a seguir não estejam configurados no appserver.ini, pare o Server e coloque a propriedade TOPMemoMega=1 ("Veja Mais sobre TopMemoMega) e a propriedade MaxStringSize ( Veja Mais Sobre MaxStringSize e o valor que deve colocar no parâmetro) |
05. PORTARIA 671
Para atender a portaria 671/2021 para a integração de marcações do Clock In será necessário a criação de novos campos nas tabelas MSA_CONTROL_MARCAC, RR1, SP8, SPG, RFE e RFH. Os novos campos irão armazenar o CPF e a convenção coletiva da marcação.
Informações | ||
---|---|---|
| ||
Para a atualização dos campos será necessário aplicar o pacote de fontes e a execução do UPDDISTR do pacote de dicionário da Expedição Contínua RH liberado a partir de 06/03/2023. |
Aviso | ||
---|---|---|
| ||
Para que o Protheus consiga realizar a gravação do CPF e convenção coletiva da marcação nas tabelas RFE, RFH, SP8, SPG e RR1 será necessário a execução do UPDDISTR. |
Após a execução do UPPDISTR os seguintes campos serão criados:
SP8
X3_CAMPO | X3_TIPO | X3_TAMANHO | X3_TITULO | X3_DESCRIC |
---|---|---|---|---|
P8_CCTREP | C | 17 | Código CCT | Código da CCT da marcação |
SPG
X3_CAMPO | X3_TIPO | X3_TAMANHO | X3_TITULO | X3_DESCRIC |
---|---|---|---|---|
PG_CCTREP | C | 17 | Código CCT | Código da CCT da marcação |
RFE
X3_CAMPO | X3_TIPO | X3_TAMANHO | X3_TITULO | X3_DESCRIC |
---|---|---|---|---|
RFE_CCTREP | C | 17 | Código CCT | Código da CCT da marcação |
RFH
X3_CAMPO | X3_TIPO | X3_TAMANHO | X3_TITULO | X3_DESCRIC |
---|---|---|---|---|
RFH_CCTREP | C | 17 | Código CCT | Código da CCT da marcação |
RFH_CPF | C | 12 | CPF | CPF do Funcionário |
RR1
X3_CAMPO | X3_TIPO | X3_TAMANHO | X3_TITULO | X3_DESCRIC |
---|---|---|---|---|
RR1_CCTREP | C | 17 | Código CCT | Código da CCT da marcação |
Para os clientes que utilizam a integração com o Clock e armazenam as marcações na tabela MSA_CONTROL_MARCAC, será necessário realizar a compilação do pacote de fontes, com o fonte atualizado a próxima execução da integração criará automaticamente o novo campo na tabela MSA_CONTROL_MARCAC.
MSA_CONTROL_MARCAC
Coluna | Tipo | Tamanho |
---|---|---|
COD_CCT | Varchar | 17 |
06. CONFIGURAÇÃO SSL
Para realizar requisições para a Carol, será necessária a configuração do SSL no Appserver. Atualmente a Carol utiliza a versão SSL 1.3 e por este motivo é necessária a configuração do SSL por parte do Protheus. Segue abaixo um exemplo da configuração:
Para mais informações de como realizar a configuração do SSL no AppServer, no final da desta documentação, em anexos, estará disponível o link do passo a passo de como realizar a configuração.
Âncora | ||||
---|---|---|---|---|
|
07. TELA DE CADASTRO DE SCHEDULE
Cadastro de Rotina
Preenchimento da periodicidade dos acionamentos:
Interface de Agents.
Gerenciamento da fila e execução dos agents.
08. TELA DE CADASTRO DE MENU
Tela de listagem de menus
Tela de configuração do menu escolhido
09. CONVERSÃO DE HORAS
O horário da marcação do Clock In é integrada em segundos ou seja, se o funcionário realizou uma marcação às 02:00 teremos salvo na tabela de integração a quantidade total de segundos de 7200. Para achar o horário da marcação em horas e minutos é utilizado a fórmula abaixo dos exemplos:
Exemplos de conversão:
1º Exemplo - Total de segundos da marcação 43239
Total de segundos divido por 3600 para achar a quantidade de horas
43239/ 3600 = 12,01083333333333 → 12 horas
Resto da divisão multiplicado por 60 e o resultado tem o arredondamento aplicado para retirar as casas decimais para encontrar a quantidade de minutos
0,01083333333333 * 60 = 0,65 (arredondando teremos 1) → 1 minuto
Hora da marcação: 12:01
2º Exemplo - Total de segundos da marcação 65710
Total de segundos divido por 3600 para achar a quantidade de horas
65710/ 3600 = 18,25277778 → 18 horas
Resto da divisão multiplicado por 60 e o resultado tem o arredondamento aplicado para retirar as casas decimais para encontrar a quantidade de minutos
0,25277778 * 60 = 15,16666666666667 (arredondando teremos 15) → 15 minutos
Hora da marcação: 18:15
10. MENSAGENS DE INTEGRAÇÃO
Para possibilitar o acompanhamento da integração do Protheus com a Carol, será apresentado algumas mensagens em tela caso o acionamento seja manual pelo menu ou no console.log, quando a rotina for acionada via Schedule.
- Caso o código NSR enviado por parâmetro e o mesmo seja abaixo de zero:
- Verifique o Código NSR Informado, pois o mesmo somente aceita números positivos!
- Inconsistências nas datas:
- Verifique as Datas informadas para acesso ao Clock In da Carol.
- Será apresentada a seguinte mensagem e a mensagem retornada da plataforma Carol.
- Não foi possível acessar a API Clockin da Carol.
- Problemas com o preenchimento dos parâmetros:
- Verifique o parâmetro MV_APICLO1 pois ele é responsável pelo cadastro da URL de EndPoint para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO2 pois ele é responsável pelo cadastro do path da API Token para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO3 pois ele é responsável pelo cadastro do Id Conector para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO4 pois ele é responsável pelo cadastro do User Name para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO5 pois ele é responsável pelo cadastro do Password para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO6 pois ele é responsável pelo cadastro do Domain Name para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO7 pois ele é responsável pelo cadastro do path da API DeviceList para a integração de Clock In da Carol.
- Verifique o parâmetro MV_APICLO8 pois ele é responsável pelo cadastro do path da API clockinrecordsList para a integração de Clock In da Carol.
- Não foi possível acessar a API Clock In da Carol. Verifique os parametros MV_APICLO0, MV_APICLO1, MV_APICLO2, MV_APICLO3, MV_APICLO4, MV_APICLO5, MV_APICLO6,MV_APICLO7, MV_APICLO8 com as informações fornecidas.
- Não foi possível acessar a API Clock In da Carol. Verifique os parametros MV_APICLO0, MV_APICLO1, MV_APICLO2, MV_APICLO3, MV_APICLO4, MV_APICLO5, MV_APICLO6,MV_APICLO7, MV_APICLO8, MV_APICLO9 com as informações fornecidas.
- Não foi possível acessar a API Clock In da Carol. Verifique o parametro MV_APICLO8 pois ele é responsável pelo cadastro do path da api clockinrecordsList para a integração de Clockin da Carol.
- O parâmetro MV_APICLO9 está vazio ou não foi criado e a Carol possui uma organização configurada. Por favor crie e preencha o MV_APICLO9 com o Nome da Organização.
08. TABELAS UTILIZADAS
- , MV_APICLO6,MV_APICLO7, MV_APICLO8, MV_APICLO9 com as informações fornecidas.
- Não foi possível acessar a API Clock In da Carol. Verifique o parametro MV_APICLO8 pois ele é responsável pelo cadastro do path da api clockinrecordsList para a integração de Clockin da Carol.
- O parâmetro MV_APICLO9 está vazio ou não foi criado e a Carol possui uma organização configurada. Por favor crie e preencha o MV_APICLO9 com o Nome da Organização.
11. TABELAS UTILIZADAS
- SP0 - Pré-Leitura\Relógio de Ponto;
- RFE - Relógio de Ponto;
- SP8 - Movimento de Marcações;
- MSA_CONTROL_MARCAC - Tabela criada na primeira carga de dados com a Carol para armazenar as marcações integradas, caso o dicionário de dados não possua a RR1. Esta tabela também é utilizada no modelo de integração com o TSA e Suricato, a partir deste momento, será processado pelo sistema onde serão gerados os registros na RFE e SP8.
- RR1 - Nova tabela padrão criada para controle total pelo Protheus para o armazenamento das marcações integradas, esta tabela substitui a MSA_CONTROL_MARCAC. Quando identificado que o cliente possui a tabela MSA, é feito uma cópia de dados da MSA para a RR1 e excluída a tabela antiga MSA. A
- SP0 - Pré-Leitura\Relógio de Ponto;
- RFE - Relógio de Ponto;
- SP8 - Movimento de Marcações;
- MSA_CONTROL_MARCAC - Tabela criada na primeira carga de dados com a Carol, esta tabela também é utilizada no modelo de integração com o TSA e, a partir deste momento, será processado pelo sistema onde será gerado serão gerados os registros na RFE e SP8.
...
12. ROTINAS ENVOLVIDAS
- GPEA010: Cadastro de Funcionários;
- PONA030: Cadastro de Relógios;
- PONM010: Leitura e Apontamento.
...
13.
...
ANEXOS
- DRHGCH-13658 Alterar rotina PONA030 - Relógio (Detalhes para funcionamento na rotina PONA030)
- DRHGCH-13255 - Integração Ponto X Carol - Batidas - API de acesso ao Token (Detalhes sobre o funcionamento na rotina PONAPI01)
- DRHGCH-13652 Integração Ponto X Carol - Batidas - API de acesso ao DeviceList
- Seção [SSLConfigure]
...