Histórico da Página
...
- Visão Geral
- Arquitetura TOTVS
- TOTVS Connector Client
- TOTVS Connector Server
- TOTVS Agro Plataforma
- TOTVS Agro Conecta Dados
- Monitoramento TOTVS Apps
- Fluxo de Dados/APIs
01.
...
Visão Geral
Esta integração foi construída para efetuar o envio de dados entre TOTVS Agro Bioenergia (módulo de Pagadoria) para Salesforce com foco em "dados mestres" de Fazenda (Nível 1), Setor (Nível 2) e Talhão (Nível 3), quando inseridos ou atualizados via aplicação (Bioenergia/Pagadoria).
...
TOTVS Agro Bioenergia (Pagadoria APIs) - Configuração IIS
02. Arquitetura TOTVS
Na imagem abaixo, podemos ver com detalhes representação arquitetural e dos componentes envolvidos, pode-se conhecer, em detalhes técnicos, o fluxo geral de eventos/dados, desde quando os dados saí do sua saída do (1) TOTVS Agro Bioenergia (módulo de Pagadoria) até chegar para Salesforce. O fluxo é divido em 3 etapas que serão detalhadas de acordo com decorrer do material, essas etapas são:, passando pelo (2) TOTVS Agro Connector Client (componente/agent On-Premise que realiza captura de dados CDC - Change Data Capture) que compartilha dados com (3) TOTVS Agro Connector Server (aplicação SaaS no domínio TOTVS), que compartilha dados com (4) TOTVS Agro Plataforma (aplicação SaaS no domínio TOTVS) e, por fim, à chamada de APIs da Salesforce pelo (5) TOTVS Agro Conecta Dados (aplicação SaaS no domínio TOTVS - via "Conector Salesforce"):
- On-Premise, ambiente do cliente, onde é instalado o TOTVS Agro Connector Client;
- TOTVS Apps, ambiente Web TOTVS que está localizado o TOTVS Agro Connector Server, TOTVS Agro Plataforma e TOTVS Agro Conecta Dados;
- Terceiros, API fornecida pela
- On-Premise, ambiente do cliente, onde é instalado o TOTVS Agro Connector Client;
- TOTVS Apps, ambiente Web TOTVS que está localizado o TOTVS Agro Connector Server, TOTVS Agro Plataforma e TOTVS Agro Conecta Dados;
- Terceiros, API fornecida pela Salesforce para realizarmos os envios dos dados;
Resumidamente a integração segue o fluxo abaixo.
O fluxo de integração e seus principais componentes são:
- TOTVS Agro Connector Client é instalado no cliente e cadastrado a base e vinculado com Schema Definition, logo após é criado uma trigger que fica monitorando quando é inserido ou atualizado um novo registro e para cada novos dados é enviado via JSON por API para o TOTVS Connector Server;
- TOTVS Agro Connector Server é responsável por receber esses dados e processar em uma fila de mensageria via RabbitMQ, tal fila que TOTVS Agro Plataforma irá receber;
- TOTVS Agro Plataforma irá fazer efetua as validações dos dados recebidos na fila e inserir no banco do próprio, garantindo-se a integridade dos dados. Com os dados validado será processado para uma nova fila no RabbitMQ que o TOTVS Agro Conecta Dados irá receber;
- TOTVS Agro Conecta Dados irá receber essa recebe esta mensagem com JSON, que será adaptada ao modelo repassado pela Salesforce, portanto, após a autenticação com os dados informado na interface web Web do TOTVS Agro Conecta Dados, fazemos realiza uma requisição PATCH passando os novos dados tratados (por meio de um componente "Conector Salesforce");
- Após a requisição PATCH é possível verificar nos logs do TOTVS Agro Conecta Dados se a mensagem foi recebida com sucesso pela Salesforce;
Após a explicação resumida acima, nas próximas seções iremos detalhas o papel de cada produto e suas funções a serem utilizadas.
2.1. TOTVS Agro Connector Client
...
2.1. TOTVS Agro Connector Client
O O TOTVS Agro Connector Client é um aplicação On-premisesPremise, que é instalado localmente no ambiente do cliente com um TENTANT_ID que é disponibilizado pela equipe do TOTVS Agro e atualmente possui uma interface do Swagger e a sua própria base de dados, conforme a imagem abaixo.
No Swagger, cadastramos cadastra-se a base de dados do produto, no caso TOTVS Agro Bioenergia.
Hoje, trabalhamos com Atualmente, o modelo de dados utiliza de Schemas Definitions, que é o mapeamento de tabelas e colunas que serão enviadas para parceira, conforme solicitação, a equipe TOTVS Agro realiza esse cadastro e será enviado os seguintes dados:
UPNIVEL1 | UPNIVEL2 | UPNIVEL3 |
---|---|---|
CD_UPNIVEL1 | CD_UPNIVEL1 + CD_UPNIVEL2 | CD_SAFRA + CD_UPNIVEL1 + CD_UPNIVEL2 + CD_UPNIVEL3 |
CD_UPNIVEL1 | CD_UPNIVEL1 | CD_SAFRA |
CD_MUNIC | CD_UPNIVEL2 | CD_UPNIVEL1 |
CD_FORNEC | CD_MUNIC | CD_UPNIVEL2 |
DE_UPNIVEL1 | DE_UPNIVEL2 | CD_UPNIVEL3 |
DE_ENDERECO | QT_AREA_TOT | CD_TP_PROPR |
NO_TELEFONE | QT_AREA_PROD | DS_TERRA |
NO_CGC_CPF | DS_ASFALTO | |
NO_INCRA | DS_HIDROVIA | |
NO_INSC_PROD | CD_SIST_COLH | |
NO_CEP | DT_PLANTIO | |
FG_TP_PESS | CD_OCUP | |
QT_AREA_TOT | CD_VARIED | |
QT_AREA_PROD | CD_ESTAGIO | |
CD_INT_ERP | CD_ESPACAM | |
INSTANCIA | CD_SIST_PLAN | |
FG_ATIVO | QT_AREA_PROD | |
CD_OCUP_ANT | ||
FG_TP_PLANTIO |
Após o cadastro, vinculamos vincula-se a base de dados com o Schema Definition (LocalProducao1, LocalProducao2 e LocalProducao3), esses Schemas Definitions (dados que serão enviados), após efetuar esse vínculo é criado uma trigger que monitora cada insert/update que foi cadastrado conforme a tabela acima. Quando é realizado algum INSERT ou UPDATE esse dado é processado através de tabelas do TOTVS Agro Connector Client e enviado por API como JSON para o TOTVS Agro Connector Server. Em caso de perda de conexão (serviço desligado) o registro fica em uma tabela criada chamada TCC_EVENT com status de UNPROCESSED, assim que serviço é ligado novamente o dado é processado e enviado, isso para garantir que não haja perca de dados.
...
O TOTVS Agro Connector Server é uma aplicação que fica nos ambientes TOTVS Apps e é utilizado pela equipe TOTVS Agro para realizar os cadastros dos clientes, gerando o TENANT_ID (para os clientes conseguirem realizar instalação do TOTVS Agro Connector Client) e os cadastros dos Schemas Definitions que foram citados Anteriormente.
Ele também Também é responsável por receber os dados que o TOTVS Agro Connector Client envia, com . Com esse JSON recebido, ele é enviado para uma fila de mensageria da TOTVS por meio do RabbitMQ para o TOTVS Agro Plataforma.
- Abaixo, são exibidos os detalhes de um exemplo de JSON que é enviado à Exemplo detalhado de JSON que irá para fila do RabbitMQ (mencionado acima).:
Bloco de código theme Confluence { "header":{ "type":"LocalProducao1", "generatedOn":"2023-03-02T12:45:19.000688Z", "locale":"pt_BR" }, "content":{ "originApp":"PIMSCS", "appVersion":"12.1.2301", "schemaName":"LocalProducao1", "schemaVersion":"12.1.2301", "action":"INSERT", "data":{ "id":{ "id":"TESTE" }, "nome":"TESTE1", "codigo":"TESTE", "originId":"Q0RfVVBOSVZFTDE9VEVTVEU=" }, "createdAt":"2023-03-02T12:45:19.303637Z", "token":"8c12da2baca8de2e6b5dd2f6999c6998cbc7b563e5c24e043fa26b72f1f406e8" } }
- Abaixo, são exibidos os detalhes de um exemplo de JSON que é enviado à Exemplo detalhado de JSON que irá para fila do RabbitMQ (mencionado acima).:
...
O TOTVS Agro Plataforma está disponível nos ambientes do TOTVS Apps, porém ele não possuí uma interface gráfica. Ele é responsável por receber as mensagens do TOTVS Connector Server que foi processado na fila do RabbitMQ, então ele pega o JSON recebido, insere os dados na própria base de dados para haver controles de chaves primárias, foreign key chaves estrangeiras e garantir a integridade das tabelas e relacionamentos. Após conclusão de inserção com sucesso, novamente esse JSON é enviado para outra fila via RabbitMQ, que será processado pelo TOTVS Agro Conecta Dados.
- Abaixo, exibiremos em detalhe um exemplo Exemplo detalhado de JSON que irá para fila do rabbit mostrado acima.RabbitMQ (mencionado acima):
Bloco de código theme Confluence { "header":{ "type":"FazendaCriada", "tenantId":"8c12da2baca8de2e6b5dd2f6999c6998cbc7b563e5c24e043fa26b72f1f406e8", "generatedOn":"2023-03-22T14:12:21.428785Z", "locale":"pt_BR" }, "content":{ "originId":"Q0RfVVBOSVZFTDE9NjAwODZB", "metadata":{ }, "codigo":"FazendaA1", "descricao":"Fazenda Teste", "documento":null, "instanciaOriginId":null, "cdMunicipio":"2308", "cdFornecedores":"94500", "endereco":"Fazenda Teste", "telefone":null, "cnpjCpf":"12345678", "incra":null, "inscricaoProdutorRural":"123.456.789-10", "cep":"111111", "tipoPessoa":"J", "qtdAreaTotal":"24", "qtdAreaProdutiva":"24", "cdIntErp":null } }
- Abaixo, exibiremos em detalhe um exemplo Exemplo detalhado de JSON que irá para fila do rabbit mostrado acima.RabbitMQ (mencionado acima):
2.4. TOTVS Agro Conecta Dados
- O TOTVS Agro Conecta Dados (Front/Web) é responsável por cadastrar as informações disponibilizadas pela Salesforce e também ativar ou desabilitar integrações, tais elas como:
...
- O TOTVS Agro Conecta Dados Server é responsável por receber o JSON via mensageria, então ele fica observando a fila que o TOTVS Agro Plataforma enviou os dados. Com o JSON disponível o TOTVS Agro Conecta Dados fica responsável por realizar a autenticação a partir dos dados informados no frontFront/Web, com isso ele monta o JSON baseado no modelo enviado e processamos a processam-se as requisições PATCH para Salesforce, conforme alguns exemplos abaixodemonstrados:
Aviso | ||
---|---|---|
| ||
Para realizar as requisições é necessário passar o token recuperado, após autenticação. |
Abaixo será exibidos Destacam-se as tabelas disponibilizadas para nós com base na API deles, ou seja, o JSON que devemos passar será inserido no body da requisição como JSON e exemplos de como estamos utilizando cada uma no postman: collections: Patch(Insert-Update)-Exemplos.postman_collection.json que pode ser importado no Postman para realizar os testes, basta inserir os dados necessários que são destacados em vermelhos na requisição após a importação.
Modelo à ser enviado: FAZENDA (Local de Produção 1) para Salesforce.
API Tipo Descrição IdConta__c Texto ID Modelo à ser enviado: FAZENDA (Local de Producão 1) para Salesforce.
API Tipo Descrição IdConta__c texto Id Fazenda CodigodaPropriedade__c Texto(6) (ID Externo) Cod Código Fazenda Municipio__r.codigoMunicipio__c PesquisaCod Municipo PIMSCódigo Município codigoFornecedor__c Numero(8) Cod Código Fornecedor descricaoCompleta__c textoTexto(70) Descrição Completa BillingStreet textoTexto(70) Endereço Phone textoTexto(70) Telefone cnpjCPF__c textoTexto(18) CNPJ ou CPF numeroIncra__c textoTexto(15) N° INCRA numeroInscricaoProdutorRural__c textoTexto(20) N° Insc.Produtor Rural Cep__c textoTexto(16) N° cepCEP Tipo_de_Pessoa__c textoTexto(1) QtdeAreaTotalHA__c numeroNumero(7,2) QtdeAreaTotalProdHectares__c numeroNumero(7,2) codigoInternoErp__c textoTexto(15) Instancia__r.CodigoInstanciaPIMS__c textoTexto(5) flagAtivo__c Lista de Opçoes
...
Modelo à ser enviado: SETOR (Local de Producão Produção 2) para Salesforce.
API Tipo Descrição IdBloco__c Texto(6) (ID Externo) Id Bloco Conta__r.IdConta__c Pesquisa(Conta) Cod Código Fazenda codigoBloco__c Texto(6) (ID Externo) Cod Código Bloco Municipio__r.codigoMunicipio__c Pesquisa Cod Municipo Código Município PIMS Name Name Descrição do Bloco Hectares__c NumberNumero(16,2) Qtde Quantidade de Area Área Total em Hectares AreaProdutivaHA__c NumberNumero(16,2) Qtde Quantidade de Area Área Produtiva em Hectares
Modelo à ser enviado: TALHÃO (Local de Producão Produção 3) para Salesforce.
API Tipo Descrição IdTalhao__c Texto Id ID Talhão Safra__c Numero(5) Codigo Código da Safra Conta__r.IdConta__c Texto(6) Cod Código Fazenda Bloco__r.IdBloco__c Pesquisa Cod Código Bloco codigoTalhao__c (ID Externo) Texto(6) Cod Código Talhão CodigoTipoPropriedade__c Lista de Opções Cod Código Tipo de Propriedade DistanciaTerra__c Numero(4,1) Distância Terra DistanciaAsfalto__c Numero(4,1) Distância Asfalto DistanciaHidrovia__c Numero(4,1) Distância Hidrovia CodigoSistemaColheita__c Lista de Opções Codigo Código de Sistema de Colheita DataPlantio__c Date Data do Plantio CodigoOcupacao__c Lista de Opções Codigo Código de Ocupação CodigoVariedade__c Lista de Opções Codigo Código de Variedade CodigoEstagio__c Lista de Opções Codigo Código de Estagio CodigoEspacamento__c Lista de Opções Codigo Código de Espaçamento CodigoSistemaPlantio__c Lista de Opções Codigo Código de Sistema de Plantio AreaProdutivaHA__c NumberNumero(7,2) Qtde Quantidade de Area Área Produtiva em Hectares CodigoOcupacaoAnterior__c Lista de Opções Codigo Código de Sistema de Plantio Anterior FlagTipoPlantio__c Lista de Opções Flag de Tipo de Plantio
...
- Exemplo de requisição Postman: PATCH - Fazenda
Exemplo de requisição Postman: PATCH - Setor
- Exemplo de requisição Postman: PATCH - Talhão
2.5.Monitoramento TOTVS Apps
- TOTVS Agro Bioenergia (via TOTVS Agro Connector Client - TCC_EVENT)
- Dentro da base de dados do TOTVS Agro Bioenergia é gerado uma tabela pelo TOTVS Agro Conector Client que é possível verificar os últimos eventos capturados pela Trigger
- Tabela: TCC_EVENT
- TOTVS Agro Bioenergia (via TOTVS Agro Connector Client - TCC_EVENT)
-
- TOTVS Agro Connector Client
- Dentro da base TOTVS Agro Connector Client é possível verificar se as mensagens estão sendo processadas e verificar o JSON.
- Tabela: OUTCOMING_DATA
- TOTVS Agro Connector Client
-
- TOTVS Agro Connector Server
- Dentro da base do TOTVS Agro Connector Server, localizado dentro do TOTVS Apps (Acesso Restrito) é possível verificar os logs.
- Tabela LOG
- TOTVS Agro Connector Server
-
- TOTVS Agro Plataforma
- Nos ambientes do TOTVS Apps (Acesso Restrito) é possível verificar os logs de rastreabilidade, ou seja, verificar se as integridades estão de acordo e se o fluxo pode seguir.
- Ferramenta: LENS
- TOTVS Agro Conecta Dados
- Nos ambientes do TOTVS Apps (Acesso Restrito) é possível verificar os logs de rastreabilidade, ou seja, verificar os dados foram efetivados e a resposta da API com Salesforce.
- Ferramenta: LENS
- TOTVS Agro Plataforma
...
03. Fluxo de Dados/APIs
1. Trigger
1.1. Trigger monitora cada novo evento na tabela
1.2. Para os eventos gerados a trigger insere o registro na tabela TCC_EVENT, com os dados que foram gerados no schema definition e status unprocessed
2. TOTVS Agro Connector Client
2.1. monitora a tabelaTCC_EVENT, por meio da classe EventScheduler.java
2.2. Após receber os dados é feito uma verificação e uma atualização na tabela TCC_EVENT, alterando o status para processed por meio da classe RowDataService.java
2.3. Com os dados validados, é processado para tabela OUTCOMING_DATA e enviado para o TOTVS Agro Connector Server por meio da classe EventProcessor.java
3. TOTVS Agro Connector Server
3.1. A lista de eventos recebidas pelo TOTVS Agro Connector Client é enviado na tabela própria do produto chamada CLIENT_DATA que pode ser encontrado por meio da classe CriateClientDataService.java
3.2. ClientDataScheduler.java é responsável por processar o JSON recebido para a fila do RabbitMQ no TOTVS Agro Plataforma.
4. TOTVS Agro Plataforma
4.1. Nesse momento o JSON é classificado de acordo com schema definition e inserido coluna por coluna nas tabelas com suas integridades na base de dados do TOTVS Agro Plataforma
4.1.1. Se for uma fazenda (Nível 1) (FazendaTCServerListener.java), é inserido ou atualizado na tabela FAZENDA, por meio da classe FazendaTCServerProcessor.java
4.1.2. Se for um setor (Nível 2) (SetorTCServerListener.java), é inserido ou atualizado na tabela SETOR, por meio da classe SetorTCServerProcessor.java
4.1.3. Se for um talhão (Nível 3) (TalhaoTCServerListener.java), é inserido ou atualizado na tabela TALHAO_LOGICO, por meio da classe TalhaoTCServerProcessor.java
4.2. Após as inserções e validações a mensagem (JSON) é novamente inserido em outra fila do RabbitMQ para enviar para o TOTVS Agro Conecta Dados por meio da classe EntidadePlataformaPublisher.java
5. TOTVS Agro Conecta Dados
5.1. Em uma fila única, a mensagem recebida é verificada o tipo do conector e a mesma é processada na classe AcaoConectorEntidade.java
5.2. Token
5.2.1 O token é recuperado por meio do preenchimento no front e inserido nas tabelas do TOTVS Agro Conecta Dados, a autenticação e atualização de token é consistido por meio da classe AtualizarTokenSalesforceService.java
5.3. Fazenda
5.3.1. SalesforceEnvioFazendaProcessor.java é a classe responsável por ler a mensagem, criar e tratar o JSON com a estrutura da Salesforce
5.3.2. SalesforceFazendaHttpClient.java realiza a autenticação e realiza o envio se comunicando com a API Salesforce.
5.4. Setor
5.4.1. SalesforceEnvioSetorProcessor.java é a classe responsável por ler a mensagem, criar e tratar o JSON com a estrutura da Salesforce
5.4.2. SalesforceSetorHttpClient.java realiza a autenticação e realiza o envio se comunicando com a API Salesforce.
5.5. Talhão
5.5.1. SalesforceEnvioTalhaoProcessor.java é a classe responsável por ler a mensagem, criar e tratar o JSON com a estrutura da Salesforce
5.5.2. SalesforceTalhaoHttpClient.java realiza a autenticação e realiza o envio se comunicando com a API Salesforce.