Módulo 1: Por qué versionar tus workflows

4. Anatomía del JSON de un workflow

Siguiente →

Descripción

Al terminar esta lección vas a poder abrir el archivo JSON de un workflow exportado y nombrar cada una de sus partes principales: los nodos, las conexiones, la configuración, los identificadores y las referencias a credenciales. Y vas a poder hacer la distinción que más importa: separar los campos estables —los que solo cambian cuando de verdad cambias la lógica del workflow— de los campos volátiles —los que cambian por razones cosméticas o de infraestructura, sin que el workflow haga nada distinto—. Esa distinción no es un tecnicismo: es lo que decide si el diff de tu workflow es legible o es un muro de ruido.

Esto importa porque a partir del Módulo 2 vas a versionar este archivo, y versionar algo que no entiendes es versionar a ciegas. Cuando veas un diff de tu workflow, tienes que poder mirar las líneas resaltadas y decir "esto es un cambio real de lógica" o "esto es solo que moví un nodo de lugar". Sin esa lectura, cada diff te va a parecer un caos y vas a perder la capacidad de revisión que es la mitad del valor de versionar. Esta lección te da los ojos para leer el archivo.

Conexión con el módulo: la lección 3 cerró prometiendo abrir la "caja cerrada" del JSON, y esta la abre. También prepara directamente la lección 5: una vez que sabes qué campos hay y cuáles son volátiles, la lección 5 te muestra cuáles de esos campos volátiles se rompen específicamente al mover el workflow a otra instancia —los IDs de credencial, los de webhook—. Y es indispensable para el proyecto de la lección 8, donde vas a leer el JSON de order-triage campo por campo. Una nota de método desde ya: los nombres exactos de los campos y su presencia pueden variar entre versiones de n8n. Voy a describir la estructura general y a pedirte que confirmes los detalles abriendo tu propio archivo exportado; no te fíes de que un campo esté palabra por palabra como aquí sin verlo en tu versión.

El JSON es el plano del workflow

Antes de mirar los campos, fijemos qué es este archivo, con una imagen.

Cuando un arquitecto diseña un edificio, hay dos cosas distintas: el edificio construido —de ladrillo, con gente adentro— y el plano —unas hojas con líneas que describen dónde va cada muro, cada puerta, cada instalación—. El plano no es el edificio; es su descripción completa en un formato que se puede guardar, copiar, comparar y entregar. Con el plano en la mano, otro constructor podría levantar el mismo edificio en otro terreno.

El JSON de un workflow es el plano. El "edificio construido" es tu workflow corriendo en la instancia de n8n: los nodos que arrastraste, las conexiones que dibujaste, cada campo que llenaste. El JSON es la descripción completa de todo eso en forma de texto. Cuando haces Download, n8n lee el edificio y te entrega el plano.

Y como todo plano, tiene una gramática: hay secciones fijas, cada cosa está en su lugar, y aprender a leerlo es aprender un lenguaje. La buena noticia es que ese lenguaje es corto. Un workflow, por complejo que sea, se describe con un puñado de secciones de nivel superior, y todo lo demás es repetición de patrones dentro de esas secciones. Vamos a recorrerlas.

Recordemos qué es JSON en una frase, por si vienes sin ese contexto. JSON —JavaScript Object Notation— es una forma de escribir datos con estructura. Usa llaves { } para agrupar un conjunto de pares "nombre: valor" (un objeto), corchetes [ ] para una lista de cosas (un arreglo), comillas para el texto, y : para separar cada nombre de su valor. Un objeto puede contener otros objetos y otras listas, anidados tan profundo como haga falta. No necesitas escribir JSON a mano para esta lección; solo leerlo, y para leerlo alcanza con reconocer esas cuatro señales: llaves, corchetes, comillas y dos puntos.

La estructura de nivel superior

Cuando abres un workflow exportado, lo primero que ves es un objeto grande —todo el archivo es un objeto, envuelto en un par de llaves— con unas cuantas claves de nivel superior. Estas son las que casi siempre vas a encontrar, con la advertencia de que su nombre exacto puede variar por versión:

