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
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), 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".
3 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 mantidas. "Assistente de ativaçaõ" disponíve.incluir print do wizard.. está dando erro na tela
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).
Já na integração Smart Link DataSharing v2, os dados são serão enviados através da execução automática de um serviço de Host chamado NotifyServer.
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, ou seja, em . Em nenhum momento duas ou mais máquinas poderá 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. Para essa máquina damos o nome de "controladora DataSharing"
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)
Nesta versão, a sincronização de dados entre o RM e a Carol irá seguir → Smart LIink → Carol seguirá o conceito de envio por pacotes (batchs). Cada pacote possui um identificador que será utilizado para rastreio dos dados conforme são enviados pelo SmartlinkSmart Link, para a Carol e por fim até ao app.
O batch é será composto por múltiplas mensagens que irão conter os registros das tabelas que deverão ser enviadas para o serviço de ingestão utilizando o protocolo de comunicação gRPC.
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"
...
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.1 Pacote (Batch)
1.2 Mensagem (Table)
...
title | Registros deletados |
---|
...
.
Para ERPs que não utilizam a prática do soft delete, é necessário que elaborem um mecanismo para conseguir recuperar os registros que foram deletados
O retorno da chamada desse serviço terá o seguinte padrão de objeto:
Bloco de código |
---|
{
"uploadVersion": 2,
"uploadVersionInfo": "Gestão de Upload de Dados via gRPC |
Informações | ||
---|---|---|
| ||
A mensagem não deve ultrapassar o tamanho de 5MB por requisição |
1.2.1 Schema
O schema deve conter uma ou mais colunas listadas para compor a chave primária da tabela. Essa chave é importante pois ela será utilizada para definir se um registro deverá ser adicionado ou atualizado na Carol.
Outra propriedade importante do schema é a propriedade flexible = true, utilizada para que a criação das demais colunas na Carol sejam realizadas automaticamente de acordo com os dados enviados. Dessa forma versões diferentes do mesmo ERP que possuírem tabelas com mais ou menos colunas poderão conviver sem conflitos.
1.2.2 Estrutura da mensagem
1.2.2.1 Table
...
1.2.2.2 TableRow
...
1.2.2.3 RowColumn
...
1.2.2.4 Schema
...
1.2.2.5 SchemaColumn
...
1.2.2.6 SchemaPrimaryKey
...
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:
- Permitir a observabilidade dos pacotes em relação ao número de mensagens enviadas. Permitindo a identificação de mensagens que podem ter sido perdidas e emissão de alertas.
- Serve como um sinalizador para a execução otimizada dos pipelines de dados na Carol. Garantindo que o processamento dos dados será, na maioria das vezes, executado quando pacotes completos estiverem disponíveis.
1.4 Estrutura básica de um pacote
...
1.5 Métodos utilizados para envio
O envio por pacotes possui dois principais métodos, Write() que recebe os dados e o schema da tabela e o Summary() que recebe o sumário contendo as informações sobre a quantidade de mensagens assim como intervalo de datas utilizado para selecionar os dados.
1.5.1 Write
Método utilizado para envio da mensagem com os dados e o schema.
1.5.2 Summary
Método utilizado para envio do summary. Deve ser chamado quando todas as mensagens de um determinado pacote foram enviadas pelo método Write.
1.6 Proto
No contexto do gRPC a definição do serviço contendo as chamadas e as estruturas são escritas em arquivos .proto (mais detalhes em: https://protobuf.dev/overview/).
Segue arquivo proto com as definições:
Bloco de código | ||||||
---|---|---|---|---|---|---|
| ||||||
syntax = "proto3";
option csharp_namespace = "Ingestion.Streaming";
package com.totvs.ingestion.grpc;
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
service TableStream {
rpc Write(Table) returns (TableInputResponse);
rpc Summary(BatchSummary) returns (BatchSummaryResponse);
}
message Table {
string tableName = 1;
string erp = 2;
message RowColumn {
string name = 1;
string value = 2;
}
message TableRow {
repeated RowColumn columns = 1;
}
repeated TableRow rows = 3;
message Schema {
message SchemaColumn {
string name = 1;
string type = 2;
}
bool flexible = 1;
bool exportData = 2;
repeated SchemaColumn columns = 3;
message SchemaPrimaryKey {
string name = 1;
repeated string columns = 2;
}
SchemaPrimaryKey primaryKey = 4;
}
Schema schema = 4;
int64 batchId = 6;
int32 messageNumber = 7;
int32 recordCount = 8;
bool isBaseLoad = 9;
}
message TableInputResponse {
bool success = 1;
repeated string errors = 2;
}
message BatchSummary {
string erp = 1;
int64 batchId = 2;
int32 messageCount = 3;
int32 recordCount = 4;
google.protobuf.Timestamp timestampStart = 5;
google.protobuf.Timestamp timestampEnd = 6;
}
message BatchSummaryResponse {
bool success = 1;
repeated string errors = 2;
} |
...
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 | ||||
---|---|---|---|---|
| ||||
[{ "service": "rac-token", "endpointsqueries": [ { "versiontable": "1"TMOV, "address": "https://admin.rac.dev.totvs.app/totvs.rac/connect/token" } ] }] |
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, "uploadVersionInfo": "Gestão de Upload de Dados via gRPC", "queries": [ { "table": "SE4"filter": null, "forceReload": true, "filterisNative": nulltrue, "forceReloadisCustom": false, "metadata": null }, { "table": "FKDFLAN", "filter": " FKD_DTBAIX FLAN.IDLAN > '20200101' 1000", "forceReload": false, "metadataisNative": null }, { "table": "CTT"true, "filterisCustom": null, "forceReload": 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 |
...
. |