01. VISÃO GERAL 

A partir da versão 12.1.28 é possível realizar a integração do RM com o TOTVS App (Carol). 

Neste documento é descrito o processo de configuração da integração.

02. CONFIGURAÇÃO PASSO A PASSO 

Existem 2 formas de integrar o RM ambiente com o TOTVS App. 

Primeira: Com a ativação baseada no Client Id e Client Secret do RAC. Dessa forma é necessário um ambiente provisionado (RAC ou Carol). Esta é a opção indicada para novas integrações.

        Os endereços do TotvsApp devem ser recuperados pelos links abaixo:

• Ambiente Dev = https://endpoint-registry.dev.totvs.app/api/v1/services
• Ambiente Staging = https://endpoint-registry.staging.totvs.app/api/v1/services
• Ambiente Produção = https://endpoint-registry.totvs.app/api/v1/services

Segunda: Com ativação baseada nas credenciais da Carol.

Os passos descritos abaixo, dentro do tópico 2,  são necessários apenas se a ativação usar as credenciais da Carol. Para ambientes provisionados (Client Id e Client Secret) o arquivo de configuração e os conceitos serão obtido automaticamente pelo sistema, de acordo com a versão do RM e não é necessário alterar os configs do ambiente.

Configuração do RM.Host.exe.config (Ativação baseada nas credenciais da Carol)

Nos arquivos de configuração do host (RM.Host.exe.config, RM.Host.Service.exe.config), adicione a TAG “FileServerPath”. Essa deverá apontar para um caminho compartilhado na rede, conforme abaixo:

Obs: Em ambiente 3 camadas, essa configuração deve ser realizada nas máquinas JobServer.

Verifique se o serviço do Host possui permissão de leitura nesse caminho compartilhado

Cópia dos arquivos de Conceito

Todos os arquivos de conceito, com extensão “*.concept” disponíveis no projeto, deverão ser copiados para esse diretório compartilhado. O configurador fará automaticamente o download desses arquivos e os mesmos serão gravados na tabela GTOTVSAPPCONCEITO.CONCEITO.

.Arquivo de configuração do projeto

Será disponibilizado um modelo de arquivo de configuração Json do projeto. Esse arquivo deve ter obrigatoriamente o nome de “totvsAppConfig.json”. Ele deve ser copiado para o mesmo caminho de rede descrito acima.

O correto preenchimento do mesmo é muito importante para o funcionamento do processo. Segue abaixo uma explicação de cada item da configuração:

Arquivo exemplo: totvsAppConfig.json.

a) RMVersion: versão do RM (essa opção ainda não está sendo usada pelo processo);

b) ScheduleInfo: informações de periodicidade da execução do job de integração. Conforme exemplo acima, o job será executado de 5 em 5 minutos.

Opções:

• Exemplo de execução mensal: [RecurencyType = “Monthly” | DayOfMonth = 14 | Hour = 10 | Minute = 15]. Nesse caso, o job será executado todo dia 14 de cada mês às 10 horas e 15 minutos;
• Exemplo de execução semanal: [RecurrencyType = “Weekly” | Weekdays = “Monday” | Hour = 14 | Minute = 20]. Nesse caso, o job será executado toda segunda feira, às 14 horas e 20 minutos.
• Exemplo de execução horária: [RecurrencyType = “Hourly” | HoursInterval = 2 | MinutesInterval= 0]. Nesse caso, o job será executado todos os dias de 2 em 2 horas.

c) BusinessDomain: Trata-se de uma lista que contemplará todas as integrações futuras do RM com a plataforma Totvs App. No caso do consignado, iremos criar um único objeto dentro dessa lista:

i. AppId: “1” = identificador do aplicativo consignado (valor = 1);
ii. SoftDeleteTables: informe as tabelas que farão parte do soft delete, ou seja, para cada registro excluído no RM na tabela em questão, será gravada uma informação de log na tabela de softDelete da tabela em questão, EX: ppessoa_softdelete;
iii. UpdaterControlColumns: informe as tabelas que terão todos os registros do campo “RecModifiedOn” sendo atualizados para “1900/1/01” se caso ele for null;
iv. ConceptGroup: Lista contendo os grupos de conceito.

1) GroupName: Nome do grupo (essa opção ainda não está sendo usada pelo processo)
2) Concepts: grupo de conceitos contendo informações dos conceitos que participarão do processo:

a) ConceptID: guid contendo a identificação única do conceito. Com esse atributo, poderemos resolver a situação de um conceito ser utilizado por várias integrações (businessDomain). Daí ele será executado apenas uma única vez. Ex: conceito para exportação de dados da GColigada/GFilial.
b) ConceptFileName: Nome físico do arquivo de conceito “*.concept” gravado no caminho de rede compartilhado. Esse nome tem que ser exatamente igual, contendo a extensão.
ex: "ConceptFileName": "ExportacaoFuncionarios.concept",
c) ConceptVersion: guid representando a versão do arquivo de conceito. Se o conceito sofrer alguma alteração que necessita do mesmo ser baixado novamente, esse guid deverá ser modificado. (essa opção ainda não está sendo usada pelo processo)
d) ProcessingDependency: Ordem de dependência de execução dos conceito. Ou seja, o processo não poderá executar o conceito “A” se o conceito “B” não for executado com sucesso. (essa opção ainda não está sendo usada pelo processo)

03. ASSISTENTE DE ATIVAÇÃO / DESATIVAÇÃO DO PROCESSO

Permissão no item de menu

No RM, acesse a opção “Serviços globais / Perfis / Integração” e forneça as permissões para o perfil do usuário em questão.

Selecione o sistema “Integração / Totvs App / Ativação Totvs App” e verifique se o item de menu está habilitado.

Processo de ativação

Nos patches mais recentes são disponibilizados duas formas de autenticação no ambiente: Credenciais do RAC ou credenciais da Carol. Apenas 1 mecanismo de autenticação deve ser utilizado.

Selecione a opção “Consignado” para ativar o processo de integração. Outras opções de integração serão criadas futuramente. 

Na versão 12.1.28 está disponível apenas a integração com o "Consignado". A partir da versão 12.1.29 está disponível também o "Antecipa".

Para configuração das credenciais da Carol:

• Informe o endereço da Carol:
  ex: https://totvstechfindev.carol.ai/
• Informe o Id do Connector da Carol:
  ex: 09ddb0e29e604e599a1356dab2f89df9
• Informe o token da Carol: Esse token, deverá ser recuperado do ambiente Carol, conforme este link.

Para configuração das credenciais do RAC, os dados da Carol não precisam ser preenchidos, pois o sistema usará a autenticação RAC para buscar as credenciais da Carol. 

Novas integrações devem ser configuradas com esse modelo de autenticação.

• Informe o RAC Client Id.
• Informe o RAC Client Secret: Essas informações de autenticação (Client Id, Client Secret) serão enviadas automaticamente para o cliente via e-mail ao ser realizado o provisionamento de seu ambiente na plataforma TotvsApp.

Após execução do processo de ativação, os seguintes procedimentos serão realizados:

• Será gravada uma linha na tabela GTOTVSAPP contendo informações globais da configuração.
• Os conceitos disponíveis no caminho de rede ou obtidos pelo sistema de forma automática e que estão mapeados no arquivo de configuração serão baixados e gravados na tabela “GTOTVSAPPCONCEITO”;
• Será criado um Job agendado e recorrente para execução conforme informações de agendamento disponíveis no arquivo de config;
• As stored Procedures de softDelete serão executadas para as tabelas mapeadas para criação automática das estruturas de softDelete;
• As tabelas mapeadas serão atualizadas na colulna “RECMODIFIEDON” para a data “1900/01/01” em caso de possuir o valor null;

Para cada execução do job de exportação:

• Os conceitos serão executados e os dados serão enviados para Carol conforme definido nos conceitos;
• Será gravada uma linha na tabela “GTOTVSAPPCONCEITOHST” conforme informações de execução de cada conceito (sucesso ou erro e mensagem de erro);
• Em caso de sucesso, a coluna “GTOTVSAPPCONCEITOHST.DATAULTEXEC” será atualizada para a data de início da execução do processo. 
• O status da execução pode ser consultado também na coluna “GTOTVSAPPCONCEITOHST.STATUS” (1 - sucesso, 2 - falha, 0 - não executado). E na coluna "GTOTVSAPPCONCEITOHST.MENSAGEM" a mensagem do erro ou de sucesso.

12.1.33

A partir da versão 12.1.33, estará disponível apenas autenticação com as Credenciais do RAC.

Além disso, o processo de ativação irá ativar ou desativar a integração com todos os aplicativos disponíveis. Será necessário clicar no botão "Buscar Apps" antes de avançar com o processo, e será retornado todos os Apps disponíveis na Carol para a integração com ambiente RM.

Caso a integração já esteja ativa e um novo App for disponibilizado (Exemplo: SGDP), não será necessário refazer o processo de ativação.

Processo de desativação

Após ativado, o usuário poderá a qualquer momento desativar o processo conforme opção abaixo:

