iteration-fetcher

iteration-fetcher

Finds the active iteration and fetches all work items within it. Handles both explicit iteration path configuration and automatic date-based detection. Returns work items filtered to the configured workItemTypes.

Finding the Active Iteration

With iterationPath configured

Fetch all iterations for the team and find the one whose path matches iterationPath:

GET {orgUrl}/{project}/{team}/_apis/work/teamsettings/iterations?api-version=7.1

If no iteration matches the configured path, halt immediately:

ERROR: Iteration path 'MyProject\Sprint 5' not found in project 'MyProject'.
Check ado.iterationPath in .sprint-agent.json.
Available paths are listed in Azure DevOps under: Boards → Project Settings → Iterations.

Without iterationPath (date-based detection)

Fetch all iterations for the team:

GET {orgUrl}/{project}/{team}/_apis/work/teamsettings/iterations?api-version=7.1

Find the iteration where attributes.startDate ≤ today ≤ attributes.finishDate.

• Use the UTC date for comparison
• If multiple iterations match (overlapping dates), use the first result
• If no iteration matches: return { noActiveIteration: true, iterationName: null }

Note: noActiveIteration: true is informational — not an error halt. The ticket-ingestion skill handles this as an early exit with an informational message, consistent with how sprint-fetcher documents noActiveSprint.

If team is not configured, replace {team} in the URL with the project name (ADO uses the project-level default team in this case).

Fetching Work Items

Once the active iteration is identified, fetch work items in two steps.

Step 1 — Get work item IDs

GET {orgUrl}/{project}/{team}/_apis/work/teamsettings/iterations/{iterationId}/workitems?api-version=7.1

This returns an array of { id, url } objects in workItemRelations. Extract the id values from the target.id field of each relation.

Step 2 — Batch-fetch work item fields

Send work item IDs in batches of up to 200:

POST {orgUrl}/{project}/_apis/wit/workitemsbatch?api-version=7.1
Content-Type: application/json

{
  "ids": [4721, 4722, ...],
  "fields": [
    "System.Id",
    "System.Title",
    "System.Description",
    "System.WorkItemType",
    "System.Tags",
    "System.AreaPath",
    "System.AssignedTo",
    "Microsoft.VSTS.Common.Priority"
  ]
}

Repeat with the next batch of 200 IDs until all work items are fetched. Add a 100ms delay between batches when the iteration contains more than 200 items. Follow the rate-limiting guidance in connector-guidelines.md.

Partial failure: If any batch request fails after the first succeeds, halt with:

ERROR: ADO work item batch fetch failed at offset {n} (fetched {n} of {total} items).
Retry /sprint-plan to re-fetch.

Step 3 — Fetch relations (for link mapping)

For each work item, fetch relations to capture dependency links. Because workitemsbatch never returns relations, per-item fetching is always required (when the ≤50 guard below passes). Fetch each item individually using:

GET {orgUrl}/{project}/_apis/wit/workitems/{id}?$expand=relations&api-version=7.1

Only fetch relations if there are 50 or fewer work items in the iteration, to avoid excessive API calls. For larger iterations, links will be an empty array in the normalised output.

Work item type filtering

After all pages are fetched, filter work items to those whose System.WorkItemType is in the configured workItemTypes array (default: ["User Story", "Bug", "Task"]). Filtering is case-insensitive. Discard non-matching work items silently.

Output

{
  "noActiveIteration": false,
  "iterationId": "iter-abc-123",
  "iterationPath": "MyProject\\Sprint 5",
  "iterationName": "Sprint 5",
  "total": 18,
  "workItems": [
    {
      "id": 4721,
      "fields": {
        "System.Id": 4721,
        "System.Title": "Add login endpoint",
        "System.Description": "<p>Implement JWT-based auth</p>",
        "System.WorkItemType": "User Story",
        "System.Tags": "api; auth",
        "System.AreaPath": "MyProject\\Backend\\Auth",
        "System.AssignedTo": { "uniqueName": "[email protected]" },
        "Microsoft.VSTS.Common.Priority": 2
      },
      "relations": [
        {
          "rel": "System.LinkTypes.Dependency-Forward",
          "url": "https://dev.azure.com/your-org/MyProject/_apis/wit/workitems/4722"
        }
      ]
    }
  ]
}

When no active iteration is found:

{ "noActiveIteration": true, "iterationName": null }