Guide du Développeur pour les Actions de l'Interface Web

Les actions sont le moteur de votre interface web Softyflow. Ce sont des commandes puissantes et exécutables qui donnent vie à votre application, transformant des pages statiques en expériences dynamiques et interactives. En liant des actions aux interactions de l'utilisateur (comme un clic sur un bouton) ou à des événements système (comme le chargement d'une page), vous pouvez orchestrer des workflows complexes et logiques sans avoir à écrire beaucoup de code.

Ce guide fournit une description complète de chaque action disponible dans le modeleur web. Nous explorerons leurs paramètres, partagerons des exemples pratiques et proposerons les meilleures pratiques pour vous aider à construire des applications robustes et conviviales.

Catalogue des Actions​

Trouvez rapidement l'action dont vous avez besoin en utilisant les liens ci-dessous.

1. Manipulation de l'IU: Créer une Expérience Utilisateur Réactive​

Ces actions modifient dynamiquement l'apparence et l'état des éléments de l'IU, vous permettant de créer une interface fluide et intuitive pour vos utilisateurs.

1.1. show: Révéler des Éléments Cachés​

L'action show modifie la visibilité d'un élément, changeant sa propriété CSS display de none à sa valeur par défaut, le faisant ainsi apparaître sur la page. Cette action est fondamentale pour créer des formulaires réactifs et dynamiques. Vous pouvez concevoir des interfaces qui masquent par défaut des sections complexes ou conditionnelles, ne les révélant que lorsque la saisie d'un utilisateur les rend pertinentes. Cela désencombre l'IU et guide l'utilisateur à travers le workflow.

Configuration​

• Element ID (string): L'identifiant unique de l'élément DOM que vous souhaitez rendre visible.

Scénario d'Exemple​

Imaginez un formulaire d'inscription où une case à cocher demande: "Vous inscrivez-vous en tant qu'entreprise ?". Si l'utilisateur coche cette case, vous souhaitez afficher un champ pour son numéro de TVA.

1. Déclencheur: L'événement onClick de la case à cocher "Vous inscrivez-vous en tant qu'entreprise ?".
2. Action: Une action show est configurée avec l'Element ID du conteneur contenant le champ de saisie du numéro de TVA.
3. Résultat: Lorsque la case est cochée, le champ du numéro de TVA apparaît instantanément. Lorsqu'elle est décochée (en utilisant une action hide correspondante), il disparaît, gardant le formulaire propre et pertinent par rapport au contexte de l'utilisateur.

1.2. hide: Masquer des Éléments​

L'action hide définit la propriété CSS display d'un élément à none, le supprimant ainsi de la vue de l'utilisateur et de la mise en page de la page. C'est le pendant direct de l'action show. Il est essentiel pour nettoyer l'interface en masquant les contrôles, les messages ou les sections qui ne sont plus pertinents pour le contexte actuel de l'utilisateur. Il est fréquemment utilisé dans le bloc else d'une action if pour créer des effets de basculement.

Configuration​

• Element ID (string): L'identifiant unique de l'élément DOM que vous souhaitez masquer.

Scénario d'Exemple (Focus sur hide)​

Dans un formulaire d'inscription, une case à cocher demande: "Vous inscrivez-vous en tant qu'entreprise ?" Le champ Numéro de TVA ne doit être visible que lorsque cette case est cochée.

1. Déclencheur: L'événement onClick de la case à cocher "Vous inscrivez-vous en tant qu'entreprise ?".
2. Condition: Une action if vérifie si la case est décochée (false).
3. Action: Une action hide est configurée avec l'Element ID du conteneur contenant le champ de saisie du Numéro de TVA.
4. Résultat: Lorsque l'utilisateur décoche la case, le champ Numéro de TVA est immédiatement masqué. Cela garantit que le formulaire reste propre et n'affiche que les champs pertinents pour les utilisateurs non professionnels.

1.3. toggleVisibility: Basculer Entre Visible et Caché​

L'action toggleVisibility offre un moyen pratique de basculer la visibilité d'un élément. Elle vérifie automatiquement si un élément est actuellement affiché ou masqué et applique l'état opposé. Cette action est parfaite pour créer des éléments d'IU interactifs qu'un utilisateur peut ouvrir et fermer à plusieurs reprises. Elle simplifie la logique pour des fonctionnalités comme les extenseurs "Lire la suite", les panneaux repliables, les accordéons de FAQ ou les menus déroulants, car vous n'avez pas besoin de gérer l'état avec des actions show et hide séparées.

Configuration​

• Element ID (string): L'identifiant unique de l'élément DOM à basculer.

Scénario d'Exemple​

Vous avez un bouton "Afficher les détails" qui révèle un panneau de configuration avancé. En attachant l'action toggleVisibility à l'événement onClick du bouton et en ciblant l'ID du panneau, vous pouvez créer toute la fonctionnalité d'affichage/masquage avec une seule action. Le premier clic affiche le panneau, le deuxième le masque, le troisième l'affiche à nouveau, et ainsi de suite.

1.4. setRequired: Appliquer des Règles Dynamiquement​

L'action setRequired ajoute ou supprime par programme l'attribut HTML required sur un champ de formulaire. Cela s'intègre entièrement à la validation de formulaire intégrée de Softyflow, vous permettant d'appliquer des règles dynamiquement en fonction de la saisie de l'utilisateur. Cette action vous permet de construire des formulaires intelligents et adaptatifs. Au lieu de submerger les utilisateurs d'erreurs de validation pour des champs qui ne s'appliquent peut-être pas à eux, vous pouvez rendre les champs obligatoires uniquement lorsqu'ils deviennent pertinents, guidant l'utilisateur à remplir correctement le formulaire.

Configuration​

• Element ID (string): L'ID de l'élément de formulaire cible (par exemple, un champ de texte, une liste déroulante ou une case à cocher).
• Value (boolean): Définir sur true pour rendre le champ obligatoire, ou false pour le rendre facultatif.

Scénario d'Exemple​

Dans un formulaire de commentaires, si un utilisateur sélectionne une note de "1 étoile" ou "2 étoiles" dans une liste déroulante, vous souhaitez l'obliger à laisser un commentaire.

