Marqueurs multi-instances

Vue d'ensemble (Overview)

Utilisez des marqueurs pour configurer une tâche à exécuter une fois pour chaque élément d'une variable Liste, créant plusieurs exécutions séquentielles ou parallèles. Consultez Marqueurs dans le chapitre Amorce BPMN pour obtenir des conseils conceptuels et la notation.

Quand utiliser des marqueurs multi-instances

Utilisez un marqueur multi-instances lorsque vous avez une liste d'éléments et que vous devez exécuter la même tâche une fois pour chacun, par exemple :

• Validation de chaque facture dans une liste d'ID de facture
• Enrichissement d'un ensemble d'enregistrements en appelant une API externe par enregistrement
• Envoi d'une notification à chaque destinataire dans une liste

Sans marqueur, vous devrez créer une boucle manuelle à l'aide de flux de sequence, ce qui est plus difficile à lire et à suivre. Un marqueur multi-instances maintient votre diagramme de processus propre et vous donne une visibilité par élément dans la piste d'exécution : l'exécution de chaque élément apparaît séparément, avec son propre statut et sa propre sortie.

Utilisez le mode Séquentiel lorsque l'ordre compte ou que chaque exécution dépend de la précédente. Utilisez le mode Parallèle lorsque les éléments sont indépendants et que vous souhaitez un débit plus rapide.

Types de collection pris en charge

Maestro traite les types de collection suivants comme pouvant être utilisés en boucle pour l'exécution multi-instances. Si votre variable est l'un de ces types, vous pouvez l'utiliser directement dans le champ Éléments :

• 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
• Types où collectionDataType commence par List
• Types où collectionDataType commence par Array
• Arrays .NET primitifs tels que int[], string[], bool[], double[], decimal[], long[]

Gardez le travail par élément idempotent et éphémère. Utilisez les sections Sorties et Mettre à jour les variables si vous devez collecter les résultats dans une seule variable après que toutes les itérations se sont terminées.

Comment ajouter un marqueur multi-instances

Important :

Configurez l'action de la tâche avant de la convertir en multi-instances. La configuration multi-instances se lie aux sorties de la tâche au moment où vous appliquez le marqueur. Si aucune action n'est sélectionnée à ce stade, la liaison est liée à l'espace réservé de sortie par défaut de la tâche plutôt qu'à la sortie réelle de l'action, et la sélection d'une action par la suite ne rafraîchit pas cette liaison. Chaque itération écrit ensuite dans une sortie non liée, ce qui génère des entrées null dans la variable agrégée lors du runtime. Si vous avez déjà converti la tâche en multi-instances, consultez la section La variable agrégée contient des valeurs nulles pour les éléments non définis et appliquez à nouveau la solution de contournement

1. Sélectionnez une tâche sur la zone de dessin et, dans le panneau Propriétés, configurez son action. Confirmez que la section Sorties reflète l'action que vous avez sélectionnée ; par exemple, une action d'agent expose une sortie response saisie et une sortie Error. Ne continuez que si la section Sorties correspond à l'action.

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

   

3. Choisissez Multi-instances séquentielles ou Multi-instances parallèles.

   Le marqueur apparaît en bas de la forme de la tâche.

4. Dans le panneau Propriétés, développez Instances multiples.

   

5. Dans Éléments, sélectionnez la variable de liste sur laquelle vous souhaitez itérer, par exemple, vars.invoiceList.

   Cela indique à Maestro quelle collection traiter. Sans valeur Éléments, la tâche s'exécute une fois en tant que tâche normale, et non une fois par élément. Maestro crée une exécution par élément dans la liste.

6. Vous pouvez éventuellement développer Gestion des erreurs et activer Réessayer en cas d'échec pour relancer l'exécution de chaque élément individuellement. Pour les options de configuration, consultez Nouvelles tentatives au niveau de l'élément.

Résultat

La tâche est configurée en tant que marqueur multi-instances et s'itére une fois par élément dans la variable de liste sélectionnée. Chaque itération s'exécute de manière séquentielle ou parallèlement selon le type de marqueur choisi.

Remarque :

Les instances multiples sont prises en charge uniquement pour les tâches. Le type de marqueur que vous sélectionnez (séquentiel ou parallèle) détermine l'ordre d'exécution.

Référencer l'élément actuel

