Skip to content

Synchronize Jira issues in the Requirement workspace of Squash TM

What it does

If an Xsquash4Jira synchronization is configured, Jira issues are automatically synchronized as requirements in Squash TM and updated on a regular basis. The synchronization repository as well as all the requirements it contains are created during the first update.

The synchronization is only one way, from Jira to Squash.

This part explains how these assets are organized in the Requirement workspace.

For the organisation in the Execution workspace, please consult the Synchronize sprints page.

Synchronized Requirements

Display

In Squash, synchronized requirements are the equivalent of Jira issues. In the requirements tree, their name is grayed out and preceded by this icon Sync.

This icon indicates that it is a synced requirement and also gives information on the synchronization status of the linked Jira issue using the following color code:

  • green icon: the requirement is still updated via synchronization;
  • yellow icon: the requirement is no longer updated via synchronization because the matching Jira issue is no longer in the synchronization perimeter defined in the plugin's configuration (for example, the Jira issue now has a status that is not in the filter chosen for the synchronization);
  • red icon: the requirement is no longer updated via synchronization because the matching Jira issue was deleted in Jira or was moved to another Jira project (its key was modified);
  • black icon: the issue's synchronization status is unknown (for example, when the global synchronization has failed).

Tree synchronization status

Synced requirements have three more details than native requirements:

  • a hyperlink to the original Jira issue;
  • the Jira issue's status that indicates if the requirement is still updated by synchronization and if the matching Jira issue is still in Jira;
  • the Jira issue's synchronization status, which alerts the user if the communication between Squash and Jira is disrupted or if an error has occurred during the last update.

Modify, move and delete

Synced requirements can be modified in Squash. There are two behaviors depending on the field to be modified:

  • it is a synchronized field (description, reference, or any other field with a mapping): modifications are erased with the next synchronization if the issue is updated in Jira;
  • it is not a synchronized field: modifications are kept in Squash.

Warning

'Approved' and 'Obsolete' statuses prevent requirements from modifications. As a result, when a requirement is modified with one of these statuses, it is not updated anymore. The status has to be manually set to 'Work in progress' or 'Under review' to enable again the requirement update.

Synchronized requirements can be moved in the requirement library. Again, several behaviors:

  • the requirements are moved into the same project: they are still updated and stay or do not stay at their new location depending on the organization type (see Synchronized requirements organization);
  • the requirements are moved into another project: they become native requirements in the target project and are recreated in the source project during the next synchronization.

When deleting synchronized requirements in Squash:

  • if the requirements are still in the synchronization perimeter: they are recreated with the next synchronization;
  • if the requirements are not in synchronization perimeter anymore: they are not recreated in Squash.

Attachments

Jira issues attachments are synchronized in Squash as links in the requirements description. They are direct links to the attachments in Jira.

Epics

Warning

This feature is available with Squash TM Premium plugin included in Squash Premium license.
Without this plugin, Jira epics are synchronized as standard requirements in Squash. Links with user stories are not synchronized.

Jira "epics" are synchronized in Squash as high level requirements.

Synchro epic - High level requirement

Epic - user story links (or other issuetypes) are also synchronized as high level requirement - standard requirement links.

Synchro epic - high level requirement links

To retrieve these links in Squash, epics and user stories must be synchronized with the same synchronization server. However, they can belong to two different synchronizations.

Several types of organizations can be considered:

  1. Epics and user stories are in the same synchronization:

    • for Kanban boards, filters or JQL queries synchronizations, they are all synchronized at the root of the target repository;
    • for Scrum boards, epics are synchronized at the root of the target repository whereas user stories are synchronized in the sprint folders or at the root of the target repository if they are in the backlog;

    Synchro epic case 1

  2. Epics and user stories are in different synchronizations but in the same Squash project.
    This organization allows splitting epics and user stories in two different folders. This can make reporting easier by generating dashboards or reports only on epics or user stories.

    Synchro epic case 2

  3. Epics and user stories are in different synchronizations and Squash projects.
    This organization allows having different configurations between projets containing epics and user stories (synchronizations, custom fields, user clearances configuration). This is useful if you want to authorize users to follow up only on the epics or if you want to retrieve different information between epics and user stories.

    Synchro epic case 3

Learn more

When generating dashboards in the Requirement workspace, it is possible to extend the high-level requirements' scope so the linked standard requirements are included, even if they were not in the initial selection. This way, even if epics and user stories are in different folders, it is possible to include user stories in the dashboard generated from epics.

Sub-tasks

In Squash, the link between a sub-task and a user story is represented as a requirement hierarchy if the two requirements are in the same synchronization.

Sub-tasks

This link having a specific meaning in Jira, it is not recommended breaking it in order to have correct coverage indicators for the parent requirement.

Hybrid hierarchies

It is possible to add a herarchy of native requirements under a synchronized requirement.
For example, a Jira issue could lead to several test requirements in Squash. These test requirements can be added under the synchronized requirement that matches this issue in Squash.

Target repository

The target repository is the parent repository in which the Jira issues are synchronized. Depending on the synchronization type, repositories can be automatically created under the target repository.

Synchronization status

Target repositories are also preceded by this icon Sync and their color code is similar to the one of synced requirements:

  • green icon: the synchronization of the target repository has succeeded and all the synced requirements it contains are updated via synchronization;
  • yellow icon: the synchronization of the target repository has succeeded, but it contains requirements that are no longer updated via synchronization because they are no longer in the synchronization perimeter or Jira anymore;
  • red icon: the synchronization of the target repository has failed (for example, when the communication between Squash TM and. Jira is disrupted or if an error has occurred during the last update).

Move and delete

Target repositories can be moved in the requirement library:

  • target repositories are moved in the same project: their synchronized requirements are still updated;
  • target repositories are moved in another project: their synchronized requirements become native requirements in the destination project and the target repositories are recreated with the next synchronization in the original project.

If the target repositories are deleted in Squash, they are recreated with the next synchronization, at their original location.

Synchronized Requirements organization

Scrum board synchronization

When synchronizing a scrum board, sprints are synchronized as folders in the requirement library and contain synchronized requirements corresponding to the Jira issues in the sprint.
Issues in the backlog are synchronized at the root of the target repository.

Scrum synchronizations

If an issue is moved in another sprint or in the backlog in Jira, it is automatically moved in the matching folder in Squash.

Focus

Accumulation of closed sprints in Jira leads to the creation of numerous sprint folders in Squash. To improve readability, it is possible to create one (or several) archive folders at the root of the target repository and move the closed sprints into it. In this archive folder, sprint folders can be organized by year, theme or else.

If the sprint organization is not relevant anymore, synchronized requirements can be moved anywhere in the same Squash project. The only restricion is not to delete the closed sprint folders, in order to prevent them from being recreated with the next synchronization.

Warning

It is recommended to move neither unfinished sprint folders, nor their content. Once the sprint and its issues are closed, archiving can be done in Squash.

Other synchronization types

For other synchronization types (Kanban boards, filters, JQL queries), requirements are created at the root of the target repository. You are then free to organize synchronized requirements as you want, as long as you are not moving them into another project, so they can still be updated.