1. Déclencheur: L'événement onChange de la liste déroulante de notation par étoiles.
2. Action: Une action if vérifie si SF_input.value <= 2.
3. Logique:
   • Si true, une action setRequired cible la zone de texte "Commentaires" avec une Valeur de true.
   • Dans la branche else, une autre action setRequired cible la même zone de texte avec une Valeur de false, la rendant facultative pour les notes plus élevées.

1.5. setDisable: Contrôler l'Interaction Utilisateur​

L'action setDisable vous donne un contrôle programmatique sur l'état disabled d'un élément de formulaire, vous permettant de l'activer ou de le désactiver à la volée. Un élément désactivé est visible mais en lecture seule et ne peut pas être interagi avec. Utilisez ceci pour empêcher les utilisateurs de modifier certains champs en fonction de leurs autorisations, de l'état de l'application ou d'un choix qu'ils ont fait ailleurs dans le formulaire. Il fournit un indicateur visuel clair que la valeur d'un champ est fixe et non modifiable.

Configuration​

• Element ID (string): L'ID de l'élément de formulaire à contrôler.
• Value (boolean): Définir sur true pour désactiver l'élément, ou false pour l'activer.

Scénario d'Exemple​

Sur une page "Modifier le profil", l'adresse e-mail de l'utilisateur est initialement désactivée pour éviter toute modification accidentelle. Un bouton intitulé "Modifier l'e-mail" est ajouté à côté du champ e-mail. Lorsque l'utilisateur clique sur ce bouton, une action setDisable est déclenchée avec une Valeur de false, ciblant le champ de saisie de l'e-mail. Cela déverrouille le champ e-mail, permettant à l'utilisateur de mettre à jour son adresse en toute sécurité et intentionnellement.

1.6. disableForm: Protéger l'Intégrité du Formulaire​

L'action disableForm est un utilitaire puissant qui désactive tous les éléments interactifs — y compris les entrées, les boutons et les listes déroulantes — dans un conteneur de formulaire spécifié en une seule étape. C'est une action cruciale pour maintenir l'intégrité des données et fournir un retour clair à l'utilisateur lors des événements de soumission. En désactivant le formulaire, vous empêchez les utilisateurs de cliquer accidentellement plusieurs fois sur le bouton "Soumettre" ou de modifier des données pendant qu'une opération en arrière-plan (comme un appel API ou une mise à jour de processus) est en cours.

Configuration​

• Attach form (object): Une référence au conteneur de formulaire qui contient tous les éléments à désactiver.

Scénario d'Exemple​

Lorsque l'utilisateur clique sur le bouton "Enregistrer" à l'intérieur du formulaire:

L'action disableForm est déclenchée immédiatement.

Tous les champs et boutons à l'intérieur du formulaire deviennent désactivés afin que l'utilisateur ne puisse pas modifier les données ou cliquer plusieurs fois.

Une fois l'opération terminée, le formulaire peut être réactivé ou l'utilisateur peut être redirigé vers une autre page.

1.7. refreshWidget: Afficher des Données à Jour​

L'action refreshWidget force un widget spécifique (comme une Liste, un Tableau, un Graphique ou une Grille de Données) à réexécuter sa requête de données et à se rendre avec les informations les plus récentes de sa source de données. Cette action est essentielle pour créer une expérience utilisateur dynamique en temps réel. Après toute action qui crée, met à jour ou supprime des données affichées dans un widget, vous devez appeler refreshWidget pour vous assurer que l'utilisateur voit immédiatement le résultat de son action sans avoir à recharger manuellement la page.

Configuration​

• Element ID (string): L'ID du widget que vous souhaitez rafraîchir.

Scénario d'Exemple​

Un utilisateur gère une liste de départements d'entreprise. Il souhaite ajouter un nouveau département à l'aide d'un formulaire modal.

1. Le bouton "Ajouter un département" du modal déclenche une action addToCollection pour enregistrer le nouveau département dans la collection Départements.
2. Immédiatement après, une action hide ferme la fenêtre modale.
3. L'action finale est refreshWidget, ciblant le widget de la liste principale des départements. Une fois le modal fermé, l'utilisateur voit le département nouvellement ajouté apparaître instantanément dans la liste.

1.8. fillForm: Remplir des Formulaires avec des Données​

L'action fillForm remplit efficacement les champs d'un formulaire entier avec les données d'un seul objet JSON. Elle fonctionne en faisant correspondre les clés de l'objet aux attributs id des champs de formulaire correspondants. C'est un gain de temps considérable pour toute fonctionnalité de "modification" ou de "visualisation des détails". Lorsqu'un utilisateur sélectionne un élément d'une liste à modifier, vous pouvez utiliser getDocument pour récupérer l'objet de données complet de l'élément, puis le passer directement à fillForm pour remplir instantanément et complètement le formulaire de modification.

Configuration​

• Attach form (object): Le conteneur de formulaire à remplir.
• Form model (object): Un objet JSON contenant les paires clé-valeur pour remplir le formulaire.

Scénario d'Exemple​

Dans une application de gestion d'entreprise, un utilisateur clique sur l'icône "Modifier" à côté du nom d'un département dans un tableau.

1. L'événement onClick sur l'icône déclenche une action qui ouvre une popup.
2. Remplir le Formulaire L'action suivante est fillForm, qui cible le formulaire "Modifier le Département" et utilise la variable SF_input comme Modèle de Formulaire.
3. Afficher le Formulaire Enfin, une action show affiche le formulaire "Modifier le Département", maintenant entièrement rempli avec les données du département.

1.9. clearForm: Réinitialiser la Saisie Utilisateur​

L'action clearForm offre un moyen simple de réinitialiser tous les champs d'un conteneur de formulaire spécifié à leur état d'origine, vide. C'est une fonctionnalité de qualité de vie pour améliorer l'expérience utilisateur sur les formulaires complexes. Elle est généralement attachée à un bouton "Réinitialiser" ou "Effacer", offrant aux utilisateurs une méthode en un clic pour recommencer sans la tâche fastidieuse de vider manuellement chaque champ de saisie.

Configuration​

• Attach form (object): Le conteneur de formulaire dont les champs doivent être effacés.

Scénario d'Exemple​

Un utilisateur remplit un formulaire de recherche. Tous les champs de saisie sont placés dans le même conteneur de formulaire. Dans l'action clearForm, le développeur sélectionne le formulaire en choisissant son ID dans le champ Attach form.

