Exibir origem

ÍNDICE

Objetivo
Visão Geral
Exemplo de Utilização
1. Parametrização
2. Cadastro do Relógio Carol
3. Schedule\Menu
4. Detalhes do PONAPI01
Configuração SSL
Tela de Cadastro de Schedule
Tela de Cadastro de Menu
Mensagens de Integração
Tabelas utilizadas
Rotinas envolvidas
Anexos

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.

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. 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:

https://domínioCliente.carol.ai/api/v2/oauth2/token (API de Autenticação e geradora de Token, onde será realizado os demais acessos\requisições)
https://domínioCliente.carol.ai/api/v2/queries/named/deviceList (API de Requisição de listagem de dispositivos de ponto cadastrados na Carol)
https://domínioCliente.carol.ai/api/v2/queries/named/clockinrecordsList (Api de requisição de listagem de marcações por dispositivos na Carol)

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.

03. 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:

a. 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	https://domínioCliente.carol.ai
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	Path do EndPoint DeviceList - Clock In Carol.	Caractere	api/v2/queries/named/deviceList
MV_APICLO8	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

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.

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

Linha Microsiga Protheus > Integração Protheus x Carol - Importação de Batidas > relogio.png

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 ).

Linha Microsiga Protheus > Integração Protheus x Carol - Importação de Batidas > image2020-1-22_19-28-8.png

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
lWork	Informa se a rotina está sendo executada via processo em segundo plano.	Não	Lógico	.F.
dInicio	Data de inicio para buscar as marcações de ponto	Não	Data	STOD("20000101")
dFinal	Data Final para buscar as marcações de ponto	Não	Data	dDatabase
cCoDisp	Código específico do dispositivo para buscar as marcações.	Não	String	38b0dc89a20aaf49
nCodNSR	Código do NSR a ser utilizado para buscar as marcações.	Não	Inteiro	00

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.

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.

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 SSL2 e por este motivo é necessária a configuração do SSL por parte do Protheus. Segue abaixo um exemplo da configuração:

Linha Microsiga Protheus > Integração Protheus x Carol - Importação de Batidas > image2020-7-22_18-12-25.png

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:

Imagem 2

Interface de Agents.

Linha Microsiga Protheus > Integração Protheus x Carol - Importação de Batidas > image2019-9-20_11-57-59.png

Gerenciamento da fila e execução dos agents.

Imagem 4

06. TELA DE CADASTRO DE MENU

Tela de listagem de menus

Imagem 1

Tela de configuração do menu escolhido

Linha Microsiga Protheus > Integração Protheus x Carol - Importação de Batidas > image2019-9-20_12-38-54.png

imagem 3

Imagem 4

07. 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

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 os registros na SP8.

09. Rotinas Envolvidas

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

10. Anexos

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

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