Trabajar con datos de solicitud y respuesta

Un nodo 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. Son una lista de entradas de origen a destino en el nodo. Flowker los aplica a la solicitud antes de la llamada y a la respuesta después de ella. Necesitas esto cuando la forma que lleva tu workflow no es la forma que acepta el servicio. Un ejemplo es un documento que debe viajar sin puntuación. Otro es un monto que pertenece a un objeto anidado, o una puntuación que un nodo posterior lee con un nombre corto.

Antes de empezar

Una configuración de proveedor para el servicio, y un nodo executor que la referencia. Consulta Referenciar la configuración de proveedor desde un nodo del workflow.
Los nombres de campo que espera el servicio. Cuando el documento OpenAPI del servicio está en el registro, Derivar un esquema de operación devuelve inputSchema (el cuerpo de la solicitud de la operación) y outputSchema (su respuesta de éxito). Ambos te dan los nombres de campo que escribes como destinos y orígenes de mapeo.
Un workflow en estado draft. Un workflow activo está bloqueado, así que usa Pasar un workflow a borrador antes de editar un nodo, y actívalo de nuevo después.

No envíes executorId en un nodo que llama a una operación de un documento OpenAPI cargado. Ese nodo nombra la operación con operation_path y operation_method. Flowker completa el executorId por ti, a partir de la configuración de proveedor a la que apunta el nodo, antes de validar el workflow. Lo hace cuando creas el workflow y cuando lo actualizas. Conectar tu propia API recorre toda esa vía. Los nodos de esta página nombran http, el conector HTTP genérico, que sí necesita un executorId explícito.

Paso 1: conoce qué puede leer un mapeo

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

Ruta	Qué 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 también agrega `workflow._webhook` con los metadatos de la llamada — consulta Metadatos de webhook.
`execution.id`	El identificador de la ejecución.
`execution.startedAt`	Cuándo empezó la ejecución, en UTC.
`<nodeId>`	La salida de cada nodo que se completó, bajo el id de ese nodo.

Referencia un valor por su ruta desde una de esas claves de nivel superior:

Origen	Qué selecciona
`workflow.customer.document`	Un campo anidado del payload del trigger.
`workflow.items[0].sku`	Un elemento de un arreglo.
`workflow.items[*].sku`	El mismo campo en cada elemento, como un arreglo.
`workflow`	Todo el payload del trigger como un objeto.
`score-transaction.body.score`	Un campo de la salida del nodo `score-transaction`.

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

Paso 2: declara el mapeo de entrada

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

Campo	Tipo	Obligatorio	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 destino 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 aterriza en el destino. Consulta el Paso 4.
`required`	boolean	No	Si la ruta de origen debe existir. El valor predeterminado es `false`. Aplica a todo el nodo — mira abajo.

El resultado mapeado 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 del 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 origen no selecciona nada

Una ruta de origen ausente del contexto no es un error. Flowker igual escribe el destino, con el valor null, y la solicitud sale. Define required: true cuando el nodo no debe llamar al servicio sin un valor. Flowker entonces revisa cada ruta de origen de ese nodo antes de armar la solicitud, y hace fallar el paso cuando alguna de ellas está ausente. La ejecución se detiene con FLK-0504 y el paso informa input transformation failed.

required aplica al nodo, no a la única entrada que lo lleva. Si alguna entrada del inputMapping de un nodo define required: true, cada ruta de origen de ese arreglo debe resolverse. Para mantener algunos campos opcionales, deja required desactivado en todo el nodo.

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

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

Un nodo tiene tres fuentes para el cuerpo de una solicitud. Solo data.body es exclusivo: cuando está presente, es todo el cuerpo. Sin él, Flowker compone el cuerpo a partir de las otras dos fuentes, con la superposición del mapeo escrita sobre los literales de config:

data.body

Una plantilla de cuerpo explícita gana de plano. 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 ${...} de aquí debe resolverse. Una que no lo hace hace fallar el nodo con FLK-0143, antes de que salga cualquier llamada (lo contrario de un origen de mapeo, que se resuelve como null). Usa data.body cuando un valor ausente debe detener el workflow, y un mapeo cuando la solicitud debe salir de todos modos.

