Synchronize Jira Agile Objects in Squash
What it does
Once the Xsquash4Jira plugin is correctly set up, Jira issues are automatically synced as requirements in Squash 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 Requirements workspace.
Synced Requirements
In Squash, synced requirements are the equivalent of Jira issues. In the requirements tree, their name is grayed out and preceded by this icon .
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 always 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 ticket's synchronization status is unknown (for example, when the global synchronization has failed).
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 requirements 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 the 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.
Epic - user story links (or other issuetypes) are also synchronized as high level requirement - standard 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:
-
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;
-
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. -
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.
Learn more
When generating dashboards in the Requirements 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.
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 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.
Synchronized Requirements organization
Scrum board synchronization
When synchronizing a scrum board, sprints are synchronized as folders in the requirements 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.
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.