Marshal

O EIP Marshal converte o formato interno (objetos ou estruturas) para um formato externo (como JSON ou XML) para comunicação ou armazenamento. Por exemplo, ele pode converter um objeto Java em uma representação JSON ou XML.

Diferença entre Marshal e Unmarshal

Marshal e Unmarshal são processos fundamentais para a manipulação de dados, permitindo a interoperabilidade entre sistemas.

Marshal: é o processo de transformar dados do formato interno do Camel para um formato externo padronizado, como JSON, XML, CSV, ou outros. Essa conversão é essencial para integrar o fluxo com sistemas externos, enviar mensagens a APIs, ou armazenar informações em arquivos de forma estruturada.
Unmarshal: trata-se do processo inverso, onde dados recebidos em um formato externo (por exemplo, JSON, XML, CSV) são convertidos para o formato interno utilizado pelo Camel. Esse passo é necessário para que as mensagens possam ser manipuladas, processadas ou roteadas dentro do fluxo de integração do Camel.

Custom

Na lista de tipos de formatos de dados disponíveis em Data Format Type, existe a opção Custom.

Com ela, você pode utilizar Excel como referência, possibilitando que o fluxo de integração processe arquivos nos formatos .xls e .xlsx.

Este data format converterá as linhas da planilha especificada em um array de objetos JSON. O objeto JSON gerado para cada célula conterá, além do valor, metadados sobre o tipo do dado.

Os estilos visuais da planilha (cor da célula, cor da fonte, negrito, bordas e outros) não são importados.

Para usar o componente, considere estas orientações:

O setHeader SensediaExcelFormat indica se o arquivo é do tipo .xls ou .xlsx.
- Se o valor informado for diferente, o componente indicará erro.
- Se o setHeader não for enviado, será considerado .xlsx por padrão.
O setHeader SensediaExcelSheetNames traz uma lista de nomes de abas da planilha, separados por vírgula.
- Somente as abas listadas no setHeader serão migradas.
- Se algum nome informado não existir na planilha, ele será ignorado.
Se o setHeader SensediaExcelSheetNames existir, mas nenhum dos nomes corresponder a uma aba da planilha, o componente indicará erro.
O uso de fórmulas é permitido. Contudo, se a fórmula estiver incorreta, a célula no Excel indicará erro.

Formato do JSON

Após a conversão de um arquivo Excel para JSON, os dados são organizados da forma mostrada no JSON Schema a seguir:

{
  "type": "object",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Excel spreadsheet data schema",
  "description": "Schema for a data structure representing one or more spreadsheets with rows and cells.",
  "properties": {
    "sheets": {
      "description": "An array containing data for each sheet",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "The name of the sheet.",
            "type": "string"
          },
          "rows": {
            "description": "The rows within a single sheet",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "cells": {
                  "description": "The rows within a single row",
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "v": {
                        "description": "The value of the cell. Can be a string, a number, or a boolean.",
                        "oneOf": [
                          { "type": "string" },
                          { "type": "number" },
                          { "type": "boolean" }
                        ]
                      },
                      "addr": {
                        "description": "The address of the cell (e.g., 'A1').",
                        "type": "string"
                      },
                      "type": {
                        "description": "The data type of the cell.",
                        "type": "string",
                        "enum": [
                          "str",
                          "num",
                          "bool",
                          "blank",
                          "formula"
                        ],
                        "default": "str"
                      },
                      "fmt": {
                        "description": "The formatting string for the cell's value.",
                        "type": "string",
                        "default": "General"
                      }
                    },
                    "required": [
                      "addr"
                    ],
                    "additionalProperties": false
                  }
                }
              },
              "required": [
                "cells"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "name",
          "rows"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "sheets"
  ],
  "additionalProperties": false
}

Comparação entre Excel e JSON

Agora, compare uma planilha Excel com sua versão em formato JSON:

Excel

planilha excel borda

JSON

