gojira

README

GoJira

This module contains code to access Jira, parsing both the JSON API via github.com/andygrunwald/go-jira in jirarest and code to parse a Jira XML file in jiraxml.

Various aggregate staticstics and reports are calculated/generated.

URL Formats

Accessing a list of issues by JQL is avialable via the UI and API:

• UI: https://{jira_host}/issues/?jql=
• API: https://{jira_host}/rest/api/2/search?jql=

REST API Authentication: Basic Auth

The API auth can be provided by Basic Auth using an personsal API Token.

• Docs: https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/
• Token Page: https://id.atlassian.com/manage-profile/security/api-tokens

Note on Hours Per Day and Days Per Week

This module supports custom hoursPerDay and daysPerWeek settings per Jira.

This is described here and set in the UI via the screenshot below,

Ref: https://community.atlassian.com/t5/Jira-Software-questions/What-it-JIRA-counting-as-a-quot-day-quot-in-Time-Tracking/qaq-p/1703409

Also of note is that the hours per day can be set to a decimal value, such as 8.5, but the UI may not show it:

Ref: https://community.atlassian.com/t5/Jira-questions/change-quot-Working-hours-per-day-quot-by-a-decimal-value/qaq-p/583095

Additional Discussion on Jira XML

General Discussion

General discussion including using Jira XML to:

1. export comments and issue link types
2. create CSV for flexible reporting and import

Ref: https://community.atlassian.com/t5/Jira-questions/JIRA-Issue-XML-Export-What-is-it-good-for/qaq-p/603308

Global Config

Working Hours Per Day and Working Days Per Week are global values and cannot be set on a per-project basis.

Ref: https://community.atlassian.com/t5/Jira-Software-questions/Time-Tracking-Hours-Is-it-still-a-global-change/qaq-p/1337399

JQL Examples

Goal	Example
Query by key	key = ABC-123
Query by parent	parent = ABC-123
Query by linked issue	issue in linkedIssues (ABC-123)
Query by reporter	reporter = "foo@bar.com"

https://community.atlassian.com/t5/Jira-questions/How-to-search-all-linked-issues-with-issues-from-specific/qaq-p/1027269

Backlog

Downloading the project backlog view appears to be challenging. Here is some info on attempts to do this.

• What is the equivalent JQL query for a scrum board backlog
• How can I export the Backlog to csv or Excel or TXT?

Roughly:

project = <project_name> AND resolution = Unresolved AND status!=Closed AND (Sprint not in openSprints() OR Sprint is EMPTY) AND type not in (Epic, Sub-Task) ORDER BY Rank ASC

Documentation

Index

• Constants
• func TimeRemaining(status string, timeOriginalEstimate, timeEstimate, timeSpent int) (timeRemainingOriginal, timeRemaining int)
• type Config
  • func NewConfigDefault() *Config
  • func (c *Config) CapacityForDaysPeople(days, people float32) time.Duration
  • func (c *Config) SecondsToDays(sec int) float32
  • func (c *Config) SecondsToDaysString(sec int) string
• type EstimateStats
• type EstimateVsActual
  • func (eva *EstimateVsActual) Inflate()
• type IssuesStats
• type TimeStats
  • func (ts TimeStats) SecondsToDays() (TimeStats, error)
• type TimeStatsSet
• type TimeStatsSets
  • func (tss *TimeStatsSets) AddIssue(iss jira.Issue)

Constants

const (
	StatusClosed            = "Closed"
	StatusInProgress        = "In Progress"
	StatusPOReview          = "PO Review"
	StatusPendingValidation = "Pending Validation"
	StatusReady             = "Ready"

	TypeBug   = "Bug"
	TypeSpike = "Spike"
	TypeStory = "Story"

	WorkingHoursPerDayDefault float32 = 8.0
	WorkingDaysPerWeekDefault float32 = 5.0

	JiraXMLGenerated = time.UnixDate // "Fri Jul 28 01:07:16 UTC 2023"
)

Functions

func TimeRemaining

func TimeRemaining(status string, timeOriginalEstimate, timeEstimate, timeSpent int) (timeRemainingOriginal, timeRemaining int)

TimeRemaining returns calculated timeRemainingOriginal and timeRemaiing and against the timeOriginalEstimate and timeEstimate respectively.

Types

type Config

type Config struct {
	ServerURL          string
	WorkingHoursPerDay float32
	WorkingDaysPerWeek float32
}

func NewConfigDefault

func NewConfigDefault() *Config

func (*Config) CapacityForDaysPeople

func (c *Config) CapacityForDaysPeople(days, people float32) time.Duration

func (*Config) SecondsToDays

func (c *Config) SecondsToDays(sec int) float32

func (*Config) SecondsToDaysString

func (c *Config) SecondsToDaysString(sec int) string

type EstimateStats

type EstimateStats struct {
	WithEstimate    int
	WithoutEstimate int
}

type EstimateVsActual

type EstimateVsActual struct {
	ClosedCount             int
	ClosedCountWithEstimate int
	EstimateDays            float64
	ActualDays              float64
	EstimateRatio           float64
}

func (*EstimateVsActual) Inflate

func (eva *EstimateVsActual) Inflate()

type IssuesStats

type IssuesStats struct {
	WorkingHoursPerDay       float32
	WorkingDaysPerWeek       float32
	ItemCount                int
	ItemCountByStatus        map[string]int
	ItemCountByType          map[string]int
	EstimateStatsByType      map[string]EstimateStats
	TimeOriginalEstimate     time.Duration
	TimeOriginalEstimateDays float64
	AggregateTimeSpent       time.Duration
	AggregateTimeSpentDays   float64
	ClosedEstimateVsActual   EstimateVsActual
}

type TimeStats

type TimeStats struct {
	TimeUnit                      string
	WorkingHoursPerDay            float32
	WorkingDaysPerWeek            float32
	ItemCount                     int
	TimeSpent                     float32
	TimeEstimate                  float32
	TimeOriginalEstimate          float32
	AggregateTimeOriginalEstimate float32
	AggregateTimeSpent            float32
	AggregateTimeEstimate         float32
	TimeRemaining                 float32
	TimeRemainingOriginal         float32
}

func (TimeStats) SecondsToDays

func (ts TimeStats) SecondsToDays() (TimeStats, error)

type TimeStatsSet

type TimeStatsSet struct {
	Map map[string]TimeStats
}

type TimeStatsSets

type TimeStatsSets struct {
	Map map[string]TimeStatsSet
}

func (*TimeStatsSets) AddIssue

func (tss *TimeStatsSets) AddIssue(iss jira.Issue)