Conector File Format

Descripción General

Los conectores File Format parsean y serializan formatos de texto estructurados embebidos dentro de campos de la carga. Cada conector lee desde inputKey y escribe el resultado en outputKey; todos los demás campos de la carga se pasan sin cambios.

Tipos de Conector: CsvProcessor, XmlProcessor

CSV

Modo Parse

Lee una cadena CSV desde inputKey y escribe un valor estructurado en outputKey.

{
  "type": "CsvProcessor",
  "config": {
    "direction": "parse",
    "delimiter": ",",
    "hasHeader": true,
    "inputKey": "raw_csv",
    "outputKey": "rows"
  }
}

Con hasHeader: true, la salida es un array de map[string]string con clave por la fila de cabecera. Con hasHeader: false, la salida es un array de arrays ([][]string).

Modo Serialize

Lee un array de arrays desde inputKey y escribe la cadena CSV en outputKey.

{
  "type": "CsvProcessor",
  "config": {
    "direction": "serialize",
    "delimiter": ";",
    "inputKey": "rows",
    "outputKey": "csv_text"
  }
}

Parámetros de Configuración

• direction (obligatorio): parse o serialize
• inputKey (obligatorio): Clave de la carga que contiene el valor fuente
• outputKey (obligatorio): Clave de la carga en la que escribir el resultado
• delimiter: Delimitador de campo de un solo carácter (por defecto ,)
• hasHeader: Cuando es true durante parse, trata la primera fila como nombres de columna

XML

Modo Parse

Lee una cadena XML desde inputKey y escribe un mapa anidado en outputKey. El contenido textual se almacena bajo la clave _text cuando los elementos contienen hijos mixtos.

{
  "type": "XmlProcessor",
  "config": {
    "direction": "parse",
    "inputKey": "raw_xml",
    "outputKey": "parsed"
  }
}

Modo Serialize

Lee un mapa desde inputKey y escribe una cadena XML en outputKey, envuelta en rootElement.

{
  "type": "XmlProcessor",
  "config": {
    "direction": "serialize",
    "inputKey": "data",
    "outputKey": "xml_text",
    "rootElement": "report"
  }
}

Parámetros de Configuración

• direction (obligatorio): parse o serialize
• inputKey (obligatorio): Clave de la carga que contiene el valor fuente
• outputKey (obligatorio): Clave de la carga en la que escribir el resultado
• rootElement: Etiqueta raíz que envuelve la salida serializada (por defecto root)

Casos de Uso

1. Ingestar exportaciones CSV heredadas desde sistemas MES o SCADA
2. Hacer de puente entre protocolos industriales basados en XML y conectores descendentes nativos de JSON
3. Emitir archivos CSV a S3 o almacenamiento local para informes
4. Parseo en línea de cargas CSV/XML recibidas por MQTT o HTTP

Ejemplo: Pipeline de Ingesta CSV

{
  "type": "CsvProcessor",
  "config": {
    "direction": "parse",
    "delimiter": ",",
    "hasHeader": true,
    "inputKey": "body",
    "outputKey": "records"
  }
}

Combinado con una fuente HTTP, esto convierte una carga CSV entrante en un array records estructurado que puede alimentar a Transform, Validation o un sumidero de base de datos.

Mejores Prácticas

• Para CSV con delimitadores no estándar (;, \t, |), define delimiter explícitamente
• Define siempre hasHeader: true cuando los conectores descendentes referencian columnas por nombre
• Para XML profundamente anidado, encadena el parser con Transform usando JSONPath para extraer rutas específicas
• Conserva el texto crudo en una clave dedicada (ej. raw_csv) para preservar el original si una etapa descendente falla

Conectores Relacionados

• Transform - Extraer valores vía JSONPath después del parseo
• Reshape - Renombrar o remapear campos parseados
• Protocol Translator - Convertir entre formatos estructurados