01. Apresentação
Este documento tem por objetivo auxiliar as equipes dos segmentos no entendimento do mecanismo de integração do RM com a plataforma de mensagens do Smart Link.
02. Smart Link
O Smart Link é o mediador das mensagens entre a plataforma TotvsApp (cloud ) e ERP's (on premise), e por sua vez é formado por dois componentes: Smart Link Client (on premise), e Smart Link Server (cloud).
Até o momento, essa arquitetura somente poderá ser usada na comunicação entre aplicativos hospedados na plataforma Totvs Apps (ex: TPD, Antecipa, Consignado) com os ERP's. Ou seja, não será possível utilizar essa comunicação entre os ERP's do grupo. Nesse caso, deve ser utilizado o EAI para essa comunicação entre ERP's.
Como exemplo, a integração entre o ERP RM com TPD (Totvs Privacidade de Dados) ocorre através da plataforma Smart Link.
Exemplo de uso:
- Aplicativo TPD publica uma mensagem no "Smart Link Server" solicitando uma221px anonimização de dados. Nesse momento a solicitação fica com o status de "Em Processamento".
- ERP RM (Smart Link Client) consome essa mensagem em um momento posterior, providenciando a anonimização dos dados em seu banco de dados;
- ERP RM (Smart Link Client) envia as respostas para o o Smart Link Server;
- Aplicativo TPD consome as respostas enviadas pelo RM providenciando a mudança do status original da solicitação para "Processada";
A plataforma Smart Link somente poderá ser usada pelos segmentos se o evento de negócio em questão possuir a natureza "assíncrona", ou seja, o publicador da mensagem não precisará de uma resposta imediata para prosseguir com seu processamento.
Essa comunicação entre os aplicativos hospedados na plataforma TotvsApp com o ERP RM ocorrerá através da troca de mensagens entre o componente Smart Link Server com o componente Smart Link Client (localizado na framework RM).
A intenção é que os clientes possuam em sua infraestrutura apenas o Smart Link Client, uma vez que o Smart Link Server será mantido pela TOTVS na nuvem.
02. Comunicação com a plataforma Smart Link Server
A troca de dados com a plataforma Smart Link Server ocorrerá através de comunicação com api's Rest, conforme endpoints abaixo. Toda a comunicação entre o ERP RM com as apis da plataforma "Smart Link Server" já foi implementada através de um artefato, criado na framework RM chamada "Smart Link Client".
Para acessar qualquer api com autenticação na plataforma TotvsApp, deve ser recuperado um token de acesso no Rac.
Esse accessToken deve ser gerado repassando as credenciais de "clientId" e "clientSecret" do cliente em questão conforme print acima.
Endereços da api do Rac:
Ambiente desenvolvimento: https://admin.rac.dev.totvs.app/totvs.rac/connect/token
Ambiente Staging: https://admin.rac.staging.totvs.app/totvs.rac/connect/token
Ambiente Produção: https://admin.rac.totvs.app/totvs.rac/connect/token
Essa api permite que determinados comandos sejam "escutados" pelos artefatos de consumidores criados pelos segmentos.
Ex:
{
"subscriptions": [ "SGDPDataCommand", "SGDPMaskCommand", "SGDPLogsCommand" ]
}
Mensagens criadas na plaforma poderão ser recuperadas através dessa api
Mensagens podem ser removidas da plaforma através dessa api
02. TOTVS APPS (RM)
Foi implementada na framework RM uma arquitetura que permite a leitura e consumo automático das mensagens disponibilizadas no componente Smart Link Server. Através dessa arquitetura, mensagens poderão ser publicadas ou consumidas pelos segmentos. Essa comunicação ocorrerá através de chamadas Rest em api's disponibilizadas pelo componente Smart Link Server.
Para ativar essa comunicação, o usuário receberá por e-mail duas chaves chamadas "clientId" e "clientSecret". Essas chaves são geradas através de um serviço de provisionamento do cliente (tenant) na plataforma.
Após obter essas chaves, o usuário deverá acessar o RM.exe, executar um assistente chamado "Ativação Totvs Apps" localizado em "Integração/Totvs Apps", conforme imagem abaixo.
o usuário deverá entrar com o "clientId" e "clientSecret" disponibilizado.
|
|
|---|
Após execução do processo de ativação, será criado um job chamado "ConTotvsAppExecutorTLCProcess". Esse job será agendado para ser executado de 1 em 1 minuto.
Para cada execução do job, o serviço de pooling do "Smart Link Client" será disparado. Nesse momento, todas mensagens de Upstream (mensagens a serem enviadas para a plataforma Smart Lilnk Server) serão enviadas. E todas as mensagens de Downstream (mensagens a serem executadas pelo RM) serão baixadas e executadas.
Cada mensagem publicada no componente "Smart Link Client" será armazenada no banco de dados na tabela "GTotvsLinkMessage" e cada mensagem processada será incluída na tabela "GTotvsLinkMessageExec". Mensagens processadas com sucesso serão removidas da tabela "GTotvsLinkMessage", ficando portanto seu histórico apenas na tabela "GTotvsLinkMessageExec".
As equipes dos segmentos, são as responsáveis em publicar e consumir mensagens nessa arquitetura. Para isso, foi criado um documento detalhando como publicar e criar artefatos para consumir mensagens (disponível no link abaixo):
Integração RM x SmartLink - Visão desenvolvedor
03. Tentativas de execução da mensagem em caso de erro
Caso ocorra erro na execução de alguma mensagem, a mesma será executada novamente em outro momento. A quantidade de tentativas de execução é parametrizada no json de configurações genérico da integração TotvsApp. Esse json, chamado "totvsAppConfig_v2.json", está localizado na plataforma GCP (Google Cloud Platform).
A leitura desse "totvsAppConfig_vs2.json" é feita automaticamente pelo processo de execução da integração. Portanto, o cliente não precisa se preocupar com essas configurações.
Essa configuração está localizada no atributo "TotvsAppGlobalConfig.IntegrationSmartLinkInfo.QtdeTentativasExec".
A hora de execução dessa próxima tentativa de execução é calculada baseada em algumas informações conforme os atributos abaixo:
| FatorTempoExecucao | Localizado no arquivo de configuração: "totvsAppConfig_v2.json" |
| QtdeTentativasExec | Localizado no arquivo de configuração: "totvsAppConfig_v2.json" |
| MinutesInterval | Localizado no arquivo de configuração: "totvsAppConfig_v2.json" |
| QtdeTentantivaExecCorrente | Valor recuperado da tabela "GTotvsLinkMessage.QtdeTentativaExec". Para cada mensagem, o valor desse campo é incrementado conforme a sua tentativa de execução |
| DataHoraCorrente | Representa a hora corrente no momento do cálculo da próxima execução |
Fórmula de cálculo da próxima tentativa
QtdMinutos = MinutesInterval * FatorTempoExecucao * QtdeTentativasExec * QtdeTentantivaExecCorrente
HoraProximaTentativaExecução = DataHoraCorrente.AddMinutes(QtdMinutos)
O valor calculado em "HoraProximaTentativaExecucao" é gravado na coluna "GTotvsLinkMessage.DataTentativaExec" da mensagem em questão. Portanto, a próxima execução dessa mensagem acontecerá somente após essa data/hora calculada.
04. Log de execução da integração RM x SmartLink
Todos os logs de execução das mensagens Smart Link Client são gravados na tabela GTotvsLinkLog. Essa tabela contém os seguinte atributos:
| Coluna | Descrição |
|---|---|
| ID | Chave primária da tabela. Identificador único do Log. |
| IDMENSAGEM | Identificador único da mensagem relacionada a mensagem gravada em "GTotvsLInkMessage.ID". É através desse campo que o usuário poderá filtrar todos os logs de uma determinada mensagem. |
| LOGTYPE | 0 - Mensagem de informação 1 - Mensagem de aviso 2 - Mensagem de erro |
| LOGMENSAGEM | Texto contendo o log |
| LOGDATE | Data de geração do Log |
| DATADEBUG | Informações extras do log |
05. Modelo de dados do RM SmartLink client
| Tabela | |
|---|---|
| GTOTVSLINKMESSAGE | Tabela utilizada para armazenar todas as mensagens geradas e enviadas para execução pelo Smart Link Client. Sempre que uma mensagem é executa com sucesso, a linha referente a mensagem é excluída dessa tabela , deixando essa tabela sempre leve. Esse procedimento melhora a performance do processo, visto que vários "updates" são realizados nessa tabela. Quanto menor o volume de uma tabela, mais rápido serão as operações do update e detele. |
| GTOTVSLINKMESSAGEEXEC | Tabela contendo todos os dados de execução de uma determinada mensagem. O conteúdo dessa tabela nunca será excluído, ficando portanto como um histórico de execução. Porém, essa tabela poderá ter um volume muito grande. Sendo assim, seria importante de tanto em tanto tempo mensagens muito antigas serem excluídas dessa tabela. |
| GTOTVSLINKLOG | Tabela contendo todos os logs de execução de uma mensagem. O conteúdo dessa tabela nunca será excluído, ficando portanto como um histórico de log de execução. Porém, essa tabela poderá ter um volume muito grande. Sendo assim, seria importante de tanto em tanto tempo logs muito antigos serem excluídos dessa tabela. |
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas