Marcadores multiinstancia

Información general

Usa los marcadores para configurar una tarea para que se ejecute una vez para cada elemento de una variable de lista, creando varias ejecuciones secuenciales o paralelas. Consulta Marcadores en el capítulo de introducción de BPMN para obtener información sobre la notación y la orientación conceptual.

Cuándo utilizar marcadores multiinstancia

Usa un marcador multiinstancia cuando tengas una lista de elementos y necesites ejecutar la misma tarea una vez para cada uno, por ejemplo:

• Validar cada factura en una lista de ID de facturas
• Enriquecer un conjunto de registros llamando a una API externa por registro
• Enviar una notificación a cada destinatario de una lista

Sin un marcador, tendrías que crear un bucle manual utilizando flujos de secuencia, lo que es más difícil de leer y de rastrear. Un marcador multiinstancia mantiene limpio tu diagrama de procesos y te da visibilidad por elemento en el seguimiento de ejecución: la ejecución de cada elemento aparece por separado, con su propio estado y salida.

Usa el modo secuencial cuando el orden importe o cada ejecución dependa de la anterior. Usa el modo paralelo cuando los elementos sean independientes y quieras un rendimiento más rápido.

Tipos de colección compatibles

Maestro trata los siguientes tipos de colección como bucles para la ejecución en varias instancias. Si tu variable es de uno de estos tipos, puedes utilizarla directamente en el campo Elementos:

• 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[]

Haz que el trabajo por elemento sea idempotente y de corta duración. Usa las secciones Salidas y Actualizar variables si necesitas recopilar los resultados en una sola variable después de finalizar todas las iteraciones.

Cómo añadir un marcador multiinstancia

Importante:

Configura la acción de la tarea antes de convertirla en multiinstancia. La configuración multiinstancia se vincula a las salidas de la tarea en el momento en que aplicas el marcador. Si no se selecciona ninguna acción en ese momento, el vínculo se asocia al marcador de posición de salida predeterminado de la tarea en lugar de a la salida real de la acción, y este vínculo no se actualiza si se selecciona una acción después. Cada iteración escribe en una salida no vinculada, lo que produce null entradas en la variable agregada en runtime. Si ya has convertido la tarea en multiinstancia, consulta La variable agregada contiene valores nulos para corregirlo desconfigurándola y volviéndola a aplicar.

1. Selecciona una tarea en el lienzo y, en el panel de propiedades, configura su acción. Confirma que la sección Salidas refleje la acción que has seleccionado: por ejemplo, una acción de agente expone una salida tipo response y una salida Error.Continúa solo después de que la sección Salidas coincida con la acción.

2. In the element toolbar above the task, select Iteration.

   

3. Elige Multiinstancia secuencial o Multiinstancia paralela.

   El marcador aparece en la parte inferior de la forma de la tarea.

4. En el Panel de propiedades, expande Multiinstancia.

   

5. En Elementos, selecciona la variable de lista sobre la que quieres iterar, por ejemplo, vars.invoiceList.

   Esto le indica a Maestro qué colección procesar. Sin un valor de elementos, la tarea se ejecuta una vez como tarea normal, no una vez por elemento. Maestro crea una ejecución por elemento de la lista.

6. Opcionalmente, expande Gestión de errores y habilita reintentar en caso de error para reintentar las ejecuciones de elementos individuales de forma independiente. Para opciones de configuración, consulta Reintentos a nivel de elemento.

Resultado

La tarea se configura como un marcador de instancias múltiples y se itera una vez por elemento en la variable de lista seleccionada. Cada iteración se ejecuta de forma secuencial o en paralelo dependiendo del tipo de marcador elegido.

Nota:

Multiinstancia solo se admite para tareas. El tipo de marcador que seleccionas (secuencial o paralelo) determina el orden de ejecución.

Hacer referencia al elemento actual

La sección Multiinstancia solo necesita la lista de elementos: ahí es donde se indica a Maestro qué colección se va a iterar. Las expresiones de iterador van a un lugar diferente: la sección Entradas de la tarea, donde asignas el elemento actual a una entrada específica en cada ejecución.

La expresión que utilizas depende de si el marcador se aplica directamente a la tarea o de si la tarea se ejecuta dentro de un subproceso llamado desde una tarea multiinstancia.

Escenario	Expresión	Dónde usarlo
Marcador aplicado directamente a la tarea	iterator.item	En los campos Entradas de la tarea
La tarea se ejecuta dentro de un subproceso llamado desde una tarea multiinstancia	iterator[0].item	En los campos Entradas de la tarea de subproceso

Nota:

El [0] en iterator[0].item se refiere al ámbito del iterador más externo cuando una Tarea se ejecuta dentro de un subproceso. En la multiinstancia estándar de un solo nivel, siempre utilizarás [0] — no hay iterator[1].

Para pasar todo el elemento actual, utiliza iterator.item. Para pasar una PropiedadIndividual, utiliza iterator.item.propertyName. Algunos ejemplos:

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

