Configurer Xsquash4Jira dans Squash TM

Info

Cette page est dédiée à la configuration générale du plugin Xsquash4Jira. Pour la configuration des synchronisations en elles-mêmes, consulter la page Gérer les synchronisations Xsquash4Jira dans Squash TM.
Pour en savoir plus sur les fonctionnalités de Xsquash4Jira, consulter la page Synchroniser des objets agiles Jira dans Squash.

Le plugin Xsquash4Jira est un plugin Squash TM dédié à la synchronisation de tickets depuis Jira Data Center et Jira Cloud. Il s'articule autour des fonctionnalités suivantes :

• un module de synchronisation automatique qui permet à Squash TM d'importer et de maintenir automatiquement à jour :
  • des tickets Jira (Data Center et Cloud) sous forme d'exigences synchronisées dans l'espace Exigences ;
  • des sprints Jira (Data Center et Cloud) ainsi que leur contenu sous forme de sprints synchronisés dans l'espace Exécutions. Cette fonctionnalité permet de voir dans l'espace Exécutions les tickets d'un sprint à valider et d'alimenter automatiquement le plan d'exécution du sprint avec les tests associés aux tickets ;
• un module de reporting qui permet d'afficher sur les tickets Jira des informations concernant le déroulement de la recette dans Squash TM. Ces informations prennent la forme de champs personnalisés à ajouter sur les tickets Jira qui sont ensuite complétés par Squash TM ;
• un module de création de plan de test à partir des objets Jira accessible depuis l'espace Exécutions. Cet assistant permet de créer des plans de test à partir d'un filtre sur les versions livrées, les sprints ou des requêtes JQL de Jira. Tous les cas de test associés aux tickets compris dans le périmètre choisi sont proposés à l'utilisateur afin d'être ajoutés au plan d'exécution.

Une partie des fonctionnalités du plugin sont automatiques et se déclenchent seules une fois la configuration complète effectuée :

Nom	Déclenchement	Sens de circulation
Synchronisation des tickets Jira	Automatique une fois la configuration faite	De Jira vers Squash TM
Synchronisation des sprints Jira	Automatique une fois la configuration faite	De Jira vers Squash TM
Reporting des données de recette Squash TM	Automatique une fois la configuration faite	De Squash TM vers Jira
Création d'un plan de test dans Squash TM à partir d'objets Jira	Manuel depuis l'espace Exécutions de Squash TM	De Jira vers Squash TM

Attention

Lors des opérations automatiques, le plugin n'effacera jamais d'objets synchronisés dans Squash TM (exigences et sprints) ou d'objets dans Jira (tickets et sprints). Si des objets venaient à être supprimés ou déplacés dans Jira, les objets synchronisés correspondants resteront dans Squash TM et devront être supprimés manuellement par les utilisateurs de Squash TM si nécessaire.

Installation et prérequis

Info

Le plugin Xsquash4Jira est embarqué par défaut dans la distribution de Squash TM Freeware. Il est donc déjà installé sur Squash TM.
Consulter la page suivante pour en savoir plus : Les plugins de Squash TM.

Communication Squash TM/Jira

Le plugin Xsquash4Jira est un plugin reposant sur une communication bidirectionnelle entre Squash TM et Jira. Il s'agit d'une communication de serveur à serveur, passant essentiellement par l'API Rest de Jira. Pour que le plugin puisse fonctionner il faut que la communication soit possible ce qui nécessite souvent des interventions sur l'infrastructure réseau : ouverture de flux dans les firewalls, ajout de certificats dans les JVM, etc.

Si le même serveur Jira est déjà utilisé avec succès en tant que bugtracker au moyen du plugin Jira Bugtracker la communication est déjà possible.

En cas de problème, il faut effectuer un test directement sur le serveur Squash TM pour vérifier si Jira est accessible : essayer de passer une requête vers l'API Jira directement depuis le serveur hébergeant Squash TM au moyen d'un curl ou un wget. Si la requête ne passe pas, c'est un problème réseau.