O processo de desativação executará os seguintes procedimentos:

• As informações das tabelas “GTOTVSAPP, GTOTVSAPPCONCEITO, GTOTVSAPPCONCEITOHST e GTOTVSAPPLOG " serão excluídas da base;
• O Job Executor do processo será finalizado e excluído;
• As tabelas de softDelete não serão mais alimentadas com informações de deleção.

04. Como Funciona

Através da ferramenta de Conceito o RM envia para a Carol (Inteligência artificial da TOTVS) informações chaves baseadas nas configurações dos conceitos de cada integração.

Após a ativação da integração o processo ConTotvsAppActivatorProcess que configura a integração será disparado.

Após a execução do processo que configura a integração será iniciado o processo que Executa a integração ConTotvsAppExecutorProcess. 

O processo será recorrente de acordo com a configuração de periodicidade utilizada no arquivo totvsAppConfig.json.

05. VISUALIZAÇÃO DE LOG

Na tabela GTOTVSAPPLOG é armazenado o log detalhado de cada execução dos conceitos e envios cadastrados na tabela GTOTVSAPPCONCEITOHST.

Informações relevantes sobre a tabela GTOTVSAPPLOG:

Na coluna Tipo, deve ser considerado:
0 - Mensagem de Sucesso
1 - Mensagem de Alerta
2 - Mensagem de Erro

Caso ocorram erros, as colunas Mensagem e Descrição podem ser consultadas para obter mais detalhes.

Exemplo de mensagens de erro:
Mensagem: Erro ao enviar dados para serviço de api!| {"code":404,"message":"HTTP 404 Not Found"}
Mensagem: Pacote '1' de '1' enviado com erro!|Erro ao enviar dados para serviço de api!| {"code":405,"message":"HTTP 405 Method Not Allowed"}

Para analisar os registros da tabela de log, é importante filtrar a busca pela chave GTOTVSAPPLOG.IDTOTVSAPPCONCEITOHST, relacionada a coluna GTOTVSAPPCONCEITOHST.ID

06. HABILITAR TLS

Em alguns casos é necessário ajustar o TLS do servidor.

Para ajustar basta criar um arquivo com a extensão .Reg e escrever o comando abaixo. Após criar o arquivo basta executar.

Importante que todos os servidores que processam Jobs estejam com essa configuração.

Windows Registry Editor Version 5.00
; 0x00000008	Habilitar o SSL 2.0 por padrão
; 0x00000020	Habilitar SSL 3.0 por padrão
; 0x00000080	Habilitar TLS 1.0 por padrão
; 0x00000200	Habilita o TLS 1.1 por padrão
; 0x00000800	Habilitar TLS 1.2 por padrão


[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp]
     "DefaultSecureProtocols"=dword:0x00000800

[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp]
     "DefaultSecureProtocols"=dword:0x00000800 

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] 
 "DisabledByDefault"=dword:00000000
 
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] 
 "DisabledByDefault"=dword:00000000

07. MECANISMO DE EXECUÇÃO DA INTERGRAÇÃO COM O TLC

      O campo "IDJOB" já existente na tabela "GTOTVSAPP" é responsável em fazer a subida dos dados para Carol (busca do RM e envia para Carol).

      Com a nova implantação do TLC, após realizar a ativação do TotvsApp, será criado um novo IDJOB na tabela "GTOTVSAPP", mas que estará disponível no novo campo "JOIBIDTLC". Ele é o responsável por enviar mensagens localizadas na tabela "GTOTVSLINKMESSAGE" para o TotvsLinkClient. 

      A cada exportação realizada com sucesso, o dado das métricas será localizado na tabela "GTOTVSLINKMESSAGE", após o envio das métricas serem realizados com sucesso, os dados serão enviados para a tabela "GTOTVSLINKMESSAGEEXEC" e excluído na tabela "GTOTVSLINKMESSAGE". 

      Na tabela "GJOBXEXECUCAO", deve existir dois Jobs recorrentes (de acordo com a configuração de periodicidade utilizada), referentes aos Ids criados no campos "JOBID" e "JOIBIDTLC" da tabela "GTOTVSAPP".

      E ao realizar a desativação do processo, o Jobs devem ser desabilitados (status = 8).

      As métricas, estão sendo enviadas para o Grafana (Uma aplicação web de análise, onde são fornecidos tabelas, gráficos, etc). 

      A execução do "JOBIDTLC", fará uma leitura na tabela "GTOTVSLINKMESSAGE" e realizará o envio das métrica para o Grafana.
      Segue abaixo o exemplo da visualização das métricas dentro da aplicação: