Manage Xsquash4Jira Synchronizations in Squash TM

Info

This page is dedicated to the management of Xsquash4Jira synchronizations. For general configuration of the Xsquash4Jira plugin, go to: Configure Xsquash4Jira in Squash.
To learn more about Xsquash4Jira's features, please visit the page Synchronize Jira Agile Objects in Squash.

A synchronization is the work unit of the Xsquash4Jira plugin. It represents all the Jira issues defined by a dynamic perimeter that are retrieved by Squash. This dynamic perimeter is recalculated every time there is an update. By default, there is a 5-minute delay between each synchronization (this delay can be set up in the Squash's configuration file).

You can define this perimeter from the Synchronization type column of the Synchronization table. This synchronization type can either be a "Board", a "Filter", or a "JQL Query". For boards, you can refine the filter with the field Additional JQL and the option Restrict to active sprint.

Here is the perimeter retrieved according to the chosen synchronization type:

Type	Perimeter	Note
Board	All the issues included in the filter used to build the board in Jira.	In Jira, a filter controls the perimeter. This filter is in fact the filter linked to the targeted board. As a reminder, a Jira board is first and foremost a filter, to which are added more filters.
Filter	All the issues sent back by this filter call in Jira	In Jira, a filter controls the perimeter. If the filter is modified in Jira, the perimeter in Squash will be modified, without any warning nor message. If the filter is deleted in Jira, the synchronization will fail, and you will receive an error message in the logs.
JQL	All the issues sent back by sending this to Jira's search API	Squash controls the perimeter. This is useful when you cannot create the right filters in Jira.

The Synchronizations block looks like this:

Following chapters detail this table's usage.

Create a synchronization

To create a synchronization, click on the button on top of the Synchronizations block.

Requirement synchronization (Requirement workspace)

This first step of a synchronization creation is mandatory.

This table details the pop-up fields and how to fill them out:

Name	Mandatory	Editable	Notes
Name	Yes	Yes	Unrestricted name. Must be unique in all the Squash instance.
Target path	Yes	No	Initial path of the synchronization's target repository. This repository must not exist in the Requirements workspace. It is created by Xsquash4Jira during the first update.
Server	Yes	No	Xsquash4Jira server used for the synchronization. Choose it in the list of configured servers of the Bugtrackers and Synchronization Servers administration page.
Selected by	Yes	No	Perimeter type. There are three options available: Board, Filter, or JQL Query. The next fields in the pop-up will change depending on the option you choose.
Board Name	Yes	Yes	Name of the board to synchronize as it appears in Jira. Case-sensitive.
Additional JQL	No	Yes	Enables you to refine the perimeter using an extra JQL clause. This clause must not contain any operator (AND, OR…) at the beginning or the end of any clause; it must only contain selection criteria (no ORDER BY or any other clauses…).
Filter name	Yes	Yes	Name of the filter to synchronize, as it appears in Jira. Case-sensitive.
JQL Request	Yes	Yes	JQL request that defines the synchronization perimeter. It must not contain any operator (AND, OR…) at the beginning or the end of any clause; it must only contain selection criteria (no ORDER BY or any other clauses…).
Restrict to active sprint	-	Yes	Enables you to keep synchronized only the issues in a sprint with an "Active" status in Jira. This only makes sense for a "Board" type, that references a SCRUM-type board, since the other boards do not have any sprints.
Synchronize sprints in Execution workspace	-	Yes	If checked, enables the access to a second step to configure the synchronization in Execution workspace (Sprints). Only available for "Board" synchronizations.

Restrictions for target path

The target path cannot:

• Point exactly to an existing synchronized folder, or be identical to another synchronization path (from another synchronization configuration);
• Begin or end with a space or a /;
• Include a series of multiple spaces in a row;
• Have a space located immediately before or after a /.

Simulate a synchronization

When adding a new synchronization, you must simulate it to be able to confirm its creation or access the second step of the configuration.

For this, click on the [Simulate] button in the Add a synchronization in the requirement workspace window. This enables you to view the number and details of the tickets the synchronization contains. Thus, you can verify that they belong to your desired perimeter.

Info

If a value is set to limit the number of elements authorized for a synchronization (see Squash TM's configuration file options), this value is also taken into account for simulation. Thus, the simulation fails if the number of issues to be synchronized is too high.

Sprint synchronization (Execution workspace)

This second step is optional. It is only available with a Selection by Board, and if the checkbox Synchronize sprints in Execution workspace is checked.

The following table details the pop-up fields and how to fill them out.

Name	Mandatory	Editable	Notes
Sprint synchronization target path	Yes	Yes	Initial path where sprints are synchronized. It is created by Xsquash4Jira during the first update. The last part of this path will be created as a Sprint group, and if there are parts before, they will be created as folders.
Selected by	Yes	No	To be able to synchronize sprints in Execution workspace, selection must be by Board. Thus, this field is prefilled and not editable.
Board Name	Yes	No	Name of the board to synchronize as it appears in Jira. Its value is the same as the one in first step.
Additional JQL	No	Yes	Enables you to refine the perimeter using an extra JQL clause. If an additional JQL query is set in first step, the default value will be that one. This clause must not contain any operator (AND, OR…) at the beginning or the end of any clause; it must only contain selection criteria (no ORDER BY or any other clauses…).
Restrict to active sprint	-	Yes *	Enables you to keep synchronized only the issues in a sprint with an "Active" status in Jira. * Editable only if the equivalent checkbox is unchecked in the first step Add a synchronization in the requirement workspace.

Restrictions for target path

The target path cannot:

• Point to an already existing sprint group from Execution workspace, or start like a path already configured in another synchronization;
• Begin or end with a space or a /;
• Include a series of multiple spaces in a row;
• Have a space located immediately before or after a /.

Simulate a sprint synchronization (for Execution workspace)

When adding a new synchronization, you must simulate it to be able to confirm its creation.

For this, click on the [Simulate] button on the second step of the configuration window. This enables you to view the number and details of the issues and sprints the synchronization contains. Thus, you can verify that they belong to your desired perimeter.

Focus

Sprints are created in the Execution workspace according to the status of Jira's sprint:
- Upcoming / Active: the sprint and its tickets are created;
- Closed / Deleted: the sprint and its tickets are ignored.

Info

If a value is set to limit the number of elements authorized for a synchronization (see Squash TM's configuration file options), this value is also taken into account for simulation. Thus, the simulation fails if the number of issues to be synchronized is to high.

Track Synchronizations

Once you have configured the synchronization, an additional row appears in the synchronization table. During the next update, all the synchronized requirements and sprints corresponding to the perimeter will be created. If the synchronization fails, nothing is created in Squash. The status of every synchronization is displayed in the synchronization table.

The configuration page can be refreshed thanks to the button , to see if the status of the synchronizations was updated following the synchronization process.

Update an existing synchronization

It is possible to update some elements of a synchronization's configuration after it has been created. After modifications, when the update happens, only the last version of the configuration is taken into account.

Update the requirement synchronization

The REQ. SYNC. column shows what type of synchronization is selected (Filter, Board or JQL Query). The button allows you to see and update the configuration of the requirement synchronization.

Board name and Additional JQL fields are editable for a selection by Board. If the selection is by Filter, only the Filter name field is editable, whereas for JQL Query selection, only the JQL query itself is editable.

A simulation must be performed to be able to confirm modifications.

Add a sprint synchronization (Execution workspace)

If an existing requirement synchronization allows the configuration of a sprint synchronization (i.e. if requirements are selected by Board), the SPRINT SYNC. column indicates if one is already set up (Yes or No). Otherwise, an - is displayed.
If "No" is displayed, the button lets you add a new sprint synchronization.

As for creating a new synchronization, current perimeter (selection type and board name) is copied from the requirement synchronization, and those fields are not editable.

Fields Target path and Additional JQL are editable, and they work exactly the same as described in second step of the creation of a synchronization. The Restrict to active sprint checkbox is editable only if the equivalent checkbox is unchecked in the requirement synchronization.

A simulation must be performed to be able to confirm the addition of a sprint synchronization.

Update a sprint synchronization (Execution workspace)

If SPRINT SYNC. column displays "Yes", the button lets you consult and modify the configuration of the existing sprint synchronization.
It works exactly like adding a new sprint synchronization, except that Additional JQL is the only editable field.

A simulation must be performed to be able to confirm modifications.

Delete a sprint synchronization

There is a [Delete] button in the sprint synchronization update window. It deletes the configuration for the synchronization in the Execution workspace.

Like a complete deletion of a synchronization, synchronized sprints are transformed in manual sprints. Thus, they are not updated from Jira anymore and behave as any other sprint of Squash TM. The same is true for synchronized folders (target folders and sprint groups).
If a user wants to delete those entities, they must do it manually, as they would for any Squash TM entity.

Info

Requirement synchronization is unaffected, and synchronized requirements will still be updated.

Synchronization owner

In the synchronizations table, the Owner column shows which credentials were used for each synchronization. There are several possibilities:

• the synchronization is done with the technical account, i.e. synchronization server's credentials. In this case, the Owner column displays "Technical account";
• the synchronization is done with the user credentials. In that cas, the Owner column displays the owner's username. The default owner is the user who has added the synchronization.

It is possible to modify an existing synchronization owner. The synchronization will then be done with the new owner credentials.

To do so, when clicking on a synchronization owner, a pop-up window allows the user to assign the synchronization to himself/herself or to the technical account. They can also do a synchronization simulation to make sure that the synchronization brings back the expected issues with the new owner credentials.

Warning

It is impossible to delete a user who is a synchronization owner. The synchronization owner must be modified first.

Force a complete Synchronization

By default, the plugin only updates the synchronized requirements that were modified in Jira since the last known update, and that are in success.

In the case of a change of field or value mapping in Squash, you must resynchronize all the requirements in Squash, even if nothing has changed in Jira.

The button enables you to force the update of all the synchronized issues in the current perimeter of one or multiple synchronizations.

Info

To avoid useless updates, we recommend that you do the mapping before declaring the synchronizations.
If the mapping must evolve afterwards, we recommend that you first do all the changes of the field, value, and link mappings, and then force all the project synchronizations just once.

Deactivate a Synchronization

The radio button at the beginning of each row lets you deactivate or reactivate a synchronization without deleting it.

When a synchronization is deactivated, sprints and their tickets in its perimeter are no longer synchronized. The row is grayed out and the name of the synchronization can no longer be edited. It is still possible to delete the synchronization, or update its configurations (configuration for requirements and/or sprint synchronization).

When it is reactivated, the sprint and their tickets are synchronized again in Squash TM and take back their synchronization attributes, as well as the mapping and reporting defined in the other blocks.

Delete a Synchronization

The button enables you to delete one or multiple synchronization. In keeping with the non-deletion policy, synchronized requirements and sprints are not deleted but transformed into Squash native requirements.

They are no longer updated from Jira and behave as any other Squash requirement or sprint would. The same is true for synchronized repositories (target folder or sprint group, and sprint folders).

If you want to delete these entities, you must do it manually as you would for any Squash entity.