> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de mapeo de campos

> Referencia completa para mapeos de entrada, mapeos de salida y transformaciones de datos en los nodes executor de Flowker.

Los mapeos de campos y las transformaciones te permiten remodelar datos entre tu workflow y los servicios externos sin escribir código. Se definen dentro del objeto `data` de los nodes executor en la definición de tu workflow.

<Note>
  Estos campos viven dentro de la propiedad `data` del node — un objeto flexible de clave-valor que varía según el tipo de node. No son campos separados de primer nivel en el schema del workflow.
</Note>

## Mapeo de entrada

***

El mapeo de entrada convierte los campos del workflow en los campos que espera un executor. Flowker aplica los mapeos de entrada **antes** de llamar al servicio externo.

Define un array `inputMapping` en el objeto `data` del node executor. Cada entrada especifica un `source` (una ruta de campo del workflow) y un `target` (el campo del executor al que se mapea).

```json theme={null}
{
  "id": "executor-balance",
  "type": "executor",
  "name": "Check Balance",
  "data": {
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "inputMapping": [
      { "source": "workflow.customerId", "target": "executor.accountId" },
      { "source": "workflow.amount", "target": "executor.minimumBalance" }
    ]
  }
}
```

### Campos de una entrada de mapeo

| Campo            | Tipo    | Requerido | Descripción                                                                                                           |
| ---------------- | ------- | --------- | --------------------------------------------------------------------------------------------------------------------- |
| `source`         | string  | Sí        | JSONPath al valor de origen (p. ej., `workflow.customer.cpf`).                                                        |
| `target`         | string  | Sí        | JSONPath al campo destino (p. ej., `executor.document`).                                                              |
| `transformation` | object  | No        | Transformación opcional a aplicar durante el mapeo. Consulta [Transformaciones en línea](#transformaciones-en-línea). |
| `required`       | boolean | No        | Si es `true`, el mapeo falla cuando la ruta de origen no existe. Por defecto es `false`.                              |

## Mapeo de salida

***

El mapeo de salida extrae campos de la respuesta del executor y los escribe de vuelta en el contexto del workflow. Los nodes posteriores pueden entonces acceder a los valores mapeados. Flowker aplica los mapeos de salida **después** de recibir la respuesta.

```json theme={null}
{
  "data": {
    "outputMapping": [
      { "source": "executor.currentBalance", "target": "workflow.balance" },
      { "source": "executor.accountStatus", "target": "workflow.status" }
    ]
  }
}
```

Aplican los mismos campos de entrada que en el mapeo de entrada (`source`, `target`, `transformation`, `required`).

## Transformaciones en línea

***

Cuando un simple mapeo campo-a-campo no es suficiente, adjunta un objeto `transformation` a una entrada de mapeo. La transformación se aplica al valor de origen antes de escribirlo en el destino.

```json theme={null}
{
  "source": "workflow.phone",
  "target": "executor.phoneNumber",
  "transformation": {
    "type": "remove_characters",
    "config": {
      "characters": ".- ()"
    }
  }
}
```

### Tipos de transformación disponibles

| Tipo                | Qué hace                                        | Campos de configuración                         |
| ------------------- | ----------------------------------------------- | ----------------------------------------------- |
| `remove_characters` | Elimina caracteres especificados de una string. | `characters` — string de caracteres a eliminar. |
| `add_prefix`        | Antepone una string al valor del campo.         | `prefix` — string a anteponer.                  |
| `add_suffix`        | Agrega una string al valor del campo.           | `suffix` — string a agregar.                    |
| `to_uppercase`      | Convierte una string a mayúsculas.              | —                                               |
| `to_lowercase`      | Convierte una string a minúsculas.              | —                                               |

## Transformaciones Kazaam

***

Para transformaciones avanzadas JSON-a-JSON que van más allá del mapeo de campos, define un array `transforms` en el objeto `data` del node executor. Estas usan el motor de transformación [Kazaam](https://github.com/qntfy/kazaam).

```json theme={null}
{
  "data": {
    "transforms": [
      {
        "operation": "shift",
        "spec": {
          "outputField": "inputField"
        }
      }
    ]
  }
}
```

### Campos de una operación Kazaam

| Campo       | Tipo    | Requerido | Descripción                                                                                  |
| ----------- | ------- | --------- | -------------------------------------------------------------------------------------------- |
| `operation` | string  | Sí        | El tipo de operación Kazaam (p. ej., `shift`, `concat`, `remove_characters`).                |
| `spec`      | object  | Sí        | Configuración específica de la operación.                                                    |
| `require`   | boolean | No        | Si es `true`, todas las rutas referenciadas en `spec` deben existir. Por defecto es `false`. |

Kazaam soporta operaciones como `shift` (mover/renombrar campos), `concat` (combinar campos), `coalesce` (primer valor no nulo) y `default` (establecer valores de respaldo). Las operaciones personalizadas listadas en [transformaciones en línea](#transformaciones-en-línea) también están disponibles como operaciones de Kazaam.

<Note>
  Cuando uses transformaciones personalizadas como `remove_characters` en operaciones de Kazaam, el objeto `spec` debe incluir un campo `path` que apunte a la ruta JSON de los datos a transformar. Esto difiere de las transformaciones en línea, donde la ruta se deriva automáticamente del mapeo `source`/`target`.
</Note>

## Orden de ejecución

***

Cuando Flowker ejecuta un node executor:

1. Los **mapeos de entrada** se aplican primero — los datos del workflow se mapean al formato de entrada del executor.
2. Las **transformaciones Kazaam** se ejecutan a continuación sobre la entrada mapeada (si están definidas).
3. Se realiza la llamada al executor hacia el servicio externo.
4. Los **mapeos de salida** se aplican a la respuesta — los datos del executor se mapean de vuelta al contexto del workflow.

## Solución de problemas

***

Si una transformación falla durante la ejecución, el paso se marca como `failed` con un mensaje que indica qué mapeo causó el error.

Problemas comunes:

* **La ruta de origen no existe** — verifica que el node anterior realmente produzca el campo que estás referenciando. Establece `required: true` para detectar campos faltantes a tiempo.
* **Desajuste de tipo** — las conversiones de string a número no son automáticas. Usa una transformación para convertir formatos.
* **Spec de Kazaam inválido** — verifica el nombre de la operación y la estructura del spec contra la documentación de Kazaam.