Integração Protheus x Suricato

ÍNDICE

01. VISÃO GERAL

Este documento de referência tem como objetivo explicar o funcionamento da integração do Protheus com o Suricato, desde a configuração dos parâmetros necessários e os WebServices envolvidos na integração, basicamente eles são os mesmos utilizado pelo TSA.

02. PARÂMETROS

Antes da configuração dos parâmetros, será necessário já possuir o Suricato instalado e configurado, pois existe um parâmetro que deve ser preenchido com o endereço do servidor onde se encontra o Suricato. Informações sobre o Suricato podem ser obtidas através de contato com a parceira mantenedora do produto, através de abertura de ticket.

Atenção:

03. PORTARIA 671

Com a portaria 671/2021 surgiu a necessidade de realizar 2 alterações no Protheus, para que o sistema consiga realizar corretamente a integração de marcações vindas do Suricato.

A primeira alteração foi a estrutura da tabela que armazena as marcações (RR1 ou MSA_CONTROL_MARCAC).
A segunda alteração foi a API recordClockMarkings, ela foi atualizada para receber os novos campos da Portaria 671/2021.

03.1 CAMPOS DA TABELA RR1/MSA_CONTROL_MARCAC

RR1

Caso a tabela responsável por armazenar as marcações seja a RR1 será necessário a execução do UPPDISTR para a atulização da tabela, para isso baixe o último pacote da Expedição Contínua do RH.

Após a execução do UPPDISTR os seguintes campos serão criados na tabela RR1:

MSA_CONTROL_MARCAC

Se a tabela utilizada for a MSA_CONTROL_MARCAC, além da execução do UPPDISTR será necessário a compilação do pacote de fontes da última Expedição Contínua. Após a execução do pacote de dicionários será criada a pergunta "Atualiza Tabela MSA"? na rotina de Carga Inicial (PONM430). Esta pergunta será responsável para dizer se o sistema deve ou não atualizar a MSA_CONTROL_MARCAC com os novos campos. A pergunta terá apenas 2 respostas 1 - Sim e 2 - Não, caso seja preenchida com 1 - Sim, o sistema irá criar o novos campos da MSA_CONTROL MARCAC, caso ela esteja preenchida com não, o sistema não irá atualizar a tabela.

Com a pergunta preenchida com Sim as demais perguntas podem ficar em branco, o sistema irá desconsiderar as demais perguntas e a execução da rotina será exclusivamente para a criação dos novos campos na MSA_CONTROL_MARCAC. 

Caso a tabela MSA_CONTROL_MARCAC já exista no banco de dados, ao executar a rotina de Carga Inicial (PONM430) preenchendo apenas a pergunta "Atualiza Tabela MSA"? com sim será realizada a criação dos novos campos.

Caso a tabela MSA_CONTROL_MARCAC não exista no banco de dados, ao executar a rotina de Carga Inicial (PONM430), preenchendo apenas a pergunta "Atualiza Tabela MSA"? com sim será realizada a criação da tabela com os novos campos.

Após a execução da rotina, os novos campos serão criados.

03.2 ALTERAÇÃO DA API RECORDCLOCKMARKINGS

A API recordClockMarkings, foi alterada para receber, validar e salvar os dados nos novos campos da RR1. Se as marcações a serem integradas forem referentes a Portaria 671, antes de consumir a API será necessário validar se os novos campos, mencionados anteriormente, já foram criados no Protheus. Para isso foi criada uma nova API que irá dizer para o Suricato se o Protheus já possui os novos campos e se poderá ser utilizado os mesmo na API RecordclockMarkings.

RECORDVALIDATEDVERSION
A API RecordValidatedVersion irá verificar no sistema se os novos campos foram criados, respeitando o conteúdo do parâmetro MV_APISUR. Se o parâmetro MV_APISUR estiver configurado com .T. (integração via API) o sistema irá verificar a tabela RR1, nos casos onde o parâmetro estiver com .F. será verificada a tabela MSA_CONTROL_MARCAC

Para mais informações sobre a API, acesse o link abaixo:
DT API recordValidatedVersion.

