JOLT e Double Braces na Digibee: Escolhendo o método certo para transformar dados

A Digibee capacita usuários a conectar sistemas diversos e orquestrar fluxos de dados complexos. Uma parte importante desse processo é a transformação de dados, pois permite remodelar e adaptar os dados para atender à estrutura e aos requisitos dos sistemas de destino.

Na Digibee, dois métodos principais estão disponíveis para transformar dados:

• JOLT: Transformação de JSON para JSON

• Double Braces: Linguagem de expressões própria da Digibee

Compreender quando usar cada uma dessas abordagens ajuda a criar transformações claras e fáceis de manter. Este artigo explora os pontos fortes e os casos de uso tanto do JOLT quanto do Double Braces, orientando você a escolher o mais adequado para suas necessidades específicas de transformação.

Entendendo o JOLT: O arquiteto do JSON

JOLT é uma linguagem de transformação baseada em JSON projetada para remodelar documentos JSON inteiros. Ele funciona por meio de uma série de especificações que definem como o JSON de entrada deve ser transformado na estrutura de saída desejada. O JOLT pode lidar com alterações estruturais complexas ao combinar várias especificações em uma única transformação, permitindo mover, renomear e reorganizar dados. A Digibee disponibiliza o conector Transformer (JOLT) para realizar transformações com JOLT.

Resumo das operações principais

O JOLT fornece uma série de operações para remodelar dados JSON, incluindo:

• shift: Move e renomeia campos.

• default: Insere valores padrão para campos ausentes.

• remove: Exclui campos.

• sort: Ordena os campos em ordem alfabética.

• cardinality: Alterna entre itens únicos e arrays.

• modify-default-beta / modify-overwrite-beta: Adiciona ou atualiza campos dinamicamente com funções.

O JOLT também oferece suporte a wildcards como *, @, $ e outros. Isso o torna flexível para evoluir estruturas JSON sem precisar conhecer todos os nomes de campos com antecedência.

Para explorar cada operação em detalhes, confira o artigo Conhecendo o JOLT.

Casos de uso do JOLT

1. Padronização de dados de múltiplas fontes: Imagine receber dados de clientes de diferentes sistemas, cada um com sua própria estrutura JSON. A operação shift do JOLT pode mapear campos como customerName e nameClient para customer.fullName no seu modelo de dados.

// Entrada do Sistema A
{
  "customerName": "Alice Smith",
  "email": "[e-mail]"
}

// Entrada do Sistema B
{
  "nameClient": "Bob Johnson",
  "correo": "[e-mail]"
}

// Transformação JOLT
[
  {
    "operation": "shift",
    "spec": {
      "customerName|nameClient": "customer.fullName",
      "email|correo": "customer.email"
    }
  }
]

// Saída (para o Sistema A)
{
  "customer": {
    "fullName": "Alice Smith",
    "email": "[e-mail]"
  }
}
// Saída (para o Sistema B)
{
  "customer": {
    "fullName": "Bob Johnson",
    "email": "[e-mail]"
  }
}

1. Achatamento de estruturas JSON aninhadas: Ao lidar com APIs que retornam dados aninhados, a notação de ponto do JOLT na operação shift pode achatar essas estruturas para facilitar o processamento.

// Entrada
{
  "order": {
    "details": {
      "orderId": "12345",
      "totalAmount": 100.5
    },
    "customer": {
      "name": "Charlie Brown"
    }
  }
}

// Transformação JOLT
[
  {
    "operation": "shift",
    "spec": {
      "order": {
        "details": {
          "orderId": "orderId",
          "totalAmount": "totalAmount"
        },
        "customer": {
          "name": "customerName"
        }
      }
    }
  }
]

// Saída
{
  "orderId" : "12345",
  "totalAmount" : 100.5,
  "customerName" : "Charlie Brown"
}