inputMapping o transforms

En caso contrario, Flowker arma una superposición a partir de inputMapping. Cuando inputMapping está vacío, arma la superposición a partir de transforms. Los dos son mutuamente excluyentes: un nodo con al menos una entrada de inputMapping nunca corre sus transforms sobre la entrada.

literales de config

Los valores literales de data.config siembran el cuerpo. Con una superposición presente, los literales son la base y la superposición gana en cualquier clave que ambos definan. Por eso un nodo puede combinar valores fijos con valores mapeados. Sin superposición, los literales son el cuerpo por sí solos.

El transporte nunca se vuelve contenido del cuerpo. Antes de que config pueda sembrar el cuerpo, Flowker le quita estos nombres: method, path, url, endpointName, query, headers, auth, retry, timeout, timeout_seconds, request_format, success_status_codes, allowedHosts y allowedPrivateHosts. Por eso un nodo que deja el transporte en config por error no envía nada de eso al destino. Un bloque auth puesto ahí nunca puede viajar como contenido de la solicitud. El nodo lee su propio transporte desde el nivel superior de su objeto data: path, endpointName, method, headers, query, auth, timeout_seconds, retry, success_status_codes y request_format. Las listas de hosts salientes permitidos no están entre ellos: configuras allowedHosts y allowedPrivateHosts en la configuración de proveedor, donde cada una aplica a cada nodo que llama a través de ella.

Ejemplo: valores fijos más 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 fusionan, y el anidamiento se fusiona con el anidamiento:

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

Paso 4: cambia la forma de un valor en tránsito

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

