Agile Hive version restriction
Use this call only if you are on version 4.11.2 of the Agile Hive Suite. For versions starting with 4.11.3 use the more powerful Analyse-API: Recreate missing Sprint References (starting with version 4.12.0)
On this page, we show how to restore a lost mapping between an iteration and its existing sprint without creating a new sprint.
This feature is provided via the Agile Hive Public API. You can find the public REST interface at .../rest/agilehive/latest/public/. The two endpoints explained below (.../sprint-reference/suggestions and .../sprint-reference) are part of this API and are documented there along with the other public Agile Hive endpoints.
What is the purpose of this feature?
In Agile Hive, each iteration of a Planning Interval corresponds to a Jira Sprint on the Primary Scrum Board of a team project. The link between both (the "SprintReference") could be lost in earlier versions of Agile Hive, even though the Sprint itself still exists on the board.
Typical signs:
It is not possible to set a capacity for a sprint on the Team Breakout Board.
The Burn-Up Chart graphs show unexplained spikes or drops or appear incomplete.
On the Team Report, the sprint is missing, even though it is present in the Jira board or backlog.
You see the HealthCheck message "Missing Sprints or Sprints in wrong Board".
This feature restores the lost link to the existing sprint. It does not create a new sprint. This is the key difference to the "Recreate Missing Sprints" feature, which creates a new sprint and could therefore cause duplicates or data loss.
Requirements
The sprint still exists in the Jira board or backlog. (If the sprint itself was deleted, this is the wrong tool; see below.)
The request is made by a Jira administrator (Agile Hive admin user). Other users receive an "Administrative access required" (HTTP 403) error.
A valid Agile Hive license.
The project key of the affected team project (not the ART project).
Two-step procedure
The recovery process always takes place in two steps: first, preview the changes, then apply the verified mappings.
In the examples <user>:<password>, <jira-base-url> and <TEAM-KEY> are placeholders - replace them with your own values.
Step 1 - Get preview
The preview shows a suggestion for each iteration without a resolvable sprint, indicating which existing sprint it belongs to, along with a confidence assessment.
GET <jira-base-url>/rest/agilehive/latest/public/sprint-reference/suggestions?projectKey=<TEAM-KEY>
Example using curl:
curl -u <user>:<password> '<jira-base-url>/rest/agilehive/latest/public/sprint-reference/suggestions?projectKey=<TEAM-KEY>'
The response contains:
candidates: all existing sprints on the boards of the team project (with board name; Primary Board first).suggestions: one line per iteration without sprint, each with the proposed sprint (suggestedSprintId), whichconfidence, - if confidenceNONE- thenoMatchReasonand theexistingReferenceSprintIds(sprint ID(s) of an existing reference that blocks recovery; empty if none).readyToApplyRequest: a complete application body (projectKeyandmappings), pre-filled with all cleanly applicable suggestions - that is, those with a candidate and without a blocking reference.null, if nothing is automatically applicable.diagnostics: Runtime and scope of the call — total duration (totalMillis), sub-times per step (stepTimingsMillis) and the number of candidate sprints checked (candidatesEnumerated). Shows how extensive and slow the call is on the respective system; the same block is also in the response of the Apply step.
If candidates is empty, there's no recoverable sprint. In that case, "Recreate Missing Sprints" might be the right approach (see below).
Step 2 - Restore (apply)
After reviewing the proposals, the confirmed assignments are applied. Only the pairs from iteration and sprint are passed; the project itself is determined by the call from the data projectKey.
You don't need to build the application body manually: The preview already provides it in the field readyToApplyRequest. If you follow all suggestions, submit it unchanged; otherwise remove the respective entries in mappings (see "Following only individual suggestions"). Confidence is only stored in the `<confidence>` field suggestions - please check it before submitting.
With jq both can be combined:
curl -s -u <user>:<password> '<jira-base-url>/rest/agilehive/latest/public/sprint-reference/suggestions?projectKey=<TEAM-KEY>' \ | jq '.readyToApplyRequest' \ | curl -u <user>:<password> -X POST '<jira-base-url>/rest/agilehive/latest/public/sprint-reference' -H 'Content-Type: application/json' -d @-
Alternatively, assemble the body manually:
curl -u <user>:<password> -X POST '<jira-base-url>/rest/agilehive/latest/public/sprint-reference' \
-H 'Content-Type: application/json' \
-d '{
"projectKey": "<TEAM-KEY>",
"mappings": [
{ "iterationId": 123, "sprintId": 456 }
]
}'
The response reports whether each mapping was successful (success) and, if failed, a reason ( message). Iterations that have already been correctly linked are considered successful without any changes (the call is repeatable without causing harm). Multiple mappings can be passed in a single call; each is checked individually, and an error in one does not block the others.
Following only individual suggestions
If not all suggestions are to be applied, the readyToApplyRequest can be modified before sending. The jq method is recommended because it guarantees the generation of valid JSON.
Using jq to selectively filter out (chain remains): remove the unwanted iterations over its iterationId value (here 5 and 12).
curl -s -u <user>:<password> '<jira-base-url>/rest/agilehive/latest/public/sprint-reference/suggestions?projectKey=<TEAM-KEY>' \ | jq '.readyToApplyRequest | .mappings |= map(select(.iterationId != 5 and .iterationId != 12))' \ | curl -u <user>:<password> -X POST '<jira-base-url>/rest/agilehive/latest/public/sprint-reference' -H 'Content-Type: application/json' -d @-
Conversely, with == instead of !=, only specific iterations can be retained (whitelist).
In the editor, go through the process: save the body to a file, delete entries there, and send the file.
curl -s -u <user>:<password> '<jira-base-url>/rest/agilehive/latest/public/sprint-reference/suggestions?projectKey=<TEAM-KEY>' | jq '.readyToApplyRequest' > apply.json # edit apply.json and remove unwanted entries from "mappings" curl -u <user>:<password> -X POST '<jira-base-url>/rest/agilehive/latest/public/sprint-reference' -H 'Content-Type: application/json' -d @apply.json
When editing the file, ensure the JSON is valid: In mappings, there is a comma between each entry, but none after the last entry. The @ in -d @apply.json instructs curl to read the body from the file (without it, @curl would send the filename as text). The jq method described above avoids this potential source of error.
What does the confidence rating mean?
The proposal compares two independent signals: the expected sprint name and the iteration data (start and end).
Level | Meaning | Recommendation |
|---|---|---|
HIGH | The name and date match and clearly point to the same sprint. | Can be applied directly. |
MEDIUM | Only the name is a clear match (the sprint may have been re-dated). | Check briefly before using. |
LOW | Only the date is definitely correct (the sprint may have been renamed). | Check before using. |
NONE | No applicable suggestion. The field | Depending on which |
For NONE the noMatchReason field states the reason:
AMBIGUOUS - multiple candidates share the same best signal (e.g., two sprints with the same name); there is no clear recommendation. Manually select the appropriate sprint
candidatesand assign it via the Apply step.NO_CANDIDATE_MATCH - no candidate matches by name or date. The sprint is probably missing entirely; in that case, "Recreate Missing Sprints" is the correct approach, not recreating only the SprintReference.
When this feature is NOT the right tool
The sprint was deleted (the preview shows no matching candidates): Then the sprint must be recreated. This is what "Recreate Missing Sprints" is for.
The reference exists but doesn't resolve (in the preview, these iterations are labeled
existingReferenceSprintIdswith the sprint ID of the blocking reference): Since the preview is run as an administrator and uncached, this practically always means that the referenced sprint has actually been deleted. In this case, "Recreate Missing Sprints" is the correct approach, not recreating only the SprintReference - the existing reference would block it (which is why the affected iterations are not included inreadyToApplyRequest). The case "Sprint exists but is not displayed" (permissions or cache issue) is visible to end users in boards and reports, not in this administrative preview; there, a targeted cache flush or checking board permissions will resolve the issue.
Good to know
The feature never creates a new sprint; it only establishes a link to an existing sprint.
It is accessible only to administrators.
Each call is logged in the
atlassian-jira.logfile at INFO level: the preview with the number of candidates and gaps as well as the confidence distribution, and the application with the summary (applied / unchanged / rejected). Both lines specify the Agile Hive admin user used and the duration of the call.Sprints on a non-primary board can also be linked. However, a subsequent "Recreate Missing Sprints" run could remove such a SprintReference.