Permissions du compte Jira

Pour fonctionner le plugin doit pouvoir communiquer avec Jira au travers d'un utilisateur Jira. Cet utilisateur doit avoir à minima des droits en lecture par l'API sur l'ensemble des objets à synchroniser (tickets et sprints). Si le reporting de Squash vers Jira est activé, l'utilisateur doit impérativement avoir des droits en écriture par l'API sur l'ensemble des tickets concernés.

Création du serveur Xsquash4Jira dans Squash TM

Pour utiliser le plugin Xsquash4Jira, il faut déclarer un serveur de synchronisation de type jira.xsquash dans l'espace Serveurs>Bugtrackers et serveurs de synchronisation de l'Administration Squash TM.

Dans la pop-up de création d'un nouveau serveur, renseigner le nom du serveur (nom libre), le type jira.xsquash et l'URL du Jira la plus simple possible puis cliquer sur [Ajouter]. Le plugin Xsquash4Jira est opérationnel avec Jira Data Center et Jira Cloud.

Attention

Un serveur de synchronisation Xsquash4Jira ne peut être supprimé s'il est utilisé pour réaliser des synchronisations. Il faut supprimer au préalable les synchronisations avant de pouvoir supprimer le serveur.

Identifiants utilisés pour les synchronisations

Le plugin utilise l'API Jira pour récupérer les données avec une authentification de type "Basic Authentication" avec les identifiants d'un utilisateur Jira.

Focus

Selon le mode d'hébergement de Jira, les identifiants de l'utilisateur Jira sont : couple login/mot de passe pour Jira Data Center ou adresse mail/jeton d'API pour Jira Cloud. Pour plus d'informations sur les jetons d'API, consulter la page Jeton d'API pour Jira Cloud.

En savoir plus

Pour des raisons de sécurité, les logins et mots de passe saisis pour la connexion aux outils tiers sont chiffrés dans la base de données avec une clé de chiffrement. Le plugin Xsquash4Jira possède également deux propriétés à configurer directement dans le fichier de configuration de Squash TM squash.tm.cfg.properties. Pour en savoir plus, consulter la page suivante : Gestion du fichier de configuration Squash TM.

Deux options sont possibles pour effectuer les synchronisations.

Compte technique

Cette option permet d'effectuer toutes les synchronisations avec le même compte Jira. Dans ce cas, la bonne pratique conseillée est de créer un compte technique dédié au plugin dans Jira et disposant des droits nécessaires uniquement sur les projets Jira souhaités.

Ensuite, sur la page de configuration du serveur de synchronisation, dans le bloc Politique d'authentification, il est nécessaire de renseigner les identifiants du compte technique Jira dans la partie Identifiants du compte technique.

Identifiants de l'utilisateur

Cette option permet d'effectuer les synchronisations avec des comptes Jira différents. Elle est utile lorsque les projets Jira sont cloisonnés en offrant d'avantage de contrôle sur le périmètre qui pourra être synchronisé. Dans ce cas, ce sont les identifiants du compte Jira de l'utilisateur propriétaire de la synchronisation qui sont utilisés. Il s'agit des identifiants renseignés dans le bloc Mode de configuration des bugtrackers de l'espace Mon compte. Par défaut, le propriétaire correspond à l'utilisateur qui a ajouté la synchronisation mais un autre utilisateur peut s'assigner la synchronisation par la suite.

Si cette option est choisie, sur la page de configuration du serveur de synchronisation, dans le bloc Politique d'authentification, il est nécessaire de laisser vide les champs dans la partie Identifiants du compte technique.

Configuration de Xsquash4Jira sur un projet

Les synchronisations de tickets et de sprints Jira se configurent individuellement pour chaque projet Squash TM. Cette configuration se fait au niveau de l'ancre Plugins de la page de consultation d'un projet.

