#Événement d'action personnalisée

#Introduction

NocoBase intègre les opérations de données les plus courantes (création, suppression, modification, lecture, etc.). Lorsque ces opérations ne suffisent pas pour des besoins métier complexes, vous pouvez utiliser un événement d'action personnalisée dans un workflow et lier cet événement à un bouton « Déclencher le workflow » d'un bloc de page : à chaque clic de l'utilisateur, un workflow d'action personnalisée est déclenché.

#Créer le workflow

Lors de la création d'un workflow, sélectionnez « Événement d'action personnalisée » :

#Configuration du déclencheur

#Type de contexte

v.1.6.0+

Le type de contexte détermine sur quels boutons de bloc le workflow peut être lié :

• Sans contexte : c'est un événement global, peut être lié aux boutons d'action des panneaux d'action et des blocs de données ;
• Enregistrement unique : peut être lié aux boutons d'action des blocs de données comme les lignes de tableau, les formulaires, les détails ;
• Plusieurs enregistrements : peut être lié aux boutons d'opération en lot d'un tableau.

#Table de données

Lorsque le type de contexte est « Enregistrement unique » ou « Plusieurs enregistrements », vous devez sélectionner la table de données à laquelle lier le modèle de données :

#Données de relation à utiliser

Si vous avez besoin d'utiliser dans le workflow les données associées à la ligne déclenchée, vous pouvez sélectionner ici des champs de relation profonds :

Ces champs seront automatiquement préchargés dans le contexte du workflow lorsque l'événement sera déclenché, pour pouvoir être utilisés dans le workflow.

#Configuration de l'action

Selon le type de contexte du workflow, la configuration des boutons d'action diffère selon les blocs.

#Sans contexte

v1.6.0+

Dans les panneaux d'action et les autres blocs de données, vous pouvez ajouter un bouton « Déclencher le workflow » :

Une fois le bouton ajouté, liez-le au workflow sans contexte créé précédemment ; en prenant le bouton du panneau d'action en exemple :

#Enregistrement unique

Dans n'importe quel bloc de données, vous pouvez ajouter un bouton « Déclencher le workflow » dans la barre d'actions sur un enregistrement unique : formulaire, ligne de tableau, détails, etc. :

Une fois le bouton ajouté, liez-le au workflow créé précédemment :

Cliquer sur ce bouton déclenche alors l'événement d'action personnalisée :

#Plusieurs enregistrements

v1.6.0+

Dans la barre d'actions d'un bloc tableau, lors de l'ajout d'un bouton « Déclencher le workflow », une option supplémentaire apparaît pour choisir le type de contexte « Sans contexte » ou « Plusieurs enregistrements » :

Choisir « Sans contexte » correspond à un événement global et ne permet de lier que des workflows de type sans contexte.

Choisir « Plusieurs enregistrements » permet de lier un workflow de type plusieurs enregistrements, utilisable pour des opérations en lot après sélection multiple (actuellement, seul le tableau le prend en charge). La portée des workflows sélectionnables se limite alors à ceux configurés pour la table du bloc de données courant :

Au moment du clic sur le bouton, vous devez avoir coché des lignes du tableau, sinon le workflow ne sera pas déclenché :

#Exemple

Par exemple, supposons une table « Échantillons » : pour les échantillons « Collectés » (statut), nous voulons fournir une action « Envoi à inspection » qui vérifie d'abord les informations de base de l'échantillon, puis génère un enregistrement « Suivi d'inspection », puis change le statut de l'échantillon en « Envoyé à inspection ». Cette série d'actions ne peut pas être réalisée par un simple clic sur les boutons CRUD : c'est un cas d'usage typique pour un événement d'action personnalisée.

Créez d'abord une table « Échantillons » et une table « Suivi d'inspection », puis saisissez quelques données de test dans la table des échantillons :

Créez ensuite un workflow « Événement d'action personnalisée » ; si vous souhaitez un retour relativement immédiat sur l'opération, choisissez le mode synchrone (en mode synchrone, les nœuds asynchrones de type traitement manuel ne sont pas utilisables) :

Dans la configuration du déclencheur, sélectionnez la table « Échantillons » :

Selon les besoins métier, organisez la logique du processus ; par exemple, n'autoriser l'envoi à inspection que si le paramètre indicateur est supérieur à 90, sinon afficher un message d'erreur :

Une fois le workflow configuré et activé, retournez sur l'interface du tableau et ajoutez un bouton « Déclencher le workflow » dans la colonne d'actions du tableau :

Ensuite, dans le menu de configuration du bouton, choisissez de lier un workflow et ouvrez la popup de configuration :

Ajoutez le workflow précédemment activé :

Après soumission, modifiez le texte du bouton avec le nom de l'opération, par exemple « Envoyer à inspection » : la configuration est terminée.

À l'utilisation, sélectionnez n'importe quelle ligne d'échantillon dans le tableau et cliquez sur « Envoyer à inspection » pour déclencher l'événement d'action personnalisée. Conformément à la logique configurée, si le paramètre indicateur est inférieur à 90, un message s'affiche :

Si le paramètre indicateur est supérieur à 90, le processus s'exécute normalement, génère un enregistrement « Suivi d'inspection » et change le statut de l'échantillon en « Envoyé à inspection » :

Voilà, un événement d'action personnalisée simple est terminé. De même, pour des opérations métier complexes telles que le traitement de commandes ou la soumission de rapports, vous pouvez utiliser des événements d'action personnalisée.

#Appel externe

Le déclenchement d'un événement d'action personnalisée n'est pas limité aux opérations dans l'interface utilisateur ; il peut aussi être déclenché via l'HTTP API. En particulier, l'événement d'action personnalisée fournit pour toutes les opérations de table un nouveau type d'opération trigger qui peut être appelé via l'API d'opération standard de NocoBase.

#Sans contexte

Les workflows sans contexte doivent être déclenchés sur la ressource workflows :

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/workflows:trigger?triggerWorkflows=workflowKey"

#Enregistrement unique

À l'instar du workflow déclenché par bouton dans l'exemple, vous pouvez l'appeler ainsi :

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Comme l'opération porte sur une seule donnée, lors de l'appel sur des données existantes, vous devez spécifier l'ID de la ligne en remplaçant la portion <:id> de l'URL.

S'il s'agit d'un appel sur un formulaire (par exemple création ou mise à jour), pour un formulaire de création, vous pouvez ne pas passer d'ID, mais vous devez transmettre les données soumises pour servir de contexte d'exécution :

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger?triggerWorkflows=workflowKey"

Pour un formulaire de mise à jour, il faut passer à la fois l'ID de la ligne et les données mises à jour :

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Si l'ID et les données sont passés simultanément, la ligne correspondante à l'ID sera d'abord chargée, puis les propriétés de l'objet de données passées en paramètre écraseront la ligne d'origine pour produire le contexte de déclenchement final.

Par ailleurs, le paramètre d'URL triggerWorkflows est la key du workflow ; plusieurs workflows sont séparés par des virgules. Cette key peut être obtenue en survolant le nom du workflow en haut du canvas :

L'appel réussi déclenchera l'événement d'action personnalisée correspondant à la table samples.

#Plusieurs enregistrements

Similaire à l'appel sur enregistrement unique, mais les données passées ne nécessitent que plusieurs paramètres de clé primaire (filterByTk[]), sans la partie data :

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/samples:trigger?filterByTk[]=1&filterByTk[]=2&triggerWorkflows=workflowKey"

Cet appel déclenchera l'événement d'action personnalisée en mode plusieurs enregistrements et utilisera les lignes d'ID 1 et 2 comme données du contexte du déclencheur.