2.09 - Xsquash

Installation

The Xsquash plug-in is installed just like any Squash TM plug-in, by copying the file plugin.requirement.xsquash4jira-X.Y.Z.RELEASE.jar, delivered in the plugins directory of Squash TM. Restarting the server is necessary for the plug-in to be detected by Squash TM.

Prerequisites

Squash-JIRA communication

The plug-in Xsquash4Jira is based on a bidirectional communication between Squash TM and Jira. It is a communication between the Squash and JIRA servers, using essentially the JIRA Rest API. For the plug-in to work, there needs to be communication between both, which often requires interventions on the network infrastructure (opening of flow in firewalls, addition of certificates in the JVM).

If the same JIRA server is already used as a bugtracker using the JIRA REST Bugtracker, then the communication is already possible.

In case you are experiencing difficulties, it is necessary to check directly on the Squash TM server whether JIRA is accessible: try to reach the JIRA API directly from the server, using a curl or a wget. If the request does not pass, then you are experiencing a network problem.

JIRA technical account

The plug-in communicates with JIRA through a JIRA user. This user needs to have the rights to read all tickets to be synchronized. If the reporting of Squash towards Jira is activated, then the user needs to have the rights to write on all these tickets.

The best way to proceed is to create a technical account dedicated to the plugin in JIRA, and to grant rights only on the JIRA projects.

Authentification

The plug-in uses the JIRA API using a "Basic Authentification" (login / password). The JIRA technical account mentioned above has to be authentified by the JIRA API with said login details.

Declaring the JIRA Server in Squash TM

Once the technical user was configured in JIRA, it is necessary to configure the plug-in in Squash TM using the "Authentification policy" available in the Bugtrackers details workspace (from the Administration screen, click on the Bugtrackers button )

Add the new Bugtracker jira.xsquash, then click on its name to access the Bugtracker Details Workspace, as follows :

• in the Authentification Policy, choose "Use Squash-TM credentials",

• type in the login and password configured earlier for the Squash technical account in JIRA,

• test the configuration,

• save if the test is OK.

Squash TM can now connect to the JIRA server under the specified URL using the specific login details.

These credentials are stored in the database, using an encryption key that you can modify in adding the following property in the Squash configuration file squash.tm.cfg.properties:

squash.crypto.secret=my_secret_key

If you do not want the keyboard to display clear text in the configuration file, you can add the -Dsquash.crypto.secret=my_secret_key parameter among the java launching options of Squash-TM, in the startup.bat or startup.sh file. The value my_secret_key can be transmitted through an environment which is variable for more confidentiality.

There is a default encryption key, but we recommend that you contact your system administrator to have it changed.

Once the JIRA server is configured in Squash TM, you have access to the functionnalities offered by the plug-in.

The configuration file

Two properties have to be set in the file squash.tm.cfg.properties:

• • squash.external.synchronisation.delay: sets the time between two synchronisations, in seconds. If this property is not set or not properly set, the default value will be 5 minutes (300 seconds), and a warning will be issued in the log of Squash TM while starting up.

  • CAUTION: the shorter this delay is, the more ressources the plug-in will need to keep the data up to date. For most of the current uses, a time between 5 and 15 minutes is absolutely enough.

    • plugin.synchronisation.jira.batchSize: sets the size of the batch used to keep the informations up to date. The default value is 50. This size has to be lower or equal to the value of jira.search.views.default.max defined in the file jira-config.properties.

    • The default value 50 works fine with JIRA On Premises and JIRA Cloud, if no modification were made to the default value in JIRA.

To go further, see the Administrator guide, chapter 12 - Xsquash configuration.