1. Informations Générales

Cette version de Mantis Connect à été développer en utilisant les logiciels suivant : Mantis 1.0.8, NuSoap 0.7.2, PHP 5.1.6, Apache 2.2.4 et MySql 2.9.1.1.
Le développement a été réalisé par Alexandre Laborie pour la société Axidea : http://www.axidea.fr/.

2. Installation du Webservice

Créez un répertoire nommé webservice à la base du répertoire de Mantis dans lequel vous mettez l'ensemble des fichiers de Mantis Connect. Ensuite il suffit de changer la valeur de la constante FILE_MANTIS_CONNECT se trouvant dans le fichier config_inc.php du répertoire test-unitaire. Pour s'assurer que tout fonctionne correctement, il serait bon de lancer le scénario de test pour voir si tous les tests retournent des résultats correct. Pour cela il faut que la base de donnée de Mantis soit entièrement vide, hormis les informations sur le compte administrateur. Ensuite connectez-vous à Mantis et effectuer les actions suivantes :

• Ajouter les utilisateurs suivant : dv (type : développeur), dv2 (type : développeur), rap (type : rapporteur), inv (type : invité). Ensuite indiquer dans le fichier scenario_bug.php du répertoire test-integration, les mots de passe correspondant aux utilisateurs (voir ligne 19). Tout en sachant que la 5ième entrée dans le tableau correspond à un utilisateur existant avec un mauvais mot de passe, et que la sixième entrée correspond à un nom d'utilisateur inexistant.
• Ajouter trois projets dans Mantis; le projet 1 est public et porte le nom de 'tgv', le projet 2 est prive et porte le nom de 'projet top secret', le projet 3 est public et porte le nom de 'ameli'. Ensuite dans le fichier scenario_bug.php indiquer les identifiants des projets que vous venez de créer (voir ligne 37).
• Ajouter au projet 1, les catégories suivante : 'front face' et 'back face'.
• Ajouter dv au projet 2 en tant que développeur.
• Ensuite ajouter un bug public dans un projet public. Ajouter deux fichiers attachés à ce bug. Puis créez un autre bug public mais dans un projet privé. Ajoutez un fichier à ce bug. Ensuite indiquez dans le fichier scenario_bug.php les identifiants des deux derniers bugs que vous venez d'ajouter, ainsi que l'identifiant du dernier fichier ajoutés (respectivement ligne 30 et 34).

• Le script de test doit être le seul à manipuler Mantis durant toutes son exécution.
• Tous les droits sont les droits par défaut de Mantis (hormis l'utilisateur dv qui a les droits d'un développeur sur le projet 2).

3. Evolutions depuis Mantis Connect 1.0a4

