Scripts et modèles JavaScript javascript-scripts-and-templates
Les scripts vont permettre de calculer des valeurs, d'échanger des données entre les différentes tâches du processus et d'exécuter des opérations spécifiques à l'aide d'appels SOAP.
Les scripts sont omniprésents dans un diagramme de workflow :
-
Toute activité possède un script d'initialisation. Ce script est exécuté à l'activation de l'activité, il permet d'initialiser des variables ou de modifier les propriétés de l'activité.
-
L'activité 'Code JavaScript' a pour seule fonction d'exécuter un script.
-
L'activité 'Test' évalue des expressions JavaScript pour activer la bonne transition.
-
La plupart des champs de type texte sont des templates JavaScript : ils peuvent inclure des expressions JavaScript entre les caractères <%= et %>. Ces champs proposent un bouton qui permet d'accéder à une liste déroulante pour l'aide à la saisie des expressions.
Objets exposés objects-exposed
Tout script JavaScript exécuté dans le contexte du workflow accède à une série d'objets globaux supplémentaires.
- instance : représente le workflow en cours d’exécution. Le schéma de cet objet est xtk:workflow.
- task : représente les tâches en cours d’exécution. Le schéma de cet objet est xtk:workflowTask.
- event : représente les événements qui ont activé la tâche en cours d’exécution. Le schéma de cet objet est xtk:workflowEvent. Cet objet n’est pas initialisé pour les activités de type AND-join qui ont été activées à partir de plusieurs transitions.
- events : représente la liste des événements qui ont activé la tâche active. Le schéma de cet objet est xtk:workflowEvent. Ce tableau contient généralement un élément, mais il peut en contenir plusieurs pour les activités de type AND-join qui ont été activées en fonction de plusieurs transitions.
- activity : représente le modèle de la tâche en cours d’exécution. Le schéma de cet objet dépend du type d’activité. Cet objet peut être modifié par le script d’initialisation ; dans d’autres scripts, les modifications auront des effets indéterminés.
Les propriétés disponibles pour ces objets sont accessibles depuis le menu déroulant du bouton situé à droite de la barre d'outils du script.
Exemple
Dans cet exemple et pour les exemples suivants, créez un workflow comprenant une activité Code JavaScript et une activité Fin comme sur le diagramme ci-dessous.
Double-cliquez sur l'activité Code JavaScript et insérez le script suivant :
logInfo("Label: " + instance.label)
logInfo("Start date: " + task.creationDate)
La fonction logInfo(message) ajoute un message dans le journal.
Cliquez sur OK pour fermer l'assistant de création, puis démarrez le workflow en utilisant les boutons d'action en haut à droite de la liste des workflows. A la fin de l'exécution, consultez le journal. Vous devez voir deux messages correspondant au script : l'un affiche le libellé du workflow, l'autre affiche la date d'activation du script.
Variables variables
Les variables sont des propriétés libres des objets instance, task et event. Les types JavaScript autorisés pour ces variables sont string,number et Date.
Les variables d'instances instance-variables
Les variables d’instances (instance.vars.xxx) sont comparables à des variables globales. Elles sont partagées par toutes les activités.
Les variables de tâches task-variables
Les variables de tâches (task.vars.xxx) sont comparables à des variables locales. Elles ne sont accessibles que par la tâche en cours. Ces variables sont utilisées par des activités persistantes pour conserver des données et sont parfois utilisées pour échanger des valeurs entre différents scripts d’une même activité.
Les variables d'événements event-variables
Les variables d'événements (vars.xxx) permettent l'échange de données entre les tâches élémentaires d'un processus de workflow. Ces variables sont passées par la tâche qui a activé la tâche en cours. Il est possible de les modifier ou d'en définir de nouvelles, elles sont ensuite transmises aux activités suivantes.
Les événements sont les variables les plus communément utilisées et doivent être préférées aux variables d'instances.
Certaines variables d'événements sont modifiées ou lues par les différentes activités. Il s’agit des variables de type chaîne. Par exemple, un export définit la variable vars.filename avec le nom complet du fichier qui vient d’être exporté. Toutes ces variables lues ou modifiées sont documentées dans À propos des activités, dans les sections Paramètres d’entrée et Paramètres de sortie des activités.
Cas pratiques example
Exemple 1
Dans cet exemple, une variable d’instance est utilisée pour calculer dynamiquement le pourcentage de partage à appliquer à une population.
-
Créez un workflow et ajoutez une activité Début.
-
Ajoutez et configurez une activité de code JavaScript pour définir une variable d’instance.
Par exemple:
instance.vars.segmentpercent = 10;
-
Ajoutez une activité Requête et ciblez les destinataires en fonction de vos besoins.
-
Ajoutez une activité Partage et configurez-la pour effectuer un échantillonnage aléatoire de la population entrante. Le pourcentage d’échantillonnage ne dépend que de votre choix. Il est défini sur 50 % dans cet exemple.
C’est ce pourcentage qui est mis à jour dynamiquement grâce à la variable d’instance définie précédemment.
-
Dans la section Script d’initialisation de l’onglet Avancé de l’activité Partage, définissez une condition JS. La condition JS sélectionne le pourcentage d’échantillonnage aléatoire de la première transition sortant de l’activité Partage et la met à jour vers une valeur définie par la variable d’instance créée précédemment.
code language-none activity.transitions.extractOutput[0].limiter.percent = instance.vars.segmentpercent;
-
Assurez-vous que le complément est généré dans une transition distincte de l’activité Partage et ajoutez les activités Fin après chacune des transitions sortantes.
-
Enregistrez et exécutez le workflow. L’échantillonnage dynamique est appliqué en fonction de la variable d’instance.
Exemple 2
-
Reprenez le workflow de l'exemple précédent et modifiez le script de l'activité Code JavaScript avec le script suivant :
code language-none instance.vars.foo = "bar1" vars.foo = "bar2" task.vars.foo = "bar3" -
Ajoutez le script suivant au script d'initialisation de l'activité Fin :
code language-none logInfo("instance.vars.foo = " + instance.vars.foo) logInfo("vars.foo = " + vars.foo) logInfo("task.vars.foo = " + task.vars.foo) -
Démarrez le workflow, puis consultez le journal.
code language-none Workflow finished task.vars.foo = undefined vars.foo = bar2 instance.vars.foo = bar1 Starting workflow (operator 'admin')
Cet exemple montre que l'activité suivant Code JavaScript accède aux variables d'instances et aux variables d'événements, mais les variables de tâches ne sont pas accessibles en dehors de celles-ci ('undefined').
Appeler une variable d'instance dans une requête calling-an-instance-variable-in-a-query
Lorsque vous avez défini une variable d'instance dans une activité, vous pouvez la réutiliser dans une requête du workflow.
Ainsi, pour appeler la variable instance.vars.xxx = "yyy" dans un filtre, saisissez $(instance/vars/xxx).
Par exemple :
-
Créez une variable d'instance qui définit le nom interne d'une diffusion via l'activité Code JavaScript : instance.vars.deliveryIN = "DM42".
-
Créez une requête dont les dimensions de ciblage et de filtrage sont les destinataires. Dans les conditions, indiquez que vous souhaitez trouver tous les destinataires auxquels la diffusion spécifiée par la variable a été envoyée.
Pour rappel, ces informations sont stockées dans les logs de diffusion.
Pour faire référence à la variable d'instance dans la colonne Valeur, saisissez $(instance/vars/@deliveryIN).
Le workflow retournera les destinataires à qui la diffusion DM42 a été envoyée.
Fonctions avancées advanced-functions
En plus des fonctions JavaScript standard, d'autres fonctions spécifiques sont disponibles pour manipuler les fichiers, lire ou modifier des données dans la base ou encore ajouter des messages dans le journal.
Journal journal
logInfo(message) a déjà été présenté dans les exemples précédents. Cette fonction ajoute un message d'information au journal.
logError(message) ajoute un message d'erreur au journal. Le script interrompt son exécution et le workflow passe en état d'erreur (par défaut, l'instance sera mise en pause).
Script d'initialisation initialization-script
Vous pouvez modifier une propriété d'une activité au moment de l'exécution sous certaines conditions.
La plupart des propriétés des activités peuvent être calculées dynamiquement, soit en utilisant un template JavaScript, soit parce que les propriétés du workflow permettent explicitement de calculer la valeur par un script.
Toutefois, pour d’autres propriétés, vous devez utiliser le script d’initialisation. Ce script est évalué avant l’exécution de la tâche. La variable activity référence l'activité correspondant à la tâche. Les propriétés de cette activité peuvent être modifiées et n'affecteront que cette tâche.
Rubriques connexes
Exemples de code JavaScript dans les workflows