ClaveQué contieneEn una frase
nameEl nombre del workflowEl título que ves en el editor
nodesLa lista de todos los nodosLos "ladrillos": cada caja del lienzo
connectionsCómo se enlazan los nodos entre síLas "flechas": qué sale de dónde y entra a dónde
settingsLa configuración general del workflowZona horaria, política de errores, guardado de ejecuciones
activeSi el workflow está encendidotrue o false
pinDataDatos "fijados" para pruebasEntradas de ejemplo congeladas en ciertos nodos
meta / versionId / idMetadatos e identificadoresDatos administrativos que n8n usa por dentro
tagsEtiquetas del workflowClasificación para organizar

De todas ellas, dos concentran casi toda la sustancia —nodes y connections— y son las que vamos a mirar de cerca. Las demás son importantes pero cortas.

nodes: la lista de ladrillos

nodes es un arreglo: una lista donde cada elemento es un nodo del lienzo. Si tu workflow tiene siete cajas, este arreglo tiene siete objetos. Cada objeto describe un nodo por completo. Veamos uno real de order-triage —el nodo que llama al CRM por HTTP—, con la advertencia de que lo simplifiqué para que quepa y sea legible:

{
  "parameters": {
    "method": "GET",
    "url": "https://crm.example.com/api/customers/{{ $json.customer_id }}",
    "authentication": "genericCredentialType"
  },
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Get customer from CRM",
  "type": "n8n-nodes-base.httpRequest",
  "typeVersion": 4.2,
  "position": [1040, 300],
  "credentials": {
    "httpHeaderAuth": {
      "id": "27",
      "name": "Cumbre CRM - Header Auth"
    }
  }
}

Detengámonos en cada campo, porque estos son los que vas a ver cientos de veces:

  • name — el nombre que le pusiste al nodo en el editor, "Get customer from CRM". Es cómo lo identificas visualmente y cómo lo referencian otros nodos. Es un campo estable: solo cambia si tú renombras el nodo.

  • type — qué clase de nodo es, "n8n-nodes-base.httpRequest". Le dice a n8n qué comportamiento cargar. Es estable: solo cambia si reemplazas el nodo por otro de tipo distinto.

  • typeVersion — la versión de ese tipo de nodo, "4.2". n8n mejora sus nodos con el tiempo y mantiene varias versiones para no romper workflows viejos. Cambia solo cuando actualizas el nodo a una versión nueva.

  • parameters — la configuración del nodo: aquí vive lo que llenaste en el formulario. Para este HTTP Request, el método GET, la URL a la que llama, el tipo de autenticación. Esta es la parte más estable y más importante: es la lógica real del nodo. Cuando cambias el comportamiento de un workflow, casi siempre cambias algo dentro de parameters.

  • position — dónde está el nodo en el lienzo, [1040, 300] (coordenadas X, Y). Este es el ejemplo clásico de campo volátil: si arrastras el nodo diez píxeles a la derecha para acomodar el diagrama, este número cambia, y aparece en el diff como si hubieras modificado el workflow, aunque hace exactamente lo mismo.

  • id — un identificador único del nodo, ese "a1b2c3d4-..." que parece código de barras. n8n lo genera solo y lo usa internamente para referirse al nodo. Es volátil en un sentido peligroso: lo estudiamos en detalle en la lección 5, porque puede regenerarse al reimportar.

  • credentials — la referencia a la credencial que usa el nodo. Este campo es el corazón del problema de portabilidad, y merece su propia sección.

El campo credentials: una referencia, no un secreto

Mira otra vez la sección credentials del nodo de arriba:

"credentials": {
  "httpHeaderAuth": {
    "id": "27",
    "name": "Cumbre CRM - Header Auth"
  }
}

Aquí hay una idea que es fácil malentender y que es central para toda la guía: el JSON del workflow NO contiene tu credencial. Contiene una referencia a ella.

Piénsalo como la llave de una casillero de gimnasio. En el JSON no está guardada tu contraseña del CRM ni tu llave de API; está guardado algo como "usa la credencial número 27, que se llama 'Cumbre CRM - Header Auth'". El secreto real —el token, la contraseña— vive cifrado en la base de datos de tu instancia de n8n, en otro lado, no en este archivo. El workflow solo dice cuál credencial usar, no cuál es la credencial.