Tipo	Qué hace	Config
`remove_characters`	Quita del texto los caracteres indicados.	`characters` — los caracteres que se quitan.
`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.	—

Estas cinco son el conjunto completo. Un type fuera de él falla cuando guardas el workflow, con FLK-0140. Dos reglas para escribirlas:

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

Ejemplo: normalizar un documento y estampar 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-" }
      }
    }
  ]
}

Desde {"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}, el nodo envía:

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

Transformaciones de documento completo

Para el trabajo que el mapeo entrada por entrada no expresa (combinar dos campos, elegir el primer valor presente, rellenar un valor predeterminado), declara en su lugar un arreglo transforms. Cada operación lee todo el contexto del workflow y escribe toda la superposición. 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 (quitar una clave), timestamp, uuid y pass. Los cinco tipos de transformación de arriba también están disponibles aquí. Como operaciones, toman la ruta de destino de la especificación en path.

Ejemplo: un shift y un default en un mismo nodo

{
  "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 nodo envía:

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

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

transforms corre solo cuando el nodo no tiene inputMapping. Usa uno u otro en un nodo dado, nunca ambos.

Paso 5: lee de vuelta la respuesta

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

Ruta	Qué contiene
`status`	El código de estado HTTP.
`status_text`	La línea de estado HTTP, como `200 OK`.
`url`	La URL que solicitó Flowker, con la query string que armó.
`headers`	Los headers de la respuesta, como un objeto clave-valor bajo sus nombres canónicos, como `Content-Type`. Un header que el servicio envió más de una vez llega como un único valor separado por comas.
`body`	El cuerpo de la respuesta, parseado 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 para una respuesta XML.
`body_format`	Vale `xml` cuando se decodificó un cuerpo XML.
`body_parse_error`	Presente en lugar de `body` cuando no se pudo decodificar un cuerpo XML, para que el workflow pueda ramificar según eso.

Por eso los campos de la respuesta quedan bajo body:

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

En un nodo con el id score-transaction, eso guarda:

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

Los nodos posteriores leen entonces ${score-transaction.score} y ${score-transaction.httpStatus}. Un nodo que no declara outputMapping guarda en su lugar el envelope completo bajo su id, y los nodos posteriores leen la ruta del envelope directamente: ${score-transaction.body.score}. Agrega un mapeo de salida cuando quieras el nombre más corto. Omítelo cuando la ruta del envelope sea suficientemente clara. Un origen de salida que no selecciona nada se comporta como uno de entrada. Flowker guarda el destino como null a menos que una entrada de ese nodo defina required: true.

Paso 6: revisa el mapeo antes de llamar al servicio

Previsualizar una solicitud de executor usa las vías de mapeo, transformación y armado de la solicitud sin hacer una llamada de red al servicio. No lee el vault ni obtiene un token de autenticación. Enmascara los valores secretos suministrados y usa el catálogo de Flowker para resolver el proveedor y el executor. Ninguna credencial aparece en nada de lo que devuelve, incluido el curl. Envía el nodo, la configuración de proveedor a la que apunta y un payload de ejemplo. La configuración de proveedor va en la solicitud misma, así que la previsualización no necesita una configuración de proveedor guardada ni una lectura del vault. El catálogo del lado del servidor igual debe resolver el proveedor y el executor:

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 orígenes 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ó: la puntuación desapareció del documento, el nombre está en mayúsculas y la referencia lleva su prefijo. Ninguna llamada llegó al servicio. Léelo en este orden:

Revisa la URL

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

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

Se recomienda que cada target aparezca donde el servicio lo quiere. Un campo que lleva null es una ruta source que no selecciona nada.

Revisa unresolved

Lista las referencias ${...} de los campos de plantilla del nodo que tu payload de ejemplo no resolvió. Flowker las deja literales en la solicitud renderizada. Un arreglo vacío significa que cada referencia encontró un valor.

Para revisar además los campos fijos de un nodo contra el esquema del executor del catálogo, llama a Validar la configuración de un nodo. Envía la configuración del nodo en config y, en mappedTargets, las rutas de destino que suministra tu inputMapping. Flowker las cuenta como satisfechas, así que un nodo que mapea un campo obligatorio desde el trigger pasa la verificación.

Qué sale mal

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

Código de error	Cuándo	Qué significa
`FLK-0140`	Creación, actualización o activación	El `inputMapping` del nodo no forma una especificación válida — casi siempre un `transformation.type` fuera de los cinco tipos admitidos.
`FLK-0141`	Creación, actualización o activación	Lo mismo, para el `outputMapping` del nodo.
`FLK-0142`	Creación, actualización o activación	Lo mismo, para los `transforms` del nodo.
`FLK-0143`	Tiempo de ejecución	Una referencia `${...}` del `data.body` del nodo no se resuelve contra el contexto del workflow. El nodo falla sin llamar al servicio.
`FLK-0504`	Tiempo de ejecución	El nodo falló. El mensaje del paso nombra la etapa: `input transformation failed` para un origen obligatorio ausente o una transformación que no pudo correr, `output transformation failed` para el lado de la respuesta.

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

Qué sigue

Guía de integración

Crea la configuración de proveedor a través de la cual llama un nodo, 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 datos de solicitud y respuesta

Antes de empezar

Paso 1: conoce qué puede leer un mapeo

Paso 2: declara el mapeo de entrada

Cuando un origen no selecciona nada

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

Paso 4: cambia la forma de un valor en tránsito

Transformaciones de documento completo

Paso 5: lee de vuelta la respuesta

Paso 6: revisa el mapeo antes de llamar al servicio

Qué sale mal

Qué sigue

Guía de integración

Configurar un trigger de webhook

​Antes de empezar

​Paso 1: conoce qué puede leer un mapeo

​Paso 2: declara el mapeo de entrada

​Cuando un origen no selecciona nada

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

​Paso 4: cambia la forma de un valor en tránsito

​Transformaciones de documento completo

​Paso 5: lee de vuelta la respuesta

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

​Qué sale mal

​Qué sigue

Guía de integración

Configurar un trigger de webhook

Antes de empezar

Paso 1: conoce qué puede leer un mapeo

Paso 2: declara el mapeo de entrada

Cuando un origen no selecciona nada

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

Paso 4: cambia la forma de un valor en tránsito

Transformaciones de documento completo

Paso 5: lee de vuelta la respuesta

Paso 6: revisa el mapeo antes de llamar al servicio

Qué sale mal

Qué sigue