Marcadores multiinstancia

Información general

Utiliza marcadores para configurar la ejecución de un determinado tipo de tarea para crear múltiples ejecuciones de esa tarea iterando sobre una variable de Lista . Consulta Marcadores en el capítulo Manual de BPMN para obtener más información.

Con cualquier tipo de tarea seleccionada, selecciona Cambiar elemento y elige uno de los tipos de marcadores.

Cómo añadir un marcador de instancias múltiples

Puedes convertir cualquier tarea compatible en una tarea multiinstancia desde el diseñador BPMN:

1. Selecciona una tarea en el lienzo.
2. En la barra de herramientas del elemento encima de la tarea, selecciona Cambiar elemento.
3. Elige el marcador de instancias múltiples (icono secuencial o paralelo).
   • Esto adjunta el marcador BPMN a la tarea.
4. Abre el panel de Propiedades y expande la sección Multiinstancia para configurar la lista de Elementos .

Notas

• Añadir el marcador BPMN no expone controles adicionales como alias o modo; la única configuración aparece en la sección Instancia múltiple , en Elementos.
• El marcador es declarativo; Maestro determina el modo de ejecución automáticamente.
• La instancia múltiple solo es compatible con las tareas, no con los subprocesos.

Cuando usarlo

Utiliza la ejecución de varias instancias para desplegar una actividad en una colección, por ejemplo:

• validar una lista de ID de factura
• Enriquecer registros
• enviar notificaciones por destinatario

Este patrón se escala mejor que un bucle manual y conserva la observabilidad.

Configuración

• Selecciona la tarea que deseas ejecutar para cada elemento de una lista.
• En el panel Propiedades, expande Multiinstancia.
• En Elementos, elige la variable de la lista que contiene los elementos sobre los que quieres iterar (por ejemplo, vars.invoiceList).
  Maestro crea una ejecución por elemento de la lista.
  Referencia al elemento actual utilizando el índice o sus propiedades (vars.invoiceList[index].id).
• (Opcional) Expande Gestión de errores y activa Reintentar en caso de fallo para reintentar ejecuciones de elementos individuales.
• Ejecuta o depura el proceso para ver una instancia de actividad por elemento de la lista en el seguimiento de ejecución.

Expresión de iterador (cuando esté disponible)

Algunas actividades proporcionan un campo dedicado para asignar el elemento actual al valor de entrada exacto por ejecución.

Ejemplos:

• item.invoiceId
• item.customer.email
• { id: item.id, flags: ["recheck"] }

Los iteradores representan elementos individuales cuando una tarea de varias instancias procesa una colección.

La sintaxis correcta depende de dónde se produzca la iteración:

iterator.item — cuando una tarea tiene un marcador de instancias múltiples aplicado

Guía del panel de propiedades

• Acción: elige cómo se ejecuta la tarea (acción de Integration Service, acción de agente o Ninguna para el modelado).
• Entradas: proporciona valores para cada iteración.
  Ejemplo:
  • Entrada: invoiceId
  • Value: vars.invoiceList[index].id
• Salidas: Maestro agrega todas las salidas automáticamente.
• Actualizar variables: elige qué actualizar después de cada iteración o después de que finalice el subproceso.

iterator[0].item — cuando se trabaja dentro de un subproceso llamado desde una tarea de varias instancias

Guía del panel de propiedades

• Acción: configura cómo interactúa el subproceso con el sistema externo, la API o el agente.
• Entradas: asigna el elemento actual o sus propiedades.

Ejemplo:

• Entrada: currentItemId
• Value: vars.itemsToProcess[index].id

Ejemplo: validar una lista de facturas utilizando la ejecución de varias instancias

Este ejemplo muestra cómo configurar una tarea de servicio para que se ejecute una vez por factura.

1. Preparar una variable de lista

1. Abre Data Manager.
2. Crear una variable:
   • Nombre: invoiceList
   • Tipo: matriz de objetos o matriz de cadenas
   • Valor de ejemplo: ["INV-001", "INV-002", "INV-003"]