Il faut commencer par activer le plugin Connecteur Xsquash4Jira pour pouvoir accéder à sa page de configuration spécifique depuis le bouton .

Pour désactiver l'utilisation du plugin sur le projet, il suffit de cliquer sur le même bouton radio que pour l'activer. L'option Conserver la configuration du plugin permet de sauvegarder durant la désactivation du plugin la configuration et les synchronisations du projet lorsqu'elle est cochée. Si l'option est décochée, la configuration et les synchronisations du projet sont définitivement supprimées à la désactivation du plugin.

La page de configuration de Xsquash4Jira est accessible en cliquant sur le bouton présent en bout de ligne du Connecteur Xsquash4Jira.

Elle se compose de cinq blocs :

• le bloc Synchronisations qui permet de configurer le périmètre des synchronisations (consulter la page détaillée Gérer les synchronisations);
• le bloc Champs de reporting Squash vers Jira qui permet de configurer le reporting de l'avancement de la recette sur les tickets Jira ;
• le bloc Équivalences entre les champs qui permet de configurer les équivalences entre les champs Jira et les champs Squash TM ;
• le bloc Équivalences entre les valeurs des champs qui permet de configurer les équivalences de valeurs pour les champs de type liste : Criticité, Catégorie et Statut ;
• le bloc Équivalences des liens entre exigences qui permet de configurer les équivalences des liens entre tickets Jira en liens entre exigences dans Squash TM.

Configurer le reporting de Squash vers Jira

Le plugin Xsquash4Jira est capable de remonter vers Jira des informations relatives à la recette réalisée dans Squash TM. Ces informations sont reportées directement au niveau des tickets Jira dans des champs personnalisés configurés à cet effet.

Sept informations sont disponibles : trois taux d'avancement de la recette (Rédaction des cas de test, Vérification des tickets Jira, Validation des tickets Jira), trois ratios reprenant ces taux d'avancement ainsi que le nombre de tests concernés, et enfin un champ qui présente une analyse synthétique de ces trois taux : le champ Statut de la recette.

Ce reporting est optionnel. Il est possible de configurer le plugin de sorte à ne rien récupérer dans Jira ou ne récupérer qu'une partie de ces informations.

Focus

Les champs Taux et Ratios contiennent des informations similaires. Il est donc inutile de tous les synchroniser et plus intéressant de faire un choix entre les taux et les ratios.
La différence se fait sur la forme. Les champs Taux renvoient un nombre simple compris entre 0 et 100.
Les champs Ratio reprennent dans une chaîne de caractères le nombre remonté dans le taux avec le symbole % suivi du nombre de tests concernés (X/Y tests).

Création des champs de reporting dans Jira

Le reporting dans Jira s'effectue au moyen de champs personnalisés à rajouter directement dans les tickets Jira concernés par la synchronisation :

Information de recette	Champs personnalisés à créer côté Jira
Taux d'avancement (Rédaction, Vérification, Validation)	Dans Jira, il faut créer un champ personnalisé de type numérique pour chacun des trois taux proposés par le plugin que l'on souhaite récupérer dans Jira. Le nom est libre.
Ratios d'avancement (Rédaction, Vérification, Validation)	Dans Jira, il faut créer un champ personnalisé de type texte (mono-ligne) pour chacun des trois ratios proposés par le plugin que l'on souhaite récupérer dans Jira. Le nom est libre.
Statut de la recette	Dans Jira, il faut créer un champ personnalisé de type texte (mono-ligne) pour le champ "Statut de la recette". Le type de moteur de rendu pour le champ doit être "Générateur de rendu de style Wiki" pour permettre d'afficher les icônes. Le nom est libre.

Les champs personnalisés Jira créés doivent ensuite :

• être affectés à tous les types de tickets qui sont susceptibles d'être synchronisés dans Squash TM ;
• être accessibles dans les écrans de modification des types de tickets et des projets concernés ;
• être modifiables par l'utilisateur technique déclaré dans Squash TM.

Le nom des champs déclaré dans Jira est libre. Attention néanmoins à ce que tous les tickets Jira concernés par les synchronisations d'un même projet Squash aient les mêmes champs puisque que dans Squash TM la configuration se fait au niveau du projet.

Ces champs sont ensuite alimentés par Squash TM en fonction de l'avancement de la recette et remontés dans Jira à chaque cycle de mise à jour si nécessaire.

Configuration des champs de reporting dans Squash TM

Dans Squash TM, la configuration du reporting s'effectue dans le second bloc de l'écran de configuration du plugin Xsquash4Jira : Champs de reporting Squash vers Jira. Pour les configurer, il faut renseigner en face des données que l'utilisateur souhaite récupérer, les noms des champs personnalisés correspondants créés dans Jira en respectant bien la casse.
Une fois la configuration du bloc terminée, il ne faut pas oublier de bien forcer la synchronisation pour que la modification soit prise en compte.
Si l'utilisateur ne désire aucun reporting dans Jira, il suffit de laisser les champs du bloc vides.

Taux de Rédaction :

Ce taux permet de suivre l'avancement de la rédaction des cas de test. Pour une exigence synchronisée donnée ce taux est égal à :
Nombre de cas de test couvrant l'exigence ou l'une de ses descendantes et au statut "À Valider" ou "Validé" / Nombre de cas de test couvrant l'exigence ou l'une de ses descendantes quel que soit le statut.
Si une exigence n'est pas couverte, le taux vaut 0.

Ratio de Rédaction :

Ce champ reprend la valeur du taux de rédaction suivi du nombre de cas de tests concernés (X/Y cas de test).

Taux de Vérification :

Ce taux permet de suivre l'avancement de l'exécution des cas de test liés à une exigence ou à l'une de ses filles. Pour une exigence synchronisée donnée ce taux est égal à :
Nombre d'items de plan d'exécution liés à un CT couvrant l'exigence synchronisée ou l'une de ses descendantes ayant un statut d'exécution final ("Bloqué", "Échec", "Non testable", "Succès", "Arbitré"), en ne tenant compte que de la dernière exécution (ou du dernier fastpass) / Nombre d'items liés à des cas de test couvrant l'exigence synchronisée ou l'une de ses descendantes.

Ratio de Vérification :

Ce champ reprend la valeur du taux de vérification suivi du nombre de cas de tests concernés (X/Y cas de test).

Taux de Validation :

Ce taux permet de suivre la validation d'une exigence. Pour une exigence synchronisée donnée ce taux est égal à :
Nombre d'items de plan d'exécution liés à un CT couvrant l'exigence synchronisée ou l'une de ses descendantes ayant un statut d'exécution validé ("Succès" ou "Arbitré"), en ne tenant compte que de la dernière exécution (ou du dernier fastpass) / Nombre d'items liés à un CT couvrant l'exigence synchronisée ou l'une de ses descendantes ayant un statut d'exécution final, en ne tenant compte que de la dernière exécution (ou du dernier fastpass).

Ratio de Validation :

Ce champ reprend la valeur du taux de validation suivi du nombre de cas de tests concernés (X/Y cas de test).

Statut de la recette :

Il s'agit d'un champ synthétique qui présente un résumé des différents états de recette possibles pour une exigence donnée.
Le mode de calcul est le suivant :

Taux de Rédaction	Taux de Vérification	Taux de Validation	Statut de la Recette
0	0	0	Non initialisé
0 < Taux de Rédaction < 100	0	0	Conception en cours
100	0	0	À exécuter
Tous	0 < Taux de Vérification < 100	100	En cours d'exécution
Tous	0 < Taux de Vérification	Taux de Validation < 100	Non Validé
Tous	100	100	Validé

Il est possible de n'afficher que ce champ dans Jira s'il est configuré seul. Les taux sont calculés mais non transmis à Jira.

En savoir plus

Pour plus d'informations sur l'affichage des indicateurs dans Jira, consulter la page Suivre les activités de test dans Jira.

Configurer les équivalences de champs

Afin de permettre à Squash TM d'afficher les informations contenues dans les champs des tickets Jira, il faut configurer des équivalences de champs. Cette configuration se fait dans le troisième bloc de l'écran de configuration Xsquash4Jira.

Le bouton présent au sommet du bloc permet d'ajouter une nouvelle équivalence.

Les champs Squash TM disponibles sont présentés dans une liste déroulante. Il est possible d'enrichir cette liste en ajoutant des champs personnalisés aux exigences du projet. Il est recommandé d'utiliser des champs personnalisés Squash TM de type "Texte simple" pour récupérer les données des tickets Jira dans la majeure partie des cas. Pour mapper les champs "Texte multi-lignes" Jira, il est préférable d'utiliser un champ personnalisé Squash TM de type "Texte riche".

En savoir plus

Pour en savoir plus sur les champs personnalisés, consulter la page suivante : Gérer les champs personnalisés.

Les champs Jira doivent être renseignés par leur nom tel qu'il s'affiche dans les requêtes JQL pour les champs natifs ou dans les tickets Jira pour les champs personnalisés. Les champs natifs Jira comme par exemple Type, État, et Priorité doivent donc être renseignés en anglais en minuscule dans le tableau d'équivalences : issuetype, status, priority.

Une fois la configuration du bloc terminée, il ne faut pas oublier de bien forcer les synchronisations du projet pour que la modification soit prise en compte. Il est également nécessaire de forcer la synchronisation après une suppression d'équivalence dans le tableau sans quoi des erreurs apparaissent dans les logs.

Info

Si une équivalence ne fonctionne pas, vérifier l'affichage du nom du champ Jira dans les requêtes JQL et essayer avec cette valeur.

Configurer les équivalences des valeurs de champs

Si une équivalence de champs a été configurée pour les champs Squash TM Criticité, Catégorie ou Statut, il faut réaliser une configuration des équivalences des valeurs de champs pour avoir un mapping complet. Celle-ci s'effectue dans le quatrième bloc de l'écran.

Cette configuration utilise la syntaxe YAML. Il est donc indispensable de bien respecter le format indiqué dans l'aide à la configuration.

Dans l'aide à la configuration :

• champsquash correspond au nom du champ Squash TM en anglais en minuscule comme affiché dans la liste des champs et valeurs disponibles à la fin de l'aide ;
• valeurjira est la valeur du champ Jira telle qu'affichée dans les requêtes JQL sur Jira ou dans les tickets Jira ;
• valeursquash est la valeur du champ Squash TM telle qu'affichée dans la liste des champs et valeurs disponibles à la fin de l'aide.

Voici un exemple de configuration pour ces trois champs :

Une fois la configuration du bloc terminée, il ne faut pas oublier de bien forcer les synchronisations du projet pour que la modification soit prise en compte. Il est également nécessaire de forcer la synchronisation après une suppression d'équivalence.

En savoir plus

Il est possible d'associer une liste personnalisée au champ Catégorie des exigences du projet pour récupérer la valeur des types de tickets Jira dans Squash TM comme dans l'exemple ci-dessus.
Pour en savoir plus sur les listes personnalisées, consulter la page suivante : Gérer les listes personnalisées.

Attention

Les statuts "Approuvé" et "Obsolète" bloquent toutes modifications sur une exigence.
Si un mapping est fait avec ces deux statuts, les exigences qui prendront ces statuts automatiquement ne seront plus mises à jour par la suite.
Il faudra modifier le statut manuellement à "En cours de rédaction" ou "À approuver" pour réactiver la mise à jour de l'exigence.

Configurer les équivalences des liens entre exigences

Xsquash4Jira permet également de récupérer les liens entre tickets Jira sous forme de liens entre exigences. Cette configuration se fait dans le cinquième bloc de la page de configuration de Xsquash4Jira.

