Árvore de páginas

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

ÍNDICE

...

Índice

...

  1. Parametrização
  2. Cadastro do Relógio Carol
  3. Schedule\Menu
  4. 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
titleIMPORTANTE

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

Image Added

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
titleInformação Importante

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.

...

04EXEMPLO 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 . Nos próximos tópicos detalharemos melhor , os passos a seguir.

...

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âmetroDescrição do ParâmetroTipoExemplo de utilização
MV_APICLO0Clock in In da Carol - Utiliza integração com Carol Clock in?LógicoExemplo: .T.
MV_APICLO1CLockin Clock In da Carol - Endereço de Acesso ao EndPointCaractere

https://domínioCliente.carol.ai

MV_APICLO2Clockin Clock In da Carol - Patch de Acesso ao EndPoint.Caractereapi/v2/oauth2/token
MV_APICLO3Clockin Clock In da Carol - ID de Conexão de Acesso.Caractereclockinmobile
MV_APICLO4Clockin Clock In da Carol - Username de Acesso ao EndPoint.Caractereusername@totvs.com.br
MV_APICLO5Clockin Clock In da Carol - Password de Acesso ao EndPoint.Caracteresenha1
MV_APICLO6Clockin Clock In da Carol - Domain Name de Acesso EndPoint.CaracteredomínioCliente
MV_APICLO7Clock In da Carol - Path do EndPoint DeviceList -ClockIn Carol.Caractereapi/v2/queries/named/deviceList
MV_APICLO8Clock In da Carol - Path EndPoint clockinrecordsList - Clockin Carol.Caractereapi/v2/queries/named/clockinrecordsList
MV_APICLO9Clock In da Carol - Nome da Organização de acesso EndPoint  Caractereambiente
MV_APICLOAClock In da Carol - Codigo do API Token (Connector Token) Caractere00a00a0a000007e597b39b8a07qw5f60
MV_APICLOBClock 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ógicoExemplo: .T.
MV_APICLOCDefine se será gerado o log de integração com a
Carol. .T. = Gera o log; .F. = Não gera o log
LógicoExemplo: .T.
MV_APICLODDefine se a integração utilizará a tabela RR1 ou 
MSA_CONTROL_MARCAC. .T. = RR1 .F. = MSA
LógicoExemplo: .T.
Informações
titleInformativo

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
titleImportante

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.
2. Se o API Token estiver inválido e o usuário e senha estiverem corretos, o Protheus irá gerar uma nova API Token e irá armazenar seu conteúdo no parâmetro MV_APICLOA. Com isso o Protheus irá atualizar o API Token para um Token válido e utilizará ele para as integrações futuras. 

...

Informações
titleMV_APICLOB

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
titleImportante

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:

  1. Controle (P0_CONTROL) = "P"  //Relógio de Ponto
  2. Tipo Arquivo (P0_TIPOARQ) = "R" //Integração com Carol ou TSA
  3. Rep (P0_REP) = "" //Se o relógio for da Carol este campo não deve ser preenchido
  4. 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.

Image AddedImage Removed

Informações
titleInformativo

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

  1. Acessar o módulo SIGACFG - Configurador;
  2. Acessar o caminho do menu AMBIENTE/SCHEDULE/SCHEDULE;
  3. Clicar na opção Cadastro no calendário de agendamentos, conforme imagem1 da tela no Tópico 04.06;
  4. O preenchimento é simples e intuitivo para o preenchimento correto do schedule (leia o item 5 abaixo, antes de confirmar o cadastro);
  5. 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 0406).;
  6. Após a confirmação do cadastramento, será necessário habilitar os agents (Imagem 3 do Tópico 0406 ), onde você pode cadastrar manualmente ou pressionar o ícone de radar verde no canto superior direito e os agents serão incluídos automaticamente.;
  7. 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 0406 ).

...

Image Added

4.3.2. PREENCHIMENTO DO CADASTRO DA ROTINA NO MENU

  1. Acessar o módulo SIGACFG - Configurador.;
  2. Acessar o caminho do menu AMBIENTE/CADASTROS/MENU.;
  3. Selecione o módulo\Menu que deseja realizar a inclusão da rotina, conforme imagem 1 do Tópico 05.06;
  4. Quando clicar em "OK" será aberta uma tela semelhante a imagem 2 do Tópico 0506 e você deverá pressionar o primeiro botão central "Adicionar>>" e o menu inteiro será transferido para o lado direito da tela.;
  5. Clique na pasta azul que desejar incluir o item da rotina e pressione o botão Novo Item conforme imagem 3 do Tópico 0506, desta forma será exibida uma nova tela para inclusão da rotina conforme imagem 4.;
  6. Preencha o nome que deseja que apareça no menu e digite o nome da rotina citada no inicio início deste documento PONAPI01, conforme imagem 4.;
  7. Confirme o cadastro e clique no botão central de Gerar.;
  8. 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 

Desenvolvido o processo conforme estudo realizado. Este processo buscará todas as marcações de todos os períodos de todos os dispositivos conforme os parâmetros existentes, sendo eles:

...

Parâmetro

...

Observação

...

Obrigatório

...

Tipo

...

Exemplo

...

38b0dc89a20aaf49

...

  1. .


