Carol

Árvore de páginas

A Carol permite efetuar o consumo de dados do Data Subscription. Esse recurso permite sincronizar dados da Carol para outros ambientes através de uma arquitetura similar ao Web Hook.


Nesta arquitetura, você registra na Carol o seu endpoint preparado para receber os dados da Carol, e quando esse Data Model receber novos registros, atualizações ou eliminação de dados, uma mensagem será enviada ao seu endpoint propagando a ação ocorrida na plataforma Carol.


Esse recurso deve ser utilizado em casos especificos, sendo que normalmente o consumo dos dados na plataforma Carol através de comandos SQL já é suficiente para vários cenários.


Índice


Visão Geral


Neste capítulo da documentação vamos efetuar os seguintes passos:

  • Configuração em Data Model com o recurso de Data Subscription.
  • Recebimento de mensagens no endpoint (inclusão/alteração e eliminação de registros).
  • Aplicativo NodeJS de com implementação de exemplo.


Configuração Data Model


Para habilitar o Data Subscription, você deve incluir o endpoint que estará preparado para processar as mensagens enviadas pela Carol. Para isso, abra o módulo Data Model e vá na opção Option e depois Data Subscription:



Na tela que abrir, você poderá efetuar ajustes em Subscriptions existentes ou adicionar novas. Um Data Model pode ter várias subscriptions enviando os dados para endereços diferentes.



Para adicionar uma subscription, você deve informar os seguintes parâmetros:


PropriedadeDescrição
Subscription NameNome da subscrição. Deverá ser úncio por Data Model e ele é obrigatório. Este é utilizado como identificador.
ConnectorO conector relacionado ao consumo dos dados. Parâmetro obrigatório.
Start date & timeData de início para o recebimento dos dados, este é utilizado para determinar a carga inicial a ser enviada.
Content-EncodingEncoding dos dados, podendo sere GZIP ou SNAPPY.
Webhook URLA URL do Webhook que vai receber os dados. Essa URL aponta para o endpoint que está preparado para receber requisições POST conforme o content-encoding definido acima.
Max Batch SizeO tamanho máximo de eventos/registros que será enviado para a URL acima. Batches menores são esperados, sendo que as mensagens são enviadas de forma online. Uma sugestão de valor é 700 ou 1000 mensagens. Quanto maior melhor, e deve haver preocupação quanto ao tempo da URL em processar esses dados antes de alcançar timeout.
Max in FlightNúmero de envio paralelo que pode ocorrer. Neste caso, se o Max Batch estiver definido com 1000 e o Max in Flight estiver com 5, a URL poderá receber, no total, 5000 mensagens paralelamente. Um valor recomendado é 2, ou acima. Atentar se o endpoint acima está preparado para escalar se receber mensagens simultaneamente.
Max RetriesEste parâmetro define a quantidade máxima de tentativas para entregar a mesma mensagem antes de descartar a mensagem. Este parâmetro é para evitar a Carol tentando entregar repetidamente a mensagem sem o recebimento de ACK (será discutido mais abaixo). Valor padrão 10.
HeadersCaso seja necessário algum header para o endpoint acima, este deverá estar especificado nesta lista.


Exemplo de configuração:


Com essa configuração estamos preparados para receber dados da Carol. Agora é necessário o processamento de dados na plataforma para que os dados sejam recebidos.


Simulador Endpoint

Você pode utilizar o http://pipedream.com/ para simular a criação de um endpoint e executar os testes descritos neste capítulo.


Recebimento de mensagens


A Carol efetua o envio de mensagens no formato abaixo:

Exemplo mensagem Data Subscription
{
  "messageId": "2453103412224342",
  "publishedAt": "2021-05-28T22:38:56.188538Z",
  "records": [
    {
      "mdmCounterForEntity": 1622241532763000,
      "mdmCreated": "2021-05-28T22:38:52.763Z",
      "mdmDeleted": false,
      "mdmEntityTemplateId": "eec1dd50a14546a6894e7636ba03f62f",
      "mdmEntityType": "apinvoiceaccountingGolden",
      "mdmGoldenFieldAndValues": {
        "amount": 1000,
        "account_id": "f768115f14863655f390e996d125699b",
        "invoice_id": "40b090c2867f26aa6f13918430e5a58c",
        "invoiceaccounting_id": "00434889e9627d466ecf4f40da482921",
        "_orgid": "1728332a9cddf2f391aa7b48a23255e2",
        "costcenter_id": "be1f4298cd0eb0733a7c92bb3a8ae034"
      },
      "mdmId": "d3f1c0cf246bf087ff001a1d98dc4125",
      "mdmLastUpdated": "2021-05-28T22:38:52.763Z",
      "mdmMasterCount": 1,
      "mdmPreviousIds": [],
      "mdmTenantId": "3895e1c66df14611bc017a69594a3894"
    }
  ],
  "subscriptionId": "624bccd237c44ddc883bbc7689c4bd83",
  "subscriptionName": "apinvoiceaccounting",
  "subscriptionType": "GOLDEN",
  "tenantId": "3895e1c66df14611bc017a69594a3894"
}


Observações sobre a mensagem recebida:

  • As mensagens podem conter dentro de "records" a quantidade máxima de registros informado em "Batch Size" do subscription.
  • Um documento em "records" significa um golden record na plataforma Carol.
  • Eventos de eliminação de registro são propagados com o atributo "mdmDeleted" com o valor "true" por padrão. Todas as columas do Golden Record são enviados para facilitar o processo de integração e identificação do registro por parte do endpoint.


Feature Flag Propagação de Mensagens de eliminação

A propagação de mensagens quando registros são eliminados eram feitos pelo parâmetro "mdmSubscriptionDeletesEnabled". Porém o mesmo foi removido da plataforma, uma vez que uma vez deletados, a plataforma envia por padrão esta mensagem de notificação de deletados.



Formas de responder mensagens recebidas (ACK):

Respondendo ACK para todos os registros recebidos:

ACK total
{
  "ack": true
}



Respondendo ACK e informando registros que devem ser reenviados:

ACK Parcial
{
  "ack": true, 
  "redeliverRecordIds": [
    "{golden_record_id_1}",
    "{golden_record_id_2}"
  ]
}



Respondendo ACK falso e informando o motivo:

ACK Falso com motivo
{
  "ack": false,
  "message": "Failed constraint xyz"
}


Observabilidade/Monitoramento mensagens Data Subscription


Você pode monitorar o envio de mensagens pelo Data Subscription através do Carol Insights Studio, pelo link: https://carol.ai/insights/dashboard/102


Informações disponíveis:

  • Quantidade de mensagens enviadas com o ACK (true/false).
  • Motivo pelo ACK falso, quando o endpoint disponibiliza.


É possível customizar a query para filtrar dados em especifico e facilitar o processo de debug.


Código fonte de Exemplos


O repositório abaixo possui um exemplo implementado em NodeJS que abre uma API para receber mensagens do Data Subscription.

https://github.com/totvslabs/caroljs/

Se você tiver alguma dúvida ou sugestão, você pode enviar através do projteto no Github.


Próximos Passos

Agora você deve praticar o ciclo de vida dos dados na Carol, desde o processo de injestão de dados até o consumo através de recursos SQL ou Data Subscription. Se tiver alguma dúvida, abra um chamado no Zendesk.