2. Añadir una tarea de servicio

1. Añade una Tarea de servicio y nómbrala Validar factura.
2. Abre el panel Propiedades y expande Multiinstancia.
3. En Elementos, selecciona invoiceList.

3. Utilizar el elemento actual en las entradas

En la sección Entradas :

• Ejemplo: establecer InvoiceId = vars.invoiceList[index].
• Si la lista contiene objetos:
  Usa vars.invoiceList[index].Id.

4. Configurar la implementación

En la sección Implementación :

• Acción: Iniciar y esperar al agente
• Agente: tu agente de validación de facturas

5. Depurar el proceso

1. Selecciona Depurar paso a paso.
2. Verá una ejecución de Validar factura por elemento de la lista.
3. El Seguimiento de ejecución muestra la ejecución de cada elemento por separado.

Ejemplo de varias instancias paralelas

1. Añade una tarea de servicio llamada Validar factura.
2. Selecciona Cambiar elemento → elige Multiinstancia paralela.
3. En el panel de Propiedades, expande Multiinstancia.
4. En Elementos, elige la variable de la lista (por ejemplo, vars.invoiceList).
5. Debug the process to view one activity instance per list element in the Execution trail.

Soporte para bucles

Utilice la instancia múltiple para reemplazar los bucles manuales. Trata la colección como el límite del bucle. El modo secuencial procesa los elementos en orden y espera a que finalice cada uno antes de que comience el siguiente. El modo paralelo inicia muchos elementos a la vez y se completa cuando todos terminan o cuando se cumple tu condición de parada. Mantén el trabajo por elemento idempotente y de corta duración. Utiliza Agregación si necesitas una única salida combinada.

Comportamiento de runtime

1. Fan-out/fan-in: Maestro crea una instancia de actividad por elemento y completa el grupo cuando finalizan todas las instancias (o antes, si utilizas una política de detención personalizada en sentido descendente).
2. Ordenación: garantizada en modo secuencial ; no garantizado en modo paralelo .
3. Concurrencia: el modo paralelo ejecuta elementos simultáneamente, sujeto a los límites de la plataforma y la disponibilidad de recursos.
4. Fallos: trata el resultado de cada elemento de forma independiente. La lógica descendente debe definir cómo manejar los fallos parciales (por ejemplo, continuar, reintentar o detenerse en función de los umbrales).
5. Observabilidad: se realiza un seguimiento de cada ejecución de elemento, lo que permite el estado por elemento y los resultados agregados.

Ejemplo

Escenario: recibes una lista de ID de facturas de una API externa y debes validar cada factura a través de una segunda API.

Planificar:

1. Obtenga una lista dinámica de ID de facturas (de un paso anterior o de una consulta externa).

2. Aplica un marcador de instancias múltiples paralelas a la actividad de validación para desplegar una acción por factura.

3. Utiliza Agregación para producir una única salida combinada (por ejemplo, una lista de {invoiceId, isValid, errors}) para los pasos posteriores.

   

Mejores prácticas

1. Valida la colección antes de la distribución ramificada (listas vacías, nulas o excesivamente grandes).
2. Mantener el trabajo por elemento de corta duración y tolerante a fallos; añade reintentos cuando corresponda.
3. Agrega solo lo que necesitas. Las agregaciones grandes pueden afectar al rendimiento y la legibilidad.
4. Haz explícitos los criterios de éxito (por ejemplo, proceed if ≥95% items succeed).

Nota:

Actualmente, la multiinstancia paralela ejecuta elementos en lotes de 50.

Lee Marcadores (BPMN Manual) para obtener orientación conceptual y de notación, y Compatibilidad con BPMN para ver la lista completa de elementos BPMN compatibles con Maestro.

¿Trabaja en un subproceso o actividad de llamada? Para conocer el alcance de las variables, las asignaciones de entrada/salida y las variables de Evento de finalización, lee Subprocesos.