Lorsque le bouton "Réinitialiser" (également à l'intérieur du formulaire) est cliqué, l'action clearForm s'exécute et efface toutes les entrées de ce formulaire, le ramenant à un état vide.

1.10. confirm: Demander une Confirmation à l'Utilisateur​

L'action confirm affiche une boîte de dialogue de confirmation native du navigateur avec un message personnalisé. C'est une action modale qui interrompt l'exécution des actions suivantes jusqu'à ce que l'utilisateur clique sur "OK" ou "Annuler". C'est un mécanisme de sécurité essentiel qui doit toujours être utilisé avant toute opération destructrice ou irréversible. Utilisez-le pour éviter la perte accidentelle de données lorsqu'un utilisateur essaie de supprimer un enregistrement, d'abandonner des modifications non enregistrées ou de soumettre une application finale.

Retours​

• Output (boolean): La caractéristique la plus importante de cette action est sa sortie booléenne. Elle renvoie true si l'utilisateur clique sur "OK" et false s'il clique sur "Annuler". Cette sortie doit être utilisée comme condition pour une action if suivante pour contrôler le workflow.

Configuration​

• Message (string): La question ou l'avertissement à afficher dans la boîte de confirmation (par exemple, "Êtes-vous sûr de vouloir supprimer définitivement cette facture ?").

Scénario d'Exemple​

Un utilisateur remplit un formulaire et a déjà saisi plusieurs valeurs. À l'intérieur du formulaire, il y a un bouton "Réinitialiser" qui efface tous les champs à l'aide de l'action clearForm.

Pour éviter de perdre des données par erreur, la première action déclenchée par le bouton est confirm, avec un message comme: "Êtes-vous sûr de vouloir réinitialiser le formulaire ?"

• Si l'utilisateur clique sur "OK", l'action confirm renvoie true, et le workflow continue vers l'action suivante, qui est clearForm, effaçant toutes les entrées du formulaire.
• Si l'utilisateur clique sur "Annuler", l'action confirm renvoie false, et le workflow s'arrête — le formulaire reste inchangé.

Cela garantit que l'utilisateur ne perd pas accidentellement sa saisie.

1.11. alertMessage: Fournir un Retour Utilisateur Clair​

L'action alertMessage affiche une petite notification pop-up non bloquante (souvent appelée "toast") pour fournir un retour immédiat et contextuel à l'utilisateur. C'est la manière standard et la meilleure de communiquer le résultat d'une opération en arrière-plan. Elle informe l'utilisateur du succès ou de l'échec de son action sans interrompre son workflow, contrairement à une alerte de navigateur standard.

Configuration​

• Type: Définit le style et la couleur de l'alerte. Les options valides sont info, success, warning et error.
• Message (string): Le contenu textuel à afficher dans la notification. Il peut s'agir de texte statique ou inclure des valeurs dynamiques provenant de variables.

Scénario d'Exemple​

Un utilisateur sélectionne une date dans un sélecteur de date. Une condition if vérifie si la date sélectionnée est aujourd'hui ou une date future.

• Si selected_date >= today, la condition renvoie true, et un alertMessage avec Type: success est affiché: "La date est valide."
• Si selected_date < today, la condition renvoie false, et un alertMessage avec Type: Warning est affiché: "Date invalide: Veuillez sélectionner aujourd'hui ou une date future."

Cela donne à l'utilisateur un retour immédiat tout en gardant le workflow fluide.

2. Gestion des Données et des Variables​

Ces actions sont les blocs de construction pour gérer l'état, manipuler les données et contrôler les informations qui alimentent votre application.

2.1. setModel: Gérer les Variables de Processus​

L'action setModel est utilisée pour définir ou mettre à jour une variable de processus (également appelée modèle). Ces variables sont l'état des données de base de votre application, sont persistantes au sein d'une instance de processus donnée et peuvent être transmises aux processus back-end. Utilisez setModel pour stocker et manipuler toutes les données essentielles à la logique de votre workflow, telles que l'ID d'un client, un total calculé ou l'état actuel d'une application. Ces données agissent comme la "mémoire" de votre processus d'une étape à l'autre.

Configuration​

• Name (string): Le nom de la variable de modèle (par exemple, invoice_data).
• Update variable value (any): La nouvelle valeur pour la variable. Il peut s'agir d'une valeur statique ou de données provenant d'un autre élément ou d'une autre variable.

Scénario d'Exemple​

Un utilisateur remplit un formulaire d'achat où il sélectionne le prix d'un produit et entre une quantité.

Un calcul est effectué pour déterminer le montant total à payer.

• L'expression {{ price }} * {{ quantity }} est évaluée.
• Une action setModel stocke le résultat dans une variable de processus appelée total_amount.

Par exemple, si le prix est de 100 et la quantité est de 3, la valeur calculée 300 est automatiquement enregistrée dans total_amount.

Cela permet de réutiliser le montant total plus tard dans le workflow, par exemple en l'affichant dans l'IU ou en l'envoyant au back-end lors de la soumission de la commande.

2.2. setVariable: Gérer les Variables au Niveau de la Page​

L'action setVariable définit ou met à jour une variable globale et temporaire accessible n'importe où sur la page actuelle. Contrairement aux modèles, ces variables ne sont pas persistantes et sont réinitialisées si la page est rechargée. setVariable est parfait pour stocker un état d'IU temporaire qui n'a pas besoin d'être enregistré avec les données de l'instance de processus. C'est utile pour suivre des informations spécifiques à l'IU comme des indicateurs, des compteurs, des sélections temporaires de l'utilisateur ou si une animation a déjà été jouée.

Configuration​

• Name (string): Le nom de la variable de page globale (par exemple, is_details_panel_visible).
• Value (any): La valeur à assigner à la variable.

Scénario d'Exemple​

Une page contient un champ de saisie et un bouton.

1. L'utilisateur tape un message dans un champ de saisie.
2. Lorsqu'il clique sur Entrée, une action setVariable stocke la valeur de saisie dans une variable de page nommée var_alert.
3. Une action alert est ensuite déclenchée et affiche un message dynamique en utilisant la variable: vm.var_alert.

Résultat: L'alerte affiche la valeur exacte saisie par l'utilisateur. Les données sont temporaires et seront effacées si la page est actualisée.

2.3. pushToArray: Construire des Listes Dynamiquement​

L'action pushToArray ajoute un nouvel élément (généralement un objet JSON) à un tableau stocké dans un modèle ou une variable de page. Si le tableau spécifié n'existe pas, cette action le créera d'abord avant d'ajouter l'élément. Cette action est inestimable pour toute fonctionnalité où un utilisateur a besoin de construire dynamiquement une liste d'éléments. C'est le mécanisme de base derrière les paniers d'achat, l'ajout de lignes à une facture, l'attachement de plusieurs fichiers ou l'ajout d'invités à une liste d'événements.

Configuration​

• Array Name (string): Le nom du modèle ou du tableau de variables auquel vous souhaitez ajouter (par exemple, invoice_items).
• Json Object (object): L'objet à ajouter comme nouvel élément au tableau.

Scénario d'Exemple​

Dans un formulaire de création de facture, il y a un sous-formulaire pour ajouter une seule ligne (avec des champs pour la description, la quantité et le prix). Lorsque l'utilisateur clique sur un bouton "Ajouter un article":

1. Une action pushToArray est déclenchée.
2. Le Nom du Tableau est défini sur table_invoice_items.
3. L'Objet Json est construit à partir des champs du sous-formulaire: { "desc": "Souris sans fil", "qty": "2", "price": "19.99" }.
4. Enfin, une action refreshWidget met à jour la liste des lignes de la facture pour afficher l'article nouvellement ajouté.

3. Logique et Contrôle de Flux​

Contrôlez le flux d'exécution de vos actions avec une logique conditionnelle et des boucles, vous permettant de construire des comportements complexes et réactifs.

3.1. if: Prendre des Décisions dans Votre Logique​

L'action if est la pierre angulaire de la prise de décision dans Softyflow. Elle vous permet d'exécuter différents ensembles d'actions imbriquées selon qu'une condition donnée est évaluée à true ou false. Elle prend en charge les branches if, else if et else pour construire une logique complexe. Cette action est fondamentale pour presque tous les workflows non triviaux. Elle est utilisée pour valider les entrées de formulaire, vérifier les rôles et autorisations des utilisateurs, répondre aux sélections des utilisateurs, gérer différentes réponses d'API et créer tout type de chemin logique conditionnel.

Configuration​

• condition (boolean): Une expression qui doit être résolue en un booléen true ou false. Vous pouvez écrire des conditions complexes en utilisant JavaScript.
• actions: Blocs d'actions imbriqués séparés pour les branches if, else if et else.

Scénario d'Exemple​

Dans un formulaire d'approbation commerciale, un utilisateur doit choisir une option: Approuver ou Rejeter.

1. L'utilisateur sélectionne une option et clique sur le bouton "Soumettre".
2. Une action if vérifie la décision sélectionnée avec la condition: {{ decision }} == 'approve'
3. Si la condition est vraie (Approuver sélectionné): Un alertMessage est affiché: "La demande a été approuvée avec succès."
4. Sinon (Rejeter sélectionné): Un alertMessage est affiché: "La demande a été rejetée."

3.2. repeat (boucle): Exécuter des Actions Plusieurs Fois​

L'action repeat crée une boucle simple qui exécute un ensemble d'actions imbriquées un nombre de fois spécifié. Elle fournit une variable spéciale SF_loop.currentIndex à laquelle vous pouvez accéder dans la boucle pour connaître le numéro d'itération actuel (en commençant par la valeur "From"). C'est utile pour effectuer des tâches répétitives qui ne sont pas basées sur l'itération d'une collection de données. Les exemples incluent la création d'un nombre défini d'enregistrements par défaut, l'exécution d'un calcul plusieurs fois avec des changements incrémentiels ou la génération de données de test.

Configuration​

• From (number): L'index de départ de la boucle (inclus).
• To (number): L'index de fin de la boucle (inclus).

Scénario d'Exemple​

Une page contient un bouton intitulé Générer des Messages.

1. Lorsque l'utilisateur clique sur le bouton, une action repeat est déclenchée.
2. La boucle est configurée avec From 1 et To 4.
3. À l'intérieur de la boucle, une action alert affiche un message dynamique en utilisant Message number ${Sf_loop_index}.

Résultat: Trois alertes sont affichées séquentiellement:

• Message number 1
• Message number 2
• Message number 3

Cela démontre comment l'action repeat peut exécuter la même action plusieurs fois en utilisant l'index de la boucle.

3.3. loopArray: Itérer sur des Collections de Données​

L'action loopArray itère sur un tableau de données donné (à partir d'un modèle, d'une variable ou d'une réponse d'API), exécutant un bloc d'actions imbriquées pour chaque élément de ce tableau. C'est l'équivalent d'une boucle forEach ou for...of en programmation. C'est l'une des actions les plus puissantes pour le traitement de données par lots. Elle est essentielle pour mettre à jour plusieurs enregistrements de base de données, appeler une API pour chaque élément d'une liste, effectuer des calculs sur chaque ligne d'un panier d'achat ou envoyer des e-mails personnalisés à une liste d'utilisateurs.

Variables Contextuelles​

À l'intérieur de la boucle, vous avez accès à deux variables spéciales et contextuelles:

• SF_loop.currentItem: L'objet complet ou la valeur pour l'itération actuelle.
• SF_loop.currentIndex: L'index de base zéro de l'élément actuel dans le tableau.

Configuration​

• arraydata (array): Le tableau sur lequel vous souhaitez itérer.
• actions (array): Le bloc d'actions à exécuter pour chaque élément.

Scénario d'Exemple​

Une page contient un bouton et une liste de messages stockés dans une variable de tableau.

1. La page a une variable de page nommée messages avec la valeur suivante: ["Bonjour", "Bienvenue", "Au revoir"]
2. Lorsque l'utilisateur clique sur le bouton, une action loopArray est déclenchée.
3. Le arraydata est défini sur {{ variables.messages }}.
4. À l'intérieur de la boucle, une action alert affiche un message dynamique en utilisant {{ SF_loop.currentItem }}.

Résultat: Une alerte est affichée pour chaque message dans le tableau:

• Bonjour
• Bienvenue
• Au revoir

Cela montre comment loopArray traite chaque élément d'un tableau un par un et utilise l'élément actuel de manière dynamique.

4. Actions de Processus et de Workflow​

Gérez les processus métier, contrôlez la progression des tâches et gérez la navigation des utilisateurs dans votre application.

4.1. startProcess: Lancer un Nouveau Workflow​

L'action startProcess lance formellement une nouvelle instance d'un modèle de processus Softyflow. C'est le point de départ de tout processus métier structuré dans votre application. Cette action est déclenchée lorsqu'un utilisateur effectue une action qui doit lancer un workflow, comme cliquer sur "Soumettre la Demande", "Créer une Nouvelle Commande" ou "Commencer l'Intégration". Elle crée une nouvelle entrée dans le moteur de processus qui peut ensuite être suivie, surveillée et progressée.

Retours​

• Cette action peut éventuellement stocker l'instanceId du processus nouvellement créé dans un modèle ou une variable de page. Cet ID est l'identifiant unique de cette instance de workflow spécifique et est crucial pour la suivre ou y naviguer plus tard.

Configuration​

• instanceIdVar (string, facultatif): Le nom d'une variable pour stocker l'ID de la nouvelle instance de processus.
• process: Une référence au modèle de processus que vous souhaitez démarrer.

4.2. OpenNextTask: Guider les Utilisateurs à Travers les Workflows​

L'action OpenNextTask est un utilitaire de navigation intelligent qui améliore l'expérience utilisateur en les guidant automatiquement vers leur prochaine tâche. Elle inspecte une instance de processus pour la prochaine tâche humaine disponible et redirige immédiatement l'utilisateur vers le formulaire correct. Utilisez ceci pour créer un workflow guidé et transparent. Par exemple, après qu'un manager a approuvé une demande, OpenNextTask peut vérifier si une autre approbation est en attente dans sa file d'attente et l'y emmener directement, lui évitant d'avoir à retourner à un tableau de bord et à trouver manuellement sa prochaine tâche.

Configuration​

• instanceId (string): L'ID de l'instance de processus à vérifier pour une tâche suivante.
• Fallback Redirect url (string): Une URL vers laquelle rediriger l'utilisateur si aucune tâche suivante n'est trouvée (par exemple, parce que le processus est terminé ou que la prochaine étape est une tâche automatisée).

4.3. update: Terminer une Tâche et Faire Avancer le Processus​

L'action update signale au moteur de processus Softyflow que la tâche humaine actuelle est terminée. C'est le mécanisme principal pour faire avancer un workflow d'une étape à l'autre comme défini dans votre modèle de processus. Cette action doit être attachée à l'action de conclusion principale sur un formulaire de tâche, comme un bouton "Approuver", "Rejeter", "Soumettre" ou "Terminer". Le déclenchement de cette action termine la tâche et permet au processus d'évaluer l'étape suivante dans le flux.

Configuration​

• Task Id (string): L'ID de la tâche actuelle en cours de finalisation. Ceci est souvent disponible dans le contexte de la page.
• Measures (object, facultatif): Un objet de données clé-valeur que vous souhaitez transmettre de cette tâche aux étapes suivantes du workflow. C'est ainsi que vous transmettez des décisions (par exemple, { "approval_status": "rejected" }) ou des données en aval.

4.4. save: Enregistrer un Brouillon​

L'action save enregistre les données et l'état actuels d'un formulaire de tâche sans terminer la tâche ni faire avancer le processus. C'est une fonctionnalité d'expérience utilisateur cruciale pour les formulaires longs ou complexes où un utilisateur pourrait avoir besoin de rassembler des informations au fil du temps. Elle leur permet d'enregistrer un brouillon de leur travail et d'y revenir plus tard. La tâche leur reste assignée et le workflow ne progresse pas.

Configuration​

• Task Id (string): L'ID de la tâche actuelle dont vous souhaitez enregistrer les données. Ceci est généralement disponible dans le contexte de la page.

4.5. openInstance: Afficher les Détails du Processus​

L'action openInstance navigue l'utilisateur vers la "Vue d'Instance" détaillée pour une instance de processus donnée, l'ouvrant généralement dans un nouvel onglet du navigateur. Cette vue fournit une piste d'audit complète, montrant l'historique du processus, l'état actuel, les données associées et les éventuelles erreurs. C'est parfait pour fournir des capacités de "détail" à partir de tableaux de bord, de rapports ou de vues de liste. Lorsqu'un utilisateur voit un résumé de nombreuses instances de processus, cette action lui permet de cliquer sur une instance spécifique pour enquêter sur son historique complet et ses détails.

Configuration​

• Instance Id (string): L'ID unique de l'instance de processus que vous souhaitez ouvrir.

4.6. redirect: Naviguer dans Votre Application​

L'action redirect navigue par programme le navigateur de l'utilisateur vers une nouvelle URL, soit au sein de votre application, soit vers un site externe. C'est une action fondamentale pour contrôler le flux et la navigation de l'application. Elle est utilisée pour envoyer les utilisateurs vers une page de "Remerciement" après une soumission, vers une page de connexion s'ils ne sont pas authentifiés, ou vers un tableau de bord spécifique en fonction de leur rôle.

Configuration​

• Redirect url (string): L'URL de destination.
• params (object, facultatif): Un objet de paires clé-valeur qui seront ajoutées à l'URL en tant que paramètres de chaîne de requête (par exemple, { "id": 123 } devient ?id=123).
• New page: Si défini sur true, l'URL s'ouvrira dans un nouvel onglet du navigateur. La valeur par défaut est false.

5. Opérations sur les Collections (Base de Données)​

Effectuez des opérations CRUD (Créer, Lire, Mettre à jour, Supprimer) directement sur vos collections de base de données Softyflow.

5.1. addToCollection: Créer de Nouveaux Enregistrements de Base de Données​

L'action addToCollection insère un seul nouveau document dans une collection de base de données spécifiée. C'est l'action principale pour créer de nouveaux enregistrements dans la base de données de votre application. Elle est utilisée chaque fois qu'un utilisateur enregistre une nouvelle entité, comme la création d'un nouveau contact, la soumission d'un nouveau formulaire ou la journalisation d'un nouvel événement.

Configuration​

• Collection (object): Une référence à la collection de base de données cible.
• Data model (object): Un objet JSON représentant le document à insérer.

Scénario d'Exemple​

Une page contient un formulaire simple avec deux champs de saisie: Nom et Email, et un bouton Soumettre.

1. L'utilisateur remplit les champs Nom et Email.

2. Lorsque l'utilisateur clique sur le bouton Soumettre, une action addToCollection est déclenchée.

3. La Collection est définie sur Users_demo.

4. Le Modèle de données est défini comme suit:

   {
     "name": "{{ name }}",
     "email": "{{ email }}"
   }
   

5. Après la création de l'enregistrement, une action refresh recharge la source de données du tableau.

5.2. addManyToCollection: Insérer des Données en Masse​

L'action addManyToCollection insère un tableau entier de documents dans une collection en une seule opération de base de données haute performance. C'est le moyen le plus efficace d'effectuer des importations de données en masse ou de créer plusieurs enregistrements à la fois. C'est idéal pour des scénarios comme le téléchargement et le traitement d'un fichier CSV de contacts, la migration de données d'un autre système ou la génération d'un grand ensemble de données par défaut.

Configuration​

• Collection: La collection cible.
• Data model (array): Un tableau d'objets JSON, où chaque objet représente un nouveau document à insérer.

Scénario d'Exemple​

Une page contient un bouton intitulé Importer des Produits.

1. Une variable de page nommée data_list contient un tableau de produits:

[
  { "name": "Laptop", "price": 1200 },
  { "name": "Mouse", "price": 25 },
  { "name": "Keyboard", "price": 80 }
]

2. Lorsque l'utilisateur clique sur le bouton Importer des Produits, une action addManyToCollection est déclenchée.
3. La Collection est définie sur Produits.
4. La variable de données est définie sur data_list.
5. Après la création de l'enregistrement, une action refresh recharge la source de données du tableau.

Résultat: Tous les produits du tableau sont insérés dans la collection Produits en une seule opération, rendant l'importation rapide et efficace.

5.3. updateCollection: Modifier des Enregistrements Existants​

L'action updateCollection trouve un document existant dans une collection par son _id unique et le met à jour avec de nouvelles données. C'est l'action standard pour toute fonctionnalité de "modification" ou de "mise à jour". Elle est utilisée lorsqu'un utilisateur enregistre des modifications de son profil, modifie une commande existante ou change le statut d'un projet.

Configuration​

• Collection: La collection cible.
• Document id (string): L'_id du document que vous souhaitez mettre à jour.
• Data model (object): Un objet contenant uniquement les champs que vous souhaitez modifier et leurs nouvelles valeurs.

Scénario d'Exemple:​

Vous avez déjà un backoffice de gestion des utilisateurs avec un tableau qui affiche les utilisateurs.

1. L'administrateur clique sur le bouton Modifier sur une ligne d'utilisateur dans le tableau.

2. Une popup s'affiche, et l'_id de l'utilisateur sélectionné est stocké dans une variable de page nommée editid.

3. Les données actuelles de l'utilisateur (nom et email) sont chargées dans les champs de saisie du formulaire.

4. L'administrateur modifie les champs Nom et/ou Email.

5. Lorsque l'administrateur clique sur Mettre à jour, une action updateCollection est déclenchée.

6. La Collection est définie sur Users_demo.

7. L'ID du document est défini sur editid.

8. Les données du formulaire sont attachées à partir de la section du formulaire:

   {
     "name": "{{ data_form.name }}",
     "email": "{{ data_form.email }}"
   }
   

9. Après la mise à jour, une action show rafraîchit le tableau des utilisateurs pour afficher les informations mises à jour.

Résultat: L'enregistrement de l'utilisateur sélectionné est mis à jour dans la base de données, et les modifications sont immédiatement répercutées dans le tableau du backoffice.

5.4. getCollection: Interroger Plusieurs Documents​

L'action getCollection récupère une liste de documents d'une collection qui correspondent à une requête donnée. Elle prend en charge de puissantes capacités de filtrage, de tri et de pagination en utilisant la syntaxe de requête de MongoDB. C'est le moyen le plus courant de récupérer les données nécessaires pour peupler l'IU de votre application. Elle est utilisée pour remplir des listes, des grilles de données, des sélections de listes déroulantes et des données de graphiques.

Retours​

• Output (array): L'action déverse le tableau de documents correspondants dans une variable spécifiée pour être utilisé dans des widgets ou d'autres actions.

Configuration​

• Dump var (string): Le nom de la variable où le tableau de résultats sera stocké.
• Collection: La collection à interroger.
• Criteria (json, facultatif): Un objet de requête de style MongoDB pour filtrer ({ "status": "active" }), trier ({ "sort": { "createdAt": -1 } }) et limiter les résultats.

Scénario d'Exemple:​

Une page contient un bouton intitulé Obtenir les Utilisateurs et un tableau d'utilisateurs masqué.

1. Lorsque l'utilisateur clique sur le bouton Obtenir les Utilisateurs, une action getCollection est déclenchée.
2. La Collection est définie sur Users_demo.
3. La Variable de vidage est définie sur users_list.
4. Aucun critère n'est défini, donc tous les utilisateurs sont récupérés.
5. Les données récupérées sont stockées dans la variable users_list.
6. Une action show est utilisée pour afficher le tableau des utilisateurs.
7. Le tableau utilise users_list comme source de données.

Résultat: En cliquant sur le bouton, tous les utilisateurs sont récupérés de la base de données et affichés dans le tableau.

5.5. getDocument: Récupérer un Seul Document​

L'action getDocument récupère un seul document complet d'une collection par son _id unique. Cette action est utilisée chaque fois que vous avez besoin de récupérer les détails complets d'un élément spécifique. Elle est généralement déclenchée lorsqu'un utilisateur clique sur un élément d'une liste, ce qui prépare ensuite les données pour un formulaire de "modification" ou une vue de "détails".

Retours​

• Output (object): L'action déverse l'objet de document complet dans une variable spécifiée.

Configuration​

• Collection: La collection à interroger.
• Document id (string): L'_id du document à récupérer.
• Dump var (string): Le nom de la variable où le document résultant sera stocké.

Scénario d'Exemple:​

Une page affiche un tableau d'utilisateurs avec un bouton Modifier pour chaque ligne.

1. L'utilisateur clique sur le bouton Modifier sur une ligne d'utilisateur spécifique.
2. L'_id de l'utilisateur sélectionné est stocké dans une variable de page nommée editid.
3. Une action getDocument est déclenchée.
4. La Collection est définie sur Users_demo.
5. L'ID du document est défini sur editid.
6. La Variable de vidage est définie sur data_form.
7. Les données de l'utilisateur récupérées sont automatiquement disponibles sur la page.
8. Une action show ouvre une popup ou affiche un formulaire rempli avec:
   • {{ data_form.name }}
   • {{ data_form.email }}

Résultat: Le document complet de l'utilisateur est récupéré de la base de données et affiché, permettant à l'utilisateur de visualiser ou de modifier les détails de l'utilisateur sélectionné.

5.6. deleteDocument: Supprimer des Données​

L'action deleteDocument supprime définitivement un seul document d'une collection, identifié par son _id unique. Cette action est utilisée pour supprimer des enregistrements. Parce que c'est une action destructrice et irréversible, elle doit toujours être protégée par une action confirm pour éviter la perte accidentelle de données.

Configuration​

• Collection (object): La collection à partir de laquelle supprimer.
• Document id (string): L'_id du document à supprimer.

Scénario d'Exemple:​

Une page affiche un tableau d'utilisateurs avec un bouton Supprimer pour chaque ligne.

1. L'utilisateur clique sur le bouton Supprimer sur une ligne d'utilisateur spécifique.
2. Une action confirm s'affiche demandant à l'utilisateur de confirmer la suppression.
3. Si l'utilisateur confirme, l'_id de l'utilisateur sélectionné est stocké dans une variable de page nommée delete_id.
4. Une action deleteDocument est déclenchée.
5. La Collection est définie sur Users_demo.
6. L'ID du document est défini sur {{ variables.delete_id }}.
7. Après la suppression, une action show rafraîchit le tableau des utilisateurs.

Résultat: L'utilisateur sélectionné est définitivement supprimé de la base de données, et le tableau est mis à jour pour refléter le changement.

5.7. AggregateCollection: Effectuer des Requêtes de Base de Données Avancées​

L'action aggregateCollection exécute un pipeline d'agrégation MongoDB puissant, qui permet un traitement, une transformation et une analyse de données en plusieurs étapes directement dans la base de données pour une efficacité maximale. Utilisez-la pour des rapports avancés et des analyses de données qui vont au-delà du simple filtrage. C'est parfait pour regrouper des données, calculer des sommes et des moyennes (par exemple, pour un tableau de bord), remodeler les structures de documents, joindre des données de collections connexes et effectuer des requêtes complexes en plusieurs étapes.

Retours​

• Output (array): L'action déverse les résultats de la dernière étape du pipeline d'agrégation dans une variable spécifiée.

Configuration​

• Dump var (string): La variable pour stocker le résultat de l'agrégation.
• Collection (object): La collection sur laquelle exécuter l'agrégation.
• Aggregation (array): Un tableau d'étapes de pipeline d'agrégation MongoDB (par exemple, $match, $group, $sort, $lookup).

Scénario d'Exemple:​

Vous souhaitez afficher uniquement les utilisateurs actifs dans un tableau de backoffice.

1. L'utilisateur clique sur un bouton intitulé Afficher les Utilisateurs Actifs.

2. Une action aggregateCollection est déclenchée.

3. La Collection est définie sur Users_demo.

4. La Variable de vidage est définie sur active_users.

5. Le pipeline d'Agrégation est défini comme suit:

   [{ "$match": { "status": "active" } }]
   

6. Le résultat de l'agrégation est stocké dans la variable active_users.

7. Un widget de tableau utilise {{ variables.active_users }} comme source de données.

8. Une action show affiche le tableau des utilisateurs.

Résultat: Seuls les utilisateurs avec un statut actif sont récupérés de la base de données et affichés dans le tableau.

6. Actions de Source de Données Externe (EDS)​

Intégrez et interagissez avec des bases de données externes (comme SQL Server, PostgreSQL, MySQL) que vous avez configurées comme Sources de Données Externes.

6.1. insertTable: Créer des Enregistrements dans des Systèmes Externes​

L'action insertTable insère une nouvelle ligne dans une table spécifiée d'une base de données externe configurée. Utilisez-la pour créer des enregistrements dans des systèmes externes ou hérités, en assurant la synchronisation des données entre votre application Softyflow et d'autres parties de l'infrastructure informatique de votre entreprise.

Configuration​

• clientDatabase (object): La connexion EDS configurée à utiliser.
• Table (string): Le nom de la table cible dans la base de données externe.
• Statement (object): Un objet où les clés sont les noms de colonnes et les valeurs sont les données à insérer pour la nouvelle ligne.

Scénario d'Exemple: Insérer un Utilisateur dans une Base de Données Externe (insertTable)​

Vous souhaitez enregistrer les données des utilisateurs dans une base de données SQL externe en plus de votre base de données principale.

1. Une page contient un formulaire avec des champs de saisie Nom et Email.

2. L'utilisateur remplit le formulaire et clique sur le bouton Enregistrer.

3. Une action insertTable est déclenchée.

4. La base de données client est définie sur la connexion à la base de données externe configurée (par exemple, Main_SQL_DB).

5. La Table est définie sur users.

6. Le Statement est défini comme suit:

   {
     "name": "{{ form.name }}",
     "email": "{{ form.email }}"
   }
   

7. Après l'insertion, une action show affiche un message de succès ou met à jour l'interface utilisateur.

Résultat: Une nouvelle ligne est insérée dans la table externe des utilisateurs, maintenant le système externe synchronisé avec les données de l'application.

6.2. updateTables: Modifier des Enregistrements dans des Systèmes Externes​

L'action updateTables met à jour une ou plusieurs lignes existantes dans une table de base de données externe qui correspondent à une clause where donnée. Utilisez-la pour modifier des données dans vos systèmes externes lorsqu'un événement correspondant se produit dans votre application Softyflow, en gardant tous vos systèmes disparates synchronisés sans intervention manuelle.

Configuration​

• clientDatabase (object): La connexion EDS à utiliser.
• Table (string): Le nom de la table cible.
• Find Table (object): La clause where pour identifier la ou les lignes à mettre à jour (par exemple, { "user_id": 123 }).
• Updated Table (object): Un objet contenant les nouvelles valeurs de colonne à définir.

Scénario d'Exemple:​

Vous souhaitez mettre à jour le statut d'un utilisateur dans une base de données SQL externe lorsqu'il change dans votre application.

1. Une page affiche une liste d'utilisateurs avec un bouton Mettre à jour.
2. L'administrateur clique sur le bouton pour un utilisateur spécifique.
3. L'ID de l'utilisateur sélectionné est stocké dans une variable de page nommée external_user_id.
4. Une action updateTables est déclenchée.
5. La base de données client est définie sur la connexion à la base de données externe configurée (par exemple, softyflow_test).
6. La Table est définie sur my_table.
7. La Table de recherche (clause where) est définie comme suit:

   {
     "id": external_user_id
   }
   
8. La table mise à jour est définie comme suit: {"status": "active"}
9. Après la mise à jour, une action show rafraîchit la liste des utilisateurs ou affiche un message de succès.

Résultat: L'enregistrement de l'utilisateur correspondant dans la base de données externe est mis à jour avec succès, maintenant le système externe synchronisé avec l'état de l'application.

6.3. findMany: Interroger des Données Externes​

L'action findMany récupère plusieurs lignes d'une table externe qui correspondent à une requête donnée, similaire à une instruction SELECT ... WHERE en SQL. Cette action vous permet de récupérer et d'afficher des données de systèmes externes et hérités directement dans l'interface utilisateur de votre application Softyflow, offrant une vue unifiée et complète de toutes vos données métier pertinentes à l'utilisateur.

Retours​

• Output (array): L'action déverse un tableau de lignes correspondantes dans une variable spécifiée.

Configuration​

• Dump var (string): La variable pour stocker le tableau de résultats.
• clientDatabase (object): La connexion EDS à utiliser.
• Table (string): Le nom de la table.
• Find (object, facultatif): La clause where pour la requête.

Scénario d'Exemple:​

Vous souhaitez afficher une liste d'utilisateurs provenant d'une base de données SQL externe à l'intérieur de votre application.

1. Une page contient un bouton intitulé Obtenir les Utilisateurs.

2. Lorsque l'utilisateur clique sur le bouton, une action findMany est déclenchée.

3. La base de données client est définie sur la connexion à la base de données externe configurée.

4. La Table est définie sur my_table.

5. La Variable de vidage est définie sur external_users.

6. (Facultatif) La clause Find est définie pour ne charger que les utilisateurs actifs:

   {
     "status": "active"
   }
   

7. Les lignes récupérées sont stockées dans la variable external_users.

8. Un widget de tableau utilise external_users comme source de données.

9. Une action show affiche le tableau.

Résultat: Tous les utilisateurs correspondants de la base de données externe sont récupérés et affichés dans l'interface de l'application.

6.4. exectuteStatement: Libérer la Puissance du SQL Brut​

L'action exectuteStatement offre la capacité puissante mais potentiellement dangereuse d'exécuter une chaîne de requête SQL brute directement sur une base de données externe. C'est votre outil de dernier recours pour une flexibilité ultime. Utilisez-la pour des requêtes complexes impliquant plusieurs JOIN, l'appel de procédures stockées ou toute autre opération SQL avancée qui n'est pas facilement couverte par les actions EDS structurées standard.

Retours​

• Output (array): L'action déverse les résultats de la requête dans une variable spécifiée.

Configuration​

• Dump var (string): La variable pour stocker les résultats de la requête.
• clientDatabase (object): La connexion EDS.
• Statement (string): La requête SQL brute à exécuter.

7. Actions d'API et d'Intégration​

Connectez votre application Softyflow au monde en l'intégrant à des API et des services externes.

7.1. invokeApi: Se Connecter à n'Importe Quelle API​

L'action invokeApi appelle un point de terminaison d'API préconfiguré et renvoie la réponse complète. Cette action est votre passerelle vers le monde extérieur. Utilisez-la pour vous intégrer à n'importe quel service tiers (par exemple, les passerelles de paiement comme Stripe, les services de validation d'adresse, les convertisseurs de devises) ou pour communiquer avec les microservices personnalisés de votre propre entreprise.

