Páginas filhas
  • Integração com Salesforce - Arquitetura

Versões comparadas

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.


  1. Visão Geral
  2. Arquitetura TOTVS
    1. TOTVS Connector Client
    2. TOTVS Connector Server
    3. TOTVS Agro Plataforma
    4. TOTVS Agro Conecta Dados
    5. Monitoramento TOTVS Apps

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).

A partir destes eventos, dados mestres de Locais de Produção são compartilhados com a plataforma Salesforce, possibilitando a criação de novos contratos (no Salesforce). Desta forma, esta documentação técnica fornece detalhes arquiteturais e de tecnologia para tal integração (via TOTVS Agro Plataforma e TOTVS Agro Conecta Dados).

Salesforce Integration - Guia de Referência

TOTVS Agro Bioenergia (Pagadoria APIs) - Configuração IIS

02. Arquitetura TOTVS

Na imagem abaixo, podemos ver com detalhes o fluxo geral, desde quando os dados saí do TOTVS Agro Bioenergia até chegar para Salesforce. O fluxo é divido em 3 etapas que serão detalhadas de acordo com decorrer do material, essas etapas são:

    • 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.

    • 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 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 mensagem com JSON, que será adaptada ao modelo repassado pela Salesforce, portanto, após a autenticação com os dados informado na interface web do TOTVS Agro Conecta Dados, fazemos uma requisição PATCH passando os novos dados tratados;
    • 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

O TOTVS Agro Connector Client é um aplicação On-Premise, 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.



No Swagger, cadastramos a base de dados do produto, no caso TOTVS Agro Bioenergia.



Hoje, trabalhamos com 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:


UPNIVEL1UPNIVEL2UPNIVEL3
CD_UPNIVEL1CD_UPNIVEL1 + CD_UPNIVEL2CD_SAFRA + CD_UPNIVEL1 + CD_UPNIVEL2 + CD_UPNIVEL3
CD_UPNIVEL1CD_UPNIVEL1CD_SAFRA
CD_MUNICCD_UPNIVEL2CD_UPNIVEL1
CD_FORNECCD_MUNICCD_UPNIVEL2
DE_UPNIVEL1DE_UPNIVEL2CD_UPNIVEL3
DE_ENDERECOQT_AREA_TOTCD_TP_PROPR
NO_TELEFONEQT_AREA_PRODDS_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, 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.


2.2. TOTVS Agro Connector Server

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.



Também é responsável por receber os dados que o TOTVS Agro Connector Client envia. 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 à do RabbitMQ (mencionado acima).


      Bloco de código
      themeConfluence
      {
         "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"
         }
      }

2.3. TOTVS Agro Plataforma

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 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 de JSON que irá para fila do rabbit mostrado acima.


      Bloco de código
      themeConfluence
      {
         "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
         }
      }

2.4. TOTVS Agro Conecta Dados

    • O TOTVS Agro Conecta Dados Front é 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 front, com isso ele monta o JSON baseado no modelo enviado e processamos a requisições PATCH para Salesforce, conforme alguns exemplos abaixo:


Aviso
titleAtenção

Para realizar as requisições é necessário passar o token recuperado, após autenticação.


Abaixo será exibidos as tabelas disponibilizadas para nós com base na API deles, ou seja o que devemos passar no body da requisição como JSON e exemplos de como estamos utilizando cada uma no postman:


    • Modelo à ser enviado: FAZENDA (Local de Producão 1) para Salesforce.

      APITipoDescrição
      IdConta__ctextoId Fazenda
      CodigodaPropriedade__cTexto(6) (ID Externo)Cod Fazenda
      Municipio__r.codigoMunicipio__cPesquisaCod Municipo PIMS
      codigoFornecedor__cNumero(8)Cod Fornecedor
      descricaoCompleta__ctexto(70)Descrição Completa
      BillingStreettexto(70)Endereço
      Phonetexto(70)Telefone
      cnpjCPF__ctexto(18)CNPJ ou CPF
      numeroIncra__ctexto(15)N° INCRA
      numeroInscricaoProdutorRural__ctexto(20)N° Insc.Produtor Rural
      Cep__ctexto(16)N° cep
      Tipo_de_Pessoa__ctexto(1)
      QtdeAreaTotalHA__cnumero(7,2)
      QtdeAreaTotalProdHectares__cnumero(7,2)
      codigoInternoErp__ctexto(15)
      Instancia__r.CodigoInstanciaPIMS__ctexto(5)
      flagAtivo__cLista de Opçoes


    • Modelo à ser enviado: SETOR (Local de Producão 2) para Salesforce.

      APITipoDescrição
      IdBloco__cTexto(6) (ID Externo)Id Bloco
      Conta__r.IdConta__cPesquisa(Conta)Cod Fazenda
      codigoBloco__cTexto(6) (ID Externo)Cod Bloco
      Municipio__r.codigoMunicipio__cPesquisaCod Municipo PIMS
      NameNameDescrição do Bloco
      Hectares__cNumber(16,2)Qtde de Area Total em Hectares
      AreaProdutivaHA__cNumber(16,2)Qtde de Area Produtiva em Hectares


    • Modelo à ser enviado: TALHÃO (Local de Producão 3) para Salesforce.

      APITipoDescrição
      IdTalhao__cTextoId Talhão
      Safra__cNumero(5)Codigo da Safra
      Conta__r.IdConta__cTexto(6)Cod Fazenda
      Bloco__r.IdBloco__cPesquisaCod Bloco
      codigoTalhao__c (ID Externo)Texto(6)Cod Talhão
      CodigoTipoPropriedade__cLista de OpçõesCod Tipo de Propriedade
      DistanciaTerra__cNumero(4,1)Distância Terra
      DistanciaAsfalto__cNumero(4,1)Distância Asfalto
      DistanciaHidrovia__cNumero(4,1)Distância Hidrovia
      CodigoSistemaColheita__cLista de OpçõesCodigo de Sistema de Colheita
      DataPlantio__cDateData do Plantio
      CodigoOcupacao__cLista de OpçõesCodigo de Ocupação
      CodigoVariedade__cLista de OpçõesCodigo de Variedade
      CodigoEstagio__cLista de OpçõesCodigo de Estagio
      CodigoEspacamento__cLista de OpçõesCodigo de Espaçamento
      CodigoSistemaPlantio__cLista de OpçõesCodigo de Sistema de Plantio
      AreaProdutivaHA__cNumber(7,2)Qtde de Area Produtiva em Hectares
      CodigoOcupacaoAnterior__cLista de OpçõesCodigo de Sistema de Plantio Anterior
      FlagTipoPlantio__cLista de OpçõesFlag 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