Histórico da Página
...
Nesse modelo de integração, o dado é recuperado do ERP RM e enviado para o Smartlink server (serviço hospedado na plataforma TotvsApp).
Na versão anterior de integração com Smart Link DataSharing v1 , o dado é recuperado do ERP RM e enviado diretamente para a Carol (mais detalhes disponível em https://tdn.totvs.com/x/l-55IQ,).
01.Configurando a integração
incluir componente desk card contendo os passos...
a) - Solicitar a criação do app junto a equipe de plataforma do TotvsApp.
b) - Abrir 1 - Deve abrir uma issue de apoio para equipe de framework BH (DFRWFOUNDATION) solicitando o registro do app em questão nas configurações gerais de integração (disponíveis no arquivo nos arquivos de configuração (TotvsAppSaas.json).
incluir print do wizard.. está dando erro na tela
, O identificador do App deve ser enviado nessa issue.
c) - Efetuar ativação do app através do "Processo de ativação do TotvsApp" disponível em: "Integração/TotvsApp".
c) - Informar o "RAC clienteId" e "RAC clientSecret" enviados para o cliente e selecionar o App a ser ativado.
Informações |
---|
O app somente aparecerá na lista para ser ativado se o clientId em questão tiver permissão para esse app. Para conferir, basta fazer uma chamada de api para o endpoint "api/data-management/v1/apps/by-tenant" e verifica no retorno se o app está presente nos itens do json. ex: https://provisioning.dev.totvs.app/api/data-management/v1/apps/by-tenant |
e) Limpeza de Histórico:
Para facilitar o uso da funcionalidade de limpeza de histórico da tabela GTOTVSAPPCONCEITOHST, foi implementada uma nova opção de "Limpeza de Histórico" no sistema.
Como Utilizar:
Acessar a Opção de Limpeza:
- No processo de atividades com o TOTVS APP, haverá um botão chamado "LIMPEZA DE HISTÓRICO".
Configurar a Limpeza:
- Dias que devem ser mantidos no histórico: Defina quantos dias de histórico você deseja preservar. Os registros dentro desse período não serão removidos.
- Número máximo de registros a serem removidos: Determine quantos registros antigos devem ser apagados, começando dos mais antigos até os mais recentes.
Executar a Limpeza:
- Após configurar as opções de limpeza, clique em "Executar" para realizar a limpeza dos registros conforme as configurações selecionadas.
Observação:
O sistema sempre preservará o último registro executado com sucesso para cada conceito na tabela, garantindo que as informações essenciais sejam mantidas2 - Informar o clienteId e clientSecret enviados para o cliente no "Assistente de ativaçaõ" selecionando o app em questão.
02.Serviço RM de envio dos dados
Na integração anterior (Smart Link DataSharing v1, ) os dados são enviados em ciclos de execução de Job's (mecanismo de Job do RM - https://tdn.totvs.com/x/_Z4YIQ).
...
Nesse mecanismo, somente uma máquina do ambiente do cliente (seja um servidor de aplicação ou um servidor de Job) terá a responsabilidade de enviar os dados. Em nenhum momento duas ou mais máquinas poderão enviar os dados ao mesmo temposimultaneamente.
Caso ocorra algum problema com essa a máquina responsável pelo envio, ficando portanto indisponível, outra máquina assumirá o papel de envio.
O envio dos dados ocorrerá de 5 em 5 segundos, ou seja, caso um algum registro (de alguma tabela integrada) seja alterado, a alteração será enviada para o Smart Link Server após 5 segundos.
Nota | ||
---|---|---|
| ||
O modelo de integração SmartLink DataSharing v1 em breve será descontinuado pela equipe de Framework BH. |
03.Envio dos pacotes (batchs)
...
Cada mensagem é formada por 200 registros.
No RM, o rastreio dos dados enviados podem ser verificados através de uma sentença sql na tabela "GDataShareRecords'.
Informações |
---|
A tabela GDataShareRecords é responsável em manter um rastro dos registros que já foram enviados (por tabelas). Portanto, operações de update, delete e insert não poderão ser efetuadas nessa tabela de forma manual. O processo de limpeza dessa tabela é feito automaticamente pelo serviço de envio de dados. |
04.Serviço de entidades
As entidades consistem em uma parte fundamental do processo. Elas determinam todas as entidades que o RM deve subir de acordo com os app's contratados.
A lista das tabelas que participarão do processo de envio é recuperada através da chamada de um serviço com endpoint "/api/carol-definitions/v1/entities/RM".
...
O retorno da chamada desse serviço terá o seguinte padrão de objeto:
Bloco de código |
---|
zxdfas\fasdf
asd
fas
dfa
sdfa
sdf
asd |
Portanto, solicitações de inclusão / exclusão de tabelas para a integração devem ser tratadas diretamente com a equipe de plataformas do TotvsApp.
...
1.3 Sumário
No final do job será necessário enviar um sumário do pacote, informando o numero de mensagens enviadas, o total de registros enviados e o range de datas que o pacote representa.
O sumário é o responsável por duas tarefas importantes:
...
1.4 Estrutura básica de um pacote
...
Mecanismo de job que deverá rodar em um período configurável de tempo, executando a sequência de chamadas de APIs descritas a seguir:
- Registry (eventual)
- Token (eventual)
- Entidades (eventual)
- Write
- Summary
Ou seja, se todos os mecanismos recomendados forem implementados, será possível em alguns momentos de execução do job, chamar apenas a API Intake da Carol para enviar os dados.
O framework deverá implementar uma rotina de controle dos registros baseado em timestamp, este controle poderá ser nativo/prévio ou habilitado somente para as tabelas que forem retornadas pela chamada da api Entities.
2.1 Registry
Serviço responsável por centralizar todas as URLs acessadas pelo ERP. Não possui autenticação e deve ser a única URL configurada diretamente.
Os serviços cadastrados são retornados usando a seguinte estrutura:
Bloco de código | ||||
---|---|---|---|---|
| ||||
[{ "serviceuploadVersion": "rac-token"2, "endpointsuploadVersionInfo": [ "Gestão de Upload de Dados { "version": "1"via gRPC", "address": "https://admin.rac.dev.totvs.app/totvs.rac/connect/token""queries": [ }{ ] }] |
2.2 Autenticação
As chamadas disponíveis na solução (Write e Summary) são autenticadas pelo RAC. Cada cliente provisionado recebe um client id e um client secret que são utilizados para gerar o token de serviço onde além de autenticar também é utilizado para identificar o cliente.
Segue um exemplo da chamada para geração do token:
- A url responsável pela geração do token de serviço para o tenant deve ser recuperada pela chave rac-token na listagem dos serviços do Registry (2.1)
Bloco de código | ||||
---|---|---|---|---|
| ||||
curl --location 'https://admin.rac.dev.totvs.app/totvs.rac/connect/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=authorization_api' \ --data-urlencode 'client_id=xxxxxxxxx' \ --data-urlencode 'client_secret=xxxxxxxxx' |
2.3 Entidades
As entidades consistem em uma parte fundamental do processo, elas determinam todas as entidades que o ERP deve subir de acordo com os produtos contratados e o ERP utilizado.
Quando o ERP inicia um ciclo de envio, após gerar as credenciais conforme o passo 2.2, é necessário fazer um solicitação para a API de entidades, onde serão retornadas no seguinte formato
- A url responsável pela geração do token de serviço para o tenant deve ser recuperada pela chave provisioning-carol-definitions-entities na listagem dos serviços do Registry (2.1)
Bloco de código | ||||
---|---|---|---|---|
| ||||
{ "uploadVersion": 2"table": "TMOV, "uploadVersionInfo": "Gestão de Upload de Dados via gRPC", "queriesfilter": [ {null, "tableforceReload": "SE4"true, "filterisNative": nulltrue, "forceReloadisCustom": false, "metadata": null }, { "table": "FKDFLAN", "filter": " FKD_DTBAIX FLAN.IDLAN > '20200101' 1000", "forceReload": false, "metadataisNative": null }, {true, "table": "CTT", "filter": null, "forceReloadisCustom": false, "metadata": null }, ] } |
2.3.1 Migração progressiva
Para habilitar uma migração progressiva dos clientes é necessário enviar no no endpoint provisioning-carol-definitions-entities, o header http x-upload-version,
esse header vai nos informar qual versão da subida de dados é suportada pela versão do ERP instalada no cliente.
- Versão 1: Utiliza rest para enviar direto para a Carol (
x-upload-version: 1)
- Versão 2: Utiliza o framework gRPC para envio e permite observabilidade (
x-upload-version: 2)
Características:
- Cada item da lista "queries", representa uma tabela do RM que será integrada. No exemplo acima, teremos a integração das tabelas TMOV e FLAN.
...
- Filtro de dados (atributo filter): clausula SQL ANSI obrigatória para entidades que possuem dados históricos ou de movimentação, atualmente a plataforma trabalha com dados no máximo até de 2 anos para trás. Deve ser . Será utilizado sempre que o ciclo de envio estiver enviando a tabela pela primeira vez (carga inicial) ou quando uma solicitação de recarga dessa tabela (force reload = true) seja sinalizada para o ERP.RM.
Informações |
---|
No filtro, sempre deve ser informado "Tabela.Campo" conforme exemplo abaixo: TMOV.DATAMOVIMENTO > '2012-01-01'. |
3. Recarga de uma tabela específica (atributo forceReload): é um campo do tipo booleano que indicará para o
...
RM efetuar a recarga desta tabela.
...
. Recurso importante para tratar cenários com problema sem a necessidade de acessar o ambiente do cliente
...
- Quando efetuar uma recarga de dados é obrigatório que as mensagens referentes as tabelas envolvidas na recarga sejam enviadas com a flag isBaseLoad igual a true, para evitar que grandes quantidades de dados entrem na mesma fila que os dados incrementais (delta) gerados no durante uso das funcionalidades que afetam dados no ERP.
...
Informações | ||
---|---|---|
| ||
O recurso para recarregar uma determinada tabela forceReload é bastante importante para o processo, utilizado sempre que é identificado algum problema em pipelines de dados na Carol ou até para as aplicações TOTVS Apps. Nesse sentido, a correção é executada (pipelines ou aplicação) e a recarga é sinalizada para receber os dados novamente da forma correta sem que haja necessidade de acessar o ambiente do cliente. |
2.4 Tratamento de erros para a rotina de envio
...
.
Informações |
---|
Solicitações de inclusão / exclusão de tabelas devem ser tratadas diretamente com a equipe de plataformas do TotvsApp |
...
. |