La section Multi-instances n'a besoin que de la liste Éléments, c'est là que vous indiquez à Maestro sur quelle collection itérer. Les expressions de l'itérateur vont à un endroit différent : la section Entrées de la tâche, où vous mappez l'élément actuel à une entrée spécifique pour chaque exécution.

L'expression que vous utilisez dépend du fait que le marqueur est appliqué directement à la tâche ou que la tâche s'exécute dans un sous-processus appelé à partir d'une tâche multi-instances.

Scénario	Expression	Où l'utiliser
Marqueur appliqué directement à la tâche	iterator.item	Dans les champs Entrées de la tâche
La tâche s'exécute à l'intérieur d'un sous-processus appelé à partir d'une tâche multi-instances	iterator[0].item	Dans les champs Entrées de la tâche de sous-processus

Remarque :

Le [0] dans iterator[0].item fait référence à l'étendue de l'itérateur la plus externe lorsqu'une tâche s'exécute à l'intérieur d'un sous-processus. Dans le multi-instance à un seul niveau standard, vous utiliserez toujours [0] - il n'y a pas de iterator[1].

Pour transmettre l'ensemble de l'élément actuel, utilisez iterator.item. Pour transmettre une seule propriété, utilisez iterator.item.propertyName. Quelques exemples :

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

Référencer l’élément actuel dans une tâche

Lorsque le marqueur multi-instances est appliqué directement à une tâche, utilisez iterator.item dans la section Entrées du panneau Propriétés pour transmettre l'élément actuel à chaque exécution.

Référence du panneau Propriétés

• Action : choisissez comment la tâche s'exécute - Action Integration Service, action de l'agent ou Aucun pour la modélisation uniquement.