1. Processamento de arrays de objetos: O JOLT pode transformar arrays de objetos. Em vez de iteração explícita, suas especificações se aplicam a cada objeto no array. Isso é útil para padronizar dados dentro de uma lista, extrair informações específicas de cada item ou reestruturar coleções de dados.

Imagine receber uma lista de produtos de diferentes fornecedores, cada um com nomes de campos distintos. O JOLT pode padronizar essa lista em um formato consistente.

// Entrada do Fornecedor A
{
  "products": [
    {"productName": "Laptop", "priceUSD": 1200},
    {"productName": "Mouse", "cost": 25}
  ]
}

// Entrada do Fornecedor B
{
  "items": [
    {"name": "Keyboard", "value": 75},
    {"name": "Monitor", "price_eur": 300}
  ]
}

// Transformação JOLT
[
  {
    "operation": "shift",
    "spec": {
      "products": {
        "*": {
          "productName|name": "productsOut[].name",
          "priceUSD|cost|value|price_eur": "productsOut[].price"
        }
      },
      "items": {
        "*": {
          "productName|name": "productsOut[].name",
          "priceUSD|cost|value|price_eur": "productsOut[].price"
        }
      }
    }
  }
]

// Saída (para o Fornecedor A)
{
  "productsOut": [
    {"name": "Laptop", "price": 1200},
    {"name": "Mouse", "price": 25}
  ]
}

// Saída (para o Fornecedor B)
{
  "productsOut": [
    {"name": "Keyboard", "price": 75},
    {"name": "Monitor", "price": 300}
  ]
}

1. Extração de dados de uma lista de usuários: O JOLT pode extrair apenas o id e o email de um array de objetos de usuários.

// Entrada
{
  "users": [
    {"userId": "user123", "emailAddress": "[e-mail]", "details": {"age":40 }},
    {"userId": "user456", "emailAddress": "[e-mail]", "info": {"country":"BR" }}
  ]
}

// Transformação JOLT
[
  {
    "operation": "shift",
    "spec": {
      "users": {
        "*": {
          "userId": "usersOut[&1].id",
          "emailAddress": "usersOut[&1].email"
        }
      }
    }
  }
]

// Saída
{
  "usersOut": [
    {"id": "user123", "email": "[e-mail]"},
    {"id": "user456", "email": "[e-mail]"}
  ]
}

Para explorar mais exemplos do mundo real e casos de uso avançados, confira o artigo Transformações com JOLT.

Entendendo o Double Braces: O motor por trás dos conectores Digibee

Double Braces é a linguagem de expressões da Digibee. Ela foi desenvolvida para o acesso e a manipulação dinâmica de dados dentro da configuração dos conectores e cápsulas da Digibee. Diferente do JOLT, que transforma estruturas JSON inteiras usando especificações separadas, o Double Braces permite referenciar e manipular dados diretamente nos parâmetros da maioria dos conectores da Digibee, como o JSON Generator, o JSON Transformer e muitos outros.

Uma característica importante do Double Braces é sua abordagem baseada em funções e sua capacidade de acessar diversos aspectos do contexto de execução, incluindo o payload da mensagem recebida, metadados do pipeline, contas e variáveis globais.

Casos de uso do Double Braces

1. Construção dinâmica de JSON com o JSON Generator: O conector JSON Generator (Mock) é um bom exemplo de como o Double Braces pode ser usado para criar objetos JSON dinamicamente, permitindo:

   • Inserir valores da mensagem recebida incorporando campos diretamente do JSON de entrada usando {{ message.nomeDoCampo }}.

   • Transformar dados utilizando várias funções embutidas do Double Braces, como manipulação de strings, lógica condicional, matemática, formatação de datas e mais.
   • Adicionar valores estáticos usando funções como CONCAT para combinar strings fixas com valores dinâmicos, como {{ CONCAT("Usuário ", message.userId) }}.

   • Acessar variáveis globais e contas recuperando valores predefinidos com {{global.nome-global}} ou {{ account.username }}.