Retours​

• Output (any): L'action déverse la réponse entière de l'API — y compris le corps, les en-têtes et le code d'état — dans une variable spécifiée pour que vous puissiez la traiter et l'utiliser dans votre application.

Configuration​

• Dump variable (string): La variable pour stocker l'objet de réponse complet de l'API.
• Api endpoint (object): Le point de terminaison d'API configuré à appeler.
• params (object, facultatif): Paramètres à envoyer avec la requête API, qui peuvent être mappés sur le corps de la requête, la chaîne de requête ou les en-têtes en fonction de la configuration du point de terminaison.

7.2. sendEmail: Communiquer avec les Utilisateurs​

L'action sendEmail envoie un e-mail à un destinataire à l'aide d'un fournisseur de messagerie configuré (comme SendGrid ou Mailgun) et d'un modèle d'e-mail dynamique prédéfini. C'est essentiel pour toute communication automatisée avec les utilisateurs. Elle doit être utilisée pour tous les e-mails transactionnels, tels que les messages de bienvenue, les réinitialisations de mot de passe, les confirmations de commande et les notifications de statut de workflow.

Configuration​

• Provider (object): Le fournisseur de services de messagerie à utiliser pour l'envoi.
• Template (object): Le modèle d'e-mail prédéfini à utiliser.
• To (string): L'adresse e-mail du destinataire.
• variables (object, facultatif): Un objet de données utilisé pour remplir les champs dynamiques de votre modèle d'e-mail (par exemple, en fournissant une valeur pour {{name}} ou {{order_id}}).

7.3. previewPDF: Générer des Documents à la Volée​

L'action previewPDF génère dynamiquement un document PDF en fusionnant un objet de données JSON avec un modèle PDF prédéfini. Utilisez-la pour créer des documents professionnels et imprimables à la demande. C'est parfait pour générer des factures, des rapports, des certificats d'achèvement, des étiquettes d'expédition, des contrats et tout autre document formaté basé sur les données de votre application.

Retours​

• Output (object): L'action déverse les données PDF générées (généralement sous forme de chaîne base64 ou d'objet de fichier) dans une variable spécifiée. Celles-ci peuvent ensuite être utilisées pour afficher un aperçu du PDF à l'utilisateur, lui permettre de le télécharger ou de le joindre à un e-mail.

Configuration​

• Dump var (string): Une variable pour stocker les données PDF générées.
• Template (object): Le modèle PDF à utiliser pour la génération.
• Context (object): L'objet de données JSON contenant les informations pour remplir le modèle.

8. Meilleures Pratiques pour Construire avec des Actions​

En maîtrisant ces actions et en respectant ces meilleures pratiques, vous pouvez dépasser les simples formulaires et construire des applications web sophistiquées, performantes et conviviales avec la puissante plateforme low-code de Softyflow.