Marcadores multiinstancia

Información general

Usa marcadores para configurar la ejecución de un determinado tipo de tarea para crear varias ejecuciones de esa tarea iterando sobre una variable de tipo Lista. Consulta Marcadores en el capítulo de introducción de BPMN para obtener más detalles.

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

Cómo añadir un marcador multiinstancia

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 multiinstancia (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 Multiinstancia, en Elemento.
• El marcador es declarativo; Maestro determina automáticamente el modo de ejecución.
• Multiinstancia solo se admite para tareas, no para subprocesos.

Cuando usarlo

Usa la ejecución multiinstancia para desplegar una actividad en una colección, por ejemplo:

• validar una lista de ID de facturas
• enriquecer registros
• Enviar notificaciones por destinatario

Este Patrón se escala mejor que un bucle manual y mantiene la observabilidad.

Configuración

• Seleccionar la Tarea que quieres ejecutar para cada Elemento de una lista.
• En el Panel de propiedades, expande Multiinstancia.
• En Elementos, elige la variable de lista que contiene los elementos sobre los que quieres iterar (por ejemplo, vars.invoiceList).
  Maestro crea una ejecución por elemento de lista.
  Referencia al elemento actual con el índice o sus propiedades ().
• (Opcional) Expandir el manejo de errores y alternancia Reintentar en caso de error para reintentar las ejecuciones de elementos individuales.
• Ejecuta o depura el proceso para ver una instancia de actividad por elemento de 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 multiinstancia procesa una colección.

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

iterator.item — cuando una Tarea tiene aplicado un marcador multiinstancia

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 Ninguno para modelar).
• Entradas: proporciona valores Para cada iteración.
  Ejemplo:
  • Entrada: invoiceId
  • Value: vars.invoiceList[index].id
• Salidas: Maestro agrega automáticamente Todos las salidas.
• Actualizar variables: elige qué actualizar después de cada iteración o después de que el subproceso termine.

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

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 ejecución multiinstancia.

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 el Gestor de datos.
2. Crear una variable:
   • Nombre: invoiceList
   • Tipo: array de objetos o array 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 dale el nombre Validar factura.
2. Abre el Panel de propiedades, expande Multiinstancia.
3. En Elementos, selecciona invoiceList.

3. Utilizar el elemento actual en entradas

En la sección Entradas:

• Ejemplo: establece InvoiceId = .
• 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ás una ejecución de Validar factura por elemento de lista.
3. El seguimiento de ejecución muestra la ejecución de cada elemento por separado.

Ejemplo de multiinstancia en paralelo

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 lista (por ejemplo, vars.invoiceList).
5. Depura el proceso para ver una instancia de actividad por elemento de lista en el seguimiento de ejecución.

Soporte para bucles

Usa multiinstancia para reemplazar bucles manuales. Trata la Colección como el límite del bucle. El modo secuencial processes los elementos en orden y espera a que cada uno finalice antes de que se inicie el siguiente. El modo paralelo inicia muchos elementos a la vez y se completa cuando todos terminan o cuando se cumple la condición de detener. Haz que el trabajo por elemento sea idempotente y de corta duración. Usa Agregación si necesitas una sola salida combinada.

Tipos de colección tratados como iterables

Para la ejecución multiinstancia, Maestro trata los siguientes tipos de colección como iterables:

• System.Collections.Generic.List<T>
• System.Collections.Generic.IList<T>
• System.Collections.Generic.IEnumerable<T>
• System.Collections.IEnumerable
• System.Data.DataTable
• Newtonsoft.Json.Linq.JArray
• Tipos donde collectionDataType comienza con List
• Tipos donde collectionDataType comienza con Array
• Matrices .NET primitivas como int[], string[], bool[], double[], decimal[], long[]

Comportamiento de runtime

1. Fan‑out / fan‑in: Maestro crea una instancia de actividad por elemento y completa el grupo cuando todas las instancias finalizan (o antes, si utilizas una política de parada personalizada hacia abajo).
2. Ordenación: garantizado en modo Secuencial; no garantizado en modo Paralelo.
3. Concurrencia: el modo paralelo ejecuta elementos de forma concurrente, sujetos a los límites de la plataforma y la disponibilidad de recursos.
4. Errores: trata de forma independiente el resultado de cada elemento. La lógica descendente debe definir cómo el manipulador gestiona los fallos parciales (por ejemplo, continuar, reintentar o detener en función de los umbrales).
5. Observabilidad: se realiza un seguimiento de cada ejecución de elemento, lo que permite obtener el estado por elemento y los resultados agregados.

Ejemplo

Escenario: se recibe una lista de ID de facturas de una API externa y hay que validar cada factura a través de una segunda API.

Plan:

1. Obtén una lista dinámica de ID de facturas (de un paso anterior o de una interrogación externa).

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

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

   

Mejores prácticas

1. Valida la colección antes de desplegar (listas vacías, nulas o excesivamente grandes).
2. Haz que el trabajo por elemento sea 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 a la legibilidad.
4. Haz que los criterios de éxito sean explícitos (por ejemplo, proceed if ≥95% items succeed).

Nota:

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

Consulta Marcadores (Introducción a BPMN) para obtener orientación conceptual y notación y consulta soporte de BPMN para obtener la lista completa de elementos BPMN que se admiten en Maestro.

¿Trabajas en un subproceso o una actividad de llamada? Para establecer el ámbito de variable, asignar entrada/salida y variables de evento de fin, consulta Subprocesos.