Após validar se o sistema possui os novos campos, bastar utilizar a API RecordclockMarkings, informando os novos campos como o exemplo abaixo:

{
    "items": [
                {
                    "codRelogioExtChave": "",
                    "codFuncMsa": "003651",
                    "codNsr": 1,
                    "codPisMsa": "022036983234",
                    "datMarcacAces": "2022-11-01 09:00:00.000",
                    "numHorarMarcacAces": 32400,
                    "codRep": "00000000000000123",
                    "codUnidExtChave": "T1D MG 01",
                    "codUsuarExtChave": "T1D MG 01 003651",
                    "codFuso": "-0300",
                    "codCPF": "16046091098",
                    "numVersLayout": 3,
                    "inscrEmp": "11456156000111",
					"codCCT": "00000000123212111"
                }
        ]
}

04. CADASTRO DO RELÓGIO

Para efetuar a leitura de marcações a partir do Suricato, deve-se alterar o cadastro do relógio e informar o conteúdo “R” no campo Tipo Arquivo (P0_TIPOARQ). Ao iniciar o processo de leitura de marcações, a rotina irá buscar os registros da tabela MSA_CONTROL_MARCAC de determinada data de/até que contém o campo LOG_IMPORT_PRODUT = 0.

Atenção: A leitura de marcações somente irá funcionar se a tabela MSA_CONTROL_MARCAC estiver cadastrada no mesmo banco de dados do Protheus.

Exemplo de configuração dos campos no Cadastro de Relógios para integração de marcações no Suricato:

05. CONFIGURAÇÃO DO SCHEDULE

Após o cadastro do relógio, é possível realizar a configuração do Schedule para que a rotina de Leitura e Apontamento seja executada de tempos em tempos. Desta maneira todas as marcações que foram integradas serão processadas pelo Protheus. O processo também pode ser realizado de forma manual, para isso acesse a rotina de Leitura Apontamento em SIGAPON → Miscelanea → Cálculos → Leitura/Apontamento Marcações, preencha os parâmetros informando o código do relógio cadastrado anteriormente e execute a rotina.

Para a configuração do Schedule, será necessário acessar o Configurador (SIGACFG). Após acessar o configurador acesse Ambiente → Schedule → Schedule.

Na tela seguinte inicialmente será necessário cadastrar um Agent. O Agent é responsável por gerenciar e distribuir as tarefas a serem executadas. 

Clicando no primeiro ícone à direita, o sistema irá criar um Agent para cada grupo de empresas automaticamente.

Após a criação do Agent, precisaremos criar um Execute, que são os componentes responsáveis por realizar a chamada das rotinas agendadas.

Preencha a rotina com PONM010 (Leitura e Apontamento), e posteriormente preencha os parâmetros informando o código do relógio cadastrado anteriormente. 

Iremos agora selecionar a periodicidade em que a rotina será executada, as imagens abaixo são um exemplo de um cadastro que será executado 24 vezes por dia, a cada 1 hora, todos os dias da semana, começando no dia 05/10/2020 e sem data de término.

Confirme e salve o agendamento. O próximo passo é colocar todos os serviços cadastrados para serem executado. Para isso clique em Schedule e clique em "Iniciar todos os serviços", depois em Agent "Iniciar todos os serviços".

Após todo este processo de cadastro o Schedule já está sendo executado. É possível acompanhar o resultado da execução clicando em Agendamentos e depois em monitor.

Para mais informações sobre o Cadastro do Schedule, acesse o link da documentação que está no final desta página. Na seção Links.

06. INTEGRAÇÕES REALIZADAS ENTRE OS PRODUTOS

07. TABELAS E ROTINAS ENVOLVIDAS NA INTEGRAÇÃO

07.1 CAMPOS DA TABELA UTILIZADA

08. PRINCIPAIS FONTES E WEB SERVICES

09. RELACIONAMENTO ROTINAS X WEB SERVICES

Seguem abaixo os nomes das rotinas e seus serviços relacionados:

10. MONTAGEM DO CONTEÚDO DO XML

