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 bucleables para la ejecución multiinstancia. 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:

Configure la acción de la tarea antes de convertirla en multiinstancia. La configuración de instancias múltiples 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 punto, la vinculación está vinculada al marcador de posición de salida predeterminado de la tarea en lugar de a la salida real de la acción, y seleccionar una acción después no actualiza esta vinculación. Cada iteración escribe en una salida independiente, produciendo entradas null en la variable agregada en runtime. Si ya convertiste la tarea a multiinstancia primero, consulta La variable agregada contiene valores nulos para la solución alternativa no establecida y volver a aplicar.

1. Selecciona una tarea en el lienzo y, en el panel Propiedades, configura su Acción. Confirma que la sección Salidas refleja la acción que has seleccionado; por ejemplo, una acción de agente expone una salida response con tipo y una salida Error . Continuar solo después de que la sección Salidas coincida con la acción.

2. En la barra de herramientas del elemento encima de la tarea, selecciona Cambiar elemento.

   

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.

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 en 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 acciones de agente) aparecen aquí automáticamente, cada una vinculada a su origen a través del chip de valor . Para añadir un valor adicional por iteración además de las salidas de la acción, selecciona + Añadir nuevo y dale 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 finalizan todas las iteraciones. Selecciona Establecer valor de variable y elige la variable de destino, por ejemplo, vars.validationResults. La variable contiene una matriz con una entrada por iteración: una matriz de cadenas si cada iteración devuelve una cadena, una matriz de objetos 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 en el panel 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 con Error. Continuar solo después de que esto coincida.

3. Convertir la tarea en multiinstancia

1. Con la tarea seleccionada, abre la barra de herramientas del elemento y selecciona Cambiar elemento → Multiinstancia secuencial.
2. En el Panel de propiedades, expande Multiinstancia y establece Elementos en vars.invoiceList.

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 de la lista actual, selecciona su campo de valor e 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 simultánea en lugar de secuencialmente, elige Multiinstancia paralela en el paso 2. Consulta también el ejemplo de distribución a continuación.

Ejemplo: desplegar y recopilar resultados

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

1. Asegúrate de que una variable de lista, por ejemplo, vars.invoiceIds , se rellena 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 sola 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. Con la tarea seleccionada, elige Cambiar elemento → Multiinstancia paralela.

4. En la sección Multiinstancia , establece Elementos en vars.invoiceIds.

5. En la sección Entradas , asigna iterator.item al parámetro de ID de factura de tu acción; por ejemplo, establece la entrada invoiceId en iterator.item.

6. En la sección Salidas , verifica que la salida response de la acción aparezca en la lista y esté vinculada al resultado de la acción. Si necesitas un valor agregado adicional por iteración, selecciona + Añadir nuevo y defínelo. Si las salidas enumeradas no coinciden con lo que expone tu acción, el marcador se aplicó antes de configurar 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 para almacenar los resultados agregados, por ejemplo, vars.validationResults. Una vez finalizadas todas las iteraciones, esta variable contiene una entrada por factura: una matriz de cadenas si tu acción devuelve una cadena, o una matriz de objetos si devuelve un objeto.

   

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 para cada iteración (por ejemplo, [null, null, null]) aunque cada iteración se haya ejecutado correctamente.

Esto sucede cuando la tarea se convirtió en multiinstancia antes de seleccionar su Acción . La configuración de instancias múltiples está vinculada al marcador de posición de salida predeterminado de la tarea en lugar de a la salida real de la acción, y seleccionar una acción después no actualiza esta vinculación. Cada iteración escribe en una salida independiente y el agregador registra null.

Para corregir una tarea existente:

1. En la barra de herramientas del elemento, selecciona Cambiar elemento y convierte la tarea de nuevo en una tarea regular.
2. Confirma que la acción está seleccionada y que la sección Salidas refleja la acción (por ejemplo, response escrito por la acción, más Error para acciones de agente).
3. Convierte la tarea en multiinstancia de nuevo con Cambiar elemento → Multiinstancia secuencial o Multiinstancia paralela.
4. En la sección Salidas , verifica que las entradas sigan coincidiendo con las salidas de la acción.

Para evitar esto en las nuevas tareas, 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. Comprueba el tipo de variable en Data Manager con Tipos de colección compatibles. Si definiste la lista como una cadena simple, conviértela en Matriz de cadenas o Matriz de objetos.

Las entradas de 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 genérico response .

Las salidas se capturaron antes de que la selección de acciones terminara de propagarse. Desestablece el marcador de instancias múltiples a través de Cambiar elemento → tarea regular, confirma que la sección Salidas refleja la acción y luego vuelve a aplicar el marcador.

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 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 pueden mantenerse simultáneamente.

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.