Langage W4. Note technique W4 Engine

Transcription

1 Note technique W4 Engine Cette note technique décrit la conception d écrans HTML dynamiques prenant en charge un processus de workflow ; elle explique comment utiliser les mots clés et les API W4 dans les différents types de page gérés par le serveur de workflow. Sommaire 1 Conception d une page Web dynamique 3 2 Types de page HTML 8 3 Emplacement des fichiers utilisés par W4 Engine 12 4 Mécanismes de substitution 14 5 Appel d une API à l intérieur d un prototype de page 49 6 Cas particuliers : facilités d écriture 61 Référence : W4TN_W4_LANGUAGE_010_FR

2 Note technique W4 Engine W4. Tous droits réservés. L'acquisition du présent document confère un droit d'utilisation incessible, non exclusif et personnel et non un droit de propriété. L'utilisation, la copie, la reproduction et la distribution du présent document sont permises à condition : 1. que la mention de droits d'auteur ci-dessus figure sur toutes les copies et que cette mention de droits d'auteur et la présente mention d'autorisation apparaissent conjointement ; 2. que le présent document ne soit utilisé qu'à des fins d'information et non commerciales ; 3. que le présent document ne soit modifié de quelque manière que ce soit. Tous les produits et marques cités sont la propriété de leurs titulaires respectifs. Les informations contenues dans ce document pourront faire l objet de modifications sans préavis.

3 1 Conception d une page Web dynamique 1.1 Principes de base Le serveur W4 Engine est composé d un distributeur central de messages (ou CMD, Central Message Dispatcher), d un ensemble de services de workflow connectés en permanence à la base de données, d un ensemble de services clients (comme le module de surveillance) et d un service assurant la coopération avec les autres serveurs W4 Engine. Le CMD est chargé de réceptionner tous les messages (requêtes et réponses) et de les transmettre aux destinataires via des canaux appropriés. Il gère aussi la liste des sessions ouvertes, ce qui permet à un utilisateur déjà connecté de soumettre une requête sans s authentifier de nouveau. Services et modules Les services connectés en permanence à la base de données sont au nombre de six : ordonnancement, recherche, traduction, administration, coopération et archivage (non représenté sur le schéma ci-dessus). 1 Le service d administration gère tous les objets créés lors de la définition de la procédure ou lors de la modélisation de l organisation : procédure, étapes, activités, définitions de variable, participants, rôles, serveurs. Il assure aussi l identification des participants lors d une ouverture de session ou d une reconnexion. 2 Le service d ordonnancement doit gérer tous les objets créés lors de l exécution des procédures : dossiers, tâches, variables, références de document, commentaires, événements. Il assure en particulier l ordonnancement des tâches, l assignation des tâches aux participants, et l enregistrement de toutes les actions relatives au déroulement des dossiers. 3 Le service de recherche permet d obtenir les attributs d un objet ou d une liste d objets vérifiant certains critères. Il ne modifie jamais la base de données. 4 Le service de traduction transforme chaque commande d appel de dictionnaire en un texte correspondant à la langue de l utilisateur et au contexte. 5 Le service d archivage permet d exporter l historique des processus terminés dans un fichier d'archives (sur disque optique, par exemple) et de restaurer sélectivement les archives. 6 W4 Engine possède aussi un service assurant la coopération du serveur W4 Engine principal avec d autres serveurs W4 Engine, installés sur des machines distantes. Le rôle de ce module est de garantir, dans le cadre d une application distribuée géographiquement, qu un participant recevra toutes ses tâches à partir d un serveur W4 Engine unique. Ces services traitent, par ordre d arrivée, les requêtes reçues sur leur canal de communication. Pour s adapter à la charge du système et aux ressources disponibles, plusieurs instances d un même service peuvent être activées simultanément. 3 NOTE TECHNIQUE Conception d une page Web dynamique

4 W4 Engine possède aussi un certain nombre de modules clients, tels que la surveillance, l administration système et l acteur automatique. Le module de surveillance envoie périodiquement des requêtes au service de recherche pour connaître les dates limites et d alarme dépassées, ainsi que les événements survenus. Dans le cas d un dépassement, il demande au service d ordonnancement de prendre les mesures nécessaires pour le traiter. Dans le cas d un événement survenu, il demande à ce même service de "réveiller" les tâches ou dossiers en attente de cet événement. Le module d administration système permet de démarrer le système, de l'arrêter, de connaître les utilisateurs connectés, de connaître l état des files d attente (ou canaux) des services, de lancer de nouvelles instances d un service et de les arrêter. Le module d acteur automatique assure les fonctions d un participant spécial appelé automatic, auquel sont affectées des tâches ne demandant pas d interaction humaine (par exemple, une mise à jour de base de données). Si, par erreur, cet acteur reçoit une tâche qu il ne peut pas réaliser, il la réaffecte au responsable du dossier ou à l administrateur. Mode de fonctionnement Comme un navigateur Web client ne dialogue qu avec le serveur Web, l activation d une requête de workflow déclenche le traitement suivant : 1 L activation de la requête correspond à la demande d accès à une adresse URL désignant un programme passerelle W4 Engine. 2 Le serveur Web lance ce programme en créant un nouveau processus de façon dynamique. 3 Le programme passerelle s identifie auprès du CMD, poste sa requête, puis se met en attente de la réponse. 4 Le CMD vérifie que le participant pour le compte duquel la passerelle soumet la requête possède bien le numéro de session indiqué, puis transmet la requête au service adéquat. 5 Lorsque le service soumet sa réponse, le CMD la renvoie au programme passerelle, qui insère cette réponse dans un modèle de page HTML et transmet au serveur Web la page ainsi formée. Remarque L architecture décrite ici suppose que le serveur Web et le serveur de workflow sont installés sur la même machine physique. Cette configuration peut se révéler inadéquate pour des raisons de sécurité ou de charge du serveur Web. Ainsi, W4 Engine permet d installer les différents serveurs sur deux machines différentes, à condition qu elles puissent communiquer via TCP-IP. 1.2 Circuit de traitement d une requête de workflow Le navigateur Web soumet au serveur Web soit un formulaire, soit un lien correspondant à l activation du programme passerelle de W4 Engine. Un certain nombre de données peuvent être associées à ce lien. Remarque la passerelle W4 Engine est constituée par un programme CGI unique, qui couvre toutes les API (interfaces de programmation d application) de W4 Engine et dont l adresse relative au serveur Web est /w4/cgi.exe. W4 BPM Suite NOTE TECHNIQUE 4

5 Le programme passerelle est lancé par le serveur Web et exécute les actions suivantes : 1 récupération et enregistrement des données transmises par le navigateur ; 2 connexion au système de messages W4 Engine ; 3 vérification du droit de connexion de l utilisateur ; 4 recherche des API à soumettre ; 5 récupération des paramètres de l API ; 6 appel des APIs ; 7 recherche du prototype HTML de présentation de la réponse ; 8 présentation de la réponse ; 9 déconnexion du système de messages W4 Engine. 1 - Récupération des données transmises par le navigateur Les données peuvent être indifféremment transmises dans la chaîne de requête (ou ligne de commande) associée à l URL ou dans l entrée standard du programme cgi.exe. Elles sont passées sous la forme attribut=valeur. Le programme CGI cgi.exe enregistre toutes ces données dans une liste, sans les interpréter. Dans cette liste, les données de la chaîne de requête précèdent celles de l entrée standard. Ce tri a une importance si un attribut apparaît deux fois dans les informations soumises à cgi.exe : le cas échéant, seul le premier est pris en compte. Rappel Les données d un formulaire supportant la méthode POST sont passées dans l entrée standard, et les autres (méthode GET et paramètres définis directement dans l URL) dans la chaîne de requête. Il n y a pas de limite au nombre d informations transmises par la méthode POST dans un formulaire, tandis que la taille de la chaîne de requête est limitée par celle des variables d environnement d un programme sur le serveur. De manière générale, W4 recommande d employer la méthode POST, pour plusieurs raisons : il n y a pas de limite au nombre d attributs transmissibles ; les valeurs nulles (attribut='') sont correctement traitées, alors qu elles peuvent provoquer une erreur dans la chaîne de requête. Les valeurs comportant des caractères spéciaux (accents, espaces, etc.) doivent être encodées manuellement dans la chaîne de requêtes, alors qu elles le sont automatiquement par le navigateur lorsqu elles sont envoyées par la méthode POST. 2 - Connexion au système de messages W4 Engine Si plusieurs serveurs de workflow sont actifs simultanément sur une même machine, l attribut wfs ou wfsname passé dans les données de cgi.exe permet de sélectionner le serveur voulu. 3 - Vérification du droit de connexion de l utilisateur W4 Engine recherche, dans la liste des données, la valeur des attributs suivants : 5 NOTE TECHNIQUE Conception d une page Web dynamique

6 actorid, id ou userid entier non signé qui doit contenir l identificateur du compte utilisateur ; loginid, lid ou sid entier non signé qui doit contenir le numéro de login de l utilisateur. cgi.exe soumet une requête au serveur de messages W4 Engine pour vérifier la validité du couple (id, lid). 3 cas sont possibles : (id, lid) existe dans les tables du système de messages : l utilisateur est actif et a le droit de soumettre des requêtes. L utilisateur est enregistré dans les tables sous un autre lid. La validité du jeton lid est suspendue. L utilisateur doit alors fournir son mot de passe pour obtenir un nouveau jeton, et le système lui réattribue le même lid1. La requête en attente est automatiquement exécutée. L utilisateur n existe pas dans les tables. La validité de sa connexion est annulée. L utilisateur doit alors fournir son nom et son mot de passe ; le système lui attribue un nouveau jeton, puis exécute sa requête en attente. Les durées de suspension et d expiration des logins sont définies par l administrateur du système. Pour plus d'informations, veuillez consulter le document suivant : Manuel d'exploitation de W4 Engine Remarque La commande de connexion (login) n effectue pas cette vérification. 4 - Recherche des API à soumettre Le programme CGI cgi.exe recherche ensuite les requêtes de workflow (API) qu il doit soumettre au serveur W4 Engne. Leur nom lui a été transmis via les attributs cmd et cmdxx, où XX est un entier spécifiant l ordre d exécution de ces API. Dans les versions 1 et 2 de W4 Engine, les commandes initiales étaient introduites par l attribut precmdxx, où XX est un entier spécifiant l ordre d exécution de ces API. Cette terminologie est toujours supportée dans la version actuelle. Il est toutefois recommandé d utiliser la nouvelle terminologie. W4 Engine propose plus d une centaine d API différentes, qui peuvent toutes être utilisées comme valeur des attributs cmd et precmdxx. 5 - Récupération des paramètres de l API Une fois l API W4 Engine identifiée, le programme CGI cgi.exe recherche, dans la liste établie à l étape 1, la valeur des paramètres d entrée de l API. cgi.exe connaît tous les paramètres de chaque API W4 Engine. 6 - Appel de l API Une fois les paramètres de l API instanciés, le programme CGI cgi.exe soumet la requête au serveur W4 Engine et attend la réponse. 1 Dans la mesure où le nombre maximal de licences concurrentes n est pas atteint. W4 BPM Suite NOTE TECHNIQUE 6

7 Les étapes 5 et 6 peuvent être exécutées plusieurs fois si plusieurs API W4 Engine doivent être chaînées dans le même appel au programme cgi.exe. 7 - Recherche du prototype HTML de présentation Lorsque la dernière API (correspondant à l attribut cmd) a été exécutée ou lorsqu une API lancée à l étape 6 renvoie un code d erreur, le programme CGI cgi.exe recherche le prototype de présentation de la réponse ou de suite du dialogue. Si aucun code d erreur n est renvoyé, le nom du prototype est déterminé par la partie value de l élément template=value dans la liste obtenue à l étape2 1. Si l attribut template n est pas défini, un prototype appelé standard est utilisé. Le programme CGI recherche alors le fichier correspondant au nom du prototype et à la langue de l utilisateur. Cette dernière est déterminée par l élément lg=value. En l absence de valeur, cgi.exe fait référence à l anglais. Si un fichier correspondant à la langue de l utilisateur et au prototype est trouvé, il est utilisé pour la présentation de la réponse. Dans le cas contraire, cgi.exe recherche un fichier relatif à un prototype multilingue. Si aucun fichier n est trouvé, le prototype templatenotfound est utilisé. Si l une des API renvoie un code d erreur, le même mécanisme est utilisé, sauf que le prototype est déterminé par l élément error=value. Si l attribut error n est pas défini, le prototype par défaut s appelle standarderror. Il est également possible de revenir à un écran mémorisé en utilisant le paramètre contextbackup. 8 - Présentation de la réponse Le prototype sélectionné à l étape 7 est analysé afin de générer la page HTML qui sera présentée à l utilisateur. Un prototype est une page HTML dans laquelle apparaissent des mots clés W4 Engine spécifiques, qui sont remplacés par la valeur des objets de workflow correspondants. Les mots clés W4 Engine sont nombreux et permettent d insérer, entre autres : les résultats de l API ; des informations sur le participant ; des informations sur la tâche courante ou le dossier courant ; des informations sur n importe quel objet du système de workflow, par le biais de scripts. 9 - Déconnexion du système de messages W4 Engine La page générée est transmise au serveur Web. Le programme CGI cgi.exe se déconnecte du serveur W4 Engine et s arrête. 7 NOTE TECHNIQUE Conception d une page Web dynamique