Neste tópico iremos abordar como é feita a montagem do conteúdo do XML, na qual será enviado para o Web Service. Lembrando que caso haja a necessidade de pegar o XML completo, com as informações do Cabeçalho e etc, será necessário ativar o parâmetro MV_TSATLOG com o valor 5 e verificar o arquivo gerado na pasta System, conforme descrito anteriormente no tópico de Parâmetros. Neste exemplo iremos realizar a integração do a partir da rotina de Carga Inicial (Integração TSA - PONM430), integrando o Centro de Custo.

1. Ao acessar a rotina de integração, quando selecionamos apenas o Centro de Custo, podemos observar que o valor da opção é 06.
   
   
   
2. Sabendo disso, podemos localizar qual função que irá realizar essa integração, no caso é função ProcP08 no fonte da Carga Inicial (PONM430)
   
   
   
3. Verificando a função ProcP08, ela está chamando outra função, que neste caso é a WSRHCostCenter.
   
   
   
4. Vamos então procurar onde a função WSRHCostCenter está, descobrimos que ela está localizada no fonte PONXFUN1.
   
   
   Nela podemos verificar que ela faz a busca das informações dos Centro de Custos diretamente na tabela.
   
   
   Após realizar a consulta na tabela CTT, o sistema irá enviar essas informações para o método WSCostCenter.
   
   
   
5. O método WSCostCenter, está localizado no fonte PTSREPOBJ.
   
   
   Antes de enviar as informações para o Web Service, podemos verificar que o sistema está montando as informações do Centro de Custo, como a Descrição e a Chave Externa.
   
   
   Observação: O método do Web Service chamado, foi o insertOrUpdate.
   
   
6. O método insertOrUpdate localizado no Web Service WebWSClient_WSRHTSACostCenter, está realizando a integração com o Suricato. 
   
   
   
7. Antes de enviar as informações da integração, conseguiremos verificar o conteúdo do XML, no caso as informações do Centro de Custo, verificando o conteúdo do objeto oWSarg0.
   
   
   

Após todo esse processo, conseguimos verificar de fato quais informações estão sendo integradas com o Suricato. Este mesmo processo pode ser realizado com as demais integrações, como por exemplo as integração de Funcionários, Funções, Turnos e etc. Para isso só será necessário identificar qual é a opção selecionada e posteriormente a função desta opção. Em outros casos, como por exemplo, a integração de funcionário realizadas após a inclusão ou alteração do mesmo, precisaremos localizar no fonte de Cadastro de Funcionário, qual função ou método está sendo chamado para a integração. Por exemplo, no cadastro de funcionário os métodos WSNatural e WSUser estão sendo chamados.

11. OCORRÊNCIAS NA INTEGRAÇÃO

Com a utilização do parâmetro MV_TSATLOG, na qual o parâmetro permite que todas as rotinas de integração gerem um log de retorno com as críticas realizadas pelas regras do aplicativo, é possível saber exatamente qual foi o erro gerado durante o processo de integração. No exemplo que iremos mostrar utilizamos o parâmetro com o valor igual a 5, desta maneira iremos ter o XML enviado e o XML de retorno com o código do erro ou sucesso.

1. Confirmado que o parâmetro está com o valor 5.
   
   
2. Após a inclusão do funcionário no Protheus, iremos visualizar o código de retorno informado no log gerado. Para isso basta acessar a pasta System do Protheus e procurar pelo arquivo. O nome do arquivo é composto por um número sequencial, seguido de _RCV.xml para o XML de retorno e _SND.xml para o XML enviado. Em nosso exemplo o nome do arquivo de retorno gerado é 55847972_rcv.xml. Ao abrir o arquivo de retorno devemos procurar pela Tag statusCode, ela que conterá o código do retorno, que poderá ser de sucesso ou erro na integração. No  nosso teste o código gerado foi o 00100, isso significa que a integração funcionou corretamente.
   

Cada Web Service possui códigos e descrições diferentes, por isso para facilitar no entendimento dos códigos de retorno, segue abaixo a tabela de códigos de cada Web Service:

12. LINKS

Integração Suricato
Instalação Suricato (SQL)
Instalação Suricato (Oracle)
Documentação Schedule