2. Combinação de campos e cálculo de valores: As funções do Double Braces podem ser usadas para concatenar valores de campos e também realizar cálculos dinâmicos na mesma etapa de transformação.

// Entrada
{
  "firstName": "Carlos",
  "lastName": "Silva",
  "orderTotal": "95.756"
}

// Configuração do JSON Generator com Double Braces
{
  "fullName": {{ CONCAT(message.firstName, " ", message.lastName) }},
  "taxAmount": {{ TONUMBER(message.orderTotal, "###.##") }},
  "country": "Brazil"
}

// Saída
{
  "fullName": "Carlos Silva",
  "taxAmount": 95.756,
  "country": "Brazil"
}

1. Processamento condicional de dados: Com o Double Braces, você pode decidir como prosseguir com a execução do pipeline ou como transformar os dados.

// Mensagem recebida (exemplo)
{
  "countryCode": "US"
}

// Configuração do JSON Generator com Double Braces
{
  "shippingRegion": {{ SWITCHCASE("Other", EQUALTO(message.countryCode, "US"), "North America", EQUALTO(message.countryCode, "CA"), "North America",EQUALTO(message.countryCode, "EU"), "Europe") }}
}

// Saída (com a propriedade adicionada)
{
  "shippingRegion": "North America"
}

Dica: O JSON Transformer é uma alternativa para manipular dados sem alterar a estrutura original do JSON — a menos que você queira remover algo. Ele permite centralizar transformações em um único conector, mantendo os fluxos mais limpos e fáceis de manter.

Quando usar cada um: Um guia para decisão

A tabela e as diretrizes abaixo não são regras rígidas, mas sim sugestões para ajudar você a tomar decisões e simplificar o desenvolvimento.

Aspecto	JOLT	Double Braces
Objetivo principal	Reestruturar documentos JSON	Manipular valores de campos individuais e acessar o contexto
Escopo	Estrutura JSON inteira	Valores de campos específicos ou contexto do pipeline
Complexidade	Lida com mudanças estruturais complexas	Lida com lógica granular
Contexto	Foca no payload JSON	Acessa o contexto mais amplo do pipeline Digibee
Uso na Digibee	Etapa de transformação dedicada	Embutido em parâmetros de conectores e cápsulas

Escolha JOLT quando

• Sua principal tarefa é remodelar a estrutura do JSON (achatar, aninhar, mapear elementos em arrays, entre outros).

• Precisa renomear e mover um número significativo de campos.

• Está lidando com estruturas JSON diferentes ou desconhecidas e precisa de transformações dinâmicas com curingas.

• Precisa transformar arrays de objetos aplicando regras consistentes a cada elemento.

Escolha Double Braces quando

• Precisa realizar conversões de tipo de dado (formatação de datas).

• Precisa implementar lógica condicional para atribuir valores com base nos dados.

• Precisa manipular strings (concatenação, substring).

• Precisa acessar elementos específicos dentro de arrays ou objetos JSON.

• Precisa integrar valores dinâmicos com base nos metadados do pipeline.

• Precisa usar valores armazenados em variáveis de sessão.

Uma observação sobre o JSLT

Embora este artigo foque em JOLT e Double Braces como os principais métodos de transformação disponíveis na Digibee, sinta-se à vontade para explorar o conector JSLT, uma linguagem de transformação alternativa com sintaxe semelhante ao JavaScript. Ele permite modificar, extrair, remover, ordenar e acessar dados de conteúdos JSON.

Considerações finais

Combinar JOLT e Double Braces é um passo fundamental para criar transformações de dados flexíveis e sustentáveis dentro da Digibee Integration Platform. Ao entender os pontos fortes de cada abordagem e saber quando usá-las separadamente ou em conjunto, você pode simplificar sua lógica de transformação, reduzir a complexidade e manter seus pipelines adaptáveis conforme as necessidades mudam.