Trabajar con los datos de la solicitud y de la respuesta

Un node executor envía datos a un servicio externo y recibe datos de vuelta. El servicio nombra sus propios campos y tu workflow nombra los suyos. Los mapeos son la forma de mover valores entre ambos: una lista de entradas origen-a-destino en el node, que se aplican a la solicitud antes de la llamada y a la respuesta después de ella. Los necesitas cuando la forma que lleva tu workflow no es la que acepta el servicio: un documento que debe viajar sin puntuación, un importe que pertenece a un objeto anidado, un score que un node posterior lee con un nombre corto.

Antes de empezar

Una configuración de provider para el servicio y un node executor que la referencie. Consulta Referenciar la configuración de provider desde un node de workflow.
Los nombres de los campos que espera el servicio. Cuando el documento OpenAPI del servicio está en el registro, Derivar el esquema de una operación devuelve inputSchema — el cuerpo de la solicitud de la operación — y outputSchema — su respuesta correcta. Ambos te dan los nombres de campo que escribes como target y como source de tus mapeos.
Un workflow en estado draft. Un workflow activo queda bloqueado, así que usa Mover el workflow a draft antes de editar un node y actívalo de nuevo después.

No envíes executorId en un node que llama a una operación de un documento OpenAPI subido. Ese node nombra la operación con operation_path y operation_method. Flowker rellena el executorId por ti, a partir de la configuración de provider a la que apunta el node, antes de validar el workflow. Lo hace cuando creas el workflow y cuando lo actualizas. Conectar tu propia API recorre todo ese camino. Los nodes de esta página nombran http, el conector HTTP genérico, que sí necesita un executorId explícito.

Paso 1: Conoce lo que puede leer un mapeo

Todo mapeo lee del contexto del workflow, un único objeto JSON que crece a medida que avanza la ejecución:

Ruta	Lo que contiene
`workflow`	El payload del trigger: el `inputData` de una solicitud de ejecución, o el cuerpo que recibió una ruta de webhook. Una ruta de webhook agrega también `workflow._webhook` con los metadatos de la llamada — consulta Metadatos del webhook.
`execution.id`	El identificador de la ejecución.
`execution.startedAt`	El momento en que empezó la ejecución, en UTC.
`<nodeId>`	La salida de cada node ya completado, bajo el ID de ese node.

Direcciona un valor por su ruta desde una de esas claves de primer nivel:

Source	Lo que selecciona
`workflow.customer.document`	Un campo anidado del payload del trigger.
`workflow.items[0].sku`	Un elemento de un array.
`workflow.items[*].sku`	El mismo campo en cada elemento, como array.
`workflow`	Todo el payload del trigger como objeto.
`score-transaction.body.score`	Un campo de la salida del node `score-transaction`.

El source de un mapeo es una ruta simple. No lo envuelvas en ${...}: las llaves pertenecen a los campos de plantilla del node (body, headers, query, path), y dentro de un mapeo una cadena ${...} se lee como un nombre de ruta literal que no selecciona nada.

Paso 2: Declara el mapeo de entrada

Los mapeos de entrada viven en un array inputMapping dentro del objeto data del node executor. Cada entrada mueve un valor al cuerpo de la solicitud saliente.

Campo	Tipo	Requerido	Descripción
`source`	string	Sí	La ruta del contexto del workflow que se lee.
`target`	string	Sí	La ruta del cuerpo de la solicitud saliente que se escribe. Un target con puntos crea el objeto anidado: `payment.amount` envía `{"payment":{"amount":…}}`.
`transformation`	object	No	Un cambio que se aplica al valor después de que llega al target. Consulta el Paso 4.
`required`	boolean	No	Si la ruta de origen debe existir. Por defecto es `false`. Aplica a todo el node — mira más abajo.

El resultado del mapeo es el cuerpo de la solicitud. Escribe cada target exactamente como el servicio espera recibirlo: no hay objeto envolvente ni prefijo que agregar.

Ejemplo — mapear el payload del trigger a una verificación de fraude

{
  "id": "score-transaction",
  "type": "executor",
  "name": "Score transaction",
  "position": { "x": 200, "y": 0 },
  "data": {
    "executorId": "http",
    "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "method": "POST",
    "path": "/score-transaction",
    "inputMapping": [
      { "source": "workflow.transactionId", "target": "reference" },
      { "source": "workflow.amount", "target": "payment.amount" },
      { "source": "workflow.customer.document", "target": "payment.document" }
    ]
  }
}

Con un payload de trigger de {"transactionId":"txn-98765","amount":1500.00,"customer":{"document":"12345678900"}}, el servicio recibe:

{
  "reference": "txn-98765",
  "payment": { "amount": 1500.00, "document": "12345678900" }
}

Cuando un source no selecciona nada

Una ruta de origen ausente del contexto no es un error. El target se escribe igualmente, con el valor null, y la solicitud sale. Usa required: true cuando el node no deba llamar al servicio sin un valor. Flowker revisa entonces cada ruta de origen de ese node antes de armar la solicitud y falla el paso cuando alguna está ausente: la ejecución se detiene con FLK-0504 y el paso informa input transformation failed.

required aplica al node, no solo a la entrada que lo lleva. Si alguna entrada del inputMapping de un node pone required: true, cada ruta de origen de ese array debe resolverse. Para mantener algunos campos opcionales, deja required fuera en todo el node.

Dale a cada target una sola entrada. Cuando dos entradas escriben el mismo target, gana la última.

Paso 3: Decide qué arma el cuerpo de la solicitud

Un node tiene tres formas de producir un cuerpo de solicitud. Flowker las revisa en un orden fijo y se detiene en la primera que esté presente:

data.body

Una plantilla de cuerpo explícita gana por completo. Flowker resuelve sus referencias ${...} contra el contexto del workflow y envía el resultado. Mientras data.body está presente, inputMapping, transforms y config no aportan nada al cuerpo.Cada referencia ${...} aquí debe resolverse. Una que no lo hace falla el node con FLK-0143, antes de hacer ninguna llamada — lo contrario de un source de mapeo, que se resuelve como null. Usa data.body cuando un valor ausente deba detener el workflow, y un mapeo cuando la solicitud deba salir de todos modos.

inputMapping o transforms

En caso contrario, Flowker arma una capa a partir de inputMapping. Cuando inputMapping está vacío, la arma a partir de transforms. Los dos son mutuamente excluyentes: un node con al menos una entrada en inputMapping nunca ejecuta sus transforms sobre la entrada.

Literales de config

Los valores literales de data.config siembran el cuerpo. Con una capa presente, los literales son la base y la capa gana en cualquier clave que ambos definan, así un mismo node puede combinar valores fijos con valores mapeados. Sin capa, los literales son el cuerpo por sí solos.

El transporte nunca forma parte del cuerpo de la solicitud. Antes de que config pueda sembrar el cuerpo, Flowker elimina de ahí estos nombres: method, path, url, endpointName, query, headers, auth, retry, timeout, timeout_seconds, request_format, success_status_codes, allowedHosts y allowedPrivateHosts. Por eso un node que guarda transporte en config por error no envía nada de eso al destino, y un bloque auth colocado ahí nunca puede viajar como contenido de la solicitud. El node lee su propio transporte en el primer nivel de su objeto data: path, endpointName, method, headers, query, auth, timeout_seconds, retry, success_status_codes y request_format. Las listas de hosts permitidos de salida no están entre ellos: allowedHosts y allowedPrivateHosts se definen en la configuración de provider, y cada una aplica a todos los nodes que llaman a través de ella.

Ejemplo — valores fijos junto con valores mapeados

{
  "data": {
    "executorId": "http",
    "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "method": "POST",
    "path": "/score-transaction",
    "config": {
      "channel": "web",
      "payment": { "currency": "BRL" }
    },
    "inputMapping": [
      { "source": "workflow.transactionId", "target": "reference" },
      { "source": "workflow.amount", "target": "payment.amount" }
    ]
  }
}

Los literales y los valores mapeados se combinan, y el anidamiento se combina con el anidamiento:

{
  "channel": "web",
  "reference": "txn-98765",
  "payment": { "currency": "BRL", "amount": 1500.00 }
}

Paso 4: Ajusta un valor en tránsito

Cuando el servicio necesita un valor en otra forma, agrega una transformation a la entrada del mapeo. Se aplica al valor después de que llega al target.

Tipo	Qué hace	Config
`remove_characters`	Elimina del texto los caracteres indicados.	`characters` — los caracteres que se eliminan.
`add_prefix`	Pone texto delante del valor.	`prefix` — el texto que se agrega.
`add_suffix`	Pone texto después del valor.	`suffix` — el texto que se agrega.
`to_uppercase`	Convierte el texto a mayúsculas.	—
`to_lowercase`	Convierte el texto a minúsculas.	—

Estos cinco son todo el conjunto. Un type fuera de él se rechaza cuando guardas el workflow, con FLK-0140. Dos reglas para escribirlas:

Actúan sobre texto. Un valor que no es texto llega al target sin cambios.
prefix y suffix necesitan al menos un carácter cada uno, y un solo espacio cuenta. characters necesita al menos un carácter que no sea un espacio, un tabulador ni un salto de línea. Un valor que no cumple esto falla el paso en tiempo de ejecución con FLK-0504.

Ejemplo — normalizar un documento y sellar una referencia

{
  "inputMapping": [
    {
      "source": "workflow.customer.document",
      "target": "payer.document",
      "transformation": {
        "type": "remove_characters",
        "config": { "characters": ".-/" }
      }
    },
    {
      "source": "workflow.customer.name",
      "target": "payer.name",
      "transformation": { "type": "to_uppercase" }
    },
    {
      "source": "workflow.transactionId",
      "target": "payer.reference",
      "transformation": {
        "type": "add_prefix",
        "config": { "prefix": "BR-" }
      }
    }
  ]
}

A partir de {"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}, el node envía:

{
  "payer": {
    "document": "12345678900",
    "name": "ADA LOVELACE",
    "reference": "BR-txn-98765"
  }
}

Transformaciones sobre todo el documento

Para el trabajo que el mapeo entrada por entrada no expresa — combinar dos campos, elegir el primer valor presente, rellenar un valor por defecto — declara un array transforms. Cada operación lee todo el contexto del workflow y escribe toda la capa. Flowker acepta shift (mover o renombrar), concat (unir valores), coalesce (primer valor presente), default (rellenar una clave ausente), extract (subir un subárbol a la raíz), delete (eliminar una clave), timestamp, uuid y pass. Los cinco tipos de transformación de arriba también están disponibles aquí; como operaciones, reciben la ruta de destino en la spec como path.

Ejemplo — un shift y un default en un mismo node

{
  "data": {
    "executorId": "http",
    "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
    "transforms": [
      {
        "operation": "shift",
        "spec": {
          "reference": "workflow.transactionId",
          "payment.amount": "workflow.amount"
        }
      },
      { "operation": "default", "spec": { "channel": "web" } }
    ]
  }
}

El node envía:

{
  "reference": "txn-98765",
  "payment": { "amount": 1500.00 },
  "channel": "web"
}

Una operación puede poner require: true para exigir que exista cada ruta que nombra su spec, igual que required funciona en una entrada de mapeo.

transforms se ejecuta solo cuando el node no tiene inputMapping. Usa uno u otro en un mismo node, nunca ambos.

Paso 5: Lee la respuesta de vuelta

Los mapeos de salida extraen campos de la respuesta y los guardan en el contexto del workflow bajo el ID del node, para que los nodes posteriores lean nombres cortos y estables. Decláralos en un array outputMapping dentro del data del node, con los mismos cuatro campos de entrada que un mapeo de entrada. Un source de salida es una ruta dentro del envoltorio de respuesta, no dentro del cuerpo de la respuesta:

Ruta	Lo que contiene
`status`	El código de estado HTTP.
`status_text`	La línea de estado HTTP, como `200 OK`.
`url`	La URL que Flowker pidió, con la query string que armó.
`headers`	Los encabezados de la respuesta, como objeto clave-valor bajo sus nombres canónicos, como `Content-Type`. Un encabezado que el servicio envió más de una vez llega como un solo valor separado por comas.
`body`	El cuerpo de la respuesta, interpretado cuando la respuesta es `application/json` o un tipo XML — `application/xml`, `text/xml`, o un tipo cuyo nombre termina en `+xml`.
`raw_body`	La respuesta tal como llegó, como texto. Presente en una respuesta XML.
`body_format`	Vale `xml` cuando se decodificó un cuerpo XML.
`body_parse_error`	Aparece en lugar de `body` cuando un cuerpo XML no se pudo decodificar, para que el workflow pueda ramificar ante eso.

Por eso los campos de la respuesta están bajo body:

{
  "outputMapping": [
    { "source": "body.score", "target": "score" },
    { "source": "body.decision", "target": "decision" },
    { "source": "status", "target": "httpStatus" }
  ]
}

En un node cuyo ID es score-transaction, eso guarda:

{ "score": 42, "decision": "review", "httpStatus": 200 }

Los nodes posteriores leen entonces ${score-transaction.score} y ${score-transaction.httpStatus}. Un node que no declara outputMapping guarda todo el envoltorio bajo su ID, y los nodes posteriores leen la ruta del envoltorio directamente: ${score-transaction.body.score}. Agrega un mapeo de salida cuando quieras el nombre corto; omítelo cuando la ruta del envoltorio sea suficientemente clara. Un source de salida que no selecciona nada se comporta como uno de entrada: el target se guarda como null, salvo que una entrada de ese node ponga required: true.

Paso 6: Revisa el mapeo antes de llamar al servicio

Previsualizar la solicitud de un executor arma la solicitud que enviaría un node y te la devuelve. Ejecuta el mismo armado de mapeos, transformaciones y autenticación que ejecuta una ejecución real, y nunca abre una conexión con el servicio, así que puedes iterar sobre un mapeo sin que salga una sola llamada de tu despliegue. Ninguna credencial aparece en lo que devuelve, ni siquiera en el curl. Envía el node, la configuración de provider a la que apunta y un payload de muestra. La configuración de provider va en la propia solicitud, así que la previsualización no depende de nada más que de lo que envías:

POST /v1/workflows/preview-request

{
  "node": {
    "executorId": "http",
    "method": "POST",
    "path": "/score-transaction",
    "inputMapping": [
      {
        "source": "workflow.customer.document",
        "target": "payer.document",
        "transformation": {
          "type": "remove_characters",
          "config": { "characters": ".-/" }
        }
      },
      {
        "source": "workflow.customer.name",
        "target": "payer.name",
        "transformation": { "type": "to_uppercase" }
      },
      {
        "source": "workflow.transactionId",
        "target": "payer.reference",
        "transformation": {
          "type": "add_prefix",
          "config": { "prefix": "BR-" }
        }
      }
    ]
  },
  "providerConfig": {
    "providerId": "http",
    "config": { "base_url": "https://api.fraudshield.example.com" },
    "allowedHosts": ["api.fraudshield.example.com"]
  },
  "sampleInput": {
    "transactionId": "txn-98765",
    "customer": { "document": "123.456.789-00", "name": "ada lovelace" }
  }
}

Tu sampleInput se convierte en el payload del trigger, así que los source del mapeo lo leen como workflow.*, exactamente como lo harán en tiempo de ejecución. La respuesta es la solicitud armada:

{
  "method": "POST",
  "url": "https://api.fraudshield.example.com/score-transaction",
  "headers": { "Content-Type": "application/json" },
  "body": "{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}",
  "curl": "curl -X POST -H 'Content-Type: application/json' --data '{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}' 'https://api.fraudshield.example.com/score-transaction'",
  "unresolved": []
}

Cada transformación se resolvió: el documento perdió la puntuación, el nombre está en mayúsculas y la referencia lleva su prefijo — y ninguna llamada llegó al servicio. Lee la respuesta en este orden:

Revisa la URL

Es la URL base de la configuración de provider más el path del node. Una ruta que no esperabas es un campo del node por corregir, no un mapeo.

Revisa el cuerpo contra los nombres de campo que espera el servicio

Cada target debe aparecer donde el servicio lo quiere. Un campo con null es una ruta source que no selecciona nada.

Revisa `unresolved`

Lista las referencias ${...} de los campos de plantilla del node que tu payload de muestra no resolvió. Quedan literales en la solicitud armada. Un array vacío significa que cada referencia encontró un valor.

Para revisar además los campos fijos de un node contra el esquema del executor del catálogo, llama a Validar la configuración de un node con la configuración del node en config y, en mappedTargets, las rutas de target que aporta tu inputMapping. Flowker las cuenta como satisfechas, así que un node que mapea un campo requerido desde el trigger pasa la revisión.

Qué puede salir mal

Síntoma	Causa	Solución
El servicio recibe un campo con valor `null`.	La ruta `source` está ausente del contexto del workflow.	Compara la ruta con el cuerpo armado de una previsualización. Pon `required: true` en el node cuando no deba ejecutarse sin el valor.
El servicio recibe un objeto anidado que no pidió.	El `target` lleva un prefijo.	Escribe el target exactamente como lo espera el servicio. Un target `executor.accountId` envía un objeto `executor`.
El cuerpo de la solicitud está vacío.	El node no tiene `data.body`, ni mapeo, ni `transforms`, y su `config` solo contiene nombres de transporte.	Agrega los valores como literales de `config` o como entradas de mapeo.
Los mapeos parecen ignorarse.	El node lleva también `data.body`, que es la única fuente del cuerpo mientras está presente.	Elimina `data.body` para que los mapeos armen el cuerpo.
`transforms` parece ignorarse.	El node tiene al menos una entrada en `inputMapping`.	Elimina las entradas de `inputMapping`, o mueve la lógica a ellas.
Un node posterior no lee nada.	La referencia no nombra al node que produce el valor.	Lee `${<nodeId>.<target>}`. No existe un espacio de nombres compartido de primer nivel.
Un mapeo de salida guarda `null`.	El `source` omite el prefijo del envoltorio.	Mapea `body.score`, no `score`.

Código de error	Cuándo	Qué significa
`FLK-0140`	Al crear, actualizar o activar	El `inputMapping` del node no forma una spec válida — con más frecuencia, un `transformation.type` fuera de los cinco tipos admitidos.
`FLK-0141`	Al crear, actualizar o activar	Lo mismo, para el `outputMapping` del node.
`FLK-0142`	Al crear, actualizar o activar	Lo mismo, para los `transforms` del node.
`FLK-0143`	En ejecución	Una referencia `${...}` del `data.body` del node no se resuelve contra el contexto del workflow. El node falla sin llamar al servicio.
`FLK-0504`	En ejecución	El node falló. El mensaje del paso nombra la etapa: `input transformation failed` para un source requerido ausente o una transformación que no pudo ejecutarse, y `output transformation failed` para el lado de la respuesta.

Consulta la lista de errores de Flowker para ver todos los códigos.

Qué sigue

Guía de integración

Crea la configuración de provider por la que llama un node y define su autenticación.

Configurar un trigger de webhook

Elige el contrato de payload que llena el espacio de nombres workflow que leen tus mapeos.

Resumen

Guías

Console

Operaciones

Trabajar con los datos de la solicitud y de la respuesta

Antes de empezar

Paso 1: Conoce lo que puede leer un mapeo

Paso 2: Declara el mapeo de entrada

Cuando un source no selecciona nada

Paso 3: Decide qué arma el cuerpo de la solicitud

Paso 4: Ajusta un valor en tránsito

Transformaciones sobre todo el documento

Paso 5: Lee la respuesta de vuelta

Paso 6: Revisa el mapeo antes de llamar al servicio

Qué puede salir mal

Qué sigue

Guía de integración

Configurar un trigger de webhook

​Antes de empezar

​Paso 1: Conoce lo que puede leer un mapeo

​Paso 2: Declara el mapeo de entrada

​Cuando un source no selecciona nada

​Paso 3: Decide qué arma el cuerpo de la solicitud

​Paso 4: Ajusta un valor en tránsito

​Transformaciones sobre todo el documento

​Paso 5: Lee la respuesta de vuelta

​Paso 6: Revisa el mapeo antes de llamar al servicio

​Qué puede salir mal

​Qué sigue

Guía de integración

Configurar un trigger de webhook

Antes de empezar

Paso 1: Conoce lo que puede leer un mapeo

Paso 2: Declara el mapeo de entrada

Cuando un source no selecciona nada

Paso 3: Decide qué arma el cuerpo de la solicitud

Paso 4: Ajusta un valor en tránsito

Transformaciones sobre todo el documento

Paso 5: Lee la respuesta de vuelta

Paso 6: Revisa el mapeo antes de llamar al servicio

Qué puede salir mal

Qué sigue