Esto es una buena decisión de diseño de n8n, por seguridad: significa que puedes compartir el JSON de un workflow sin regalar tus secretos. Pero tiene una consecuencia enorme que es el tema de la lección 5: ese "id": "27" significa algo solo dentro de tu instancia. Es como el número de casillero: el casillero 27 de tu gimnasio no es el casillero 27 del gimnasio de otra persona. Cuando llevas este workflow a otra instancia de n8n, el "27" apunta a la nada —o peor, apunta a una credencial distinta que casualmente tiene ese ID—, y el nodo se rompe. Pero no adelantemos; por ahora quédate con la distinción: credentials guarda una referencia (un ID y un nombre), no el secreto.

Fíjate también en que aparecen dos datos: el id y el name. El id es lo que n8n usa de verdad para encontrar la credencial. El name está ahí para que un humano lo lea. Y aquí hay una advertencia de seguridad de la lección 3: ese name a veces revela información —"Cumbre CRM - Producción"— y por eso la documentación recomienda anonimizar los nombres de credencial antes de compartir un JSON.

connections: las flechas entre ladrillos

Si nodes son los ladrillos, connections son las flechas que dibujaste entre ellos. Esta sección describe qué nodo alimenta a qué otro nodo. En la mayoría de las versiones de n8n, las conexiones se describen por el nombre del nodo, no por su ID. Un fragmento simplificado:

"connections": {
  "Get customer from CRM": {
    "main": [
      [
        { "node": "Classify order (AI Agent)", "type": "main", "index": 0 }
      ]
    ]
  }
}

Léelo así: "la salida principal (main) del nodo llamado 'Get customer from CRM' se conecta a la entrada del nodo llamado 'Classify order (AI Agent)'". Es la flecha, escrita en texto.

Un detalle importante que vas a agradecer: como las conexiones usan el nombre del nodo y no su ID interno, son relativamente estables y legibles. Si renombras un nodo, tienes que actualizar tanto su name en nodes como todas las conexiones que lo mencionan —n8n lo hace por ti en el editor—. Pero mientras no renombres, esta sección es de las más tranquilas del archivo.

settings, active y pinData: lo demás

Las otras secciones son más cortas, pero conviene conocerlas.

settings guarda la configuración general del workflow: la zona horaria con la que interpreta las fechas, qué hacer cuando un nodo falla, si guarda o no el registro de cada ejecución. Son ajustes que afectan a todo el workflow, no a un nodo en particular. Es un campo estable: cambia solo cuando tú cambias esos ajustes.

active es un simple true o false: dice si el workflow está encendido (escuchando su disparador) o apagado. Este campo tiene una trampa de portabilidad que vale la pena adelantar: cuando importas un workflow en otra instancia, n8n no necesariamente respeta este valor —típicamente lo importa desactivado, para que no se dispare solo antes de que revises sus credenciales—. Es un comportamiento sensato, pero significa que active no es algo con lo que puedas contar al mover un workflow.

pinData guarda "datos fijados": entradas de ejemplo que congelas en ciertos nodos para poder probar el workflow sin ejecutar de verdad los nodos anteriores. Es una herramienta de prueba —la vas a usar mucho en el Módulo 5— y por ahora basta con saber que, si tu workflow tiene datos fijados, viajan dentro del JSON. Ojo con esto: los datos fijados pueden contener información real que capturaste en una prueba, así que son otro lugar que conviene revisar antes de compartir un JSON.

order-triage completo, de un vistazo

Antes de pasar a la distinción estable/volátil, veamos cómo se ensamblan todas estas piezas en un solo workflow, para que dejes de ver campos sueltos y veas el plano entero. Este es el esqueleto muy simplificado de order-triage —le quité casi todos los parámetros para que quepa; en la vida real cada nodo tiene mucho más adentro—:

{
  "name": "order-triage",
  "nodes": [
    {
      "name": "Order received (Webhook)",
      "type": "n8n-nodes-base.webhook",
      "position": [600, 300],
      "id": "11111111-1111-1111-1111-111111111111",
      "webhookId": "f4b9c2a1-7d3e-4a8b-9c1d-2e5f6a7b8c9d",
      "parameters": { "path": "order-triage", "httpMethod": "POST" }
    },
    {
      "name": "Get customer from CRM",
      "type": "n8n-nodes-base.httpRequest",
      "position": [820, 300],
      "id": "22222222-2222-2222-2222-222222222222",
      "parameters": { "method": "GET", "url": "https://crm.example.com/api/customers/{{ $json.customer_id }}" },
      "credentials": { "httpHeaderAuth": { "id": "27", "name": "Cumbre CRM - Header Auth" } }
    },
    {
      "name": "Classify order (AI Agent)",
      "type": "@n8n/n8n-nodes-langchain.agent",
      "position": [1040, 300],
      "id": "33333333-3333-3333-3333-333333333333",
      "parameters": { "promptType": "define" },
      "credentials": { "openAiApi": { "id": "14", "name": "Cumbre OpenAI - Dev" } }
    }
  ],
  "connections": {
    "Order received (Webhook)": {
      "main": [[{ "node": "Get customer from CRM", "type": "main", "index": 0 }]]
    },
    "Get customer from CRM": {
      "main": [[{ "node": "Classify order (AI Agent)", "type": "main", "index": 0 }]]
    }
  },
  "settings": { "timezone": "America/Mexico_City", "executionOrder": "v1" },
  "active": false,
  "pinData": {},
  "versionId": "b7e2d9-new",
  "meta": {},
  "tags": []
}

Léelo de arriba hacia abajo como un plano. Arriba, name: el workflow se llama order-triage. Después, nodes: tres ladrillos —el webhook que recibe el pedido, la llamada HTTP al CRM, y el nodo AI Agent que clasifica—. Cada uno con su name, su type, su position, su id volátil, y los dos que usan credenciales con su referencia ("id": "27" para el CRM, "id": "14" para el agente de IA). Después, connections: las flechas, que dicen que del webhook sale hacia el CRM, y del CRM hacia el AI Agent. Y al final, la configuración y los metadatos.

Fíjate en tres cosas que van a importar en la lección 5. Primera: el nodo webhook tiene un webhookId propio —otro identificador que se genera por instancia y que es fuente de rupturas al mover—. Segunda: las dos credenciales, "id": "27" y "id": "14", son números que solo significan algo en esta instancia. Tercera: el AI Agent apunta a una credencial llamada "Cumbre OpenAI - Dev" —el sufijo Dev es una pista de que en Cumbre hay credenciales distintas por entorno, tema del Módulo 4—. Con este plano completo en la cabeza, la ruptura de la próxima lección va a tener sentido: no es magia negra, son estos números concretos apuntando al lugar equivocado.

Estable contra volátil: la distinción que hace legible un diff

Ya tienes el mapa de campos. Ahora la parte que convierte ese mapa en una habilidad: separar lo estable de lo volátil.

Un campo estable es uno que cambia solo cuando cambias la lógica del workflow. Si aparece en un diff, es porque hiciste algo real: cambiaste una URL, un umbral, una conexión, un parámetro. Cuando ves un campo estable modificado, te conviene leerlo con atención, porque significa algo.

Un campo volátil es uno que cambia sin que el workflow haga nada distinto. Aparece en el diff por razones cosméticas —moviste un nodo— o de infraestructura —n8n regeneró un ID—. Cuando ves un campo volátil modificado, es ruido: no cambió el comportamiento, solo cambió un detalle que no importa para lo que el workflow hace.

Aquí está la tabla que conviene tener presente:

Campo¿Estable o volátil?Por qué
parametersEstableEs la lógica real del nodo; cambia solo si cambias el comportamiento
name (del nodo)EstableCambia solo si renombras
type / typeVersionEstableCambia solo si reemplazas o actualizas el nodo
connectionsEstableCambia solo si reconectas nodos (usa nombres, es legible)
settingsEstableCambia solo si cambias ajustes del workflow
positionVolátilCambia con solo mover un nodo en el lienzo
id (del nodo)Volátil / peligrosoPuede regenerarse al reimportar (lección 5)
credentials.idVolátil / peligrosoEs un ID por instancia; se rompe al mover (lección 5)
versionId / metaVolátilMetadatos administrativos que n8n gestiona
activeNo confiable al moverNo se respeta de forma fiable al importar

Por qué esta distinción es el centro de la lección: el objetivo de un diff limpio es que las líneas resaltadas sean casi todas de campos estables. Si cada vez que guardas una versión, el diff está lleno de position cambiados y versionId nuevos, el ruido esconde la señal, y revisar se vuelve imposible otra vez —vuelves al problema de la lección 3, pero ahora dentro del sistema de versiones—. Por eso el Módulo 3 dedica una lección entera a normalizar el JSON: reordenar los campos, y en algunos casos ignorar los volátiles, para que los diffs muestren solo lo que importa. No puedes normalizar lo que no sabes distinguir; esta lección es el prerrequisito.

Ejemplo trabajado: dos diffs, uno con señal y uno con ruido

Comparemos dos versiones de order-triage para ver la diferencia en carne propia.

Diff A — un cambio real de lógica. Cambiaste la URL del CRM de un servidor viejo a uno nuevo. El diff muestra:

   "parameters": {
     "method": "GET",
-    "url": "https://old-crm.example.com/api/customers/{{ $json.customer_id }}",
+    "url": "https://crm.example.com/api/customers/{{ $json.customer_id }}",
     "authentication": "genericCredentialType"
   },

Qué esperar: una sola línea cambiada, dentro de parameters, un campo estable. Lees el diff y en dos segundos sabes exactamente qué pasó y decides si lo apruebas. Esto es señal pura.

Diff B — el mismo workflow, pero solo moviste tres nodos y n8n regeneró metadatos. El diff muestra:

-  "position": [1040, 300],
+  "position": [1120, 340],
...
-  "position": [820, 300],
+  "position": [900, 280],
...
-  "versionId": "8f3a1c-old",
+  "versionId": "b7e2d9-new",

Qué esperar: varias líneas cambiadas, todas volátiles. position tres veces —moviste nodos— y versionId una vez —n8n lo regeneró—. El workflow hace exactamente lo mismo que antes. Ninguna de estas líneas cambió el comportamiento, pero todas ensucian el diff. Si este ruido se mezcla con un cambio real, el cambio real se pierde entre él.

La habilidad que estás construyendo es mirar el Diff B y decir, sin dudar, "esto es todo ruido, no hay cambio de comportamiento aquí", y mirar el Diff A y decir "esto es un cambio real, lo reviso con atención". Esa lectura instantánea es lo que te permite versionar sin ahogarte, y es imposible sin el mapa de campos que acabas de aprender.

Errores comunes

Creer que el JSON contiene las credenciales (conceptual y de seguridad). Qué pasa: alguien asume que como el nodo "tiene" la credencial, el secreto está en el JSON, y entonces (a) tiene miedo de versionar el workflow pensando que sube sus contraseñas, o al revés (b) comparte el JSON creyendo que la credencial viaja y funcionará del otro lado. Las dos suposiciones son falsas y opuestas. Por qué pasa: la relación entre workflow y credencial es indirecta y no es obvia hasta que abres el archivo. Cómo detectarlo: abre el JSON y busca la sección credentials; vas a ver un id y un name, nunca el secreto en sí. Cómo corregirlo: entiende que el JSON guarda una referencia (ID y nombre), no el secreto. Por eso versionarlo es seguro respecto del secreto —aunque conviene anonimizar los nombres—, y por eso mover el workflow no lleva la credencial consigo, lo que causa la ruptura de la lección 5.

Tratar todos los cambios del diff como iguales (práctico). Qué pasa: alguien empieza a versionar, ve un diff con quince líneas cambiadas, y se abruma o —peor— revisa las quince con la misma atención, perdiendo tiempo en position que no importan y a veces pasando por alto la única línea de parameters que sí. Por qué pasa: sin la distinción estable/volátil, todas las líneas resaltadas se ven igual de importantes. Cómo detectarlo: si revisar un diff te toma lo mismo sin importar cuántos cambios reales tenga, no estás filtrando el ruido. Cómo corregirlo: entrena el ojo a saltar los campos volátiles (position, versionId, id, meta) y detenerte en los estables (parameters, connections, name). Y ataca la raíz en el Módulo 3, normalizando el JSON para que los volátiles ni siquiera aparezcan en el diff.

Renombrar nodos a la ligera sin ver el efecto en las conexiones (práctico). Qué pasa: alguien renombra un nodo pensando que es un cambio cosmético y se sorprende de ver el diff lleno de cambios en la sección connections. Por qué pasa: como las conexiones se describen por el nombre del nodo, renombrar un nodo toca todas las conexiones que lo mencionan. Cómo detectarlo: si un renombre "simple" produce un diff grande, esto es lo que pasó. Cómo corregirlo: no es un error grave —n8n mantiene la coherencia por ti en el editor—, pero conviene saberlo para no asustarte al leer el diff, y para entender por qué los renombres frecuentes ensucian el historial. Renombra con intención, no por costumbre.

Asumir que la estructura del JSON es idéntica en todas las versiones de n8n (conceptual). Qué pasa: alguien memoriza los nombres de campo de un tutorial y se confunde cuando su versión los tiene distintos o agrega otros. Por qué pasa: n8n evoluciona su formato entre versiones mayores, y la documentación de un año atrás puede no coincidir. Cómo detectarlo: si un campo que "debería estar" no aparece, o hay campos que no reconoces, es diferencia de versión. Cómo corregirlo: aprende la estructura general —nodos, conexiones, configuración, IDs, credenciales— que es estable en el tiempo, y confirma los nombres exactos abriendo tu propio archivo exportado. La habilidad de leer el archivo se transfiere; los nombres literales, verifícalos en tu versión.

Ejercicios

Ejercicio 1 — Mapea tu propio workflow. Toma el archivo .json que exportaste en la lección 3 (o exporta uno nuevo). Ábrelo con un editor de texto y localiza, señalando la línea: (a) la clave nodes, (b) la clave connections, (c) el name y el type de al menos un nodo, (d) un campo position, (e) si hay algún nodo con credenciales, su sección credentials con el id y el name.

Ver solución

No hay una respuesta única porque depende de tu workflow, pero sí hay una verificación. Deberías haber encontrado nodes como una lista (empieza con [), connections como un objeto que menciona nombres de nodos, y dentro de cada nodo los campos name, type, position y parameters. Si tu workflow usa algún nodo con autenticación —HTTP Request, un nodo de una app, un AI Agent—, la sección credentials tiene un id (un número o cadena corta) y un name legible; nunca el secreto.

Si no encuentras credentials en ningún nodo, es porque tu workflow no usa ninguna credencial —lo cual está bien, solo significa que el problema de portabilidad de la lección 5 no te va a tocar en ese workflow—.

Por qué funciona: leer tu propio archivo cierra la brecha entre la descripción abstracta y el objeto real. Un campo que localizaste con tu dedo en tu archivo ya no se te olvida. Y descubriste, de paso, la advertencia de que los nombres exactos pueden variar de los de esta lección según tu versión, que era medio punto del ejercicio.

Ejercicio 2 — Clasifica ocho cambios. Para cada uno de estos cambios en order-triage, di si el diff resultante sería mayormente señal (campos estables, cambio real de comportamiento) o mayormente ruido (campos volátiles, sin cambio de comportamiento):

(a) Cambiar el umbral de revisión manual de 5000 a 3000. (b) Arrastrar todos los nodos para reacomodar el diagrama y que se vea más ordenado. (c) Cambiar la URL del CRM a un servidor nuevo. (d) Agregar una conexión de un nodo a otro nuevo. (e) Guardar el workflow sin cambiar nada (n8n regenera versionId). (f) Renombrar el nodo "HTTP Request" a "Get customer from CRM". (g) Cambiar la zona horaria en settings. (h) Importar el workflow en otra instancia, que le regenera los id de nodo.

Ver solución

(a) Señal. Cambia un valor dentro de parameters. Cambio real de comportamiento.

(b) Ruido. Solo cambia position en varios nodos. El workflow hace lo mismo.

(c) Señal. Cambia la url en parameters. El nodo ahora llama a otro lado: comportamiento distinto.

(d) Señal. Cambia connections (y agrega un nodo a nodes). El flujo cambia de verdad.

(e) Ruido. Solo cambia versionId y quizá meta. Comportamiento idéntico.

(f) Mixto, con matiz. Cambia el name del nodo (estable) y todas las connections que lo mencionan. No cambia el comportamiento, pero tampoco es ruido cosmético como position: es un cambio intencional de nombre. En un diff se ve grande, pero es un cambio consciente, no infraestructura regenerada.

(g) Señal. Cambia settings. Afecta cómo el workflow interpreta las fechas: comportamiento real.

(h) Ruido peligroso. Cambian los id de nodo, que son volátiles. No cambia el comportamiento, pero —adelanto de la lección 5— este tipo de regeneración es justo la que causa problemas al mover un workflow. Es ruido en el diff, pero no es inofensivo.

Por qué funciona: si acertaste la mayoría, ya distingues señal de ruido, que es la habilidad completa de esta lección. Los casos (f) y (h) son los interesantes porque no son ni señal pura ni ruido puro: (f) es un cambio intencional que se ve grande, y (h) es ruido que sin embargo importa. Esos matices son los que separan una lectura mecánica de una lectura con criterio.

Ejercicio 3 — Explica el campo credentials con tus palabras. Sin volver a leer la sección, escribe en tres o cuatro frases qué guarda exactamente el campo credentials de un nodo, por qué NO guarda el secreto, y qué consecuencia tiene eso para (a) versionar el workflow y (b) moverlo a otra instancia. Usa una analogía propia si te ayuda.

Ver solución

Una versión posible:

"El campo credentials guarda una referencia a la credencial —un id y un name—, no la credencial en sí. El secreto real (el token, la contraseña) vive cifrado en la base de datos de la instancia, no en el JSON. Es como el número de un casillero: el JSON dice 'usa el casillero 27', pero la llave del casillero está en otro lado. Para (a) versionar, esto es bueno: puedo guardar el workflow en Git sin subir mis secretos (aunque conviene anonimizar el name). Para (b) mover a otra instancia, esto es un problema: el 'casillero 27' de mi instancia no es el de la otra, así que la referencia apunta a la nada y el nodo se rompe."

Por qué funciona: si tu explicación distingue referencia de secreto y saca las dos consecuencias opuestas —bueno para versionar, problemático para mover—, entendiste el concepto más importante para las lecciones 5 y para todo el manejo de credenciales del Módulo 4. La analogía del casillero (o cualquiera que separe "el número" de "lo que hay dentro") es lo que hace que se te quede.

Resumen y siguiente paso

En esta lección abriste la caja del JSON y viste que es el plano del workflow: su descripción completa en texto, con una gramática corta. Recorriste la estructura de nivel superior —name, nodes, connections, settings, active, pinData, identificadores— y miraste de cerca las dos secciones con la sustancia: nodes, la lista de ladrillos, donde cada nodo tiene su name, type, parameters, position, id y credentials; y connections, las flechas, que se describen por nombre de nodo y por eso son legibles. Entendiste la idea más importante para el resto de la guía: el campo credentials guarda una referencia (ID y nombre), no el secreto, que vive cifrado en la base de datos de la instancia. Y aprendiste a separar los campos estables —parameters, connections, name, settings, que cambian solo con la lógica— de los volátiles —position, id, versionId, que cambian por cosmética o infraestructura—, porque esa distinción es lo que hace que un diff sea legible o un muro de ruido.

Antes de avanzar deberías poder: nombrar las secciones principales del JSON; explicar qué guarda credentials y qué no; y clasificar un cambio como señal o ruido según toque un campo estable o volátil.

Lo que sigue es la consecuencia directa de todo esto. Ya sabes que credentials.id es un ID que solo significa algo dentro de tu instancia, y ya intuyes que mover el workflow lo va a romper. La lección 5 hace ese peligro explícito y completo: recorre todos los puntos frágiles de un re-import ingenuo entre instancias —los IDs de credencial, los IDs de nodo, los IDs y URLs de webhook, las variables de entorno embebidas— y te muestra por qué "lo exporté y lo importé" falla en silencio, sin un error grande que te avise, hasta que alguien ejecuta el workflow y algo revienta. Es la lección que convierte tu lectura del JSON en una lista concreta de riesgos que controlar.

Recursos

← Anterior3. Los límites de exportar e importar JSONSiguiente →5. Qué cambia y qué se rompe al reimportar