jira-spillover-get

A tool to identify and report Jira "spillover": work items that weren't completed within their originally planned sprint(s). Combine with jira-spillover-chart to transform data into comprehensive charts, pivot tables, and performance insights enabling delivery pattern analysis and optimisation of workflow efficiency.

Table of contents

• Why spillover matters
• What does jira-spillover-get do?
• Key features
  • Who should use this tool
  • Use cases
  • Project structure
• Prerequisites
• Set up
  • PowerShell
  • Windows command line
  • Linux/WSL
• Build the application
  • Windows
  • Linux/macOS
  • Building from source
  • Testing
• Usage
  • Basic execution
  • Parameters
  • Examples
  • Append mode feature
  • Automated execution
• Output format
• Interpreting results
  • Key metrics to review
  • Common patterns and what they mean
  • Recommended actions
• How jira-spillover-get works
  • JQL query
  • Jira field mappings
• Error handling
• Logging
• Performance considerations
• Troubleshooting
  • Common issues
  • Debug information
• Contributing
• License
• Support

Why spillover matters

Spillover represents an inability to complete what was planned within a sprint. While occasional spillover can be justified, ongoing spillover can significantly impact Agile delivery. It indicates issues with planning and execution, leading to delays and reduced efficiency.

The biggest challenge with spillover is tracking its occurrence, as Jira doesn't provide built-in tools specifically for this purpose. This tool fills that gap by creating a TSV (tab separated variabe) output file of work items which have spilled over. The TSV file can be manipulated by Excel of simiar tools to produce rich graphical reporting.

For an in-depth examination of why spillover matters, how to analyse it, and most importantly, what strategic approaches you can implement to reduce it, check out my <exponentiallydigital.com> blog post "Mastering agile spillover, analysis and strategic solutions".

What does jira-spillover-get do?

jira-spillover-get queries a specified Jira project via Atlassian APIs to identify all issues (excluding epics, risks, and sub-tasks) that:

1. were modified within a user-defined timeframe
2. spanned multiple sprints, indicating spillover

Results are shown on-screen and saved as a tab-separated text file for analysis in Excel or similar tools. It can run interactively or in automated workflows such as scheduled tasks or CI/CD pipelines.

Key features

• Multi-sprint Detection identifies issues that have been worked on in more than one sprint
• Flexible Date Filtering filter by specific date range or days prior to today
• Epic Title Lookup automatically retrieves epic titles for linked issues
• Command Line Interface full command line support with interactive fallback
• Append Mode option to append results to existing files instead of overwriting (useful for pulling data from multiple projects)
• Progress Tracking real-time progress indicators for large datasets
• Comprehensive Logging optional detailed logging to timestamped files
• Authentication secure file-based API token authentication
• Project Validation validates project existence before processing
• TSV Output tab-separated values output for easy Excel import

Who should use this tool

• Agile teams looking to reduce their spillover rate
• Scrum Masters and Agile Coaches tracking team efficiency
• Development Team Leads identifying planning improvement opportunities
• Project Managers monitoring delivery predictability

Use cases

• Use with sprint reviews to help identify continuous improvement opportunities
• Combine multiple project spillover data for portfolio analysis
• Building long-term trend data for retrospectives
• Automated reporting pipelines that accumulate data over time

Project structure

└── jira-spillover-get/
    ├── .gitignore
    ├── DIAGRAMS.md                     # Program logic and API interaction
    ├── LICENSE                         # User license
    ├── README.md                       # The file you're reading now :D
    ├── build/
    │   ├── jira-spillover-get.exe      # Windows executable
    │   ├── jira-spillover-get-linux    # Linux executable
    │   └── jira-spillover-get-mac      # macOS executable
    ├── go/
    │   ├── build.sh                    # Unix/Linux build script
    │   ├── build.bat                   # Windows build script
    │   ├── go.mod                      # Go module definition
    │   ├── jira-spillover-get.go       # Go application source code
    │   ├── resource.syso               # Dynamically created by go generate
    │   └── versioninfo.json            # Windows resource definition (file version details)
    └── samples/
        └── all-projects.bat            # batch file for portfolio analysis

Prerequisites

1. Jira API token You need a valid Jira API token file
2. Network access Connection to your Jira instance
3. Project access Sufficient permissions to view the target Jira project

Set up

1. Clone or download the source code
2. Navigate to the go subdirectory
3. Create a Jira API token, see Manage API tokens for your atlassian account
4. Save the generated token somewhere safe eg a password manager etc.
5. Create a text file in a secure location eg. "c:\users\my-name\api-tokens\Jira-API-token.txt"
6. Add a single line to this file with your credentials in the format: "your-email-address:your-api-token"
7. Secure the API token file using one of the following methods