L'ensemble des liens entre exigences Squash s'affichent automatiquement dans le tableau d'équivalences. Il s'agit des liens paramétrés dans l'espace Entités>Liens entre exigences dans l'Administration de Squash TM.

En savoir plus

Il est possible d'ajouter de nouveaux liens entre exigences depuis l'espace Entités>Liens entre exigences.
Pour en savoir plus sur les liens entre exigences, consulter la page suivante : Gérer les liens entre exigences.

Le lien entre exigences Jira doit être désigné par son Nom, tel qu'il s'affiche dans la partie Création de liens entre des demandes dans l'Administration de Jira Data Center ou dans l'espace Liaison de tickets dans Jira cloud :

Une fois la configuration du bloc terminée, il ne faut pas oublier de bien forcer les synchronisations du projet pour que la modification soit prise en compte. Il est également nécessaire de forcer la synchronisation après une modification d'équivalence.

Configuration de Xsquash4Jira dans les modèles de projet

Il est possible de définir la configuration de Xsquash4Jira dans un modèle de projet afin de la partager avec les projets associés au modèle ou créés à partir du modèle. La configuration au niveau des projets peut ensuite être déléguée au modèle ou évoluer indépendamment de celle du modèle.

Cette fonctionnalité est utile lorsque l'on souhaite configurer le plugin Xsquash4Jira pour plusieurs projets Squash et que les tickets Jira à synchroniser sont issus de projets Jira qui partagent le même paramétrage (champs personnalisés, types de tickets, priorités, workflow…).

Configurer Xsquash4Jira dans les modèles de projet

La page de configuration du plugin Xsquash4Jira des modèles est similaire à celle des projets, à l'exception du bloc Synchronisations qui est absent pour les modèles de projet. Pour les modèles, il est donc possible de paramétrer les équivalences entre les champs Squash et Jira, à savoir :

• Champs de reporting Squash vers Jira ;
• Équivalences entre les champs ;
• Équivalences entre les valeurs des champs ;
• Équivalences des liens entre exigences.

Créer un projet en reprenant la configuration de Xsquash4Jira du modèle

Lors de la création d'un projet à partir d'un modèle, l'option Configuration de Xsquash4Jira permet à l'administrateur de reprendre la configuration de Xsquash4Jira définie au niveau du modèle.

Ainsi, dans le projet créé, le plugin Xsquash4Jira est déjà préconfiguré à l'exception des synchronisations qui seront à ajouter par le chef de projet ou l'administrateur. La configuration de Xsquash4Jira au niveau des projets peut ensuite être déléguée au modèle ou évoluer indépendamment de celle du modèle.

Lier la configuration de Xsquash4Jira du modèle aux projets liées

À la création d'un nouveau projet

Lors de la création d'un projet à partir d'un modèle, une option permet à l'administrateur de :

• lier la configuration de Xsquash4Jira du projet à celle du modèle (option cochée) :
  • la configuration au niveau du projet est déléguée au modèle, en dehors des synchronisations ;
  • toutes les modifications effectuées au niveau du modèle seront répercutées dans les projets liés ;
• ne pas lier la configuration de Xsquash4Jira du projet à celle du modèle (option décochée) :
  • la configuration au niveau du projet peut évoluer indépendamment de celle du modèle lié ;
  • les modifications de la configuration effectuées au niveau du modèle ne seront pas répercutées dans les projets liés.

À l'association d'un projet existant à un modèle

Il est également possible de lier la configuration de Xsquash4Jira lors de l'association d'un projet existant à un modèle.

Dans ce cas, si le plugin Xsquash4Jira était déjà configuré au niveau du projet, cette configuration est écrasée par celle du modèle. Seuls les paramétrages d'équivalences sont impactés, les synchronisations ne sont pas supprimées.

Désactiver Xsquash4Jira dans les modèles

La désactivation ou la suppression de la configuration dans le modèle entraîne la suppression de la configuration dans les projets liés, à l'exception des synchronisations.