W4 EXTENSION BUS TUTORIEL - DEVELOPPEMENT DE CONNECTEURS Référence: W4XT_TUTORIAL_020_FR Les prochaines mises à jour de ce document seront disponibles sur www.myw4.com
W4 EXTENSION BUS TUTORIEL - DEVELOPPEMENT DE CONNECTEURS Référence: W4XT_TUTORIAL_020_FR
2008-2010 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.
Sommaire Présentation 6 Objectif du document 6 Préparation de l environnement de développement 7 Configuration logicielle 7 Positionnement des variables d environnement 7 Répertoire de travail 7 Ressources utiles 7 Exemple 1 8 Développement du connecteur 8 Compilation 9 Création et déploiement de l archive 9 Vérification du déploiement 9 Fichier de description du connecteur 10 Test du connecteur 11 Exemple 2 12 Développement du connecteur 12 Compilation 13 Création et déploiement de l archive 13 Vérification du déploiement 14 W4 Extension Bus Tutoriel - Développement de connecteurs 4
Fichier de description du connecteur 14 Test du connecteur 14 Exemple 3 16 Développement du connecteur 16 Compilation 17 Création et déploiement de l archive 17 Vérification du déploiement 18 Fichier de description du connecteur 18 Test du connecteur 18 5 Sommaire
Chapitre 1 1 Présentation Ce chapitre présente les connecteurs que ce tutoriel vous propose de développer et les conditions préalables que vous devez observer avant de débuter le développement. 1.1 Objectif du document Ce tutoriel présente le développement de connecteurs simples destinés à s exécuter sur W4 Extension Bus : un connecteur terminant une tâche un connecteur récupérant une liste de variables et modifiant une variable de tâche un connecteur récupérant une liste de variables de tâche et de dossier Ce tutoriel aborde les différentes étapes du développement des connecteurs : création du code compilation création et déploiement de l archive création du fichier XML de description du connecteur pour mise à disposition du connecteur dans Process Composer Mise en oeuvre du connecteur dans une modélisation Process Composer Test du fonctionnement du connecteur par la génération d une application sous Process Composer W4 Extension Bus Tutoriel - Développement de connecteurs 6
1.2 Préparation de l environnement de développement Cette section vous fournit des indications sur le travail de préparation nécessaire avant de débuter le développement du connecteur. 1.2.1 Configuration logicielle Vous devez disposer sur votre poste de développement des éléments suivants : W4 Engine, version 6.5 ou ultérieure W4 Extension Bus, version 6.5 ou ultérieure Process Composer, version 6.5 ou ultérieure Un JDK (Java Development Kit) de version 1.5 ou ultérieure 1.2.2 Positionnement des variables d environnement Vérifiez que la variable d environnement PATH pointe correctement vers la variable d environnement JAVA_HOME et que cette dernière référence correctement le JDK utilisé. 1.2.3 Répertoire de travail Nous vous recommandons d utiliser un environnement de travail comportant les répertoires suivants : src: répertoire de destination des fichiers sources (extension.java) lib : fichiers requis pour la compilation des connecteurs. Copiez dans ce répertoire la bibliothèque de W4 Extension Bus - extbus.jar - que vous trouverez à l emplacement suivant : <W4ExtensionBus_Home>\product\common\lib build : répertoire de destination des fichiers compilés (extension.class) dist : répertoire de destination des fichiers archives (extension.jar) 1.2.4 Ressources utiles Consultez la Javadoc de W4 Extension Bus, disponible dans la documentation de W4 Extension Bus. Consultez la Javadoc de W4 BPM API, disponible dans la documentation de W4 Engine. 7 Chapitre 1 Présentation
Chapitre 2 2 Exemple 1 Ce chapitre présente le développement d un connecteur simple destiné à s exécuter sur W4 Extension Bus et dont la fonction consiste à terminer une tâche. 2.1 Développement du connecteur Tout connecteur destiné à fonctionner sur W4 Extension Bus doit hériter de la classe W4Connector. La classe W4Connector réside dans le package eu.w4.connector. La méthode service() est obligatoire pour l implémentation de la classe W4Connector. Cette classe définit les traitements effectués par le connecteur via l objet W4Result et son énumération W4ResultAction. Cet exemple présente le développement d un connecteur très simple,. Il se limitera à implémenter la méthode service() pour terminer une tâche. A cet effet il implémentera l énumération SUBMIT de l objet W4Result. NOTE Consultez la Javadoc de W4 Extension Bus, disponible dans la documentation de W4 Extension Bus. Le code de ce connecteur est le suivant : // Import du package W4 Extension Bus import eu.w4.connector.*; // Nom et version du connecteur @W4aConnectorDescription(name="SubmitConnector", version="1.0") public class SubmitConnector extends W4Connector { // implémentation de la méthode obligatoire service() public W4Result service() throws W4ConnectorExecutionException { W4Result result = new W4Result(W4ResultAction.SUBMIT); return result; W4 Extension Bus Tutoriel - Développement de connecteurs 8
} } Sauvegardez ce code dans un fichier nommé SubmitConnector.java dans votre répertoire src. 2.2 Compilation Exécutez la commande suivante pour compiler le connecteur (à adapter en fonction de vos noms de répertoires) : javac -classpath lib\extbus.jar -sourcepath src -d build src\*.java 2.3 Création et déploiement de l archive Exécutez la commande suivante pour créer l archive du connecteur (à adapter en fonction de vos noms de répertoires et de fichiers) : jar -cf dist\submitconnector.jar -C build SubmitConnector.class Copiez l archive SubmitConnector.jar dans le répertoire suivant : <W4ExtensionBus_Home>\product\connectors\simple\connector Redémarrez W4 Engine. 2.4 Vérification du déploiement Consultez le fichier journal extbus<i>.log situé sous <W4Engine_Home>\adm\log\<instanceName>. Une notification du type Successfully loaded connector doit y être consignée : 26 févr. 2008 17:20:06 eu.w4.connector.w4cnnloader loadconnectors INFO: Successfully loaded connector 'SubmitConnector', version '1.0'. 9 Chapitre 2 Exemple 1
2.5 Fichier de description du connecteur Pour être utilisé dans la modélisation d'une procédure, tout connecteur doit être rendu disponible dans Process Composer via un fichier descriptif au format XML. Ce fichier doit avoir pour nom celui du connecteur et doit être placé sous <ProcessComposer_Home>\lib\connector. Pour plus de détails sur ce fichier, veuillez consulter le Manuel de modélisation de Process Composer. Exemple de fichier : <?xml version="1.0" encoding="utf-8"?> <CONNECTOR xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xsi:nonamespaceschemalocation="connector.xsd" version="1.0" VersionModel="1.0"> <NAME id="submitconnector"> <LABEL lang="fr">exemple simple</label> <LABEL lang="en">simple sample</label> </NAME> <CATEGORY> <LABEL lang="fr">exemples</label> <LABEL lang="en">samples</label> </CATEGORY> <DESCRIPTION> <LABEL lang="fr">exemple de connecteur simple</label> <LABEL lang="en">simple connector sample</label> </DESCRIPTION> <ICON path="lib\connector\images\submit.gif"/> <VARIABLES> </VARIABLES> <PROPERTIES> </PROPERTIES> </CONNECTOR> IMPORTANT L attribut id de la balise NAME doit correspondre à la valeur de l attribut NAME de l annotation W4aConnectorDescription. Si l annotation W4aConnectorDescription n a pas été utilisée, cette valeur doit correspondre au nom de la classe du connecteur. Process Composer utilise les infiormations du fichier de description du connecteur pour faciliter l utilisation du connecteur dans la modélisation de la procédure : Dans la fenêtre de propriétés du noeud robot, le fait de sélectionner Etape connecteur dans le champ Type spécifique permet de sélectionner le connecteur dans le champ Nom du connecteur. Si des propréiés ont été définies dans la section PROPERTIES, celles-ci apparissent dans le dossier Attributs étendus de la fenêtre de propriétés. Si une icône a été spécifiée dans l élément ICON, celle-ci remplace la représentation graphique du noeud robot sur la fenêtre de modélisation à la sélection du connecteur dans le champ Nom du connecteur. L activité correspondant à l étape connecteur est automatiquement créée dans le dossier Activités de l environnement de travail. Les variables déclarées dans la section VARIABLES sont automatiquement créées dans la fenêtre Variables d activité et la fenêtre Association de variables est pré-renseignée pour les colonnes Entrée, Variables connecteur et Sortie. NOTE Si Process Composer ne vous fournit pas ces informations, utilisez la commande Edition Chargement des connecteurs W4 Extension Bus Tutoriel - Développement de connecteurs 10
2.6 Test du connecteur Sous Process Composer, créez une procédure de test comportant un noeud d étape robot. Dans la fenêtre des propriétés de ce noeud, sélectionnez Etape connecteur dans le champ Type spécifique. Votre connecteur doit ensuite pouvoir être sélectionné dans le champ Nom du connecteur. Vérifiez la procédure puis transférez-la sur le serveur W4 Engine. Pour que la procédure soit valide, vous devez avoir : spécifié le rôle responsable de la procédure (champ Rôle Rôle responsable de la fenêtre de propriétés de la procédure) créé (à partir du dossier Activités de l environnement de travail) et affecté (champ Activité de la fenêtre de propriétés des noeuds) une activité à chaque noeud d étape spécifié le mode d assignation de chaque noeud d étape (dossier Assignation de la fenêtre de propriétés des noeuds) Transférez la procédure sur le serveur W4 Engine. Lors du transfert de la procédure, W4 Engine crée automatiquement un acteur du nom du connecteur (correspondant à l attribut id de l élément NAME dans le fichier de description du connecteur), auquel les tâches associées au connecteur seront attribuées. Afin que ces tâches soient correctement assignées à l acteur, vous devez lui attribuer le rôle extensionconnector. Générez une application fondée sur la procédure puis déployez-la sous Tomcat. 11 Chapitre 2 Exemple 1
Chapitre 3 3 Exemple 2 Ce chapitre présente le développement d un connecteur simple destiné à s exécuter sur W4 Extension Bus, récupérant une liste de variables et modifiant une variable de tâche. 3.1 Développement du connecteur Cet exemple présente le développement d un connecteur récupérant une liste de variables et modifiant une variable de tâche. NOTE Consultez la Javadoc de W4 Extension Bus, disponible dans la documentation de W4 Extension Bus, et la Javadoc de W4 BPM API, disponible dans la documentation de W4 Engine. Le code de ce connecteur est le suivant : import eu.w4.connector.*; import eu.w4.bpm.*; import eu.w4.bpm.service.*; @W4aConnectorDescription(name="ChangeTaskVarConnector") public class ChangeTaskVarConnector extends W4Connector { @Override public W4Result service() throws W4ConnectorExecutionException { BPMVariableMap outvarmap = BPMVariables.createVariableMap(); try { BPMVariableMap invarmap = getbpmtasksnapshot().getattachedtaskvariables(); String invarvalue = invarmap.get("var_stringtest").getvalue() + "_MOD"; BPMVariable outvar = BPMVariables.createVariable("Var_StringTest", BPMDataType.STRING, W4 Extension Bus Tutoriel - Développement de connecteurs 12
} invarvalue); outvarmap.put(outvar); } catch(bpmincompletesnapshotexception e) { getlogger().error(e); } return new W4Result(W4ResultAction.SUBMIT, outvarmap, null); } Sauvegardez ce code dans un fichier nommé ChangeTaskVarConnector.java dans votre répertoire src. 3.2 Compilation Exécutez la commande suivante pour compiler le connecteur (à adapter en fonction de vos noms de répertoires) : [UNIX] javac -classpath lib\extbus.jar:w4bpmapi.jar -sourcepath src -d build src\*.java [Windows] javac -classpath lib\extbus.jar;w4bpmapi.jar -sourcepath src -d build src\*.java 3.3 Création et déploiement de l archive Exécutez la commande suivante pour créer l archive du connecteur (à adapter en fonction de vos noms de répertoires et de fichiers) : jar -cf dist\changetaskvarconnector.jar -C build ChangeTaskVarConnector.class Copiez l archive ChangeTaskVarConnector.jar dans le répertoire suivant : <W4ExtensionBus_Home>\product\connectors\simple\connector Redémarrez W4 Engine. 13 Chapitre 3 Exemple 2
3.4 Vérification du déploiement Consultez le fichier journal extbus<i>.log situé sous <W4Engine_Home>\adm\log\<instanceName>. Une notification du type Successfully loaded connector doit y être consignée : 26 févr. 2008 17:20:06 eu.w4.connector.w4cnnloader loadconnectors INFO: Successfully loaded connector 'ChangeTaskVarConnector', version '1.0'. 3.5 Fichier de description du connecteur Reportez-vous au chapitre suivant : 2.5 Fichier de description du connecteur, page 10 3.6 Test du connecteur Reportez-vous au chapitre suivant : 2.6 Test du connecteur, page 11 W4 Extension Bus Tutoriel - Développement de connecteurs 14
15 Chapitre 3 Exemple 2
Chapitre 4 4 Exemple 3 Ce chapitre présente le développement d un connecteur simple destiné à s exécuter sur W4 Extension Bus, récupérant une liste de variables de tâche et de dossier. 4.1 Développement du connecteur Cet exemple présente le développement d un connecteur récupérant une liste de variables de tâche et de dossier. NOTE Consultez la Javadoc de W4 Extension Bus, disponible dans la documentation de W4 Extension Bus, et la Javadoc de W4 BPM API, disponible dans la documentation de W4 Engine. Le code de ce connecteur est le suivant : import eu.w4.connector.*; import eu.w4.bpm.*; import eu.w4.bpm.service.*; import eu.w4.bpm.search.*; @W4aConnectorDescription(name="GetTaskCaseVarConnector") public class GetTaskCaseVarConnector extends W4Connector { @Override public W4Result service() throws W4ConnectorExecutionException { BPMVariableMap outvarmap = BPMVariables.createVariableMap(); try { BPMVariableMap invarmap = getbpmtasksnapshot().getattachedworkcasevariables(); int invarvalue = (Integer)(inVarMap.get("anIntVariable").getValue()) + 1; BPMVariable outvar = W4 Extension Bus Tutoriel - Développement de connecteurs 16
BPMVariables.createVariable("Var_StringTest", BPMDataType.STRING, "" + invarvalue); outvarmap.put(outvar); } catch(bpmincompletesnapshotexception e) { getlogger().error(e); } return new W4Result(W4ResultAction.SUBMIT, outvarmap, null); } // le fait de surcharger cette méthode demande à W4 Extension Bus de fournir également les variables de dossier @Override public BPMTaskAttachment getbpmtaskattachment() throws BPMException { BPMTaskAttachment l_bpmtaskattachment = getbpmservice().gettaskservice().createtaskattachment(); l_bpmtaskattachment.attachalltaskvariables(); l_bpmtaskattachment.attachallworkcasevariables(); return l_bpmtaskattachment; } } Sauvegardez ce code dans un fichier nommé GetTaskCaseVarConnector.java dans votre répertoire src. 4.2 Compilation Exécutez la commande suivante pour compiler le connecteur (à adapter en fonction de vos noms de répertoires) : [UNIX] javac -classpath lib\extbus.jar:w4bpmapi.jar -sourcepath src -d build src\*.java [Windows] javac -classpath lib\extbus.jar;w4bpmapi.jar -sourcepath src -d build src\*.java 4.3 Création et déploiement de l archive Exécutez la commande suivante pour créer l archive du connecteur (à adapter en fonction de vos noms de répertoires et de fichiers) : jar -cf dist\gettaskcasevarconnector.jar -C build ChangeCaseVarConnector.class Copiez l archive GetTaskCaseVarConnector.jar dans le répertoire suivant : <W4ExtensionBus_Home>\product\connectors\simple\connector Redémarrez W4 Engine. 17 Chapitre 4 Exemple 3
4.4 Vérification du déploiement Consultez le fichier journal extbus<i>.log situé sous <W4Engine_Home>\adm\log\<instanceName>. Une notification du type Successfully loaded connector doit y être consignée : 26 févr. 2008 17:20:06 eu.w4.connector.w4cnnloader loadconnectors INFO: Successfully loaded connector 'GetTaskCaseVarConnector', version '1.0'. 4.5 Fichier de description du connecteur Reportez-vous au chapitre suivant : 2.5 Fichier de description du connecteur, page 10 4.6 Test du connecteur Reportez-vous au chapitre suivant : 2.6 Test du connecteur, page 11 W4 Extension Bus Tutoriel - Développement de connecteurs 18
Illustrations W4 Extension Bus Tutoriel - Développement de connecteurs 20
21 Illustrations
Index W4 Extension Bus Tutoriel - Développement de connecteurs 22
23 Index
W4 EXTENSION BUS TUTORIEL - DEVELOPPEMENT DE CONNECTEURS Référence: W4XT_TUTORIAL_020_FR Pour toute remarque ou suggestion concernant ce document, vous pouvez contacter le support technique W4, en précisant la référence du document : par le service de traitement des dossiers Supportflow sur MyW4.com, à l adresse suivante : http://support.myw4.com Par courrier électronique : support@w4global.com Par téléphone : +33 (0) 820 320 762