Marqueurs multi-instances

Vue d'ensemble (Overview)

Utilisez des marqueurs pour configurer l'exécution d'un certain type de tâche afin de créer plusieurs exécutions de ces tâches en itérant sur une variable de liste . Consultez la section Marqueurs dans le chapitre BPMN Indexer pour de plus amples informations.

Quel que soit le type de tâche sélectionné, sélectionnez Change element (Modifier l'élément) et choisissez un des types de marqueurs.

Comment ajouter un marqueur multi-instances

Vous pouvez transformer n'importe quelle tâche prise en charge en tâche multi-instances issues du concepteur BPMN :

1. Sélectionnez une tâche sur le canevas.
2. Dans la barre d'outils des éléments au-dessus de la tâche, sélectionnez Change element.
3. Choisissez le marqueur multi-instances .
   • Cela va lier le marqueur BPMN à la tâche.
4. Ouvrez le panneau Propriétés et développez la section Multi-instance pour configurer la liste Éléments .

Remarques

• L'ajout du marqueur BPMN n'affiche pas de contrôles supplémentaires tels que l'alias ou le mode ; la seule configuration apparaît dans la section Multi-instances , sous Items.
• Le marqueur est déclaratif ; Maestro détermine automatiquement le mode d'exécution.
• L'installation multi-instances est prise en charge uniquement pour les tâches, et non les sous-processus.

Quand l’utiliser

Utilisez l'exécution multi-instances pour déployer une activité sur une collection, par exemple :

• validation d’une liste d’identifiants de facture
• Enrichissement des enregistrements
• envoi de notifications par destinataire

Ce modèle s’adapte mieux qu’une boucle manuelle et préserve l’observabilité.

Configuration

• Sélectionnez la tâche que vous souhaitez exécuter pour chaque élément d’une liste.
• Dans le panneau Propriétés, développez Multi-instance.
• Dans Éléments, choisissez la variable de liste qui contient les éléments que vous souhaitez parcourir (par exemple, vars.invoiceList).
  Maestro crée une exécution par élément de liste.
  Référencez l'élément actuel à l'aide de l'index ou de ses propriétés (vars.invoiceList[index].id).
• (Facultatif) Développez Gestion des erreurs et activez Réessayer en cas d'échec pour réessayer des exécutions d'éléments individuelles.
• Exécutez ou déboguez le processus pour afficher une instance d’activité par élément de liste dans la piste d’exécution.

Expression de l'itérateur (lorsqu'elle est disponible)

Certaines activités fournissent un champ dédié permettant de mapper l'élément actuel à la valeur d'entrée exacte par exécution.

Exemples :

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

Les itérateurs représentent des éléments individuels lorsqu'une tâche à plusieurs instances traite une collection.

La syntaxe correcte dépend de l'endroit où l'itération se produit :

iterator.item — lorsqu'un marqueur multi-instances est appliqué à une tâche

Guide du panneau Propriétés

• Action : choisissez comment la tâche s'exécute (action Integration Service, action de l'agent ou Aucune pour la modélisation).
• Entrées : fournissez des valeurs pour chaque itération.
  Exemple :
  • Entrée : invoiceId
  • Value: vars.invoiceList[index].id
• Sorties : Maestro agrége automatiquement toutes les sorties.
• Mettre à jour les variables : choisissez les éléments à mettre à jour après chaque itération ou après la fin du sous-processus.

iterator[0].item — lorsque vous travaillez à l’intérieur d’un sous-processus appelé à partir d’une tâche à plusieurs instances

Guide du panneau Propriétés

• Action : configurez la façon dont le sous-processus interagit avec le système externe, l'API ou l'agent.
• Inputs : mappez l'élément actuel ou ses propriétés.

Exemple :

• Entrée : currentItemId
• Value: vars.itemsToProcess[index].id

Exemple : valider une liste de factures à l'aide de l'exécution multi-instances

Cet exemple montre comment configurer une tâche de service à exécuter une fois par facture.

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
   • Exemple de valeur : ["INV-001", "INV-002", "INV-003"]

2. Ajouter une tâche de service

1. Ajoutez une tâche de service et nommez-la Valider la facture.
2. Ouvrez le panneau Propriétés et développez Multi-instances.
3. Dans Éléments, sélectionnez invoiceList.

3. Utiliser l'élément actuel dans les entrées

Dans la section Entrées :

• Exemple : définissez InvoiceId = vars.invoiceList[index].
• Si la liste contient des objets :
  Utilisez vars.invoiceList[index].Id.

4. Configurer l'implémentation

Dans la section Implémentation :

• Action : Démarrer et attendre un agent
• Agent : votre agent de validation des factures

5. Déboguer le processus

1. Sélectionnez Déboguer étape par étape.
2. Vous verrez une exécution de Valider la facture par élément de liste.
3. La piste d'exécution affiche l'exécution de chaque élément séparément.

Exemple de multi-instances parallèles

1. Ajoutez une tâche de service nommée Valider la facture.
2. Sélectionnez Modifier l'élément → choisissez Plusieurs instances parallèles.
3. Dans le panneau Propriétés, développez Multi-instance.
4. Dans Éléments, choisissez la variable de liste (par exemple, vars.invoiceList).
5. Debug the process to view one activity instance per list element in the Execution trail.

Prise en charge des boucles

Utilisez une multi-instances pour remplacer les boucles manuelles. Traitez la collection comme limite de boucle. Le mode séquentiel traite les éléments dans l’ordre et attend que chacun soit terminé avant le démarrage suivant. Le mode parallèle démarre plusieurs éléments à la fois et se termine lorsque tous les éléments sont terminés ou lorsque votre condition d’arrêt est remplie. Le travail par élément demeure idempotent et de courte durée. Utilisez Agrégation si vous avez besoin d’une seule sortie combinée.

Comportement du runtime

1. Fan toe-out / déploiement in : Maestro crée une instance d'activité par élément et termine le groupe lorsque toutes les instances sont terminées (ou plus tôt, si vous utilisez une politique d'arrêt personnalisée en aval).
2. Ordre : garanti en mode séquentiel ; non garanti en mode Parallèle .
3. Simultanéité : 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 : traitez le résultat de chaque élément indépendamment. La logique aval doit définir comment gérer les échecs partiels (par exemple, continuer, réessayer ou arrêter, en fonction de seuils).
5. Observabilité : chaque exécution d'élément est suivie, ce qui permet d'obtenir le statut par élément et les résultats agrégés.

Exemple

Scénario : vous recevez une liste d'identifiants de facture d'une API externe et devez valider chaque facture via une deuxième API.

Plan :

1. Obtenez une liste dynamique des ID de facture.

2. Appliquez un marqueur multi-instances parallèle à l'activité de validation pour déployer une action par facture.

3. Utilisez Agrégation pour produire une seule sortie combinée (par exemple, une liste de {invoiceId, isValid, errors}) pour les étapes en aval.

   

Meilleures pratiques

1. Validez la collection avant le déploiement.
2. Maintenez les tâches par élément de courte durée et de tolérance aux défaillances ; ajoutez de nouvelles tentatives le cas échéant.
3. Agréger uniquement ce dont vous avez besoin. Les agrégats de grande taille peuvent avoir un impact sur les performances et la lisibilité.
4. Rendez les critères de réussite explicites (par exemple, proceed if ≥95% items succeed).

Remarque :

Actuellement, les multi-instances parallèles exécutent des éléments par lots de 50.

Consultez Markers (BPMN Indexer) pour la notation et des conseils conceptuellements, et BPMN pour obtenir la liste complète des éléments BPMN pris en charge dans Maestro.

Vous travaillez dans une activité de sous-processus ou d’appels ? Pour les étendues de variables, les mappages d'entrée/de sortie et les variables End Event, lisez Sous-processus.