{
  "sheets": [
    {
      "name": "Sheet1",
      "rows": [
        {
          "cells": [
            {
              "v": "Produto",
              "addr": "A1"
            },
            {
              "v": "Preço Unitário",
              "addr": "B1"
            },
            {
              "v": "Data/hora",
              "addr": "C1"
            },
            {
              "v": "Ativo",
              "addr": "D1"
            },
            {
              "v": "Quantidade",
              "addr": "E1"
            },
            {
              "v": "Desconto (%)",
              "addr": "F1"
            },
            {
              "v": "Preço Total",
              "addr": "G1"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Caneta",
              "addr": "A2"
            },
            {
              "type": "num",
              "v": 2.5,
              "addr": "B2"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C2",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D2",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 10,
              "addr": "E2"
            },
            {
              "type": "num",
              "v": 0,
              "addr": "F2"
            },
            {
              "type": "num",
              "v": 25,
              "addr": "G2"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Caderno",
              "addr": "A3"
            },
            {
              "type": "num",
              "v": 15,
              "addr": "B3"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C3",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D3",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 5,
              "addr": "E3"
            },
            {
              "type": "num",
              "v": 10,
              "addr": "F3"
            },
            {
              "type": "num",
              "v": 67.5,
              "addr": "G3"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Lápis",
              "addr": "A4"
            },
            {
              "type": "num",
              "v": 1.5,
              "addr": "B4"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C4",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D4",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 20,
              "addr": "E4"
            },
            {
              "type": "num",
              "v": 5,
              "addr": "F4"
            },
            {
              "type": "num",
              "v": 28.5,
              "addr": "G4"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Borracha",
              "addr": "A5"
            },
            {
              "type": "num",
              "v": 3,
              "addr": "B5"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C5",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": true,
              "addr": "D5",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 8,
              "addr": "E5"
            },
            {
              "type": "num",
              "v": 0,
              "addr": "F5"
            },
            {
              "type": "num",
              "v": 24,
              "addr": "G5"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Régua",
              "addr": "A6"
            },
            {
              "type": "num",
              "v": 4.5,
              "addr": "B6"
            },
            {
              "type": "num",
              "v": 45915.4131373611,
              "addr": "C6",
              "fmt": "m/d/yyyy\\ h:mm:ss"
            },
            {
              "type": "bool",
              "v": false,
              "addr": "D6",
              "fmt": "\"TRUE\";\"TRUE\";\"FALSE\""
            },
            {
              "type": "num",
              "v": 3,
              "addr": "E6"
            },
            {
              "type": "num",
              "v": 15,
              "addr": "F6"
            },
            {
              "type": "num",
              "v": 11.475,
              "addr": "G6"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Total Geral",
              "addr": "A7"
            },
            {
              "type": "num",
              "v": 156.475,
              "addr": "G7"
            }
          ]
        },
        {
          "cells": [
            {
              "v": "Média Preço Unitário",
              "addr": "A8"
            },
            {
              "type": "num",
              "v": 5.3,
              "addr": "G8"
            }
          ]
        }
      ]
    }
  ]
}

Exemplo de código

Este fluxo expõe um endpoint REST (GET /teste-excel) que, ao ser chamado, baixa um arquivo Excel de um servidor SFTP, converte o conteúdo em JSON e retorna o resultado.

O processamento ocorre da seguinte forma:

Recebe a requisição REST.
Registra no log o início do download do arquivo via SFTP.
Realiza o download do arquivo no servidor SFTP.
Registra no log a conclusão do download e a conversão para JSON.
Converte o conteúdo para byte[].
Define no setHeader as abas da planilha que serão processadas (test1,test2).
Utiliza o marshal com o data format excel (custom) para transformar o arquivo em JSON.
Define o setHeader Content-Type como application/json para a resposta.

- from:
    uri: rest:get:/teste-excel
    steps:
      - log:
          message: "Iniciando o download do arquivo via SFTP."
      - pollEnrich:
          expression:
            simple: "sftp:eu-central-1.sftpcloud.io:22/download?username={{user}}&password={{pass}}&passiveMode=true&delete=false&fileName={{file}}&binary=true&knownHostsFile=/dev/null&strictHostKeyChecking=no"
      - log:
          message: "Download concluído. Convertendo para JSON."
      - convertBodyTo:
          type: byte[]
      - setHeader:
          name: SensediaExcelSheetNames
          expression:
            constant:
              expression: test1,test2
      - marshal:
          custom:
            ref: excel
      - setHeader:
          name: Content-Type
          constant: application/json

O Excel também pode ser usado em fluxos com o EIP unmarshal (para transformar arquivos JSON em Excel).

Neste caso, o campo addr do JSON de entrada não será considerado.
A montagem das linhas e colunas será feita baseado apenas na ordem das linhas e células. *
O resultado do unmarshal será um byte[].

Exemplos

Veja a seguir exemplos de outros formatos:

CSV
- A mensagem será convertida para csv.
- Nenhum parâmetro adicional é necessário.

- marshal:
    csv: {}

JSON
- A mensagem será convertida para json.
- Será usada a biblioteca Jackson para serializar o corpo da mensagem.

- marshal:
    json:
      library: Jackson

XML
- A mensagem será convertida para XML.
- O jacksonXml utiliza a biblioteca Jackson, mas também existe o formato genérico xml.

- marshal:
    jacksonXml: {}

- marshal:
    xml: {}

Veja como adicionar um data format diretamente pelo formulário do EIP na aba Diagram:

marshal json

Ao selecionar o formato JSON, o campo Library é preenchido automaticamente com o valor padrão "Jackson". Como é o padrão, ele não é exibido no script do fluxo na aba Source Code, aparecendo apenas se for alterado para um valor diferente.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]