PowerShell

icacls Jira-API-token.txt /inheritance:r /grant:r "$($env:USERNAME):(F)"

Windows command line

icacls Jira-API-token.txt /inheritance:r /grant:r "%USERNAME%:(F)"

Linux/WSL

chmod 400 Jira-API-token.txt && chown $(whoami) Jira-API-token.txt

Build the application

Precompiled binaries are supplied or build your own via

Windows

build.bat

Linux/macOS

chmod +x build.sh
./build.sh

Building from source

# Build for current platform
go build -o jira-spillover-get

# Build for Windows (source not specified to enable resource embedding)
go build -o jira-spillover-get.exe

# Build for Linux
GOOS=linux GOARCH=amd64 go build -o jira-spillover-get-linux jira-spillover-get.go

# Build for macOS
GOOS=darwin GOARCH=amd64 go build -o jira-spillover-get-mac jira-spillover-chart-get.go

NB requires https://github.com/josephspurrier/goversioninfo for embedding Windows file properties in the executable.

Testing

# Run with test parameters
./jira-spillover-get -help

# Validate build
go build && ./jira-spillover-get -help

Usage

Basic execution

Execute the application from the command line. It will prompt you for required parameters if not provided:

jira-spillover-get.exe

All command-line parameters:

jira-spillover-get.exe [-TokenFile token_file_path] [-url jira_base_url] 
    [-project project_key] [-fromdate yyyy-mm-dd] [-daysprior #] 
    [-outputfile filename] [-append] [-pair customfield_xxyyzz] [-log] [-debug] [-? | /? | --help | -help]

Parameters

• -TokenFile path and filename of your Jira API token (email-address:api-token)
• -url Jira base URL (e.g., https://my-company.atlassian.net)
• -project Jira project key (e.g., EXPD)
• -fromdate optional start date in yyyy-mm-dd format. Overrides daysprior if supplied
• -daysprior optional number of days prior to today to check (default: 10)
• -outputfile optional name for output file (default: issues_output.tsv)
• -append append to existing output file instead of overwriting
• -pair customfield_10186 specify the field name is you have paired assignees, this field name is specific to your Jira implementation
• -log enable logging to a file
• -debug enable detailed debugging display
• -? | /? | --help | -help show help message

Examples

Command line with all parameters:

jira-spillover-get.exe -tokenfile my-api-key.txt -url https://my-company.atlassian.net -project EXPD -daysprior 30 -outputfile spillover_report -append -pair customfield_10186 -log -debug

Interactive mode (no parameters):

jira-spillover-get.exe

With authentication and URL:

jira-spillover-get.exe -TokenFile c:\tokens\jira.txt -url https://jira.company.com -project TEAM -fromdate 2025-01-01

Append mode for accumulating data:

jira-spillover-get.exe -project EXPD -daysprior 7 -outputfile weekly_report.txt -append

Combining multiple projects in one file:

rem Create initial file
jira-spillover-get.exe -project PROJ1 -outputfile combined_report.txt

rem Append additional projects
jira-spillover-get.exe -project PROJ2 -outputfile combined_report.txt -append
jira-spillover-get.exe -project PROJ3 -outputfile combined_report.txt -append

Using a custom Pair field

If your Jira instance uses a custom field for pair programming information, supply it with -Pair.

jira-spillover-get.exe -project EXPD -daysprior 14 -Pair customfield_10186 -outputfile spillover_with_pair.tsv

Append mode feature

The -append flag enables accumulation of data across multiple runs:

Benefits:

• Historical Tracking build historical datasets by appending weekly/monthly reports
• Multi-Project Analysis combine data from multiple projects into a single file
• Incremental Data Collection add new data without losing existing results
• Automated Workflows perfect for scheduled tasks that need to accumulate data over time

Header management:

• Headers are automatically written only when creating new files or appending to empty files
• No duplicate headers when appending to existing files with data
• Maintains proper tab-separated format throughout

Automated execution

The command line parameters allow you to run this application from a scheduler like Windows Task Scheduler or via a batch file:

jira-spillover-get.exe -project EXPD -daysprior 30 -outputfile spillover_report.txt -log

Scheduled append example for weekly accumulation:

rem Weekly scheduled task to append new spillover data
jira-spillover-get.exe -project EXPD -daysprior 7 -outputfile monthly_spillover.txt -append -log

Output format

The application generates a tab-separated text file containing detailed information about each spillover issue with the following columns:

• Issue Type
• Issue Key
• Summary
• Status
• Updated Date
• Created Date
• Resolved Date
• Assignee
• Pair
• Project
• Fix Version/s
• Component/s
• Story Points
• Epic Link
• Epic Title
• Labels
• Resolution
• Reporter
• Number of Sprints
• First Sprint
• Last Sprint
• All Sprints

Interpreting results

Key metrics to review

1. Total spillover count the overall number of issues that have spilled over
2. Sprint count how many sprints each issue has been through
3. Time in progress duration between first sprint and last sprint
4. Issue types distribution of spillover across stories, bugs, and tasks
5. Epics epics which have a high number of issues which spilled over

Common patterns and what they mean

• High Bug Spillover may indicate quality issues or inadequate testing
• Story Spillover often suggests scope creep or inadequate refinement
• Multiple Sprint Spillover issues carried across more than two sprints may indicate blocked work
• Epics unclear, poorly defined or frequently changing requirements

Recommended actions

• For issues with high sprint counts, consider breaking them down into smaller pieces
• Review estimation practices if the same issue types consistently spill over
• Identify common blockers that lead to spillover and address them systematically
• Consider a team retrospective specifically focused on spillover patterns and solutions

How jira-spillover-get works

JQL query

The application uses the following JQL pattern:

project = {PROJECT} AND issuetype not in (Epic, Risk, 'Sub Task') 
    AND Sprint is not EMPTY AND updated >= -{DAYS}d

Jira field mappings

The application uses these Jira field mappings (configurable in source):

• Story Points customfield_10002 - standard for Jira Cloud
• Sprint Field customfield_14181 - standard for Jira Cloud
• Epic Link customfield_14182 - standard for Jira Cloud
• Epic Summary summary
• Pair Field customfield_10186 please note that this field number will be unique to your Jira implementation and is not enabled by default. if you don't use "pair" programming you can ignore this field

Error handling

The application includes comprehensive error handling for:

• Network connectivity issues
• Authentication failures
• Invalid project keys
• Malformed API responses
• File I/O errors
• Date format validation

Logging

When enabled with the -log flag, the application creates timestamped log files:

jira-spillover-get-YYYYMMDD-HHMMSS.log

Logs include:

• API request details
• Progress information
• Error messages and warnings
• Execution timing statistics

Performance considerations

• Execution performance depends on the number of issues in your project and the time range selected, it has been optimized for batching Jira queries and parallel lookups
• For extremely large projects and a large date range, consider running after-hours or using smaller time ranges
• Typical execution time ranges from 2 seconds to minutes depending on how many days prior you elect and the volume of issues in your project
• Recommended execution frequency at the end of every sprint or for an entire program increment or set of increments
• This application has been designed to return thousands of issues over multiple years

Troubleshooting

Common issues

1. Token file not found

   • Ensure the token file exists at the specified path
   • Check file permissions

2. Authentication failed

   • Verify your Jira credentials in the token file
   • Ensure the token file format is correct (email-address:token)
   • Check that the API token is still valid

3. Project not found

   • The project code might not exist
   • Check the project code spelling and case
   • Verify you have permission to view the project

4. API connection issues

   • Verify network connectivity to Jira
   • Check if you're behind a corporate firewall/proxy
   • Ensure the Jira URL is correct and accessible, try accessing it in a browser

5. No issues found

   • Check if the project has Story/Task/Bug issue types
   • Verify the date range (if specified) contains resolved issues
   • Ensure the project contains work items

6. Export file issues

   • Ensure you have write permissions to the target directory
   • Check that the output filename doesn't contain invalid characters
   • Verify the output directory exists (the tool creates files but not directories)
   • When using -append, ensure the existing file format matches

7. Automatic date detection issues

   • If no date range is detected, verify the project contains resolved issues
   • Check that issues have valid resolution dates in Jira

Debug information

The tool provides detailed progress information including:

• Authentication source and validation
• Project validation results
• JQL query construction
• API request progress and batch information
• Issue processing and with the optional '-debug' command line switch, display of each work item's sprint data during processing

All debug information is logged to timestamped log files for later analysis.

Contributing

Contributions to improve this tool are welcome! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request with a clear description of the improvements

Please ensure your code follows existing style patterns and includes appropriate comments.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses.

For the purposes of attribution please use https://www.linkedin.com/in/andrewnewbury

Copyright (C) 2025 Andrew Newbury

Support

This tool is unsupported and may cause objects in mirrors to be closer than they appear etc. Batteries not included.

It is suggested that you test this tool in a non-production environment to ensure it meets your needs.