Configurer Xsquash4Jira dans SquashTM

Le plugin Xsquash4Jira est un plugin SquashTM 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 à SquashTM 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 SquashTM. Ces informations prennent la forme de champs personnalisés à ajouter sur les tickets Jira qui sont ensuite complétés par SquashTM ;
• 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 :

Installation et prérequis

Communication SquashTM/Jira

Le plugin Xsquash4Jira est un plugin reposant sur une communication bidirectionnelle entre SquashTM 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 SquashTM pour vérifier si Jira est accessible : essayer de passer une requête vers l'API Jira directement depuis le serveur hébergeant SquashTM 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 a minima des droits en lecture par l'API sur l'ensemble des objets à synchroniser (tickets et sprints). Si le reporting de SquashTM 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 SquashTM

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

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.

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.

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 davantage 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 vides 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 SquashTM. 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 SquashTM 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 SquashTM ;
• 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 SquashTM.

Configurer le reporting de SquashTM vers Jira

Le plugin Xsquash4Jira est capable de remonter vers Jira des informations relatives à la recette réalisée dans SquashTM. 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.

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 :

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 SquashTM ;
• ê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 SquashTM.

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 SquashTM aient les mêmes champs puisque dans SquashTM la configuration se fait au niveau du projet.

Ces champs sont ensuite alimentés par SquashTM 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 SquashTM

Dans SquashTM, la configuration du reporting s'effectue dans le second bloc de l'écran de configuration du plugin Xsquash4Jira : Champs de reporting SquashTM 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 test 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 test 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 test 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 :

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.

Configurer les équivalences de champs

Afin de permettre à SquashTM 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 SquashTM 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 SquashTM 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é SquashTM de type "Texte riche".

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

Configurer les équivalences des valeurs de champs

Si une équivalence de champs a été configurée pour les champs SquashTM 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 SquashTM en anglais en minuscules 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 SquashTM 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.

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 SquashTM s'affiche 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 SquashTM.

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 SquashTM 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 SquashTM et Jira, à savoir :

• Champs de reporting SquashTM 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 Xsquash permet de reprendre la configuration des plugins de synchronisations (Xsquash4Jira et Xsquash4GitLab) 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 sont définies uniquement au niveau du projet. 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és

À la création d'un nouveau projet

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

• lier la configuration des plugins de synchronisations (Xsquash4Jira et Xsquash4GitLab) 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 des plugins de synchronisations (Xsquash4Jira et Xsquash4GitLab) 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.