Manage GitLab synchronizations in Squash TM

Info

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

A synchronization is the work unit of the Xsquash4GitLab plugin. It represents all the GitLab 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).

The synchronization perimeter is defined by two elements:

• the issues' perimeter: the group or project in which the issues to be synchronized are;
• the synchronization type: combined with the issues' perimeter, it enables you to define if the issues to be synchronized must match filters on their fields or are in a GitLab issue board.

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

Issues perimeter	Type	Synchronization perimeter	Note
Group or project	Filters on issues	All the group or project's issues that match the filters applied on their field. If the issues' perimeter is a group, the issues are those that are included in the group's projects.	Squash controls the synchronization perimeter.
Group or project	Board	Issues that are included in a board of the selected group or project. The board configuration is taken into account.	Squash controls the synchronization perimeter. If the board configuration is modified on GitLab, the synchronization perimeter is modified in Squash, without warning. If the board is deleted in GitLab, the synchronization fails with an error message in Squash logs.

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)

The first step of a synchronization creation is mandatory.

The following 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. It is created by Xsquash4GitLab during the first update.
Server	Yes	No	Xsquash4GitLab server used for the synchronization. Choose it in the list of configured servers, on the Bugtrackers and Synchronization Servers administration page.
Perimeter	Yes	No	Group, subgroup or project path where the issues to synchronize are. This should be the path as it appears in the GitLab URL. e.g. group-1/sub-group-1/project-1 to synchronize the Project 1 issues, or group-1 to synchronize the Group 1 issues.
Select type	Yes	No	Synchronization type. There are two options available: Issue or Board. The next fields in the pop-up will change depending on the option you choose.
Organization by	Yes	No	How the synchronized issues are organized in the Squash requirement library. There are four options depending on the synchronization type: - Flat (Issue): all the GitLab issues are synchronized at the root of the synchronization's target repository. - Iteration (Issue and Board): a repository is created for each iteration of the perimeter - Milestone (Issue and Board) (selected by default): a repository is created for each milestone of the perimeter - Tree (Issue): if the perimeter is a group, a repository is created for each subgroup and project
Board	Yes	Yes	Board to synchronize. It is displayed only if the Perimeter field is filled and if the synchronization type is "Board"
Active filters	No	Yes	Allows to refine the synchronization perimeter by applying filters on the issue fields. For example, allows to restrict the synchronization to the current iteration or milestone. Only available for the "Issue" synchronization type.
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 synchronizations organized by Milestone or Iteration.

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 requirement 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 window. This enables you to view the number and details of issues 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 an Organization by Milestone or Iteration, 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 Xsquash4GitLab 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.
Perimeter	Yes	No	Group, subgroup or project path where the issues to synchronize are. The value is the same as the one in first step.
Sprint management	Yes	No	GitLab object used for sprints (milestone or iteration) management. The value is the same as first step's "Organization by".
Select type	Yes	Yes	Synchronization type. There are two options available: Issue or Board. The next fields in the pop-up will change depending on the option you choose.
Active filters	No	Yes	Allows to refine the synchronization perimeter by applying filters on the issue fields. For example, allows to restrict the synchronization to the current iteration or milestone. Only available for the "Issue" synchronization type.
Board	Yes	Yes	Board to synchronize. It is displayed only if the Perimeter field is filled and if the synchronization type is "Board". If a board is selected in step one, it is selected by default in step two.
Mappings	No	Yes	It is possible to set one or more GitLab labels related to the Category, Criticality and Status of the issue. The values of those labels will be synchronized and displayed in every sprint ticket in Squash.

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, iterations and milestones 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 GitLab's milestone or iteration:

• Upcoming / Open / Expired: 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 (Board or Issue). The button allows you to see and update the configuration of the requirement synchronization.

Only filters (if select type is Issue) or the board (if select type is Board) are 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, the SPRINT SYNC. column indicates if one is already set up (Yes or No). If requirements are not met, an - is displayed.
If "No" is displayed, the button lets you add a new sprint synchronization.

As for creating a new synchronization, current perimeter as well as sprint management type are copied from the requirement synchronization, and are not editable.

Fields Target path, Selected type, Filters or Board, and Mappings are editable, and they work exactly the same as described in second step of the creation of a 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 Target Path field is not editable.

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

Force a complete synchronization

By default, the plugin only updates the synchronized requirements that were modified in GitLab 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 GitLab.

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 afterward, we recommend that you first do all the changes of the field and value 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, issues, milestones and iterations 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 issues, milestones and iterations are synchronized again in Squash and retake their synchronization attributes, as well as the mapping and reporting defined in the other blocks.

Delete a synchronization

The button lets you 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 GitLab and behave as any other Squash requirement or sprint would. The same is true for synchronized repositories (target folder or sprint group, and milestone, iteration or project folders).

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