8 2 Types de page HTML Un site Web intégrant des applications de workflow gérées avec W4 Engine comportera différents types de page : pages externes de présentation sans lien direct avec le workflow ; pages de connexion au serveur de workflow ; pages statiques offrant des accès directs aux pages dynamiques ; pages représentant une corbeille de tâches ; pages d activité permettant l exécution d une tâche ; pages de supervision des tâches et dossiers de workflow ; pages d information sur des objets de workflow ; pages d administration ; pages d intégration avec des applications externes. Toutes ces pages peuvent être réalisées avec n importe quel éditeur HTML du commerce. Nous recommandons cependant les éditeurs générant un code HTML lisible et simple, notamment ceux qui permettent la modification directe du code. Avec un peu d habitude, il devient aisé de créer des pages HTML en adaptant des pages existantes, en particulier pour les appels aux API de workflow et les contrôles d entrée en JavaScript, et la présentation de listes d objets complexes. Un éditeur de texte standard, avec ses fonctions de recherche/remplacement, offre une efficacité plus grande que l éditeur graphique, qui force l ouverture d un grand nombre de boîtes de dialogues pour modifier les éléments «cachés». La partie graphique de l éditeur HTML sera principalement utilisée pour la mise en page, la définition de tableaux, la couleur, l insertion d images, etc. 2.1 Pages externes de présentation sans lien direct avec le workflow Il s agit en général des pages d accueil du site Web, et des documents publiés sans restrictions ni suivi particulier. Nous n avons pas de conseil particulier quant à la création de ce type de page. Les pages externes sont accessibles simplement par leur adresse Web (URL). Leurs hyperliens vers des applications de workflow dirigeront généralement l utilisateur vers les pages de connexion au serveur de workflow. Lorsque des pages de workflow doivent présenter des liens vers des pages externes, il peut être intéressant de référencer celles-ci comme des documents de workflow. W4 BPM Suite NOTE TECHNIQUE 8

9 2.2 Pages de connexion au serveur de workflow Il s agit des pages qui assurent la transition entre les pages statiques (par exemple, l écran d accueil du site) et les pages dynamiques. Elles présentent un formulaire demandant l identifiant et le mot de passe de l utilisateur. Elles peuvent aussi permettre de créer un nouveau compte utilisateur qui sera immédiatement valide. Ces pages sont stockées sur le site Web et sont accessibles par leur URL. Après la vérification de l identifiant et du mot de passe, l utilisateur reçoit un jeton qui sera propagé de page en page et permettra au système de workflow de vérifier la validité de la connexion. L utilisateur est aiguillé vers une page statique offrant l accès direct aux pages dynamiques, ou vers une page de type corbeille de tâches. 2.3 Pages statiques offrant des accès directs aux pages dynamiques Les pages permettant des accès directs aux pages dynamiques ont une apparence statique et sont conçues comme les pages externes. La principale différence est qu elles sont liées au système de workflow. Par conséquent : Ces pages statiques sont capables d activer des requêtes de workflow en transmettant le jeton de l utilisateur connecté. La page est donc conçue de façon dynamique. Elles peuvent utiliser les mécanismes de dictionnaire de W4 Engine, et être présentées en plusieurs langues tout en maintenant un code source unique. Elles sont stockées avec les prototypes de page W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. 2.4 Pages représentant une corbeille de tâches Ces pages constituent l interface privilégiée de l utilisateur, qui y trouvera ses tâches et les moyens de créer de nouveaux dossiers. Ces pages seront souvent réalisées, après la mise au point d une nouvelle procédure, pour répondre aux besoins d utilisateurs ayant un profil spécifique. Elles permettent, en particulier, de diminuer fortement les besoins de formation des participants occasionnels. W4 Engine offre des mécanismes de génération assistée de ce type de pages. W4 Engine propose en standard une corbeille de tâches (appelée «workflow classique») qui permet à un utilisateur d accéder à toutes ses tâches et de les exécuter. Cette interface standard sera employée par les utilisateurs avertis, ainsi que dans les phases de prototypage et de mise au point. Elle est développée par les mécanismes décrits dans ce guide et peut être personnalisée par un intégrateur. Ces pages sont stockées avec les prototypes de page W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. 9 NOTE TECHNIQUE Types de page HTML

10 2.5 Pages d activité permettant l exécution d une tâche Ces pages constituent le cœur du système de workflow. Elles présentent à l utilisateur les informations dont il a besoin pour exécuter une tâche. En général, le système crée ces tâches en adaptant, en fonction de la signature des activités correspondantes, les prototypes de page générés automatiquement par W4 Engine. Remarque Le générateur de prototypes de page a été développé avec les mécanismes décrits dans ce guide et peut être adapté par un intégrateur. Ces pages sont stockées avec les prototypes d activité W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. Lorsqu une activité requiert des mécanismes d interaction sophistiqués, plusieurs écrans sont nécessaires pour la réaliser. Seul l écran initial est stocké avec les prototypes d activité W4 Engine, les écrans supplémentaires faisant partie des prototypes de page. 2.6 Pages de supervision des tâches et dossiers de workflow Ces pages permettent de superviser les tâches et dossiers de workflow et d agir sur leur déroulement. Un intégrateur aura rarement besoin de développer de telles pages, et se contentera de l interface de coordination proposée par W4 Engine (en l adaptant éventuellement). Lorsque des besoins spécifiques de coordination se font sentir, nous conseillons de développer des activités de supervision spécialisées pour une procédure. Ces pages sont stockées avec les prototypes de page W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. 2.7 Pages d information sur des objets de workflow Ce type de page permet de naviguer dans la base de données du workflow, renforçant la cohérence entre objets de workflow. Par exemple, des dossiers relevant de procédures différentes (commande, gestion de client, livraison) pourront être couplés fortement par une page d information. Ces pages sont stockées avec les prototypes de page W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. W4 BPM Suite NOTE TECHNIQUE 10

11 2.8 Pages d administration Il s agit de pages permettant d administrer les comptes, les rôles, les serveurs, les procédures et les activités. Un intégrateur aura rarement besoin de développer de telles pages, et se contentera de l interface d administration proposée par W4 Engine (en l adaptant éventuellement). Lorsque des besoins spécifiques d administration se font sentir, nous conseillons de développer des procédures spécialisées. Ces pages sont stockées avec les prototypes de page W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. 2.9 Pages d intégration avec des applications externes L exécution d une tâche impose parfois de se connecter à des applications existantes (base de données, applications patrimoniales, annuaire). Ces pages sont stockées avec les prototypes de page W4 Engine et sont accessibles via le mécanisme de substitution du programme CGI cgi.exe. 11 NOTE TECHNIQUE Types de page HTML

12 3 Emplacement des fichiers utilisés par W4 Engine Lors de l installation de W4 Engine les répertoires suivants sont créés : Bin Les programmes serveur w4 sont stockés dans ce répertoire. Cgi-bin Les programmes passerelle appelés par le serveur Web sont stockés dans ce répertoire. En particulier c est ici que réside le programme cgi.exe. L adresse Web fait référence à ce répertoire. Un concepteur d application peut utiliser ce répertoire pour stocker ses programmes passerelle Templates Le programme cgi.exe de W4 Engine soumet des requêtes au serveur workflow, puis présente les résultats des requêtes à l utilisateur en générant une page HTML à partir d un modèle de présentation des réponses (appelé template). Le programme cgi recherche le modèle de pages dans le répertoire Templates. Ce répertoire peut être hiérarchisé et W4 conseille de créer un sous-répertoire par projet. Tous les modèles de pages sont dans ce répertoire à l exception des modèles de pages permettant l exécution des activités qui sont dans le répertoire Activities. Il n existe pas d adresse Web permettant d accéder directement aux modèles de pages non substitués. Activities Ce répertoire contient les modèles de pages permettant l exécution des activités. Le nom du modèle de page est directement déduit du nom de l activité à exécuter. Tous les modèles de page des activités sont stockés à plat dans ce répertoire. Il n existe pas d adresse Web permettant d accéder directement aux modèles de pages d activités. Le programme cgi recherche le modèle de présentation de page dans le répertoire Activities lorsque l API identifiée par l attribut cmd est la commande d exécution de tâche (ProcessTask). W4 BPM Suite NOTE TECHNIQUE 12

13 Il recherche le modèle dans le répertoire Templates pour toutes les autres APIs ainsi que pour le traitement des erreurs. Public Ce répertoire est un répertoire Web classique qui contiendra des pages statiques et des documents. Les objets de ce répertoire peuvent être accédés à travers l adresse Web On stockera dans ce répertoire les pages de connexion à W4 Engine ainsi que les documents attachés aux dossiers workflow qui ont vocation à être consultés en dehors du workflow. Images W4 Engine stocke traditionnellement les images gif et jpeg dans ce répertoire accessible à travers l adresse Private Ce répertoire est réservé pour stocker sur le serveur Web des documents attachés par les utilisateurs dans le cadre de leurs activités workflow, afin de permettre leur accès par d autres utilisateurs, sans toutefois proposer une adresse publique Web pour ces documents. Ainsi, les documents ne seront accessibles qu à travers les dossiers workflow auxquels ils ont été attachés. Lorsque le serveur workflow et le serveur Web résident sur des systèmes différents, les répertoires cgi-bin, Public, Private, Images, Templates et Activities sont tous dans l espace adressable par le système hébergeant le serveur Web, tandis que le répertoire bin est sur le système hébergeant le serveur workflow. 13 NOTE TECHNIQUE Emplacement des fichiers utilisés par W4 Engine

