Documentación: Nodo Iterar Elementos (Iterate Items)

Descripción General

El Nodo Iterar Elementos (Iterate Items) es un nodo de control de flujo que recorre una lista de elementos y ejecuta una rama del flujo una vez por cada elemento (bucle / for-each). Cuando termina de recorrer todos los elementos, ejecuta una rama distinta de finalización.

Es la herramienta fundamental para aplicar la misma lógica a un conjunto de elementos dinámico: por ejemplo, recorrer todos los sensores devueltos por un nodo Obtener objeto y enviar una notificación o ejecutar una acción sobre cada uno.

---

¿Cuándo usar este nodo?

Utiliza este nodo cuando necesites:

• Repetir una acción para cada elemento de una lista (por ejemplo, enviar una alerta por cada sensor en estado de alarma).
• Procesar la salida de un nodo Obtener objeto (que devuelve un array) elemento por elemento.
• Ejecutar un bloque de lógica un número determinado de veces (pasando un número como entrada).
• Recorrer datos provenientes de un webhook, una consulta a base de datos o una respuesta HTTP.

---

Ramas de Salida (Outputs del nodo)

A diferencia de la mayoría de nodos de acción, el nodo Iterar Elementos tiene dos ramas de salida diferenciadas en el lienzo:

• loop (Bucle): Se ejecuta una vez por cada elemento de la lista. Conecta a esta salida la lógica que quieras repetir (la acción a aplicar sobre cada elemento). Dentro de esta rama puedes acceder al elemento actual de la iteración.
• done (Listo): Se ejecuta una sola vez, cuando la iteración ha terminado de recorrer todos los elementos. Conecta aquí la lógica que debe ocurrir al finalizar el bucle (por ejemplo, un resumen o una notificación final).

TIP: El patrón típico es: la rama loop realiza la acción individual y vuelve a entrar al ciclo; la rama done continúa el flujo principal cuando ya no quedan elementos por procesar.

---

Configuración del Nodo

La configuración del nodo es un único campo de texto donde defines la lista de elementos a iterar.

Elementos (Items)

Acepta tres formas de entrada, como indica el propio nodo ("You can use json array, items separated by comma, or a number for the number of items"):

1. Arreglo JSON: Una lista en formato JSON, por ejemplo ["sensor_a","sensor_b","sensor_c"] o [1,2,3].
2. Elementos separados por coma: Una cadena con valores separados por comas, por ejemplo 1,2,3.
3. Un número: Un número entero que indica cuántas veces repetir el ciclo, por ejemplo 3 (itera 3 veces).

Este campo soporta expresiones de plantilla, por lo que su uso más potente es referenciar la salida de un nodo anterior, por ejemplo {{get_object_node}} para iterar sobre los objetos encontrados por un nodo Obtener objeto.

---

Estructura JSON (Parámetros de entrada)

La configuración del nodo se reduce a un único campo items de tipo texto:

{
  "items": "[\"sensor_a\",\"sensor_b\",\"sensor_c\"]"
}

Campos del JSON

Campo	Tipo	Descripción
items	string	La lista a iterar. Puede ser un arreglo JSON ([...]), valores separados por coma (a,b,c) o un número (3). Soporta expresiones de plantilla para referenciar la salida de nodos anteriores.

---

Output: el elemento actual de la iteración

En cada vuelta del bucle (rama loop), el nodo expone el elemento actual de la iteración, que puede ser referenciado por los nodos conectados a la rama loop mediante la clave del nodo:

{{node_key}}

Si el elemento es un objeto (por ejemplo, proveniente de un nodo Obtener objeto), puedes acceder a sus propiedades directamente:

{{node_key.object_id}}
{{node_key.state_additional_properties.temperature}}

(Recuerda sustituir node_key por la clave asignada automáticamente al nodo en el lienzo.)

---

Ejemplos de uso

Ejemplo 1: Notificar por cada sensor sobre el umbral

Caso de uso: Un nodo Obtener objeto recupera todos los sensores con temperatura sobre el umbral. El nodo Iterar Elementos recorre esa lista y, por cada sensor (rama loop), envía una notificación. Al terminar (rama done), registra un evento de resumen.

• Items: {{get_object_node}} (la salida del nodo Obtener objeto)
• Rama loop → Nodo de notificación usando {{iterate_node.object_id}}.
• Rama done → Nodo de despachar evento "Revisión de temperatura finalizada".

---

Ejemplo 2: Repetir una acción un número fijo de veces

Caso de uso: Ejecutar una acción 3 veces (por ejemplo, reintentar una operación o generar 3 capturas espaciadas).

• Items: 3
• Rama loop → La acción a repetir.

JSON de configuración:

{
  "items": "3"
}

---

Validación y errores

Condición	Causa / Solución habitual
El bucle no se ejecuta	El campo items está vacío o la lista resultante no tiene elementos. Verifica el valor o la expresión de plantilla.
Formato de lista inválido	Si usas JSON, asegúrate de que el arreglo esté bien formado (comillas y corchetes correctos).
La rama done nunca se alcanza	Asegúrate de que la lógica dentro de la rama loop no quede bloqueada o en espera indefinida.

---

Buenas prácticas

• Conectar ambas ramas con intención: Usa loop para la acción repetitiva y done para la lógica de cierre. No olvides conectar la rama done si necesitas continuar el flujo tras la iteración.
• Combinar con Obtener objeto: El patrón Obtener objeto → Iterar elementos → acción es la forma estándar de aplicar lógica a conjuntos dinámicos de dispositivos.
• Nombrar el nodo descriptivamente: Cambia el nombre del nodo en el lienzo (ej. "Por cada sensor") para que las referencias {{node_key}} sean claras.
• Cuidar el volumen: Si la lista puede ser muy grande, considera limitar previamente los resultados (con el limit del nodo Obtener objeto) para no generar ciclos excesivamente largos.