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 bouclables 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 instances multiples. La configuration multi-instances est liée aux sorties de la tâche au moment où vous appliquez le marqueur. Si aucune action n'est sélectionnée à ce moment, la liaison sera 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. La sélection d'une action par la suite n'actualise pas cette liaison. Chaque itération écrit ensuite dans une sortie non liée, produisant null entrées dans la variable agrégée au moment du runtime. Si vous avez déjà converti la tâche en instances multiples, consultez la section La variable agrégée contient des valeurs nulles pour la solution de contournement Non définie et réappliquer.

1. Sélectionnez une tâche sur le canevas 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 . Continuez uniquement après que la section Sorties correspond à l'action.

2. Dans la barre d'outils des éléments au-dessus de la tâche, sélectionnez Modifier l'élément.

   

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.

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 d’agent) s’affichent automatiquement, chacune étant 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 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 Variable agrégée contient des valeurs Null.

• Mettre à jour les variables: spécifie la variable de processus qui stocke les sorties agrégées à 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 tableau avec une entrée par itération: un tableau de chaînes si chaque itération renvoie une chaîne, un tableau 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 dans 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 exécuté 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. Continuez uniquement après cette correspondance.

3. Convertir la tâche en instances multiples

1. Avec la tâche sélectionnée, ouvrez la barre d'outils des éléments et sélectionnez Modifier l'élément → Instances multiples séquentielles.
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 renseigner avec l'élément de liste actuel, sélectionnez son champ de valeur et saisissez 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 plutôt que de manière séquentielle, choisissez Instance multiple parallèle à l'étape 2. Consultez également l' exemple de déploiement ci-dessous.

Exemple : Distribution et collecte des résultats

Scénario: Vous recevez une liste d'ID de facture d'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 renseignée 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, dans la tâche habituelle, 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. Avec la tâche sélectionnée, choisissez Modifier l'élément → Instances multiples parallèles.

4. Dans la section Instances multiples , 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 response de l'action 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 un 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 la configuration de l'action; consultez la section La variable agrégée contient des valeurs null.

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 tableau de chaînes si votre action renvoie une chaîne ou un tableau d'objets si elle renvoie un objet.

   

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 Null

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

Cela se produit lorsque la tâche a été convertie en instances multiples 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 écrit dans une sortie non liée et l'agrégateur enregistre null.

Pour corriger une tâche existante:

1. Dans la barre d'outils des éléments, sélectionnez Modifier l'élément et reconvertissez la tâche en tâche standard.
2. Confirmez que l’action est sélectionnée et que la section Sorties reflète l’action (par exemple, response saisi par l’action, plus Error pour les actions d’agent).
3. Convertissez à nouveau la tâche en instances multiples avec Modifier l’élément → Instances multiples séquentielles ou Instances multiples parallèles.
4. Dans la section Sorties , vérifiez que les entrées correspondent toujours aux sorties de l’action.

Pour éviter cela sur les nouvelles tâches, configurez toujours l' action avant de convertir la tâche en instance multiple.

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 standard.

Cela se produit lorsque la variable transmise aux éléments ne fait pas partie des types de collection pris en charge. Vérifiez le type de la variable dans Data Manager par rapport aux types de collection pris en charge. Si vous avez défini la liste sous forme de chaîne simple, convertissez-la en Tableau de chaînes ou Tableau d'objets.

Les entrées de sorties 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 la fin de la propagation de la sélection d'action. Désactivez le marqueur multi-instances via Modifier l’élément → tâche standard, confirmez que la section Sorties reflète l’action, puis réappliquez 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 instances multiples parallèles exécutent des éléments par lots de 50. Si chaque élément est un objet volumineux ou complexe — plusieurs paires clé-valeur ou des structures imbriquées — maintenir la taille totale de la collection en dessous de 50 également, car la taille de l'élément affecte le nombre pouvant être soutenus 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.