Depuis la version 1.0a4 de Mantis Connect (disponible à cette adresse: http://sourceforge.net/projects/mantisconnect/), les évolutions suivante ont été effectuer:

• Refonte de l'architecture de Mantis Connect.
• Amélioration du système de droit : modification complète du système de droit pour le rendre plus performant et fidèle aux droits de Mantis.
• Surcharge des erreurs de mantis : les contrôles d'erreur des webservices sont allégées car on surcharge le rapport d'erreur de Mantis, ce qui nous permet d'éviter de faire deux fois les contrôles d'erreurs (une fois dans Mantis et une autre fois dans Mantis Connect). Maintenant on a qu'un seul contrôle d'erreur (sauf cas exceptionnel) ce qui nous permet d'être plus performant !
• Lors de la restructuration du projet, on a prit le partie d'utiliser le moins possible les ComplexType de NuSoap et d'utiliser plutôt les types élémentaires. Maintenant quand on souhaite retourner une variable de type complexe on va faire des traitements pour la convertir en chaîne de caractères (notamment serialize() de php).
• Ajout de commentaire compatible avec PhpDocumentor pour pouvoir générer de la documentation facilement.
• Découpage du fichier mc_issue_api.php en deux fichiers, mc_bug_api.php et mc_bugnote_api.php, pour être en accord avec le découpage de fichier de Mantis.
• Ajout de webservices :
• Pour la gestion des bugs (mc_bug_api.php), en plus des anciennes fonctionnalités celles-ci on été ajoutées : mettre à jour un bug, assigner un bug, changer l'état d'un bug, déplacer un bug d'un projet à un autre, démarrer/arrêter la surveillance d'un bug, copier un bug, récupérer l'historique d'un bug, envoyer un rappel à une liste d'utilisateur, récupérer le nombre de note d'un bug, récupérer la date de la dernière mise à jour, réouverture d'un bug, teste pour savoir si un utilisateur est le rapporteur du bug, teste pour savoir si un utilisateur est assigné à un bug et test pour savoir si le bug est en lecture seul.
• Pour la gestion des notes (mc_bugnote_api.php), en plus des anciennes fonctionnalités celles-ci on été ajoutées : modifier le texte d'une note, modifier la visibilité d'une note, retourner toutes les notes visibles par un utilisateur pour un bug donné, tester l'existence d'une note et tester si un utilisateurs est le rapporteur de cette note.
• Pour la gestion des fichiers attachés (mc_file_api.php) les fonctionnalités suivante on été implémentée : tester si un bug à des fichiers attachés, tester si un utilisateurs peut voir les fichiers attachés, tester si un utilisateur à le droit de télécharger les fichiers attachés, tester si un utilisateurs à le droit de supprimer les fichiers attachés, tester si un utilisateur à le droit d'ajouter des fichiers à un bug, tester si un utilisateur à le droit d'ajouter des fichiers à un projet, supprimer un fichier, supprimer tous les fichiers rattachés à un bug, supprimer tous les fichiers rattachés à un projet et retourner le nombre de fichier attachés à un bug. Lors du développement le choix a été pris de ne pas ajouter un webservice permettant l'upload de fichier, car ce n'est pas a lui de s'occuper de ça. En effet, en effectuant des tests on se rend rapidement compte que le temps de traitement du webservice est beaucoup trop long même pour des fichiers de quelques centaines de kilo octets. Ce sera donc à l'interface utilisateur de s'occuper de cette partie.
• Pour la gestion des filtres (mc_filter_api.php), en plus des anciennes fonctionnalités celles-ci on été ajoutées : tester si un utilisateur peut supprimer un filtre donné, retourner le filtre par défaut, récupérer un filtre sauvegarder dans la base de donné, retourner le nom d'un filtre, retourner les filtres utilisables pour un utilisateur et pour un projet donné, ajouter/modifier un filtre de la base de donné et supprimer un filtre de la base de donné. Le webservice permettant de récupérer la liste des bugs après lui avoir appliqué un filtre a été amélioré, avec la possibilité d'indiquer plus d'option.
• Pour la gestion des relation (mc_relationship_api.php) les fonctionnalités suivante on été implémentée : tester l'existence d'une relation, tester si un bug peut être résolue sans risque en fonction de ses relations, ajout d'une relation, mise à jour d'une relation et suppression d'une relation.

4. Informations sur les tests

Pour le développement de cette nouvelle version de Mantis Connect, une série de test on été effectué pour s'assurer du fonctionnement du webservice. C'est test sont disponible pour permettre au utilisateur de voir comment on utilise le webservice. Les tests sont divisées en deux dossiers, test-integration et test-unitaire. Les scripts du dossier test-unitaire test uniquement un webservice précis. Si vous les utilisez n'oubliez pas de modifier les informations qui sont stockés dans le tableau $aParametres. Le script du dossier test-integration test quand à une lui une série de webservice.

5. Développement de nouvelles fonctionnalités

Voici les étapes de développements pour une nouveau webservice:

• Il faut déterminer dans qu'elle fichier vous allez travaillez. Dans Mantis Connect, on a pris le partie de suivre la même structure de fichier que celle que l'on trouve dans Mantis. C'est à dire que le fichier de Mantis Connect mc_bug_api.php fait appel à des fonctions que l'on trouve dans le fichier Mantis core/bug_api.php. Dans le cas où vous créez un nouveau fichier, il ne faut pas oublier de l'ajouter dans le fichier mc_core.php de Mantis Connect.
• Il faut déterminer le nom de la fonction. Dans Mantis Connect il y a une norme; Toutes les fontions qui commencent par mc seront directement appelable par le client. En revanche toutes les fonctions qui commencent par mci ne seront utilisables que par le serveur.
• Pour la gestion des droits utilisateurs rien de plus simple. Il faut appeller la fonction mciCheckAccess, en lui fournissant en premier paramètre un tableau contenant la liste de tous les droits que nous allons contrôler et un deuxième tableau contenant la liste des variables qui nous seront utile pour la vérifications des droits. Il ne faut rien faire de plus. Si certain droit sont violé, la fonction retournera automatiquement une erreur soap. La liste de tous les droits est accessible au début du fichier mci_access_api.php.
• Ensuite il faut écrire le contenu du webservice.
• Enfin il faut enregistrer la fonction auprès du serveur Soap. Pour cela il faut déclarer sont nouveau webservice dans le fichier mantisconnect.php. La déclaration du webservice demande d'indiquer un nom, la liste des paramètres d'entrés, le type de la valeur de retour et une description de l'action du webserice.

A. Générations de documentation avec PhpDocumentor

Pour la génération de la documentation, il faut tout d'abord télécharger PhpDocumentor. Une fois que vous avez installez PhpDocumentor et que vous êtes sur la page d'accueil, cliquez sur l'onglet Config. Sélectionnez le répertoire de Mantis Connect dans le premier champ et cliquez sur Change. Ensuite dans la liste déroulante choisissez le fichier de configuration doc_ws.ini. Cliquez sur Go. Vous avez une nouvelle documentation. Par contre il faut faire une dernière manipulation car PhpDocumentor ne prend pas en compte les fichiers Readme écrit en HTML. Ouvrez votre console, déplacez vous dans le dossier de Mantis Connect et tapez sh doc_ws_sh.

B. Liens Web

Axidea : http://www.axidea.fr/

Mantis : http://www.mantisbt.org/
Mantis Connect : http://www.futureware.biz/mantisconnect/
NuSoap : http://dietrich.ganx4.com/nusoap/

PhpDocumentor : http://www.phpdoc.org/