Hacer referencia al elemento actual de una tarea

Cuando el marcador multiinstancia se aplica directamente a una tarea, utiliza iterator.item en la sección Entradas del panel de propiedades para pasar el elemento actual a cada ejecución.

Referencia del panel de propiedades

• Acción: elige cómo se ejecuta la tarea: acción de Integration Service, acción del agente o Ninguna solo para modelar.

• Entradas: muestra los parámetros definidos por la acción seleccionada. Para cada parámetro que quieras rellenar con el elemento actual de la lista, establece su valor en iterator.item (para pasar todo el elemento) o iterator.item.propertyName (para pasar una propiedad específica).

  

• Salidas: define lo que devuelve cada iteración. Cuando se configura una acción en la tarea, las salidas de la acción (normalmente response, más Error para las acciones del agente) aparecen aquí automáticamente, cada una vinculada a su origen a través del chip Valor. Para añadir un valor adicional por iteración encima de las salidas de la acción, selecciona + Añadir nuevo y ponle un nombre. Si las entradas enumeradas aquí no reflejan lo que expone tu acción (por ejemplo, el chip de valor muestra un tipo de marcador de posición genérico en lugar del tipo de salida real de la acción), consulta La variable agregada contiene valores nulos.

• Actualizar variables: especifica qué variable de proceso almacena las salidas agregadas después de que todas las iteraciones hayan finalizado. Selecciona Establecer valor de variable y elige la variable de destino, por ejemplo, vars.validationResults. La variable contiene un matriz con una entrada por cada iteración: un Array de Strings si cada iteración devuelve una cadena, un Array de Objects si cada iteración devuelve un objeto. En el modo secuencial, las entradas siguen el orden de entrada. En el modo paralelo, el orden coincide con la finalización de la iteración y no está garantizado.

Hacer referencia al elemento actual dentro de un subproceso

Cuando una tarea se ejecuta dentro de un subproceso al que se ha llamado desde una tarea multiinstancia, el elemento actual no está disponible directamente como iterator.item. En su lugar, utiliza las Entradas de la tarea de subproceso iterator[0].itempara acceder al elemento pasado desde la tarea multiinstancia principal.

Referencia del panel de propiedades

• Acción: configura cómo interactúa la tarea con el sistema externo, la API o el agente.

• Entradas: añade una entrada para cada valor que la tarea necesite. Establece el valor como iterator[0].item para pasar todo el Elemento actual o como iterator[0].item.propertyName para pasar una propiedad específica.

  Ejemplo: si tu lista contiene objetos con un campo id, añade una entrada en la sección Entradas del panel de propiedades:

  • Nombre del campo de entrada: currentItemId
  • Valor: iterator[0].item.id

  Reemplaza .id por el nombre de propiedad real de los objetos de tu lista.

Ejemplos

Ejemplo: validar una lista de facturas

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

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 predeterminado: ["INV-001", "INV-002", "INV-003"]

2. Añade una tarea de servicio y configura la acción

1. Añade una tarea de servicio al lienzo y nómbrala Validar factura.

2. Con la tarea seleccionada, abre la sección Acción del panel de propiedades y configura qué agente se ejecuta para cada factura:

   • Acción: Seleccionar Iniciar y esperar al agente.
   • Agente: selecciona el agente responsable de validar las facturas. El agente ya debe existir en tu tenant: puedes crear uno en Agent Builder.

   

3. Confirma que la sección Salidas refleja la acción del agente: la salida response debe aparecer con su tipo de salida real, junto a Error. Continúa solo después de que esto coincida.

3. Convierte la tarea en multiinstancia

1. With the task selected, open the element toolbar and select Select markers → Sequential multi-instance.
2. En el panel de propiedades, expande Multiinstancia y establece vars.invoiceList en elementos.

4. Asigna el elemento actual a una entrada

Después de seleccionar tu acción, la sección Entradas muestra los parámetros definidos por esa acción, por ejemplo, los argumentos de entrada de tu flujo de trabajo de RPA o los parámetros de tu agente.

Para cada parámetro que quieras rellenar con el elemento actual de la lista, selecciona el campo Valor e introduce iterator.item:

• Utiliza iterator.item para pasar todo el elemento actual; por ejemplo, la cadena "INV-001" si tu lista contiene cadenas.
• Utiliza iterator.item.propertyName para pasar una propiedad específica; por ejemplo, iterator.item.id si tu lista contiene objetos.

5. Depurar el proceso

1. Selecciona Depurar → Depurar paso a paso.
2. Maestro ejecuta Validar factura una vez por elemento de lista.

Resultado

El seguimiento de ejecución muestra una ejecución por factura, cada una etiquetada con su valor de elemento.

Para ejecutar todos los elementos de forma concurrente en lugar de secuencial, elige Multiinstancia paralela en el paso 2. Consulta también el ejemplo de distribución siguiente.

Ejemplo: desplegar y recopilar resultados