Dica
titleImportante

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
titleAtenção

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
titleImportante

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_CAMPOX3_TIPOX3_TAMANHOX3_TITULOX3_DESCRIC
P8_CCTREPC17Código CCTCódigo da CCT da marcação

SPG

X3_CAMPOX3_TIPOX3_TAMANHOX3_TITULOX3_DESCRIC
PG_CCTREPC17Código CCTCódigo da CCT da marcação

RFE

X3_CAMPOX3_TIPOX3_TAMANHOX3_TITULOX3_DESCRIC
RFE_CCTREPC17Código CCTCódigo da CCT da marcação

RFH

X3_CAMPOX3_TIPOX3_TAMANHOX3_TITULOX3_DESCRIC
RFH_CCTREPC17Código CCTCódigo da CCT da marcação
RFH_CPFC12CPFCPF do Funcionário

RR1

X3_CAMPOX3_TIPOX3_TAMANHOX3_TITULOX3_DESCRIC
RR1_CCTREPC17Código CCTCó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

ColunaTipoTamanho
COD_CCTVarchar17

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:

Image Added

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
Schedule
Schedule

07. TELA DE CADASTRO DE SCHEDULE  

Obs.: O parâmetro nCodNSR somente deverá ser utilizado quando for necessário realizar buscar uma marcação especifica, pois o Protheus já busca todas as marcações atuais.

Aviso
titleIMPORTANTE

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
InformacaoDevido 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 <b>TOPMemoMega=1</b> (<a href=https://tdn.totvs.com/display/tec/TOPMemoMega>"Veja Mais sobre TopMemoMega</a>) e a propriedade <b>MaxStringSize</b> ( <a href=https://tdn.totvs.com/pages/viewpage.action?pageId=161349793>Veja Mais Sobre MaxStringSize e o valor que deve colocar no parâmetro</a>)
TituloIMPORTANTE!

04. TELA DE CADASTRO DE SCHEDULE  

...

Cadastro de Rotina

Imagem 1

Preenchimento da periodicidade dos acionamentos:

...

Gerenciamento da fila e execução dos agents.

Imagem 4

...

08.

...

TELA DE CADASTRO DE MENU

...

Tela de listagem de menus.

Imagem 1

Tela de configuração do menu escolhido.

imagem 3

Imagem 4

...

09. 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 Clockin Clock In da Carol.
  • Será apresentado 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 Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO2 pois ele é responsável pelo cadastro do path da api API Token para a integração de Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO3 pois ele é responsável pelo cadastro do Id Conector para a integração de Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO4 pois ele é responsável pelo cadastro do User Name para a integração de Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO5 pois ele é responsável pelo cadastro do Password para a integração de Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO6 pois ele é responsável pelo cadastro do Domain Name para a integração de Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO7 pois ele é responsável pelo cadastro do path da api API DeviceList para a integração de Clockin Clock In da Carol.
    • Verifique o parâmetro MV_APICLO8 pois ele é responsável pelo cadastro do path da api API clockinrecordsList para a integração de Clockin Clock In da Carol.
    • Não foi possível acessar a API Clockin 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 Clockin 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.

...

10.

...

TABELAS UTILIZADAS 

  • SP0 -  Pré  Pré-Leitura\Relógio de Ponto  Ponto;  
  • RFE -  Relógio   Relógio de Ponto  ;  
  • SP8 - Movimento  Movimento de Marcações  ;  
  • MSA_CONTROL_MARCAC - Tabela criada na primeira carga de dados com a Carol , esta 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  TSA e Suricato, a partir deste momento, será processado pelo sistema onde será gerado os registros na SP8.

08. Rotinas Envolvidas

  • 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 partir deste momento, será processado pelo sistema onde serão gerados os registros na RFE e SP8.

11. ROTINAS ENVOLVIDAS

  • GPEA010: Cadastro de Funcionários;GPEA010 : Cadastro de Funcionários
  • PONA030: Cadastro de Relógios;
  • PONM010: Leitura e Apontamento.

...

12.

...

ANEXOS

  1. DRHGCH-13658 Alterar rotina PONA030 - Relógio (Detalhes para funcionamento na rotina PONA030)
    1. https://tdn.totvs.com/x/kum2Hg
  2. DRHGCH-13255 - Integração Ponto X Carol - Batidas - Api API de acesso ao Token (Detalhes sobre o funcionamento na rotina PONAPI01)
    1. https://tdn.totvs.com/x/34W2Hg
  3. DRHGCH-13652 Integração Ponto X Carol - Batidas - Api API de acesso ao DeviceList
    1. https://tdn.totvs.com/x/frC2Hg
  4. Seção [SSLConfigure]
    1. https://tdn.totvs.com/x/4Ypc
HTML
<!-- esconder o menu --> 


<style>
div.theme-default .ia-splitter #main {
    margin-left: 0px;
}
.ia-fixed-sidebar, .ia-splitter-left {
    display: none;
}
#main {
    padding-left: 10px;
    padding-right: 10px;
    overflow-x: hidden;
}

.aui-header-primary .aui-nav,  .aui-page-panel {
    margin-left: 0px !important;
}
.aui-header-primary .aui-nav {
    margin-left: 0px !important;
}
</style>

...