• Entrées : affiche les paramètres définis par l'action sélectionnée. Pour chaque paramètre que vous souhaitez remplir avec l'élément de liste actuel, définissez sa valeur sur iterator.item (pour passer l'élément entier) ou iterator.item.propertyName (pour passer une propriété spécifique).

  

• Sorties : définit ce que chaque itération renvoie. Lorsqu'une action est configurée sur la tâche, les sorties de l'action (généralement response, plus Error pour les actions de l'agent) apparaissent ici automatiquement, chacune liée à sa source via la puce Valeur. Pour ajouter une valeur supplémentaire par itération en plus des sorties de l'action, sélectionnez + Ajouter nouveau et donnez-lui un nom. Si les entrées répertoriées ici ne reflètent pas ce que votre action expose ; par exemple, la puce de Valeur affiche un type d'espace réservé générique au lieu du type de sortie réel de l'action, consultez la section La variable agrégée contient des valeurs nulles.

• Mettre à jour les variables : spécifie la variable de processus qui stocke les sorties agrégées après la fin de toutes les itérations. Sélectionnez Définir la valeur de la variable et choisissez la variable cible, par exemple, vars.validationResults. La variable contient un array avec une entrée par itération : un array de chaînes si chaque itération renvoie une chaîne, un array d'objets si chaque itération renvoie un objet. En mode séquentiel, les entrées suivent l'ordre d'entrée. En mode parallèle, l'ordre correspond à l'achèvement de l'itération et n'est pas garanti.

Référencer l'élément actuel à l'intérieur d'un sous-processus

Lorsqu'une tâche s'exécute à l'intérieur d'un sous-processus qui a été appelé à partir d'une tâche multi-instances, l'élément actuel n'est pas directement disponible en tant que iterator.item. Utilisez plutôt iterator[0].item dans les Entrées de la tâche de sous-processus pour accéder à l'élément transmis à partir de la tâche multi-instances parente.

Référence du panneau Propriétés

• Action : configurez la façon dont la tâche interagit avec le système externe, l'API ou l'agent.

• Entrées : ajoutez une entrée pour chaque valeur dont la tâche a besoin. Définissez la valeur sur iterator[0].item pour passer l'ensemble de l'élément actuel ou iterator[0].item.propertyName pour passer une propriété spécifique.

  Exemple : si votre liste contient des objets avec un champ id, ajoutez une entrée dans la section Entrées du panneau Propriétés :

  • Nom du champ d'entrée : currentItemId
  • Valeur : iterator[0].item.id

  Remplacez .id par le nom de propriété réel de votre liste d'objets.

Exemples

Exemple : valider une liste de factures

Cet exemple montre comment configurer une tâche de service pour s'exécuter une fois par facture dans une liste.

1. Préparer une variable de liste

1. Ouvrez le Gestionnaire de données.
2. Créez une variable :
   • Nom : invoiceList
   • Type : tableau d'objets ou tableau de chaînes
   • Valeur par défaut : ["INV-001", "INV-002", "INV-003"]

2. Ajouter une tâche de service et configurer l'action

1. Ajoutez une tâche de service à la zone de dessin et nommez-la Valider la facture.

2. Avec la tâche sélectionnée, ouvrez la section Action dans le panneau Propriétés et configurez l'agent qui s'exécute pour chaque facture :

   • Action : sélectionnez Démarrer et attendre l'agent.
   • Agent : sélectionnez l'agent responsable de la validation des factures. L'agent doit déjà exister dans votre locataire : vous pouvez en créer un dans Agent Builder.

   

3. Confirmez que la section Sorties reflète l'action de l'agent - La sortie response doit apparaître avec son type de sortie réel, à côté de Error. Ne continuez que si cela correspond.

3. Convertir la tâche en multi-instances

1. With the task selected, open the element toolbar and select Select markers → Sequential multi-instance.
2. Dans le panneau Propriétés, développez Multi-instances et définissez Éléments sur vars.invoiceList.

4. Mapper l'élément actuel à une entrée

Après avoir sélectionné votre action, la section Entrées affiche les paramètres définis par cette action - par exemple, les arguments d'entrée de votre workflow RPA ou les paramètres de votre agent.

Pour chaque paramètre que vous souhaitez remplir avec l'élément de liste actuel, sélectionnez son champ de valeur et entrez iterator.item :

• Utilisez iterator.item pour transmettre l'ensemble de l'élément actuel, par exemple, la string "INV-001" si votre liste contient des strings.
• Utilisez iterator.item.propertyName pour transmettre une propriété spécifique, par exemple, iterator.item.id si votre liste contient des objets.

5. Déboguer le processus

1. Sélectionnez Debug → Debug étape par étape.
2. Maestro exécute Valider la facture une fois par élément de liste.

Résultat

La piste d'exécution affiche une exécution par facture, chacune libellée avec sa valeur d'élément.

Pour exécuter tous les éléments simultanément au lieu de séquentiellement, choisissez Multi-instances parallèles à l'étape 2. Voir également l'exemple de fan-out ci-dessous.

Exemple : Distribution et collecte des résultats

Scénario : vous recevez une liste d'ID de facture depuis une API externe et devez valider chacun indépendamment, puis utiliser les résultats agrégés dans une étape en aval.

1. Assurez-vous qu'une variable de liste, par exemple, vars.invoiceIds, est remplie par une étape précédente, telle qu'une tâche de service qui appelle une API externe.
2. Ajoutez une tâche de service nommée Valider la facture et, sur la tâche régulière, configurez l'action qui valide une seule facture. Confirmez que la section Sorties reflète l'action : l'entrée response doit afficher le type de sortie réel de l'action.
3. With the task selected, select Select markers → Parallel multi-instance.
4. Dans la section Multi-instances, définissez Éléments sur vars.invoiceIds.
5. Dans la section Entrées, mappez iterator.item au paramètre ID de facture de votre action ; par exemple, définissez l'entrée invoiceId sur iterator.item.
6. Dans la section Sorties, vérifiez que la sortie de l'action response est répertoriée et liée au résultat de l'action. Si vous avez besoin d'une valeur agrégée supplémentaire par itération, sélectionnez + Ajouter nouveau et définissez-la. Si les sorties répertoriées ne correspondent pas à ce que votre action expose, le marqueur a été appliqué avant que l'action ne soit configurée ; consultez la section La variable agrégée contient des valeurs nulles.
7. Dans la section Mettre à jour les variables, sélectionnez Définir la valeur de la variable et choisissez la variable pour stocker les résultats agrégés ; par exemple, vars.validationResults. Une fois toutes les itérations terminées, cette variable contient une entrée par facture ; un array de chaînes si votre action renvoie une chaîne, ou un array d'objets si elle renvoie un objet.

Résultat

La tâche multi-instances s’exécute une fois par ID de facture en parallèle, et les résultats agrégés sont collectés dans la variable configurée à la fin de toutes les itérations.

Comportement du runtime

1. Distribution / regroupement : Maestro crée une instance d'activité par élément et termine le groupe lorsque toutes les instances se terminent.
2. Commande : garantie en mode séquentiel ; non garantie en mode parallèle.
3. Simultané : le mode parallèle exécute les éléments simultanément, sous réserve des limites de la plateforme et de la disponibilité des ressources.
4. Échecs : le résultat de chaque élément est indépendant. Définissez la logique en aval pour gérer les défaillances partielles, par exemple, continuer, réessayer ou arrêter en fonction d'un seuil.
5. Observabilité : chaque exécution d'élément est suivie individuellement dans la piste d'exécution, affichant le statut et les résultats par élément.

Résolution des problèmes

La variable agrégée contient des valeurs nulles

La variable agrégée produite par Mettre à jour les variables contient null pour chaque itération (par exemple, [null, null, null]) même si chaque itération s'est exécutée avec succès.

Cela se produit lorsque la tâche a été convertie en multi-instances avant que son action ne soit sélectionnée. La configuration multi-instances est liée à l'espace réservé de sortie par défaut de la tâche plutôt qu'à la sortie réelle de l'action, et la sélection d'une action par la suite n'actualise pas cette liaison. À chaque itération, les données sont écrites dans une sortie non liée et l'agrégateur enregistre null.

Pour corriger une tâche existante :

1. In the element toolbar, select Select markers and remove the multi-instance marker to convert the task back to a regular task.
2. Confirmez que l'action est sélectionnée et que la section Sorties reflète l'action (par exemple, response saisie par l'action, plus Error pour les actions de l'agent).
3. Re-apply the marker with Select markers → Sequential multi-instance or Parallel multi-instance.
4. Dans la section Sorties, vérifiez que les entrées correspondent toujours aux sorties de l'action.

Pour éviter cela sur de nouvelles tâches, configurez toujours l'action avant de convertir la tâche en multi-instances.

L'entrée d'éléments est ignorée et la tâche s'exécute une fois

La tâche s'exécute une seule fois et la valeur Éléments est traitée comme une entrée régulière.

Cela se produit lorsque la variable transmise à Éléments n'est pas l'un des types de collection pris en charge. Vérifiez le type de la variable dans le Gestionnaire de données par rapport aux types de collection pris en charge. Si vous avez défini la liste comme une chaîne simple, convertissez-la en Array de chaînes ou Array d'objets.

Les entrées de sortie ne reflètent pas les sorties de l'action.

La section Sorties n'affiche pas les entrées que vous attendez de l'action sélectionnée ; par exemple, une action d'agent doit exposer response et Error, mais seul un espace réservé response générique apparaît.

Les sorties ont été capturées avant que la sélection d'action ne termine la propagation. Désactivez le marqueur multi-instances via Modifier l'élément → tâche régulière, confirmez que la section Sorties reflète l'action, puis appliquez de nouveau le marqueur.

Meilleures pratiques

1. Validez la collection avant la répartition : vérifiez les listes vides, nulles ou excessivement grandes.
2. Gardez le travail par élément éphémère et tolérant aux pannes. Ajoutez des nouvelles tentatives le cas échéant.
3. Agrégez uniquement ce dont vous avez besoin. Les grandes agrégations peuvent affecter les performances et la lisibilité.
4. Rendez les critères de réussite explicites. Après la tâche multi-instances, ajoutez une passerelle exclusive qui évalue la variable de sortie agrégée - par exemple, ne passez à l'étape suivante que si le nombre de résultats positifs répond à votre seuil.

Remarque :

Les multi-instances parallèles exécutent des éléments par lots de 50. Si chaque élément est un objet grand ou complexe (plusieurs paires clé-valeur ou des structures imbriquées), gardez également la taille totale de la collection inférieure à 50, car la taille des éléments affecte le nombre d'éléments pouvant être maintenus simultanément.

Lisez Marqueurs (BPMN Primer) pour obtenir des notes et des conseils conceptuels, et Prise en charge de BPMN pour obtenir la liste complète des éléments BPMN pris en charge dans Maestro.

Vous travaillez dans un sous-processus ou une activité d'appel ? Pour la définition du périmètre des variables, les mappages d'entrée/de sortie et les variables d'événement de fin, lisez Sous-processus.