Escenario: recibes una lista de ID de facturas de una API externa y debes validar cada una de forma independiente para, luego, utilizar los resultados en un paso posterior.

1. Asegúrate de que una variable de lista, por ejemplo, vars.invoiceIds, esté rellenada con un paso anterior, como una tarea de servicio que llama a una API externa.
2. Añade una tarea de servicio llamada Validar factura y, en la tarea regular, configura la acción que valida una única factura. Confirma que la sección Salidas refleja la acción: la entrada response debe mostrar el tipo de salida real de la acción.
3. With the task selected, select Select markers → Parallel multi-instance.
4. En la sección Multiinstancia, establece vars.invoiceIds en Elementos.
5. En la sección Entradas, asigna iterator.item al parámetro de ID de factura de tu acción; por ejemplo, establece iterator.item en la entrada invoiceId.
6. En la sección Salidas, verifica que la salida response de la acción esté en la lista y vinculada a su resultado. Si necesitas otro valor agregado por iteración, selecciona + Añadir nuevo y defínelo. Si las salidas mostradas no coinciden con lo que tu acción expone, el marcador se aplicó antes de que se configurara la acción; consulta La variable agregada contiene valores nulos.
7. En la sección Actualizar variables, selecciona Establecer valor de variable y elige la variable en la que almacenar los resultados agregados, por ejemplo, vars.validationResults. Después de que finalizan todas las iteraciones, esta variable contiene una entrada por factura: un Array de Strings si tu acción devuelve una cadena, o un Array de Objects si devuelve un objeto.

Resultado

La tarea multiinstancia se ejecuta una vez por ID de factura en paralelo, y los resultados agregados se recopilan en la variable configurada una vez finalizadas todas las iteraciones.

Comportamiento de runtime

1. Desplegar/replegar: Maestro crea una instancia de actividad por elemento y completa el grupo cuando todas las instancias terminan.
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: el resultado de cada elemento es independiente. Define la lógica posterior para gestionar fallos parciales; por ejemplo, continuar, reintentar o detener en función de un umbral.
5. Observabilidad: se realiza un seguimiento individual de cada ejecución de elemento en el seguimiento de ejecución, lo que muestra el estado y los resultados por elemento.

Solución de problemas

La variable agregada contiene valores nulos

La variable agregada producida por Actualizar variables contiene null por cada iteración (por ejemplo, [null, null, null]), aunque cada iteración se ejecute correctamente.

Esto sucede cuando la tarea se convierte a multiinstancia antes de que se seleccione su acción. La configuración multiinstancia está vinculada al marcador de posición de salida predeterminado de la tarea en vez de a la salida real de la acción, y este vínculo no se actualiza si se selecciona una acción después. Cada iteración escribe en una salida no vinculada y el agregador registra null.

Para corregir una tarea existente:

1. In the element toolbar, select Select markers and remove the multi-instance marker to convert the task back to a regular task.
2. Confirma que la acción esté seleccionada y que la sección Salidas refleje la acción (por ejemplo, response tipificada por la acción, más Error para las acciones del agente).
3. Re-apply the marker with Select markers → Sequential multi-instance or Parallel multi-instance.
4. En la sección Salidas, verifica que las entradas sigan coincidiendo con las salidas de la acción.

Para evitar que ocurra esto en tareas nuevas, configura siempre la acción antes de convertir la tarea en multiinstancia.

La entrada de elementos se ignora y la tarea se ejecuta una vez

La tarea se ejecuta una sola vez y el valor de Elementos se trata como una entrada regular.

Esto sucede cuando la variable pasada a Elementos no es uno de los tipos de colección compatibles. Contrasta el tipo de la variable en el Gestor de datos con los Tipos de colección compatibles. Si has definido la lista como una cadena sin formato, conviértela en un Array de Strings o Array de Objects.

Las entradas de las salidas no reflejan las salidas de la acción

La sección Salidas no muestra las entradas que esperas de la acción seleccionada; por ejemplo, una acción de agente debe exponer response y Error, pero solo aparece un marcador de posición response genérico.

Las salidas se capturaron antes de que la selección de la acción terminara de propagarse. Quita el marcador multiinstancia a través de Cambiar elemento → tarea regular, confirma que la sección Salidas refleja la acción y, luego, vuelve a aplicarlo.

Mejores prácticas

1. Valida la colección antes de desplegar: comprueba si hay 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. Después de la tarea multiinstancia, añade una puerta de enlace exclusiva que evalúe la variable de salida agregada; por ejemplo, enruta al siguiente paso solo si el número de Resultados correctos cumple tu umbral.

Nota:

La multiinstancia paralela ejecuta elementos en lotes de 50. Si cada elemento es un objeto grande o complejo (varios pares de clave-valor o estructuras anidadas) mantén el tamaño total de la colección por debajo de 50, ya que el tamaño del elemento afecta a cuántos se pueden mantener al mismo tiempo.

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.