How does changing the Sprint dates in Jira affect Jira Align?
Summary
If the sprint dates are changed in Jira and the Jira Projects are integrated to Jira Align, then changing the dates of existing sprints can cause problems. A few of the more obvious issues being:
- The creation of duplicate sprints (multiple sprints with the same name) in Jira Align
- Jira Align users see multiple choices that show the same sprint name when trying to select sprints in dropdown fields within Jira Align.
- Jira Align Reports show confusing information where more than one sprint with the same name is displayed
- An inability to change field values in some Jira Align sprints as, when trying to save changes, a red pop-up error is displayed that states "Sprint name already exists. Please enter the unique Name."
There are some situations where a requirement to change the sprint dates of future sprints in Jira may become necessary. Typically future sprints may need to change dates if:
- Sprints were initially setup well in advance of when they will be used and now need their dates adjusted (perhaps for a different cadence than was originally created)
- Sprints have been created with the wrong dates
- The current date is after the end date of the current active sprint (and possibly also after the end date of one or more future sprints too). Note: Jira will not allow a future sprint to be started that has an End date in the past.
Reusing a sprint name in Jira, without realizing that the same name was used some time ago (in a closed/completed sprint), will cause some similar issues. As this scenario is more likely to also link the duplicated sprint names to different Program Increments, most of the effects seen in Jira Align will not be noticed by end-users.
If sprints are being mapped based on sprint order, then Re-ordering the sprints in the Jira Backlog may also cause a related issue.
This article discusses why changing the dates of existing sprints in Jira may cause issues in Jira Align and provides recommendations for how to avoid (or resolve) the problems that may be seen.
Environment
Jira Align
Solution
Why changing Jira sprint dates of future sprints can cause problems
When a sprint is first created under a Jira board that is integrated into Jira Align, it usually results in a new Team Sprint being created that is linked to a team in Jira Align. The name given to the new Team Sprint depends on what Sync Sprint Names from Jira is set to in the connector settings (Jira Align > Settings > Jira Settings > Jira Setup)
- If Sync Sprint Names from Jira is enabled (Yes) then the sprint is named using the format "Team Name - Jira Sprint Name"
- If Sync Sprint Names from Jira is disabled (No) then the sprint is named using the format "Team Name - Jira Align Sprint Anchor Name"
If this setting is enabled after the team sprint has been created in Jira Align (and mapped to a Jira Sprint) then the existing team sprint will be renamed during a future sync operation.
If this setting is disabled after the team sprint has been created and mapped then then sprint name in Jira Align won't be changed.
As well is being linked to a Jira Align team, the End date from the Jira Sprint is used to link the newly created Team Sprint to the Sprint Anchor from the Program Increment .
To maintain the sprint mapping between Jira and Jira Align, the Jira Connector uses the combination of the Board + Sprint End date (from Jira) to match with the Team + Sync date fields (in the Jira Align Team Sprint). Noting that the Sync date field content comes from a Sprint Anchor. The sprint name itself is not used as part of the mapping process.
Based on the above: If the sprint dates are changed in Jira in a way that breaks the existing match for the current sprint mapping against the Sprint Anchor (Sync date) then the connector will try to make a new sprint. If Sync Sprint Names from Jira is also enabled, the resulting new sprint will have the same name as the original sprint. This results in a duplicate sprint being created (that will have a different Sync date set than the original sprint had).
Once multiple team sprints with the same name exist in Jira Align, and these sprints are all linked to the same Team and Program Increment, it results in confusing displays relating to the multiple instances of the same name being seen in various reports and dropdown fields. Also any attempt to change a setting inside an affected sprint will fail unless the name of the sprint is changed first.
Closed / Completed or active Jira sprints are not affected by this issue, as changing their dates is not something that is easily possible (in the Jira Console) and any advanced method to change such sprints is not recommended as it may affect Jira Reports as well as the integration with Jira Align.
This example scenario shows what happens if you change the dates of Jira Sprints without changing the sprint names.
Initial State (on 14th June 2024)
- The Jira Board shows 3 sprints: an active sprint that should have completed 2 weeks ago, and 2 future sprints that should have completed 1 week ago and today
- The Jira Align > Settings > Jira Management > Jira Sprints > select board, shows the same 3 sprints with a warning triangle for "Past sprints are not complete"
- Items > Sprints > filtered by team, shows the same 3 sprints
The effects of 'Fixing' the future sprints
- The first future sprint (Sprint 16) had its dates changed in Jira to next week
- The second future sprint (Sprint 17) was deleted and then recreated with the same name but the dates set to the week after next.
- A Resync Future Sprints request was then run in Jira Align (this just speeds up the sync process that would eventually happen anyway)
- In Jira the board now shows: 3 sprints: an active sprint that should have completed 2 weeks ago, and 2 future sprints that are planned to complete next week and the week after
- The Jira Align > Settings > Jira Management > Jira Sprints > select board, now shows 4 sprints.
- The active sprint still shows the warning triangle for "Past sprints are not complete"
- The sprint that had the dates changed shows no errors or warnings with a valid mapping to what is a new sprint with a duplicated name
- The sprint that was deleted and recreated shows two entries (as Jira Align is aware of the background sprint ID in Jira): 1 entry shows an error indicating that "The Jira sprint has either been deleted or the connector no longer has permission...", 1 entry shows no errors or warnings against a valid mapping to what is a new sprint with a duplicated name
- Items > Sprints > filtered by team, now shows 5 sprints and among them are 2 duplicated pairs with different Start and Sync dates
- At this point the plan would then be to complete the active sprint and start next week's sprint, however the cause of problems has already happened and won't be addressed by the remaining steps.
How to avoid having the Jira Connector create duplicate sprints
Whoever is responsible for managing sprints in any Jira projects (that are integrated to Jira Align) needs to be aware that if they are going to adjust the dates in an existing Jira Sprint, that they must change the name of the Jira Sprint, as well as the dates. This recommendation applies whether the existing Jira Sprint is edited or it is deleted and then a new sprint is created, the resulting sprint must use a new unique name as part of making the change.
As Jira has no awareness of whether or not a Jira sprint is mapped to a sprint in Jira Align, a Jira user cannot be forced to change the name of the sprint, making it likely that user error will occur and cause the issue to re-appear.
Dates can be changed, without needing to create a unique sprint name, as long as they maintain the relationship to the original sprint anchor. As an example, if a Jira Sprint is created to end on a Thursday when it should have been Friday (of the same week) then this can be corrected without needing to also change the name.
It is possible to stop duplicate sprints getting created by setting Sync Sprint Names from Jira to Disabled (No). This still results in extra sprints being created but their names will not be duplicates of the original sprint. However, unless a good naming convention has been used for the Sprint Anchors this can result in confusing Jira Align sprint names that are difficult for users to visibly match with the Jira Sprint names - so it is not a recommended solution
In the initial summary of this article, 3 possible reasons (scenarios) for a change of the sprint date were described.
Scenarios 1 and 2, where the sprints have ended up with incorrect dates do not have any specific recommendations, as the above information covers those scenarios
If Scenario 3 applies, where the active sprint has gone past the end date, then there are some specific recommendations to deal with this, that avoid changing the sprint dates:
- If the current date is: only a few days after the planned End date of the current active sprint, before the end date of the first future sprint and there is enough time to still start that sprint, then immediately complete the current active sprint (in Jira) and start the first future sprint. No date changes are needed so this will not cause a problem. This means it is possible to accidentally overrun the planned sprint end date, by a day or two, and it not cause issues.
- If the current date is: after the planned End date of the first future sprint, or does not leave enough time to make it worthwhile starting that sprint, then delete that first future sprint (from Jira), complete the current active sprint and then start the next future sprint instead. No date changes are needed for this, however the Jira Align Administrator will need notifying of the sprint deletion so that they can remove the sprint mapping for the deleted sprint (from Jira Align > Settings > Jira Management > Jira Sprints ).
- If the current date is after the end dates of multiple future sprints then delete all of those sprints from Jira and continue with the first future sprint that still has an End Date in the future. As with the previous point, the Jira Align administrator will need notifying of the sprint deletions so that they can remove the sprint mappings for the deleted sprints.
How to fix issues when duplicate sprints have been created
If duplicate sprints have already been created then there is no automated way to correct things. A Jira Align Administrator will need to:
- Identify all the Team Sprints with duplicated names - consider using Items > Sprints, then apply a team filter and then sort by sprint name to identify them
- Rename all the duplicated sprints by a few characters so that they all have slightly different names.
- Wait about 20 minutes and refresh the list of sprints. The correct team sprint (the one that is still mapped to a Jira Sprint) will have its name reverted as the Jira Connector will undo the the change (against the mapped sprint only). In addition to this undoing of the sprint name change, the details of the correct team sprint will also show that the Sync date field matches to the dates of the Jira Sprint. The correct sprint is also usually the one with the most stories linked to it (which can be checked by going to Items > Stories and filtering on the Program Increment and current names of each of the sprints).
- Once you have identified the incorrect duplicate sprints, make a decision on if you want to keep those sprints or delete them
- If deleting the duplicates then move any associated stories linked to those sprints to a different sprint.
- If keeping the duplicates then give them appropriate, unique names to avoid the confusion caused by duplicate names.
Once all of the affected sprints have different names (Steps 2 + 3), then the confusion in dropdown fields and reports around the seeing duplicate names is resolved and the save of changes to other fields in the sprints will work correctly and not be blocked by an error