14 4 Mécanismes de substitution Pour générer les pages dynamiques présentées à un utilisateur, le programme CGI cgi.exe fusionne un prototype de page avec les données de workflow provenant de l exécution des commandes workflow ainsi que les données passées directement dans la requête ou le formulaire HTML. Un modèle de page peut être vu comme un document préparé pour du publipostage. Il contient le texte commun et la présentation commune à toutes les instances et des portions variables introduites par un marqueur de substitution, qui seront remplacées dynamiquement lors de la génération de la page résultat. Tout objet à substituer est introduit par un mot clé W4 Engine spécifique, commençant par le 2 (par exemple, la tâche courante est désignée Les objets peuvent être des structures ou des tableaux de structures. L accès à un champ de la structure s effectue à l aide d une notation pointée utilisant les noms de champ. Par exemple, la structure d une tâche comporte un champ actor de type twfname, qui est luimême une structure dotée des champs id et str. Ainsi, le nom de l acteur en charge de la tâche courante sera substitué à la Le nom des mots clés W4 Engine et des champs n est pas sensible à la casse est donc équivalent Pour mieux contrôler le format de substitution, il est possible de borner les constituants de la commande W4 par des parenthèses. sont équivalents. Ce mécanisme est utile pour composer des «phrases» à partir de mots clés W4 Engine. Exemple : dans la procédure de jeu d échecs, le nom du dossier correspondant à une partie d échecs est généré à partir du nom des joueurs blanc et noir, par la Le résultat d une substitution W4 Engine est toujours une chaîne de caractères (éventuellement vide). Cette chaîne de caractères peut contenir des caractères spéciaux (espaces, caractères accentués). Lorsqu on utilise le mécanisme de substitution W4 Engine pour construire une URL cible d un hyperlien de la page résultat, il peut être nécessaire d «échapper» les caractères spéciaux apparaissant après la substitution. Il suffit pour cela d insérer le caractère % avant le mot clé W4 Engine. Exemple seront substitués par le prénom de l acteur courant dans lequel les caractères spéciaux seront échappés par leur code hexadécimal. Si l acteur courant a pour prénom retournera Val%E9rie 2 Signe arrobas, également appelé A commercial ou escargot. Ce dernier nom a donné naissance au terme escargotage (en anglais, snail programming) pour designer la conception de prototypes de page HTML pour W4. Comme un escargot transporte sa maison, le mécanisme de substitution transporte dans HTML toute la puissance de W4 (mais sans la connotation de «lenteur» associée à cet animal!) : il transforme le langage HTML, prévu pour publier des documents statiques, en un environnement complet pour développer des applications interactives sur Internet. W4 BPM Suite NOTE TECHNIQUE 14

15 L intégrateur développant un prototype de page ou d activité HTML doit connaître toutes les structures de données W4 Engine, ainsi que la signature des API. Celles-ci sont décrites de manière détaillée dans le Manuel de référence des API. Ce manuel de référence est accessible en ligne à l adresse (serveur web NT) ou (serveur Web Unix). Les concepteurs d applications seront avisés de garder un signet sur cette adresse. 4.1 Environnement de substitution L environnement de substitution est un ensemble de données qui comprend : les résultats de l API (incluant un code retour) ; des informations sur le participant (obtenues à partir de la valeur des attributs id et lid, qui doivent être présents dans les données transmises au programme cgi.exe) ; des informations sur la tâche courante ou le dossier courant (obtenues à partir de la valeur des attributs taskid et caseid, qui peuvent être présents dans les données transmises au programme cgi.exe) ; des informations sur n importe quel objet du système de workflow, par le biais de scripts ; les valeurs des autres attributs présents dans les données passées à cgi.exe. 4.2 Substitution W4 Engine Le programme CGI cgi.exe génère une page dynamique en analysant le prototype de page qui contient des commandes W4 Engine et en substituant ces dernières. La page produite est envoyée au serveur Web, qui la transmet à son tour au navigateur Web pour affichage sur l écran de l utilisateur. La page générée reproduit fidèlement le modèle de présentation et substitue toutes les constructions introduites par le par leur valeur. Une construction à substituer a la forme et sera évaluée de la manière suivante : 1 reconnaissance de la racine de la construction à substituer ; 2 reconnaissance de la qualification éventuelle de la construction, en fonction du type induit par la racine. Reconnaissance de la racine d une construction à substituer La phase de reconnaissance de la racine suit l ordre indiqué ci-après et s arrête dès que la recherche est fructueuse. La racine de la commande W4 peut correspondre : 1 au nom de l itération courante ; 2 à un mot clé prédéfini ou à une variable d environnement du programme CGI ; 3 à un nom de variable de la tâche courante ; 4 à un nom de variable du dossier courant ; 5 à un paramètre du formulaire ou de la chaîne de requête ; 6 à un script W4 Engine. 15 NOTE TECHNIQUE Mécanismes de substitution

16 Reconnaissance de la qualification d une commande Cette phase s arrêtant à la première occurrence trouvée, il est préférable de considérer la liste des mots clés prédéfinis et la liste des variables d environnement du programme CGI comme des mots réservés. Remarque si une donnée de tâche ou une donnée de dossier porte le même nom qu un mot réservé, il reste possible d accéder à la valeur de la donnée en spécifiant son nom complet (par Une fois la racine de la commande reconnue, le programme cgi.exe en déduit le type de l objet correspondant et sa cardinalité (monovaleur ou liste). Il passe ensuite à la reconnaissance de la qualification, qui doit désigner un champ scalaire de l objet identifié ; la valeur de ce champ est alors substituée à la commande. Exemples La racine est CASE, mot clé prédéfini désignant le dossier de workflow courant. La qualification de cette commande est procedure.str, qui correspond au nom de la procédure associée au dossier. La racine est ACTOR, mot clé prédéfini qui désigne le participant courant. La qualification est , qui correspond à l adresse électronique de cet acteur. La racine est TASK, mot clé prédéfini désignant la tâche courante. La qualification creationdate.day correspond au champ «jour» de la date de création de la tâche. Constructions non reconnues La page générée étant présentée directement à l utilisateur, le programme cgi.exe ne doit pas échouer, même si certaines constructions ne sont pas reconnues. Si la racine n est pas reconnue ou que la qualification ne correspond à aucun champ de l objet identifié par la racine, une chaîne vide est substituée à la commande et une erreur est mémorisée. Cette erreur ne sera affichée que si le mot doit être substitué. 4.3 Attributs à transmettre au programme cgi.exe Les mots clés W4 Engine permettent de substituer dans la page générée des indications concernant l environnement de substitution (acteur connecté, type de navigateur, date courante, etc.) et permettent des raccourcis d écriture. Beaucoup de ces mots clés ne prennent de sens que lorsque des renseignements suffisants ont été transmis au programme cgi sous la forme attribut=valeur. Les attributs fondamentaux à passer à un programme cgi sont les suivants : Id : Identificateur de l utilisateur connecté. Lorsque cet attribut est renseigné, le mot permet d accéder aux caractéristiques de l acteur connecté. W4 BPM Suite NOTE TECHNIQUE 16

17 TaskId : Identificateur de la tâche courante. Lorsque cet attribut est renseigné, les permettent d accéder directement aux propriétés de la tâche courante (@TASK), aux propriétés du dossier auquel appartient la tâche courante (@CASE), aux propriétés de l activité associée à la tâche courante (@ACTIVITY) et aux propriétés de la procédure à laquelle est attachée la tâche courante (@PROCEDURE). Les variables de la tâche courante et du dossier attaché à la tâche courante sont aussi accessibles directement. CaseID : Identificateur du dossier courant. Lorsque cet attribut est renseigné, les mots permettent d accéder aux propriétés du dossier courant et de la procédure associée. 4.4 Mots clés W4 Engine prédéfinis La liste des constructions prédéfinies W4 Engine est donnée ci-dessous par ordre (aucun) Insertion du Aucune. Sert à insérer le dans une partie de texte statique du prototype de page. Utilisé pour des prototypes de page qui génèrent d autres prototypes de page. est est twfactivity Activité associée à la La tâche courante doit être définie par tâche courante. l attribut taskid présent dans les données du programme cgi.exe. sera remplacé par le nom de l activité associée à la tâche courante. (Mais la substitution donnera une chaîne vide si la tâche courante n est pas sera remplacé par l identificateur de l activité associée à la tâche sera remplacé par la description de l activité associée à la tâche courante. (Même remarque sera remplacé par le type (nombre entier) de l activité associée à la tâche courante. 17 NOTE TECHNIQUE Mécanismes de substitution

18 En sera remplacé par une chaîne vide, car il s agit d une référence le tableau des variables de l activité. Cette commande sera remplacée par une chaîne vide si elle se présente telle quelle. Nous verrons plus loin comment sont substitués les éléments de twfactor Participant ayant soumis la requête. Le participant est identifié par l attribut id présent dans les données du programme cgi.exe. sera remplacé par le nom de connexion du sera remplacé par l identificateur du participant sera remplacé par le prénom de sera remplacé par l identificateur du responsable du chaîne de caractères Type authentification. Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. Remplacé sera remplacé par «basic» lorsque le serveur web demande une authentification par login et mot de twfworkcase Dossier courant. Le dossier courant doit être défini par l attribut taskid ou caseid présent dans les données du programme cgi.exe. sera remplacé par le nom du sera remplacé par l identificateur de l initiateur du sera remplacé par l état du dossier (nombre sera remplacé par la valeur de la variable xx du dossier, ou par une chaîne vide si xx n est pas une variable de ce dossier. W4 BPM Suite NOTE TECHNIQUE 18

19 @CASEID twfid (entier) Identificateur du dossier courant. Le dossier courant doit être défini par l attribut taskid ou caseid présent dans les données du programme est remplacé par l identificateur du dossier courant, ou par une chaîne vide si le dossier courant n est pas défini. En général, ce mot clé est utilisé pour transmettre le dossier courant à un autre programme CGI. Exemple chaîne de caractères Longueur en octets des paramètres passés au programme cgi par la méthode POST. Gardé pour compatibilité. Remplacé Aucune. Variable d environnement passée par le serveur web au programme chaîne de caractères Type MIME du contenu de la réponse à la requête HTML Gardé pour compatibilité. Remplacé Aucune. Variable d environnement passée par le serveur web au programme entier Nombre d objets Il doit exister une boucle courante. dans une est remplacé par la cardinalité de l objet définissant la boucle courante. Cette construction peut être avantageusement remplacée par la qualification «nbitems» suivant un objet de type liste ou tableau. 19 NOTE TECHNIQUE Mécanismes de substitution

20 Exemple (aucun) Contexte du participant. est un mot clé «de confort» qui est remplacé par la chaîne : id=@id&lid=@lid&lg=@lg&wfs=@wfs. On utilise en pour transmettre les paramètres du contexte de l utilisateur à un autre programme CGI. Exemple href="/w4/cgi.exe?@ctx& twfdate Date courante du serveur. sont remplacés respectivement par l année, le mois et le jour est remplacé par la date courante au format aaaa/mm/jj chaîne de caractères Substitué par la variable d environnement «nomvariable» passée par le serveur web au programme cgi.exe. Aucune. Si la variable d environnement nomvariable n existe pas, une chaîne vide est substituée W4 BPM Suite NOTE TECHNIQUE 20

21 La liste de variables d environnement passées par le serveur Web au programme cgi.exe varie selon les serveurs web et selon les versions de ces serveurs web. Si nomvariable correspond à une variable d environnement, la valeur de cette variable est substituée. Sinon une chaîne vide est retournée. NFT-1DFT,M3.5.0/02:00,M10.5.0/03:00 Mozilla/4.03 [fr] (Win95; image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, /W4/cgi.exe Pour connaître la liste des variables disponibles dans un environnement donné, la méthode la plus simple est de passer le programme cgi cgi.exe en mode trace (commande w4 trace cgi +t +all) et d exécuter une commande W4 Engine qui va lancer le programme cgi.exe. En mode trace, chaque appel du cgi crée 2 fichiers cgi##.env et cgi##.in (## étant le numéro de process cgi). Le fichier.env contient la liste des variables d environnement passées au programme cgi.exe par le serveur web. La trace du programme cgi.exe s arrête par la commande w4 trace cgi -t. W4 Engine peut aussi fournir sur demande un programme perl w4trace.pl qui affiche à l écran l environnement passé par le serveur Web au programme cgi. 21 NOTE TECHNIQUE Mécanismes de substitution

22 @ERROR_PROCESSING (aucun) Affiche les erreurs de substitutions sur les scripts et les dictionnaires est un mot clé «de confort» qui est remplacé par le texte des messages d erreurs rencontrés lors de l analyse de la page HTML envoyé au programme cgi (exécution incorrecte d un script ou script inexistant, appel à un dictionnaire inexistant ou entrée invalide dans ce dictionnaire, erreurs de syntaxe sur le langage W4). Il est conseillé de en fin de toute page HTLM afin de détecter au plus vite ces (aucun) Ensemble des données passées au programme CGI. est remplacé par l ensemble des données transmises au programme CGI, avec le format &attribut=valeur&attribut=valeur& &attribut=valeur. Ce mot clé est peu employé. Il peut servir à passer à un programme CGI l environnement de substitution du programme CGI courant. Exemple Self.location="/W4/clearexec?cmd=ProcessTask&taskId=@taskId" + encode("@formdata") La ligne JavaScript ci-dessus indique au navigateur de remplacer la page courante par le résultat du programme CGI clearexec, auquel sont passés des paramètres propres et les paramètres du programme CGI appelant. clearexec doit être appelé à la place du programme cgi.exe traditionnel pour éviter les conflits avec le cryptage des URL mis en œuvre par W4 chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. Remplacé W4 BPM Suite NOTE TECHNIQUE 22

23 @HOME (aucun) Racine de l arborescence W4 Engine sur le serveur. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. twfid Identificateur du compte du participant. Aucune. Ce n est pas à proprement parler un mot clé mais la simple restitution de la valeur de l attribut id passé au programme cgi. Ce mot clé est utilisé de manière cachée pour transmettre le contexte de l utilisateur à un autre programme CGI. Exemple est remplacé par l identificateur du participant sous le nom duquel est exécutée la requête W4 type de l objet définissant la boucle Elément d une boucle. Il doit exister une boucle est remplacé successivement par chaque élément de la liste sur laquelle est définie une boucle. 23 NOTE TECHNIQUE Mécanismes de substitution

24 Exemple définit une itération sur une liste d objets retournée par l évaluation de ToDoList. Le texte contenu entre l en-tête de et la fin de est substitué autant de fois qu il y a d objets retournés. A chaque représente un nouvel élément de la liste retournée par l évaluation de entier Numéro d itération Il doit exister une boucle courante. dans une est remplacé par le numéro d itération dans la boucle courante. Exemple <li> sera successivement substitué par les valeurs 0,1,2, chaîne de Langue de Définie par l attribut lg présent dans caractères l utilisateur. les données du programme cgi.exe. Ce mot clé est utilisé de manière cachée pour transmettre le contexte de l utilisateur à un autre programme CGI. est remplacé par la langue du participant. W4 BPM Suite NOTE TECHNIQUE 24

25 @LID entier Numéro de login associé à l utilisateur. Utilisé comme cookie. Défini par l attribut lid présent dans les données du programme cgi.exe. Ce mot clé est utilisé de manière cachée pour transmettre le contexte de l utilisateur à un autre programme CGI. est remplacé par l identificateur de login du connu par cgi.exe ; n importe quel type W4 Engine Contient le résultat de l API appelée avant l analyse du prototype. Il peut s agir d un objet structuré monovaleur (e. g. résultat de GetTask), d un objet structuré multivaleur (e. g. résultat de SearchTask) ou d un objet scalaire. Aucune. Exemple 1 L API appelée avant l analyse du prototype de page est GetTask. En consultant la documentation des API W4 Engine, on constate que GetTask renvoie un objet de type sera remplacé par le nom du dossier associé à la tâche, par l identificateur du participant auquel la tâche a été attribuée. Exemple 2 L API appelée avant l analyse du prototype de page est SearchTask. En consultant la documentation des API W4 Engine, on constate que SearchTask renvoie un objet de type twfttask, c est-à-dire un tableau de tâches. Les objets multivaleurs ne peuvent être substitués qu en recourant au concept de boucle étudié plus entier ou chaîne de caractères Contient la valeur d entrée dans un dictionnaire. Être dans le contexte d un dictionnaire ou «map». Dans le contexte d un dictionnaire ou contient la valeur d entrée dans ce dictionnaire. Cette valeur est accessible dans le message à substituer. 25 NOTE TECHNIQUE Mécanismes de substitution

26 Exemple Le dictionnaire local ou «map» suivant [W4MAP day] [W4ENTRY 0 default]@date.day[/w4entry] [W4ENTRY default default]@mapentry[/w4entry] [/W4MAP] [W4MAP month] [W4ENTRY 0 default]@date.month[/w4entry] [W4ENTRY default default]@mapentry[/w4entry] [/W4MAP] [W4MAP year] [W4ENTRY 0 default]@date.year[/w4entry] [W4ENTRY default default]@mapentry[/w4entry] [/W4MAP] substitue l appel : {@install.value.day:day}/{@install.value.month:month}/{@install.value.year:year } soit par le contenu de la variable install de type date, soit par la date du chaîne de caractères Code d erreur de l API. est remplacé par le message d erreur de l API. Les prototypes de page analysés après qu une API a renvoyé un code d erreur non nul sont différents de ceux analysés après une exécution sans erreur. On utilisera en dans les prototypes de traitement d rend le code d erreur de l chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. Remplacé W4 BPM Suite NOTE TECHNIQUE 26

27 @PATH_TRANSLATED chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. (aucun) Substitution retardée du résultat d une précommande. Aucune. W4 Engine permet d exécuter consécutivement plusieurs API de workflow dans un seul appel au programme CGI cgi.exe. Cette technique est appelée «mécanisme de pré-commandes». Les API successives sont appelées en renseignant les attributs precmdxx=nom_api passés au programme CGI cgi.exe. XX est un entier représentant l ordre d exécution des précommandes. Les résultats d une pré-commande sont souvent utiles pour exécuter la commande suivante. Ils sont introduits par le mot et sont évalués après l exécution de la précommande, c est-à-dire par une autre instance du programme cgi.exe. Exemple Href="/W4/cgi.exe?@ctx&precmd1=NewCaseWithInitiator&initiator.id=@ID&cmd=Proces stask&[email protected]& " L activation de l hyperlien ci-dessus va déclencher le programme cgi.exe, qui lancera successivement la création d un dossier de workflow et l exécution de la première tâche de ce dossier. Cette exécution nécessite de fournir l identificateur de la première tâche du nouveau dossier. Le résultat de NewCaseWithInitiator est un objet de type tâche, représente son identificateur. Il faut bien comprendre que la substitution par l identificateur de la tâche sera effectuée par le programme cgi.exe appelé par l hyperlien, et non par le programme courant. Ce dernier se contentera de recopier la dans la page HTML en cours de génération. En outre, il peut arriver que deux pré-commandes successives aient besoin de paramètres de même nom avec des valeurs différentes. Le mot est alors utilisé pour gérer ces conflits. 27 NOTE TECHNIQUE Mécanismes de substitution

28 twfprocedure Procédure associée au dossier courant. Le dossier courant doit être défini par l attribut taskid ou caseid présent dans les données passées au programme cgi.exe. sera remplacé par le nom de la procédure associée à la tâche sera remplacé par l identificateur de la procédure associée à la tâche sera remplacé par la description de la procédure associée à la tâche courante. En sera remplacé par une chaîne vide, car il s agit d une chaîne de caractères Paramètres passés au programme cgi sous la forme attribut=valeur Gardé pour compatibilité. Remplacé Aucune. Variable d environnement passée par le serveur web au programme chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. Remplacé W4 BPM Suite NOTE TECHNIQUE 28

29 @REMOTE_HOST chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. entier Code d erreur de l API. est remplacé par le code d erreur de l API. Les prototypes de page analysés après qu une API a renvoyé un code d erreur non nul sont différents de ceux analysés après une exécution sans erreur. On utilisera en dans les prototypes de traitement d sera en général couplé 29 NOTE TECHNIQUE Mécanismes de substitution

30 @MESSAGE est remplacé par le message d erreur de l chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. (aucun) Mémorise l URL et l environnement de substitution ayant permis d accéder à la page courante. est particulièrement utile pour mémoriser un écran afin d y revenir après l exécution d autres requêtes de workflow. Prenons l exemple d un écran de corbeille de tâches : il présente des hyperliens correspondant à chacune des tâches de l utilisateur et permettant de les exécuter. Après l exécution d une tâche, il semble judicieux de revenir à la corbeille mémorise uniquement la requête ayant permis d accéder à l écran voulu. Pour revenir à cet écran, la requête sera exécutée à nouveau. Attention! N que dans des écrans dont la requête associée ne provoque aucun changement de l état du système de workflow, telle une requête de recherche ou une requête parse (qui se contente d analyser un prototype de page). Exemple Href="/W4/cgi.exe?@CTX&cmd=ProcessTask&saveContext=@SELF& " L activation de l hyperlien ci-dessus transmettra au programme CGI cgi.exe un paramètre appelé savecontext, qui contiendra les références de la page courante en cours de génération. La page présentant les résultats de la commande ProcessTask contiendra probablement une instruction demandant un retour à la page mémorisée par savecontext (contextbackup=@savecontext). W4 BPM Suite NOTE TECHNIQUE 30

31 @SERVER_NAME chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. chaîne de caractères Aucune. Variable d environnement passée par le serveur web au programme cgi.exe. Gardé pour compatibilité. twftask Informations complètes sur la tâche courante. La tâche courante doit être définie par l attribut taskid présent dans les données du programme cgi.exe. sera remplacé par l identificateur de la tâche. 31 NOTE TECHNIQUE Mécanismes de substitution

32 @TASK.actor.str sera remplacé par le nom du participant chargé de la sera remplacé par l état de la tâche (nombre sera remplacé par la valeur de la variable xx de la tâche, ou par une chaîne vide si xx n est pas une variable de cette twfid (entier) Identificateur de la tâche courante. La tâche courante doit être définie par l attribut taskid présent dans les données du programme est remplacé par l identificateur de la tâche courante, ou par une chaîne vide si la tâche courante n est pas définie. En général, ce mot clé est utilisé pour transmettre la tâche courante à un autre programme CGI. Exemple chaîne de caractères Nom du service de workflow. Aucune. Ce mot clé apparaît de manière cachée dans le transmis à un programme permet de différencier le serveur de workflow si plusieurs sont lancés sur la même machine. 4.5 Boucles Un certain nombre d API, notamment celles de recherche, génèrent des résultats sous la forme de listes d objets. C est également vrai pour les scripts W4 Engine. De même, les variables de tâche ou de dossier peuvent comporter plusieurs valeurs. Pour présenter ces objets multivaleurs, W4 Engine offre le mot clé ainsi que plusieurs variantes Cela facilite l utilisation de boucles dans les éditeurs La syntaxe de base d une boucle est la suivante : de l objet traité par la boucle) W4 BPM Suite NOTE TECHNIQUE 32

33 2 Itération dans laquelle l élément courant est référencé ou de l objet traité par la boucle) Le nom de l objet sujet à une boucle peut être qui référence le résultat de l API où xx représente le nom d une variable de la tâche courante ou du dossier courant ; nn, qui représente le nom d un script W4 Engine. Exemple Supposons un programme cgi.exe activant une requête de recherche des tâches non terminées de l utilisateur courant. L écran de présentation de ces tâches utilise la boucle suivante : <li><a href="/w4/cgi.exe?@ctx&cmd=processtask&[email protected]&[email protected] ame.id&savecontext=@self&[email protected]" est le résultat de l API de recherche de tâches ; il s agit d un tableau d objets de type twftask. La page générée contiendra alors une liste d hyperliens comportant autant d éléments que de tâches renvoyées par l API. A chaque sera remplacé par la tâche suivante du tableau. est le mot clé de bouclage le plus facile à maîtriser lorsqu on travaille avec un éditeur de texte standard. Cependant, il ne permet pas de profiter des possibilités de mise en page interactives d un éditeur HTML comme Microsoft FrontPage Editor, Adobe PageMill ou Microsoft Word. C est pourquoi W4 Engine propose plusieurs alternatives compatibles avec ces éditeurs présente les résultats dans une liste présente les résultats dans un tableau présente les résultats dans une boîte de L exemple ci-dessus aurait pu être défini directement avec Word et le mot de la manière @/LIST 33 NOTE TECHNIQUE Mécanismes de substitution

34 Nous avons ajouté un lien hypertexte avec l adresse URL suivante : "/W4/cgi.exe?@ctx&cmd=ProcessTask&[email protected]&[email protected] Le mot est prévu pour permettre l édition aisée de tableaux dynamiques : La ligne du tableau dans laquelle est ignorée. Toutefois, la cellule qui contient ce mot clé doit correspondre à la première colonne, et doit avoir le même format (fonte, couleur, taille) que la cellule correspondante de la ligne suivante. Toutes les lignes du tableau situées seront copiées autant de fois qu il y a d éléments dans l objet sujet à la boucle. Exemple Priorité de @/ROW Nom de la Les liens hypertexte sur les différents objets seront ajoutés d une manière similaire à celle décrite pour le mot On peut ainsi profiter des possibilités de mise en page proposées par les éditeurs De la même manière permet d exploiter les possibilités de l éditeur HTML pour présenter des résultats sous la forme de permet d afficher ces résultats sous la forme d options d une boîte de sélection. Avec l éditeur HTML, insérez une boîte de sélection. Ensuite, dans la fenêtre permettant de définir les options, entrez de l objet traité par Remarque Si la valeur affichée dans l option doit être différente de la valeur transmise, il est nécessaire de renseigner le champ HTML value= pour la ligne comportant le mot (voir le code source dans l exemple ci-après). Ce cas est fréquent : on peut présenter des noms d utilisateur et transmettre leur identificateur, ou présenter des options en fonction de la langue de l utilisateur mais transmettre une valeur fixe quelle que soit cette langue. W4 BPM Suite NOTE TECHNIQUE 34

35 Ces contraintes sont dues au mode de fonctionnement de W4 Engine. Il effectue en effet, pour des raisons de performances, une analyse en une seule passe (et sans lecture anticipée) du prototype de page. Ainsi, W4 Engine transmet directement au serveur Web les caractères qu il rencontre, sans les interpréter. Exemple Ci-dessous est présentée une boîte de sélection préparée sous FrontPage Editor 3 avec le mot Lorsque le code HTML sera interprété par le moteur de workflow, cette boîte affichera la liste des participants renvoyés par le script W4 UnitManagersActeurs. Chaque participant sera représenté par son prénom, son nom et son login entre parenthèses. La valeur transmise pour un participant sélectionné est son nom de login. Le code source généré par FrontPage Editor est le suivant : <select name="signataires" multiple size="3"> <option (@item.name)</option> <option value="@/option">@/option</option> </select> Dans la mesure où la valeur transmise par une option sélectionnée est explicitement spécifiée ), la pseudo option définie doit aussi comporter une valeur (n importe laquelle, car elle n est pas significative). Boucle unique sur plusieurs objets : STRUCT Le mot clé STRUCT permet d exécuter une boucle unique sur plusieurs objets multivaleurs. Si ces objets n ont pas tous le même nombre d éléments, la boucle s arrêtera sur la liste la plus courte. La référence aux éléments de chacun de ces objets se fait où ii référence l objet multivaleur en position ii après le mot clé Cette boucle affiche pour chacun des approbateurs d un document leur décision (accepté ou refusé). Dans cet exemple, les objets traités par la boucle sont des variables multivaleurs de tâche. 3 Front Page Editor 3.0 utilise le terme "menu déroulant". 35 NOTE TECHNIQUE Mécanismes de substitution

36 Imbrication de boucles Il est possible d imbriquer plusieurs fait alors toujours référence à l élément de la boucle la plus interne. Exemple d imbrication de créé Cette boucle imbriquée affiche la liste des dossiers d un participant pour une procédure donnée, ainsi que la liste des tâches qu il doit exécuter pour chaque dossier. Dans cet exemple, les objets traités par les boucles sont des scripts W4 Engine. 4.6 Inclusion de pages HTML et d URL W4 Engine propose 2 modes d inclusion différents : INCLUDE_TEMPLATE : inclusion d une page HTML INCLUDE_URL : inclusion de la page HTML résultant de l URL référencée. INCLUDE_TEMPLATE Ce mot clé spécifique permet de factoriser une partie de code HTML afin de l utiliser dans d autres pages définit la page HTML à inclure. Cette page HTML doit exister et être présente sous l arborescence Templates de W4 Engine. La page à inclure est un prototype de page «classique» HTML comprenant du code HTML, JavaScript, VBScript,, des définitions de MAP W4 Engine et tous mots clés et objets du langage W4. Cette page est elle-même analysée (substitution de tous les objets W4 Engine). Le résultat est inclus dans la page HTML appelante. W4 BPM Suite NOTE TECHNIQUE 36

37 Exemple avec W4Include/ActivityHeader.html <!-- [W4MAP getfullname] [W4ENTRY NULL [W4ENTRY [/W4MAP] --> <table border="0" width="100%"> <tr> <td><img src="/w4images/logo.gif"></td> <td width="100%"><p align="center"><font color="#000080" face="arial" </font><br><font color="#000080" face="arial" <td bgcolor="#000080" align="left"><font size="4" color="#ffffff" </tr> </table> Ainsi, chaque page HTML d une activité workflow demandant l inclusion de cette page obtiendra en en-tête de page un bandeau constitué d un logo, du nom de la procédure et du dossier en cours est positionné), du nom complet de l acteur courant. INCLUDE_URL Ce mot clé spécifique permet d appeler une URL, de l exécuter et d inclure le résultat de cette URL dans un prototype de page HTML. L exécution s effectue de la façon suivante : Analyse et substitution de tout objet W4 Engine contenu dans l URL passée en paramètre Exécution de l URL Analyse et substitution de tout objet W4 Engine dans la page résultat de l URL appelée. Inclusion de cette page résultat analysée dans la page appelante. 37 NOTE TECHNIQUE Mécanismes de substitution

38 Exemple avec rechercheproduit.asp LANGUAGE = VBScript %> <% Set dbconnection = Server.CreateObject("ADODB.Connection") dbconnection.open("catalogue") queryproduit = "SELECT * FROM produit WHERE Num=" & Request.QueryString("refProd") Set produit = dbconnection.execute(queryproduit ) %> <table> <tr> <td valign="top"><strong>référence : </strong></td> <td><%= produit("num")%></td> </tr> <tr> <td valign="top"><strong>libellé : </strong></td> <td><%= produit("libelle")%></td> </tr> <tr> <td valign="top"><strong>prix unitaire : </strong></td> <td><%= produit("pu")%></td> </tr> </table> Ordre d analyse et de substitution : Dans la page HTML est substitué par la valeur de la variable referenceproduit (de tâche ou de dossier si taskid ou caseid est positionné). L URL référençant l appel à un ASP est exécutée : recherche dans la table produit de la base de données «catalogue», la description complète du produit défini par refprod. Le code HTML définissant un tableau, contenant le résultat de la requête, est substitué puis inclus dans la page appelante. La page «asp» aurait pu elle-même contenir des objets W4 Engine à analyser et à substituer. 4.7 Données de la tâche courante S il existe une tâche courante (l attribut taskid est présent dans les données du programme cgi.exe), chaque variable de l activité associée à cette tâche peut être désignée W4 BPM Suite NOTE TECHNIQUE 38

39 Remarque Les variables d une activité sont définies à l aide de W4 Author. Avec une variable monovaleur, la est remplacée par la valeur actuelle de la donnée de la tâche. Si la variable est de type : entier ou chaîne de est remplacé par le texte correspondant. est remplacé par la date au format aaaa/mm/jj hh:mm:ss. Il est possible (et même conseillé) d accéder aux éléments constitutifs de la est remplacé par l URL du document. Il est fréquent que l on souhaite afficher une variable de type document en présentant le titre, l auteur, la classe et éventuellement la date de création du document, tout en offrant un hyperlien qui permet de visualiser son contenu. Exemple Avec une variable multivaleur, les commandes décrites ci-dessus s appliquent à la première valeur de la variable. Pour pouvoir afficher toutes les données, il faut passer par une boucle. Exemple La tâche courante comporte la variable SIGNATAIRES (multivaleur, type chaîne de caractères). L affichage de toutes ses valeurs se fera simplement 4.8 Données du dossier courant S il existe un dossier courant (soit l attribut taskid définit une tâche courante et donc un dossier courant, soit l attribut caseid est présent dans les données du programme cgi.exe), chaque variable du dossier peut être désignée Remarque Les variables d une procédure sont définies à l aide de W4 Author. Les règles décrites dans la section "" s appliquent sans restriction. S il existe une tâche courante, ses données «masquent» celles du dossier courant qui portent le même nom. Il reste toutefois possible d accéder aux données du dossier en utilisant la 39 NOTE TECHNIQUE Mécanismes de substitution

40 4.9 Scripts W4 Engine offre un mécanisme de script qui permet d appeler, pendant la génération de page HTML, des API de recherche sur les objets de workflow du système. Les scripts sont stockés sur le serveur ; l interface d administration de W4 Engine offre en outre le moyen de les consulter ou d en définir de nouveaux. Dans l exemple d imbrication de boucles, deux scripts étaient créé ClientCaseSupport fournit la liste des dossiers actifs, pour la procédure de support, dans lesquels le participant est initiateur. Ce script est défini de la manière suivante : API appelée : SearchCase. Critère Opérateur Valeur procedure = *Support* state < Terminated initiator Nombre maximal d éléments renvoyés : pas de limite. Tri croissant par date de création. Lors de l évaluation de la W4 Engine lancera le script en lui transmettant l ID de l utilisateur courant comme paramètre initiator. Le script interne ActiveTasks est défini comme suit : API appelée : SearchTask. Critère Opérateur Valeur workcase state < Terminated actor Nombre maximal d éléments renvoyés : pas de limite. Tri croissant par date de création. Lors de l évaluation de la boucle W4 Engine lancera le script en lui transmettant l ID de l utilisateur courant comme paramètre actor (désignant l identificateur du dossier de la boucle externe) comme paramètre workcase. Les scripts peuvent concerner des API qui renvoient un seul objet. Par exemple, GetCaseFromItem retourne la description complète d un dossier à partir d une représente le dossier renvoyé par le script ; son nom pourra être obtenu simplement par substitution Un participant possédant le rôle author peut créer de nouveaux scripts. W4 BPM Suite NOTE TECHNIQUE 40

41 4.10 Variables d environnement du programme CGI Le serveur Web transmet au programme CGI un certain nombre de variables d environnement. Pour insérer leur valeur dans la page dynamique générée, il faut faire précéder leur nom Liste des variables d environnement : AUTH_TYPE (@ENV.AUTH_TYPE) CONTENT_LENGTH CONTENT_TYPE GATEWAY_INTERFACE HTTP_ACCEPT PATH_INFO PATH_TRANSLATED QUERY_STRING REMOTE_ADDR REMOTE_HOST REMOTE_IDENT REMOTE_USER REQUEST_METHOD SCRIPT_NAME SERVER_NAME SERVER_PORT SERVER_PROTOCOL SERVER_SOFTWARE 4.11 Paramètres du formulaire ou de la chaîne de requête D autres paramètres de nom libre peuvent être transmis au programme CGI, puis substitués dans la page HTML générée. Dans l exemple relatif au mot le paramètre savecontext était passé au programme CGI cgi.exe comme suit : Href="/W4/cgi.exe?@CTX&cmd=ProcessTask&saveContext=@SELF& " Dans la page qui sera générée pour présenter les résultats du programme cgi.exe, la référence sera remplacée par la valeur de ce paramètre (dans la mesure ou le nom savecontext n entre pas en conflit avec le nom d une variable de la tâche courante ou du dossier courant). Ces paramètres utilisateur portent un nom libre qui n est pas sensible à la casse. Ils sont toujours de type chaîne de caractères (String) et ne peuvent avoir qu une seule valeur. Leur 41 NOTE TECHNIQUE Mécanismes de substitution

42 transmission au programme CGI s effectue indifféremment dans la chaîne de requête ou dans le formulaire du programme Dictionnaires Les systèmes de substitution décrits précédemment peuvent être complétés par des dictionnaires (également appelé «maps») : au lieu de remplacer la commande par une valeur calculée, W4 Engine consulte un dictionnaire et substitue à la commande la définition associée à cette valeur. Les mécanismes de dictionnaire sont extrêmement puissants, dans la mesure où la taille des messages n est pas limitée et où ceux-ci peuvent à leur tour contenir des commandes W4 Engine qui seront évaluées et substituées. Ils permettent de concevoir avec beaucoup de facilité : des applications multilingues avec un code source unique ; des écrans conditionnels. Mécanisme d appel L appel d un dictionnaire est défini par la syntaxe {commandew4:nomdictionnaire} ou {constante:nomdictionnaire}. Remarque Aucun espace n est toléré entre les deux accolades. Cette règle permet d éviter les risques de conflit avec des constructions présentes dans les prototypes de page HTML (par exemple, du code JavaScript). Le nom du dictionnaire est sensible à la casse. La constante est une chaîne de caractères sans espaces. Le mécanisme est le même que pour les commandes W4 Engine, dans la mesure où la constante est sa propre valeur. Lorsque W4 Engine rencontre une telle construction, il évalue la commande W4 Engine, puis recherche dans le dictionnaire nomdictionnaire une entrée correspondant à la valeur de la commande et à la langue de l utilisateur. (La langue est transmise dans le contexte, et l anglais en est utilisé en cas d absence de valeur.) Le dictionnaire proprement dit est constitué d un ensemble de triplets (entrée, langue, message), les deux premiers champs servant de clé de recherche. Pour trouver la définition adéquate, W4 Engine recherche les couples de données dans l ordre suivant : 1 (entrée, langue de l utilisateur), 2 puis (entrée, langue par défaut), 3 puis (entrée par défaut, langue de l utilisateur), 4 et enfin (entrée par défaut, langue par défaut). Le dictionnaire nomdictionnaire peut être défini localement, c est-à-dire dans le prototype de page, ou être partagé sur le serveur. Les dictionnaires créés localement sont prioritaires. W4 BPM Suite NOTE TECHNIQUE 42

43 Si W4 Engine ne trouve pas le dictionnaire ou ne repère aucun message correspondant à la valeur de la commande et à la langue de l utilisateur, la commande non évaluée est affichée à l écran et des erreurs sont mémorisées. Si la commande est remplacée par une chaîne vide, W4 Engine recherche l entrée NULL. Syntaxe Un dictionnaire est défini par les mots clés W4MAP (suivi d un nom) et /W4MAP, placés entre crochets. Entre ces deux lignes, chaque entrée est constituée d un triplet, d un message et d un indicateur de fin : [W4MAP nomdictionnaire] [W4ENTRY valeur langue] Message [/W4ENTRY] [W4ENTRY valeur langue] Message [/W4ENTRY] [W4ENTRY valeur langue] Message [/W4ENTRY] [/W4MAP] Il est possible de définir plusieurs dictionnaires dans un même prototype de page. La valeur renvoyée pour une entrée et une langue spécifiques est désignée par Message dans la syntaxe ci-dessus : il s agit de l ensemble des caractères situés entre le crochet fermant de [W4ENTRY] et le crochet ouvrant de [/W4ENTRY]. Remarque Tous les dictionnaires doivent avoir été définis avant la première demande d évaluation d une commande W4 Engine 4. Il faut notamment faire attention à la place du marqueur HTML <title>. En effet, il comporte souvent des appels au dictionnaire (par exemple, pour afficher le titre de la page en fonction de la langue) et doit être inséré après la définition des dictionnaires. Les mots clés de définition de dictionnaire peuvent perturber les éditeurs HTML. Pour éviter tout problème, nous vous conseillons d insérer les définitions entre les marqueurs HTML <head> et <title>, et entre commentaires : <head> <! [W4MAP dic1] [/W4MAP] [W4MAP dic2] [/W4MAP] --> <title {Titre:dic1}> 4 Les commandes W4 présentes dans la partie Message d une entrée ne sont pas évaluées au moment de la définition du dictionnaire. Il n y a donc aucune contrainte relative à cette partie Message, ni à l ordre dans lequel sont définis les dictionnaires (au cas où ils s appelleraient mutuellement). 43 NOTE TECHNIQUE Mécanismes de substitution

44 La valeur d une entrée est une chaîne de caractères littérale. W4 Engine distingue deux valeurs spécifiques : NULL permet de définir le message renvoyé par le dictionnaire lorsque la substitution de la commande W4 Engine donne une chaîne vide ; default permet de définir le message renvoyé lorsque la substitution de la commande W4 Engine ne correspond à aucune entrée du dictionnaire. La langue d une entrée est une chaîne de 2 caractères, définis lors de la création d une nouvelle langue à l aide de l outil d administration : Le français correspond à fr, et l anglais à en. La valeur default définit le message renvoyé lorsque la langue de l utilisateur ne correspond à aucune entrée du dictionnaire. Il est recommandé de choisir une langue de base et d entrer toutes ses définitions directement sous l entrée de langue default. Vous avez ainsi la garantie que tous les utilisateurs disposeront de messages, même si leur langue n est pas gérée par les dictionnaires. Utilisation de dictionnaires pour concevoir des applications multilingues Exemple : présentation d une date sous différents formats. [W4MAP bonjour] [W4ENTRY bonjour fr] <strong>bienvenue, nous sommes le {@thedate:date}</strong>[/w4entry] [W4ENTRY bonjour default] <strong>welcome, today's date is {@thedate:date}</strong>[/w4entry] [/W4MAP] [W4MAP month] [W4ENTRY 1 fr] janvier [/W4ENTRY] [W4ENTRY 1 default] January [/W4ENTRY] [W4ENTRY 2 fr] février [/W4ENTRY] [W4ENTRY 2 default] February [/W4ENTRY] [/W4MAP] [W4MAP date] [W4ENTRY default [/W4ENTRY] [W4ENTRY default [/W4ENTRY] [W4ENTRY default [/W4ENTRY] [/W4MAP] Ainsi, {bonjour:bonjour} sera substitué comme suit : français : Bienvenue, nous sommes le 7 janvier 1997 anglais : Welcome, today's date is 7 January 1997 américain : Welcome, today's date is January 7, 1997 W4 BPM Suite NOTE TECHNIQUE 44

45 Certains dictionnaires sont naturellement locaux à une page HTML, tandis que d autres sont partagés sur le serveur. Par exemple, le dictionnaire month, dont l utilisation est fréquente, devrait être défini sur le serveur. Par défaut, W4 Engine propose plusieurs dictionnaires en français et en anglais sur le serveur : dictionary définit le vocabulaire de workflow de base en français et en anglais. Comme il s agit du dictionnaire par défaut, les appels {commandew4} et {constante} sont interprétés respectivement comme {commandew4:dictionary} et {constante:dictionary}. message recense les messages d erreurs W4 Engine. month3 établit une correspondance entre le numéro d un mois et son nom sur 3 lettres. state traduit les codes internes des états de tâche et de dossier. D autres dictionnaires ont été utilisés pour développer les écrans d administration. Ils sont disponibles et peuvent constituer une documentation en ligne rapide d accès pour un auteur de procédure : typevariable traduit les codes internes des types de variable. Activity permet de connaître les différents types d activité. api permet de connaître le numéro interne des API utilisables dans les scripts. criterion permet de connaître les numéros de critère utilisés dans les scripts. Tous ces dictionnaires sont modifiables. Vous pouvez également en définir de nouveaux sur le serveur via l interface d administration. Utilisation de dictionnaires pour concevoir des écrans conditionnels Un auteur qui conçoit des prototypes de page dynamique a toujours besoin de mécanismes de contrôle permettant de définir des boucles et des conditions. Le mot et ses dérivés répondent à toutes les attentes concernant les boucles. Pour les conditions, l auteur dispose de JavaScript, de VBScript ou même de Java, qui se marient parfaitement avec les commandes W4 Engine (puisque celles-ci sont substituées avant l évaluation des scripts). Exemple If ('@cutomer.value' == '') { -- Définition de l écran de saisie par des instructions write si la variable customer n est pas définie. } else { -- Définition de l écran de modification par des instructions write si la variable customer est définie. } 45 NOTE TECHNIQUE Mécanismes de substitution

46 Dans cet exemple, la partie traitement (entre accolades) emploie le langage de script. Or, la présentation d un écran ou d une portion d écran est très lourde à gérer avec les instructions write, et ne peut guère être assistée par un éditeur HTML. Les dictionnaires W4 Engine offrent une alternative très intéressante aux conditions des scripts, dans la mesure où l on concevra les portions d écran conditionnelles directement en HTML, ce qui permet de profiter des éditeurs HTML. Ainsi, l exemple ci-dessus pourra être écrit comme suit : [W4MAP traitement] [W4ENTRY NULL default] Définition HTML de l écran de saisie si la variable customer n est pas définie.[/w4entry] [W4ENTRY default default] Définition HTML de l écran de modification si la variable customer est définie.[/w4entry] [/W4MAP] <! Ci-dessous, le code à substituer --> {@customer:traitement} W4 Engine utilise ce mécanisme pour générer automatiquement des prototypes de page HTML en fonction de la description des activités définies avec W4 Author. (Le code source du «métaprototype» est fourni dans W4Engine_Home/Templates/ActivityGeneration.html). Utilisation de dictionnaires pour regrouper des définitions d écran Il arrive fréquemment que des écrans soient très similaires. Les dictionnaires permettent alors de regrouper leur définition en un seul écran. Exemple : prenons le cas des menus de coordination de W4 Engine, qui sont très semblables dans leur forme (le menu Tâche ne comporte que l action supplémentaire créer). Bien que la forme soit similaire, les actions derrière les boutons créer, sélectionner et aller à sont très différentes, car elles opèrent sur des objets de nature différente. Il n empêche que le concepteur de ces écrans a pu profiter de la symétrie des API W4 Engine et de la puissance des commandes pour gérer ce menu avec un code source unique : il suffit de passer une variable d contenant le type de l objet. Le prototype de page gérant les menus de coordination des tâches, dossiers et événements est le suivant : <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> <! - Les menus se présentent tous sous la même forme : d abord, le dictionnaire "goto" présente les boîtes de saisie pour l identificateur du dossier/événement/tâche ou pour le nom du dossier/événement. W4 BPM Suite NOTE TECHNIQUE 46

47 [W4MAP goto] [W4ENTRY Case default]<p><font color="#ffffff"><input type=submit name="submit" value=" {goto} "> </font><font color="#ffff00">{name}:</font><font color="#ffffff"><input type=text size=10 maxlength=32 name="workcasename"> </font><font color="#ffff00">{or} {num}:</font><font color="#ffffff"><input type=text size=5 maxlength=5 name="workcasename.id"> </font></p>[/w4entry] [W4ENTRY Task default]<p><font color="#ffffff"><input type=submit name="submit" value=" {goto} "> </font><font color="#ffff00"> {num}:</font><font color="#ffffff"><input type=text size=5 maxlength=5 name="taskid"> </font></p>[/w4entry] [W4ENTRY default default]<p><font color="#ffffff"><input type=submit name="submit" value=" {goto} "> </font><font color="#ffff00">{name}:</font><font color="#ffffff"><input type=text size=10 maxlength=32 </font><font color="#ffff00">{or} {num}:</font><font color="#ffffff"><input type=text size=5 maxlength=5 </font></p>[/w4entry] [/W4MAP] Ensuite, le dictionnaire createtask permet d insérer le bouton "créer" pour une tâche seulement. (Notez que le nom du bouton {create} passe par le dictionnaire général pour localisation). [W4MAP createtask] [W4ENTRY Task default]<td align=center><form action="/w4/cgi.exe?@ctx&cmd=parse&template=coord/taskcreatefs" method="post" target="coord"> <p><font color="#ffffff"><input type=submit name="create" value="{create}"> </font></p> </form> </td>[/w4entry] [W4ENTRY default default][/w4entry] [/W4MAP] --> <title>{w4coordinationtitle}</title> <meta name="generator" content="microsoft FrontPage 1.1"> </head> <body background="/w4images/w4objectmenubackground.gif" bgcolor="#ecd59d" vlink="#0000ff"> <table cellpadding=2 cellspacing=0> <!-- La 1ère colonne présente le nom de l --> <tr><td align=center><form method="post"> <p><font color="#ffff00"><font size=3><strong>{@o}</strong></font></font><font color="#ffffff"><font size=3><strong> </strong></font></font></p> </form> </td> <! - La 2e colonne n est affichée que pour les tâches. --> {@o:createtask} <! - La 3e colonne sert à la sélection. Notez le nom du modèle (template). --> <td align=center><form action="/w4/cgi.exe?@ctx&cmd=parse&template=coord/@(o)selection" method="post" target="object"> <p><font color="#ffffff"><input type=submit name="select" value="{select}"> </font></p> </form> 47 NOTE TECHNIQUE Mécanismes de substitution

48 </td> <! - La 4e entrée concerne la sélection directe. --> <td align=center><form action="/w4/cgi.exe?@ctx&cmd=get@o&template=coord/@(o)modif" method="post" target="coord"> {@o:goto} </form> </td></tr> </table> <! - "ERROR_PROCESSING" ci-dessous permet de repérer les erreurs, principalement dans les dictionnaires. --> <p><font color="#808080">@error_processing</font></p> </body> </html> W4 BPM Suite NOTE TECHNIQUE 48

49 5 Appel d une API à l intérieur d un prototype de page Une application W4 se présente, du point de vue de l utilisateur, comme une succession d écrans. Chaque écran est généré dynamiquement en analysant un prototype de page et en appliquant les substitutions décrites dans ce document. Un écran présente les résultats d une requête et propose, via des hyperliens ou des formulaires, une série d actions de continuation. Les actions associées aux formulaires, ainsi que la plupart des hyperliens présents dans la page HTML présentée à l utilisateur, vont entraîner l exécution d une API W4 Engine via un programme CGI. Les prototypes de page doivent donc préparer les appels à ces API en construisant les URL associées aux hyperliens ou aux actions de formulaire. Reprenons l exemple illustrant l imbrication de boucles. Dans cet exemple, on affichait la liste des dossiers de support initialisés par le participant, ainsi que la liste des tâches qu il devait exécuter pour chaque dossier. A chaque dossier est associé un hyperlien permettant de visualiser son état ; à chaque tâche est associé un hyperlien permettant de l exécuter. Le prototype de page conçu sous FrontPage Editor et interprété par Word se présente comme créé Ci-dessous, l écran vu par un participant (le nombre de dossiers en cours et le nombre de tâches dépend bien sûr de l activité de ce participant) : client_w4 créé le 4 Mar 1997 à 11:8 Réponse Alarme Dépassement Ci-dessous, le code source complet du prototype de page. Les hyperliens associés aux dossiers et aux tâches apparaissent sous la forme d URL complexes. Pour les interpréter, souvenez-vous que ClientCaseSupport est un script qui renvoie une liste de dossiers, et ActiveTasks est un script qui renvoie un ensemble de tâches. 49 NOTE TECHNIQUE Appel d une API à l intérieur d un prototype de page

50 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> <meta http-equiv="content-type" content="text/html; charset=iso "> <meta name="generator" content="microsoft FrontPage 2.0"> <title>support W4</title> </head> <body background="/w4images/w4demobackground.gif"> <ul> <li><a e=support/followproblem" à <ul> <li><a </ul> </ul> </body> </html> Enfin, voici le code source de la page HTML présentée au participant : il s agit d une instance du prototype ci-dessus, dans lequel les commandes W4 Engine ont été substituées. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> <HTML> <HEAD> <TITLE>Support W4 Simulation</TITLE> <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso "> <META NAME="GENERATOR" CONTENT="Mozilla/3.0Gold (Win95; I) [Netscape]"> </HEAD> <BODY BACKGROUND="W4DemoBackground.gif"> <UL> <LI><B><A HREF=" se&caseid=8434&savecontext=/var/tmp/w4admkqw6ia&template=support/followproblem" target="_self">client_w4</a></b> créé le 4 Mar 1997 à 11:8</LI> <UL> <LI><A HREF=" cesstask&taskname.id=8472&taskid=8472&savecontext=/var/tmp/w4admkqw6ia&template =AnswerSimu" target="_self">réponse</a></li> <LI><A HREF=" W4 BPM Suite NOTE TECHNIQUE 50

51 cesstask&taskname.id=9795&taskid=9795&savecontext=/var/tmp/w4admkqw6ia&template =AlarmW4Support" target="_self">alarme</a></li> <LI><A HREF=" cesstask&taskname.id=9819&taskid=9819&savecontext=/var/tmp/w4admkqw6ia&template =OverdueW4Support" target="_self">dépassement</a></li> </UL> </UL> </BODY> </HTML> 5.1 Interprétation d une adresse URL L URL permettant d appeler une API W4 Engine est constituée des éléments suivants : 1 l appel du programme CGI cgi.exe ; 2 le contexte de l utilisateur ; 3 le nom des API à appeler ; 4 les paramètres des API ; 5 les paramètres libres ; 6 le prototype de page subséquent ; 7 le prototype de page de traitement d erreur. 5.2 Appel du programme CGI cgi.exe L URL du programme CGI cgi.exe peut commencer par l un des éléments suivants : /W4/cgi.exe /W4/clearexec Lors de l installation de W4 Engine, le chemin /W4 est déclaré dans l environnement ; il pointe sur le répertoire où sont installés les exécutables CGI (cgi-bin) de W4 Engine. Cela permet de concevoir des prototypes de page portables d un système à un autre. cgi.exe et clearexec ne se différencient que par leur comportement vis-à-vis du cryptage des arguments de l URL. En effet, lors de la génération d une page HTML, W4 Engine crypte par défaut les paramètres passés sur les lignes de commande contenant les appels à /W4/cgi.exe, puis les décrypte lorsqu ils sont activés. Cependant, ce mécanisme ne fonctionne pas si l URL contenant l appel à cgi.exe est construite à l aide de scripts JavaScript ou VBScript : on appellera alors /W4/clearexec, qui ne déclenche pas le cryptage. Remarque Il existe un mode debug, dans lequel les paramètres du programme cgi.exe ne sont pas cryptés. C est de cette manière que le code source de la page HTML présentée au participant a été imprimé. Le code généré par défaut contient des lignes similaires à l exemple cidessous, dont le contenu pédagogique est assez faible : 51 NOTE TECHNIQUE Appel d une API à l intérieur d un prototype de page

52 <a href="/w4/cgi.exe?arg=hukixbrephyd2ldf5lltognbgl_brf8bgwzvyodkaxpydwpdf52r5fe9v 3uVKFxWA9N_uPEJLDF5pkNoYDwDSyyDF5mlTpYDADS1yDF5pkNoYD9DVysO4WEEWYOF1YA8bNT3SYKD kaxp_imhofydahm6oaahyouoa8p6o5u6so8w" target="_self">alarme</a></li> 5.3 Contexte de l utilisateur Le contexte de l utilisateur est composé des attributs id, lid, lg et wfs, décrivant respectivement l identificateur du participant, son identificateur de login, sa langue et le serveur de workflow employé. Ces informations sont généralement transmises au programme cgi.exe par la commande W4 Exemple : /W4/cgi.exe?@ctx Mais vous pouvez aussi les passer de façon individuelle dans la ligne de commande ou dans les champs du formulaire associé. 5.4 Nom des API à appeler Le nom de chaque API à appeler est introduit par l attribut cmd. La valeur de cet attribut est le nom de l API indiqué dans le Manuel de référence des API. Ce manuel de référence est accessible en ligne à l adresse (serveur web NT) ou (serveur Web Unix). Les concepteurs d applications seront avisés de garder un signet sur cette adresse. Par exemple, l API CreateCase sera activée par la commande HTML suivante : /W4/cgi.exe?@ctx&cmd=createcase&... Remarque Le nom de l attribut (cmd) et sa valeur (le nom de l API) ne font pas la distinction majuscules/minuscules. L ordre dans lequel apparaissent les couples attribut=valeur n a pas d importance. W4 BPM Suite NOTE TECHNIQUE 52

53 Chaînage de plusieurs API dans le même appel à cgi.exe W4 Engine permet d utiliser plusieurs API dans le même appel au programme CGI cgi.exe. La dernière API est définie en premier par l attribut cmd, tandis que chacune des API précédentes doit être décrite par un attribut precmdxx (où XX est un entier représentant le numéro d ordre de la «pré-commande»). Dans l exemple suivant, cgi.exe lancera successivement les API CreateCase, SetVariable, ModifyCaseName et StartCase : /W4/cgi.exe?cmd=StartCase&precmd3=SetVariable&precmd5=ModifyCaseName&precmd1=Cr eatecase&... Les pré-commandes sont traitées en fonction de leur numéro d ordre. (Remarque : il n est pas nécessaire que ces numéros soient strictement consécutifs.) Dans les exemples, les attributs sont généralement fournis sur la ligne de commande pour des raisons de facilité d écriture. Mais rien ne vous empêche d utiliser un formulaire et de transmettre certains attributs dans les champs de ce dernier. Ci-dessous, certains attributs (tels que cmd) sont transmis dans des champs cachés du formulaire : <form action="/w4/cgi.exe?@ctx&taskname.id=@taskid&taskid=@taskid" method="post" name="taskcontrol"> <input type="hidden" name="cmd" value="exittask"> <input type="hidden" name="command" value=""> <input type="hidden" name="contextbackup" value=""> <input type="hidden" name="template" value=""> <div align="center"><center> <table border="1"> </table> </center></div><div align="center"><center> <table border="0"> <tr> <td align="center"><input type="button" name="commandbutton" value="terminer" onclick="completetask()"></td> <td align="center"><input type="button" name="commandbutton" value="suspendre" onclick="onholdtask()"></td> </tr> </table> </center></div> </form> 5.5 Passage des paramètres des API Les paramètres de toutes les API appelées par le programme cgi.exe doivent être fournis sur la ligne de commande ou dans les champs du formulaire. Pour connaître la signature de 53 NOTE TECHNIQUE Appel d une API à l intérieur d un prototype de page

54 chaque API (c est-à-dire la liste des paramètres à fournir, avec leur nom, leur type et leur description), consultez le Manuel de référence des API. Par exemple, l API CreateCase possède la signature suivante : CreateCase : INPUT: prefixcasename: twfname makesuniquename: short procedure: twfname initiator: twfname responsible: twfname priorityoverride: short alarmoverride: twfdate overdueoverride: twfdate parenttask: twfname serverparenttask: twfname OUTPUT: newcasename: twfname Paramètres de type chaîne de caractères (twfstring) Les paramètres de type twfstring sont passés simplement sous la forme nom_paramètre=valeur. La longueur maximale des chaînes est limitée à 2000 caractères par le serveur de workflow. Si la chaîne contient des espaces, des caractères accentués ou des codes de contrôle, il est préférable de passer le paramètre dans un champ (éventuellement caché) de formulaire, en utilisant la méthode POST. Il est ainsi possible de transmettre la chaîne de caractères telle quelle au programme CGI, sans encodage spécial. Si la chaîne doit être transmise sur la ligne de commande, les caractères spéciaux doivent être encodés suivant les règles du langage HTML (par exemple, "é" = &eacute). Cette méthode de transmission est obligatoire lorsqu on veut appeler une API par un lien hypertexte ou comme adresse d un cadre (frame). Paramètres de type entier (short, long ou twfid) Les paramètres de type entier sont passés sous la forme nom_paramètre=valeur. La valeur doit pouvoir être convertie en entier signé (short, long) ou non signé (twfid). Le programme CGI vérifiera les valeurs limites de l attribut. Ces paramètres correspondent parfois à des types énumérés ou à des constantes (valeur booléenne, état d une tâche, nom de critère, type d une variable, etc.). Par exemple, le paramètre makesuniquename de l API CreateCase peut prendre la valeur WF_GENERATE_UNIQUE_NAME (équivalent à WF_TRUE ou 1) ou WF_DO_NOT_GENERATE_UNIQUE_NAME (équivalent à WF_FALSE ou 0). Pour éviter de mémoriser la valeur des constantes, vous pouvez utiliser le nom symbolique WF_GENERATE_UNIQUE_NAME ou WF_TRUE à la place de la valeur 1. W4 BPM Suite NOTE TECHNIQUE 54

55 Exemple " Ces noms symboliques ne sont applicables qu aux paramètres de type entier. Paramètres de type structure (twfname, twfdate, twftask, etc.) Les paramètres des API W4 Engine sont typés et représentent souvent des structures (voire des tableaux de structures), tandis que les données passées par le navigateur sont toutes de type chaîne de caractères. Un paramètre de type structure est transmis élément par élément. Par exemple, le type du paramètre initiator de l API CreateCase est twfname, c est-à-dire une structure à 2 champs : id est un entier représentant l identificateur interne de l objet ; str est une chaîne de caractères représentant le nom externe de l objet. Pour renseigner le paramètre initiator de l API, le programme CGI cgi.exe recherchera, dans la liste établie à l étape de récupération des données, les associations initiator.id=value et initiator.str=value. L absence d un champ est interprétée comme une valeur nulle pour ce champ. L absence de tous les champs d un paramètre est interprétée comme une valeur nulle pour le paramètre. En outre, le programme CGI cgi.exe vérifie la cohérence de la valeur value par rapport au type du champ du paramètre de l API. Par exemple, une date sera entrée comme suit : alarmoverride.year=1997&alarmoverride.month=03&alarmoverride.day=31&alarmoverri de.hour=6 Les champs omis prendront la valeur 0. Si tous les champs sont absents (ce n est pas le cas ici), le paramètre de type date prend la valeur nulle. Paramètres de type tableau de scalaires (twftid, twftname) Lorsqu une API accepte un tableau de scalaires en entrée (actuellement, seuls des tableaux d identificateurs de workflow sont utilisés), les valeurs successives du paramètre sont introduites une à une, sous la forme nom_paramètre=valeur&nom_paramètre=valeur& Par exemple, l API CancelTtask, qui annule une liste de tâches, pourra être appelée comme suit : 55 NOTE TECHNIQUE Appel d une API à l intérieur d un prototype de page

56 Ce mécanisme fonctionne avec des champs de formulaires de même nom Nom_paramètre, ou avec les menus déroulants à sélection multiple. Par exemple, l interface de coordination de W4 Engine offre un système de cases à cocher permettant d annuler ou de réassigner en une fois une liste de tâches. Chaque case correspond à une entrée du paramètre taskid, la valeur associée étant celle de la tâche correspondante : <input type="checkbox" name="taskid" value="@item.name.id"> La liste des tâches pouvant être annulées ou réassignées est définie par un prototype de page utilisant la technique des boucles (l itération étant effectuée sur le résultat d une API de recherche de tâches). Certaines API prennent, en entrée, un paramètre de type tableau de structures twfname : Si vous voulez passer à l API uniquement les valeurs successives des champs id (identificateurs de workflow) de ces objets de type twfname, le mécanisme décrit cidessus peut être utilisé. Les valeurs du paramètre sont introduites une à une, sous la forme nom_paramètre.id=valeur&nom_paramètre.id=valeur& Si vous voulez transmettre à l API les valeurs successives des champs str (nom) du paramètre, il faut employer la technique décrite ci-dessous. Paramètres de type tableau de structures (twftname, twftselection, etc.) Les paramètres de type tableau (ou liste) de structures doivent être passés élément par élément, chacun étant référencé par le nom du paramètre suivi d un numéro d ordre et de la qualification du champ. Par exemple, l API de recherche SearchTask admet, comme paramètre d entrée, un tableau de sélections de type twfselection nommé selectionvalues. Le type twfselection est décrit par les champs suivants : twfselection : criterion : short op : short selectionvalue : twfdata selectionid : long Une liste de sélection contenant deux éléments peut être décrite manuellement comme suit : W4 BPM Suite NOTE TECHNIQUE 56

57 selectionvalues1.criterion=wf_crit_procedure &selectionvalues1.op=wf_equal &selectionvalues1.selectionvalue.type=wf_union_data_integer &selectionvalues1.selectionvalue.value=10 &selectionvalues2.criterion=wf_crit_state &selectionvalues2.op=wf_equal &selectionvalues2.selectionvalue.type=wf_union_data_integer &selectionvalues2.selectionvalue.value=wf_done Les numéros d ordre sont des entiers positifs ou nuls ; ils peuvent comporter des «trous» (par exemple, selectionvalues0 et selectionvalues2 existent, mais pas selectionvalues1). Si, pour un numéro donné, certains champs ne sont pas renseignés, une valeur nulle leur est assignée. Celle-ci correspond au type du champ (0 pour un entier, une chaîne vide pour une chaîne de caractères). L ordre dans lequel les différents champs sont transmis n a pas d importance. Ce mécanisme est assez lourd, mais il présente l intérêt d être homogène et systématique. En outre, il pourra servir à générer automatiquement des prototypes de page. Pour le cas des listes de sélection, W4 Engine a défini un langage abrégé permettant de définir plus rapidement les appels aux API de recherche. Passages successifs de paramètres entre API Grâce au mécanisme de pré-commandes, W4 Engine permet d exécuter consécutivement plusieurs API de workflow dans un seul appel au programme CGI cgi.exe. En général, le résultat (ou un champ du résultat) de la première API est transmis en paramètre à l une des API suivantes. Pour ce faire, on utilisera le mot Exemple : vous voulez lancer successivement l API de création d un dossier de workflow et l API d exécution de la première tâche de ce dossier. NewCaseWithInitiator permet de créer un tel dossier et renvoie une tâche à exécuter par l initiateur de celui-ci. /W4/cgi.exe?@ctx&precmd1=NewCaseWithInitiator&initiator.id=@ID& Le résultat de cette API (notamment l identificateur de la tâche renvoyée) doit être transmis à l API ProcessTask via le paramètre taskname. Ce résultat est un objet de type twftask, dont l identificateur correspond au champ name.id. Pour transmettre cette valeur au paramètre taskname de l API ProcessTask, spécifiez [email protected]. /W4/cgi.exe?@ctx&precmd1=NewCaseWithInitiator&initiator.id=@ID&cmd=ProcessTask& [email protected]& 57 NOTE TECHNIQUE Appel d une API à l intérieur d un prototype de page

58 Conflits de noms de paramètre entre des API successives Il peut arriver que plusieurs API successives aient un paramètre portant le même nom. C est notamment le cas lorsqu on désire lancer deux fois la même API 5 dans un seul appel d un programme CGI. Les paramètres des pré-commandes et de la commande principale étant fournis dans un ordre aléatoire, il est nécessaire de cacher les paramètres conflictuels des API subséquentes pendant l exécution des API initiales, et inversement. Pour gérer la visibilité de ces paramètres, on utilisera à nouveau le mot mais comme préfixe du nom des paramètres conflictuels. Ainsi, la ne rendra visible la valeur du paramètre qu après l exécution de la pré-commande PRECMDxx. Exemple /W4/cgi.exe?@ctx&precmd1=createCase&procedure.str=work&initiator.id=@id&..&cmd= createcase&@precmd1.procedure.str=bigbrother&@precmd1.initiator.id=bigbrotherid & A l issue de l exécution de la première API createcase (concernant l utilisateur courant et la procédure WORK), les paramètres procedure.str et initiator.id sont remplacés par la procédure BIGBROTHER et l initiateur BIGBROTHERID, en vue de l exécution de la seconde API createcase. Il est tout à fait possible de combiner les deux modes d utilisation Cela signifie que le paramètre nom_paramètre.qualification deviendra visible après l exécution de la pré-commande precmdxx, et que sa valeur ne sera attribuée qu à l issue de la pré-commande precmdyy. 5.6 Paramètres libres En plus des paramètres liés à l exécution des API et déterminés par la signature de celles-ci, il est possible de passer des paramètres libres, de type chaîne de caractères. Ils sont transmis au programme CGI sous la forme nom_paramètre_libre=valeur. Ces paramètres ne sont pas utilisés lors de l exécution des API, mais lors de la génération de la page HTML de réponse. Il existe aussi des paramètres libres prédéfinis, tels que template (prototype de page résultat), error (prototype de page d erreur) et le contexte de retour contextbackup. 5 Une utilisation intéressante concerne la création simultanée d une tâche de supervision et d une tâche «normale». W4 BPM Suite NOTE TECHNIQUE 58

59 5.7 Prototype de page subséquent Si aucune des API lancées ne renvoie de code d erreur, la suite du dialogue entre W4 Engine et l utilisateur est déterminée par la valeur du paramètre contextbackup ou template. Utilisation de contextbackup S il est défini, contextbackup est prioritaire sur template. Il indique au programme CGI cgi.exe de restaurer un contexte précédemment sauvegardé à l aide du mot (qui mémorise la commande en cours et tous les paramètres d appel). Ce contexte sauvegardé est transmis d écran en écran par le biais d un paramètre libre (nous utilisons habituellement savecontext, mais tout autre nom convient), jusqu à son affectation à contextbackup. Le traitement s effectue comme suit : 1 Lorsque contextbackup est instancié, le programme CGI réexécute la commande incluse dans le contexte sauvegardé. En revanche, les pré-commandes correspondantes sont ignorées. 2 Ainsi, l utilisateur voit s afficher un écran auquel il est possible de revenir après avoir lancé l une des actions qu il propose (il peut s agir de l exécution d une série d API et, éventuellement, de la présentation de plusieurs pages de dialogue intermédiaires). Exemples classiques : un écran d accueil contenant une liste de tâches à effectuer, ou un écran d exécution de tâche contenant un bouton pour ajouter un commentaire libre ou une pièce jointe. 3 Cet écran initial a été généré à partir d un prototype de page, et contient un certain nombre d hyperliens ou de boutons de commande associés à des formulaires. Il est important, dans ce prototype, de transmettre à chacune des API associées aux hyperliens ou aux formulaires un paramètre libre sauvegardant le contexte. Exemple : savecontext=@self (bien doit avoir été instancié au préalable dans l écran). 4 L activation d un hyperlien déclenchera l API correspondante et présentera à l utilisateur un écran de résultat. Ce dernier sera probablement généré à partir d un prototype de page déterminé par le paramètre template (voir ci-après) transmis à l API. 5 En général, l écran de résultat contient lui-même un certain nombre de liens et de boutons spécifiant la suite du dialogue et activant des API. Si certains de ces hyperliens proposent des écrans de continuation du dialogue, il faut veiller à propager le contexte sauvegardé en utilisant un paramètre libre (on peut garder le même, c est-à-dire passer systématiquement savecontext=@savecontext). 6 D autres liens activeront une dernière API, puis stopperont le dialogue et permettront de revenir à l écran initial : c est ici qu on utilisera vraiment les données de contexte, à l aide de contextbackup=@savecontext. Utilisation de template Si contextbackup n est pas instancié, c est le paramètre template qui détermine la suite du dialogue. Le programme CGI cgi.exe utilise alors la valeur du paramètre et la langue de l utilisateur pour rechercher un fichier HTML contenant le prototype de page : 59 NOTE TECHNIQUE Appel d une API à l intérieur d un prototype de page

60 1 Si un fichier correspondant à la langue de l utilisateur et au prototype est trouvé, cgi.exe s en sert pour présenter la réponse. 2 Si le fichier n existe pas, cgi.exe recherche un prototype multilingue ou dans une langue "hiérarchiquement" au-dessus de celle de l utilisateur. 3 Si aucun fichier n est trouvé, le prototype standard est utilisé. Remarques sur les fichiers de prototype Les prototypes de page sont répartis dans deux répertoires situés sous le répertoire d installation de W4 Engine : Les prototypes relatifs à l exécution d une tâche (API ProcessTask) sont dans Activities. Ils sont directement liés aux activités associées aux nœuds des procédures. Bien que le répertoire Activities puisse être hiérarchisé, cette opération est déconseillée. Pour identifier le nom du prototype relatif à une activité, il est préférable d utiliser le nom de l activité, éventuellement suivi de la langue, avec le suffixe HTML. Ainsi, le prototype correspondant à l exécution d une tâche sera spécifié systématiquement par [email protected]. Tous les autres prototypes sont dans Templates. Ce répertoire peut être hiérarchisé, et il est recommandé de l organiser par projet. Le nom d un prototype sera passé sous la forme template=projet/sous-projet/nom_prototype. Evitez d employer des espaces et des caractères accentués dans les noms de prototype, d activité ou de projet. Sinon, vous devrez systématiquement les encoder pour pouvoir les passer sur la ligne de commande. Les prototypes de page peuvent être fournis en plusieurs langues. Pour ce faire, W4 Engine propose deux méthodes : Vous pouvez créer plusieurs fichiers HTML distingués par un code de langue de deux caractères. Par exemple, le prototype accueil pourra être fourni en français, en anglais et en portugais. Les fichiers correspondants seront alors accueil.fr.html, accueil.en.html et accueil.pt.html. Il est généralement plus astucieux d utiliser les mécanismes de dictionnaire de W4 Engine. Il suffit alors de fournir un fichier accueil.html unique intégrant des dictionnaires de traduction. Cependant, si vous utilisez des dictionnaires partagés (situés sur le serveur), vous devrez peut-être pré-compiler les différentes langues. En effet, dans ce cas, la traduction s effectue par appel d une API W4 Engine pour chaque terme à traduire, ce qui dégrade les performances. 5.8 Prototype de page de traitement d erreur Lorsque l une des API lancées renvoie un code d erreur, les paramètres template et contextbackup sont ignorés, et l écran de réponse est généré à partir d un prototype de page défini par le paramètre error. Les prototypes de page relatifs aux erreurs sont placés dans le répertoire Templates. Les règles définies pour le paramètre template s appliquent également à error. Cependant, si aucun prototype n est spécifié ou si le fichier indiqué est introuvable, le prototype utilisé par défaut est standarderror.html : il affiche le code d erreur sur un fond rouge, puis renvoie à un écran de navigation au bout de quelques secondes. W4 BPM Suite NOTE TECHNIQUE 60

61 6 Cas particuliers : facilités d écriture L ensemble des mécanismes décrits jusqu ici offre une grande homogénéité et garantit une couverture complète des API W4 Engine en HTML. Cette homogénéité présente toutefois une certaine lourdeur, et des raccourcis d écriture ont été introduits pour simplifier le développement de pages HTML : ils concernent certains comportements par défaut, ainsi que le développement d API spéciales pour HTML. 6.1 Comportements par défaut Type twfname twfname est le type le plus fréquemment utilisé dans les API W4 Engine. Il s agit d une structure à deux champs : id contient l identificateur de workflow de l objet ; str contient le nom de l objet. Par défaut, lors d une substitution ou d un passage de paramètre, toute référence à un objet non qualifié est interprétée comme un accès au champ str de cet objet. Par est interprété Le même mécanisme est appliqué aux paramètres de type twfname d une API quelconque. Ainsi, nom_paramètre=value est interprété comme nom_paramètre.str=value. Qualification d un objet multivaleur L accès aux données d un objet multivaleur s effectue, normalement, par le biais d une @/LOOP Une qualification directe telle est interprétée comme une référence à l information champ du premier élément de cet objet. 61 NOTE TECHNIQUE Cas particuliers : facilités d écriture

62 6.2 API HTML spécifiques Il existe quatre API développées spécialement pour HTML : Parse, ExitTask, RegisterFile et GenerateForm. Cette section décrit leur action et tous leurs paramètres (en entrée et en sortie), puis donne un exemple d emploi. Chaque paramètre est suivi de son type (entre parenthèses) et d un descriptif. Pour des informations sur les autres API W4 Engine, consultez le Manuel de référence des API. Parse Paramètres d entrée Aucun. Paramètres de sortie Aucun. Action Cette API ne déclenche aucune action de workflow ; elle se contente de présenter la page HTML correspondant au prototype défini par le paramètre template. Exemple d utilisation Parse est très utile pour afficher des écrans d accueil auto-consistants, c est-à-dire des écrans qui contiennent les scripts de sélection des objets à présenter. Elle est aussi très utilisée pour introduire les cadres (frames). ExitTask Paramètres d entrée taskname (twfname) : identificateur de la tâche. Ici, seul le champ id est significatif. command (twfstring) : nom de la commande de sortie de tâche. Valeurs admises : EndTask, EndTaskGetNext, OnHoldTask, PushTaskBack, CreateEventWaitFor, WaitForEvent, CancelTask. nom des variables de sortie de l activité associée à la tâche. Non applicable à CancelTask et à PushTaskBack. outvalue (twfname) : valeur de sortie. Uniquement pour les commandes EndTask et EndTaskGetNext. event (twfevent) : nom d événement. Uniquement pour les commandes CreateEventWaitFor et WaitForEvent. W4 BPM Suite NOTE TECHNIQUE 62

63 Paramètres de sortie Aucun. Action Cette méta-api sert à contrôler la sortie d un écran d exécution de tâche. Elle présente de nombreux intérêts par rapport aux API qu elle émule (EndTask, EndTaskGetNext, OnHoldTask, PushTaskBack, CreateEventWaitFor, WaitForEvent, CancelTask) : 1 Il devient très simple de placer dans le même formulaire plusieurs boutons de commande correspondant aux différentes actions (Terminer, Terminer et passer à la tâche suivante, Suspendre, Rejeter, Se mettre en attente d un événement). Il suffit de définir le paramètre command en fonction du bouton sélectionné. 2 Les valeurs des variables de sortie de l activité (WF_INOUT et WF_OUT) sont directement obtenues sous la forme nom_variable=value. Elles sont transmises à l API principale comme un tableau de structures de type twftrawvariable, extrêmement fastidieux à construire en HTML. 3 Le type et la cardinalité des variables sont vérifiés. Les variables multivaleurs sont passées de la même manière que les paramètres multivaleurs scalaires (ceci est valable pour les types entier, chaîne de caractères et document) : nom_variable=value1&nom_variable=value2&nom_variable=value3& Les variables multivaleurs de type twfdate doivent être passées comme des paramètres multivaleurs de type structuré : nom_variable1.day=value1&nom_variable2.day=value2& nom_variable1.month=value3&nom_variable2.month=value4& La sémantique d ExitTask est celle de l API correspondant au paramètre command. Exemple d utilisation W4 Engine propose la génération automatique de prototypes de page à partir de la définition d une activité ; cette génération automatique repose totalement sur ExitTask. RegisterFile Paramètres d entrée (seul registeredfile est obligatoire) maxsize (long) : taille maximale, en octets, du fichier à envoyer. Doit apparaître avant le paramètre registeredfile dans le formulaire. contenttype (twfstring) : type du fichier à envoyer. Il s agit d une chaîne de caractères définissant un type de contenu au format MIME (par exemple, "text/html", "image/gif", etc.). Doit apparaître avant le paramètre registeredfile dans le formulaire. 63 NOTE TECHNIQUE Cas particuliers : facilités d écriture

64 registeredfile (file) : nom du fichier local dont le contenu est passé en format MIME dans le formulaire. docid (twfid) : identificateur du document de workflow dont la référence et le contenu doivent être changés. Remarque : le fichier transmis ne sera enregistré avec cet identificateur que si l utilisateur courant est le créateur du document initial ou détient les droits d administrateur. access (twfstring) : permet de définir le répertoire du serveur dans lequel sera stocké le fichier. Valeurs admises : Private, Protected, Public, Templates, Activities. Valeur par défaut : Private. location (twfstring) : permet de définir le sous-répertoire du serveur dans lequel sera stocké le fichier. Ignoré si l accès est Private. Valeur par défaut : chaîne vide. filename (twfstring) : permet de définir le nom du fichier cible. Ignoré si l accès est Private. Valeur par défaut : création d un nom unique. filesuffix (twfstring) : permet de définir le suffixe du fichier cible. Ignoré si l accès est Private. Pas de valeur par défaut. name (twfstring) : attribut name de l objet de workflow (de type twfdocument) créé sur le serveur W4 Engine à partir du fichier transmis. docclass (twfstring) : attribut docclass de l objet de workflow (de type twfdocument) créé. Paramètres de sortie docid (WFunion_data_document) : identificateur de l objet de workflow créé ou renvoyé. Action L objectif premier de cette API est la transmission d un document depuis le navigateur Web vers le serveur de workflow. Le formulaire dans lequel apparaît une telle API doit utiliser l encodage MIME multipart/formdata ; il doit également comporter une entrée de type file, qui permettra de choisir un fichier dans une boîte de sélection et d envoyer son contenu via l un des champs du formulaire. Les paramètres maxsize et contenttype peuvent servir à contrôler la taille maximale du fichier et son type. Lors de la transmission, contenttype sera comparé avec l attribut MIME Content-Type, qui est renseigné par le navigateur en fonction de la nature du fichier choisi. Dans la requête envoyée par le navigateur au serveur de workflow, ces deux paramètres doivent apparaître avant le contenu du fichier, pour pouvoir servir de "filtre" avant l extraction de ce contenu. Par conséquent, toute référence à maxsize et à contenttype doit précéder la commande HTML type=file. (Plus simplement, ces paramètres doivent figurer dans la ligne de commande, qui est décodée avant le formulaire.) Si docid n est pas défini, la commande RegisterFile crée sur le serveur W4 Engine un nouvel objet de workflow de type twfdocument (elle appelle alors l API W4 Engine CreateDoc, qui génère un document vide). Dans le cas contraire, elle remplace le contenu de l objet initial par celui du fichier transmis. En sortie, l API renvoie l identificateur de l objet créé ou modifié. RegisterFile appelle également l API RegisterDoc, qui permet d associer une URL à un document ou de la modifier. W4 BPM Suite NOTE TECHNIQUE 64

65 Exemple d utilisation Envoi d un fichier situé sur le disque local de l utilisateur ; sa taille maximale est octets et son type est image/gif. <form enctype="multipart/form-data" method="post" name="attach" target="_self" action="/w4/cgi.exe?@ctx&cmd=registerfile&contenttype=image/gif&maxsize=20000&d occlass=gif&[email protected]" > <input type=file size=35 name="registeredfile" value="0"> <input type=submit value="attacher le fichier" </form> Le nom du document de workflow sera le nom de l acteur qui lance la commande. La classe sera GIF. Le fichier fourni par l utilisateur sera stocké dans le répertoire Private du serveur W4 Engine. Remarque sur le stockage du fichier sur le serveur W4 Engine Si le champ access contient la valeur Private, le document est créé dans le répertoire W4Private du serveur. Un nom unique est généré, sauf si un identificateur docid est fourni en entrée. Si le champ access contient une autre valeur, le document est créé dans le répertoire correspondant (c est-à-dire W4Protected, W4Public, W4Templates ou W4Activities), conformément aux règles suivantes : Si location est défini et que le sous-répertoire spécifié n existe pas, ce dernier est créé. Si filename est défini, le contenu du fichier est copié sous /access/location/filename. Dans le cas contraire, l API génère un nom de fichier unique avant d effectuer le transfert. Si filesuffix est défini, le contenu du fichier est copié sous /access/location/filename.filesuffix. Si /access/location/filename correspond à un fichier existant et que docid n est pas défini, la copie échoue. Si docid est défini mais correspond à un autre fichier, la copie échoue également. Si ni filename ni docid ne sont définis, la création et la copie échouent. Si seul filename n est pas défini, le contenu du fichier transmis remplace celui du document existant. GenerateForm Paramètres d entrée (seul formtemplate est obligatoire) formtemplate (twfstring) : nom du prototype à partir duquel le document est généré. Ce prototype doit être situé dans le répertoire W4Templates du serveur W4 Engine. access (twfstring) : permet de définir le répertoire du serveur dans lequel sera stocké le fichier contenant le formulaire. Valeurs admises : Private, Protected, Public. Valeur par défaut : Private. docid (twfid) : identificateur du document de workflow dont la référence et le contenu doivent être changés. Remarque : le fichier transmis ne sera enregistré avec cet identificateur que si l utilisateur courant est le créateur du document initial ou détient les droits d administrateur. 65 NOTE TECHNIQUE Cas particuliers : facilités d écriture

66 location (twfstring) : permet de localiser le sous-répertoire du serveur dans lequel sera stocké le fichier contenant le formulaire. Ignoré si l accès est Private. Valeur par défaut : chaîne vide. filename (twfstring) : permet de définir le nom du fichier cible. Ignoré si l accès est Private. Valeur par défaut : création d un nom unique. filesuffix (twfstring) : permet de définir le suffixe du fichier cible. Ignoré si l accès est Private. Pas de valeur par défaut. formname (twfstring) : attribut name de l objet de workflow (de type twfdocument) créé sur le serveur W4 Engine à partir du fichier généré. docclass (twfstring) : attribut docclass de l objet de workflow (de type twfdocument) créé. Paramètres de sortie docid (WFunion_data_document) : identificateur de l objet de workflow créé. Action GenerateForm permet de générer un fichier de type quelconque (HTML ou autre) à partir d un prototype de page déterminé par le paramètre formtemplate. Les règles définies pour le paramètre template s appliquent également à formtemplate. L intérêt d une telle API est de transformer un ensemble de variables de dossier en un document unique qui sera rattaché à une autre variable du dossier. Par exemple, l ensemble des variables décrivant un client sera transformé en une fiche client. Les documents ainsi créés peuvent avoir une visibilité publique ou privée. Ils sont aisément transportables d un dossier à un autre et peuvent faire l objet d un classement particulier. Exemples d utilisation Génération d un fichier basé sur le prototype SQLFORM, à partir des informations du dossier courant. L adresse URL du nouveau document est /W4Public/Clients/nom_du_dossier.sql. Le répertoire Clients sera créé s il n existe pas. Action="/W4/cgi.exe?@CTX&cmd=GenerateForm&formTemplate=sqlForm&access=Public&lo cation=clients&[email protected]&filesuffix=sql&docclass=sql" Remplacement du fichier généré ci-dessus par une nouvelle version : Action="/W4/cgi.exe?@CTX&cmd=GenerateForm&docId=Id_document_précédent&formTempl ate=sqlform&access=public&location=clients&[email protected]&filesuffix=sql&d occlass=sql" W4 BPM Suite NOTE TECHNIQUE 66

67 Note technique W4 Engine Pour toute remarque ou suggestion concernant ce document, vous pouvez contacter le support technique W4, en précisant la référence W4TN_W4_LANGUAGE_010_FR : par le service de traitement des dossiers Supportflow sur MyW4.com, à l adresse suivante : par courrier électronique : [email protected] par téléphone : 33 (0)