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.

CAUTION
Les propriétés de ces objets sont accessibles en lecture seule à l'exception des sous-propriétés de la propriété vars.
La plupart de ces propriétés ne sont mises à jour qu'après l'exécution d'une tâche élémentaire ou au moment de la passivation de l'instance. Les valeurs lues ne correspondent pas nécessairement à l'état en cours mais à l'état précédent.

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. À 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.

CAUTION
Dans le cas d'activités de type AND-join, les variables sont fusionnées mais si une même variable est définie deux fois, il y a conflit et la valeur est indéterminée.

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

NOTE
Retrouvez d’autres cas d’utilisation de workflows dans cette section.

Exemple 1

Dans cet exemple, une variable d’instance est utilisée pour calculer dynamiquement le pourcentage de partage à appliquer à une population.

  1. Créez un workflow et ajoutez une activité Début.

  2. Ajoutez et configurez une activité de code JavaScript pour définir une variable d’instance.

    Par exemple: instance.vars.segmentpercent = 10;

  3. Ajoutez une activité Requête et ciblez les destinataires en fonction de vos besoins.

  4. 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.

  5. 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;
    

  6. 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.

  7. Enregistrez et exécutez le workflow. L’échantillonnage dynamique est appliqué en fonction de la variable d’instance.

Exemple 2

  1. 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"
    
  2. 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)
    
  3. 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 :

  1. Créez une variable d'instance qui définit le nom interne d'une diffusion via l'activité Code JavaScript  : instance.vars.deliveryIN = "DM42".

  2. 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

recommendation-more-help
601d79c3-e613-4db3-889a-ae959cd9e3e1