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 cette tâche en itérant sur une variable Liste. Consultez Marqueurs dans le chapitre BPMN de base pour de plus amples détails.

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 toute tâche prise en charge en une tâche multi-instances depuis le 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 Modifier l'élément.
3. Choisissez le marqueur multi-instances (icône séquentielle ou parallèle).
   • Cela attache le marqueur BPMN à la tâche.
4. Ouvrez le panneau Propriétés et développez la section Instances multiples pour configurer la liste Éléments.

Remarques

• L'ajout du marqueur BPMN n'expose pas des contrôles supplémentaires tels que l'alias ou le mode ; la seule configuration apparaît dans la section Instances multiples sous Éléments.
• Le marqueur est déclaratif ; Maestro détermine automatiquement le mode d'exécution.
• Les instances multiples sont prises en charge uniquement pour les tâches, et non pour les sous-processus.

Quand l’utiliser

Utilisez l'exécution en plusieurs instances pour étendre une activité dans une collection, par exemple :

• validation d'une liste d'ID 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 Instances multiples.
• Dans Éléments, choisissez la variable de liste qui contient les éléments que vous souhaitez itérer (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éployer la gestion des erreurs et activer/désactiver Réessayer après échec pour réessayer les exécutions d'éléments individuels.
• Exécutez ou déboguez le processus pour visualiser une instance d'activité par élément de liste dans le chemin d'exécution.

Expression d'itérateur (lorsque disponible)

Certaines activités fournissent un champ dédié pour mapper l'élément actuel dans 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 à instances multiples Processes une collection.

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

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

Guidage 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 ce que vous souhaitez mettre à jour après chaque itération ou après la fin du sous-processus.

iterator[0].item — lors de l'utilisation d'un sous-processus appelé depuis une tâche multi-instances

Guidage 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.
• Entrées : associez 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 d'une exécution en instances multiples

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, développez Multi-instance.
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 la mise en œuvre

Dans la section Mise en œuvre :

• Action : Démarrer et attendre un agent
• Agent : votre agent de validation de 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 d'instances multiples parallèles

1. Ajoutez une tâche de service nommée Valider la facture.
2. Sélectionnez Changer l'élément → choisissez Instance multiple parallèle.
3. Dans le panneau Propriétés, développez Multi-instances.
4. Dans Éléments, choisissez la variable de liste (par exemple, vars.invoiceList).
5. Déboguez le processus pour visualiser une instance d'activité par élément de liste dans la piste d'exécution.

Prise en charge des boucles

Utilisez manuel pour remplacer les boucles manuelles.Traitez la collection comme limite de la boucle. Le mode séquentiel traite les éléments dans l'ordre et attend que chacun se termine avant que le suivant ne démarre.Le mode parallèle démarre de nombreux éléments à la fois et s'achève lorsque tous se terminent ou lorsque votre condition d'arrêt est remplie. Gardez le travail par élément idempotent et éphémère. Utilisez l'agrégation si vous avez besoin d'une seule sortie combinée.

Comportement du runtime

1. Fan‑out/fan‑in : Maestro crée une instance d'activité par élément et complète le groupe lorsque toutes les instances se terminent (ou plus tôt si vous utilisez une politique d'arrêt personnalisée en aval).
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 : traitez le résultat de chaque élément indépendamment. La logique en aval doit définir la gestion des échecs partiels (par exemple, continuer, réessayer ou arrêt en fonction des seuils).
5. Observabilité : chaque exécution d'élément est suivie, ce qui active le statut par élément et les résultats agrégés.

Exemple

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

Plan :

1. Obtenez une liste dynamique d'ID de facture (à partir d'une étape précédente ou d'une interrogation externe).

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

3. Utilisez l'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 (listes vides, nulles ou excessivement grandes).
2. Gardez le travail par élément de courte durée et tolérant aux pannes ; ajoutez des tentatives supplémentaires le cas échéant.
3. Agrégez uniquement ce dont vous avez besoin. Les grandes agrégations peuvent avoir un impact sur les performances et la lisibilité.
4. Rendez explicites les critères de succès (par exemple, proceed if ≥95% items succeed).

Remarque :

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

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 de l'étendue des variables, les mappages entrée et sortie, et les variables d'événement de fin, lisez Sous-processus.