Skip to content
main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.

jira-status-reporter

Collection of node scripts to query, store, and report on Jira issues.

Features

  • Timeline: See the history of an issue using vis-timeline. Here's a full timeline, showing all change events: Full Timeline Here's a filtered timeline - just add the fields you want to see as the value of the "field" query parameter (e.g. ?field=status,labels,Component,priority,assignee,issuetype): Filtered Timeline
  • Estimate Report: See which Stories have/have not been estimated User Report
  • User Report: See progress on Stories, per Assignee User Report
  • Graphical display of issue links (using Mermaid) Links with icon Links without icons
  • JSON/HTML list of projects (with or without issue type counts) Project list - sample
  • JSON/HTML list of fields (standard & custom) Field list - sample

Installation and Setup

For live queries

  • git clone https://github.com/jolewis-ddn/jira-status-reporter
    cd jira-status-reporter
    npm install
    mkdir data

Configuration

  • Copy (or rename) default-template.json to default.json
    • Note: Other formats may be used. See node-config Configuration Files wiki page for full details. The fields in default-template.json` must exist in whatever config file/format you choose.
  • Update the values in default.json as appropriate
    • fa is optional and must include the full URL to your FontAwesome JavaScript kit - e.g. , "fa": "https://kit.fontawesome.com/0123456789.js"
      • If you enable FontAwesome, you may wish to adjust the faIcons object to point to different icons.
    • All others fields are required

For cached queries

  • Create the database (where DATABASE_NAME is set in the config file (or dataPathPrefix + 'jira-stats.db' by default))
    • cd $dataPath
      sqlite3 DATABASE_NAME
      >.read ../jira-stats.sql
      >.quit
      

Running

node app.js

Cache notes

  • ?flush=yes is available for many endpoints to force a cache refresh. Note: this will wipe out the cache for all users

Endpoints

  • /: no-op

Configuration

  • /components: Unique and sorted list of all the Components
  • /config: Current config
  • /fields: All Jira fields (standard and custom)

Requirements

  • /requirements: Requirements report (cached)

Estimates

  • /estimates: List which Stories have been estimated (cached)

Issues

  • /chart: Visualize timeseries data using cache
  • /dashboard: Data visualization of current status (no cache)
  • /epics: Visualize Epic status (includes linked issues)
    • Parameters:
      • id: Jira key value (Required; no default)
      • release: Only include issues that have a matching fixVersion.Name value. No value supplied = no filter (Optional; no default)
    • Note: response is cached on the first request.
  • /filter: Visualize issue status using existing Jira filter
  • /issueTypes: List of issue types (either project-specific or global)
  • /links: Visualize issue links
  • /remainingWorkReport: Per-issue work left for specified release. [See config option "workInSubtasksOnly" for important information impacting this report.]
  • /report: Simple data report on issue statuses over time (epic count, open issue count, updates this month/week, etc.)
  • /timeline: Show the history of an issue (uses vis-timeline)
  • /unestimated: Table showing the number of unestimated Stories (with a link to Jira)

Releases

  • /burndown: Burndown charts (with optional forecast) for all issues or specific release and/or Component
  • /releases: List of versions (cached); links to /progress
  • /progress: Release progress report (parameter: release ID)

Users and Groups

  • /groups: Shows a list of groups.
    • ?format=html to see the list in HTML (unordered list)
    • ?filter=yes to see the subset (as specified by the userGroups config value)
      • If userGroups array is set in the config, it will be excluded (and the members of the remaining groups will be fetched).
      • If userGroups is not set, the full list of groups (without members) will be fetched.

Cache

General

  • /cache/stats: All dates covered by cache
  • /cache/flush: All dates covered by cache

JSR Cache

  • /dates: All dates covered by cache
  • /homedir: The current root cache folder
  • /series: Issue counts by status
  • /cacheJSR: Current in-memory cache
  • /datafilesJSR: List of data files in cache
  • /rebuild-cacheJSR: Delete and recreate the cache from source data
  • /refresh-cacheJSR: Update the cache with new source data files
  • /reread-cacheJSR: Re-read the cache from disk
  • /resetJSR: Re-initialize the cache
  • /update-cacheJSR: Add missing files to the cache
  • /wipe-cacheJSR: Delete the cache

Usage example

  1. Collect status for a specific month: ./getIssueCountsByMonth.sh <month-number> (e.g. 6 for June)
  2. Collect stats for a specific status and month: node getIssueCountsByStatusAndMonth.js -s ICEBOX -m 6
  3. Pull all Jira issue data for all statuses from yesterday and store as JSON files in ./$dataPath/: ./pullDataForYesterday.sh
    • ** Warning ** This can result in significant data storage, depending on your Jira project size
  4. Run the status server
  • Production: npm run server
  • Debug: npm run server-debug
  1. Open http://localhost:9999/chart to see the default chart (use server.port as set in your config file)
  • You can specify alternate configurations by setting NODE_ENV.
    • For example, if a config file named Production.json exists in the config directory, setting NODE_ENV to Production before running JiraStatusServer.js will pick up the values from config/Production.json (or config/Production.yaml or any other config file supported by node-config (see above).)

Configuration File

The following elements can be set in the config file:

  • jira:
    • protocol: http or https
    • host: Jira server hostname
    • username: Full Jira username
    • password: User password or token with sufficient rights to execute the queries
    • apiVersion: Set to the integer or latest
  • server: Local server port
  • graphicServer
  • project: Jira project as the default
  • dataPath: Relative path to data files (Default: 'data')
  • ignore
  • fa: Font Awesome link (full URL, including .js)
  • forecast
    • teamSize: Additional forecast line on burndown chart based on team size
  • userGroups: Groups in Jira which are commonly used; membership is fetched only for groups in this list
  • userExclude: Individuals to not include in userGroup membership (type: array)
  • releaseExcludeTypes: Status(es) to exclude from the Progress Report (type: array) [Note: this has the same result as using the exclude query parameter, but cannot be overridden by the end user.]
  • adminKey: Parameter to enable/display administrative functions
  • issueTypes: Optional list of specific issue types. (Default: Epic, Story, Task, Sub-task, Bug, Test)
  • unassignedUser: String to represent unassigned items. May be used in various reports (including remainingWorkReport). (Default: 'UNASSIGNED')
  • workInSubtasksOnly: Boolean indicating whether or not Stories contain work in addition to work in Sub-Tasks. If this value is true then Stories that contain Sub-Tasks do not contain work in themselves (i.e. all work is in the Sub-Tasks). If this value is false then Stories may contain work above and beyond work estimates in the Sub-Tasks. (Stories without Sub-Tasks are always included.) This is currently only honored by the Remaining Work Report, which now shows, at the top of the report, a string indicating this value: "Stories with Sub-Tasks are shown/included" (false) or "Stories with Sub-Tasks are not shown/included" (true). (Default: false)

Getting help

  1. All node scripts have a help page: node script.js --help

Development setup

To turn on debug output, set the DEBUG environment variable, like so:

set DEBUG=*

Folders

  • ./$dataPath/: Where the database and all JSON files will be stored (dataPath is set in Config file; default = 'data')
  • ./.cache/: Project data (JSR) cache

Main Files

  • JiraStatusServer.js: Run a local server for handling queries
  • JiraStatusReporter.js: The main Javascript class
  • *.sh: Shell-wrappers for the Javascript files
    • pullDataForYesterday.sh queries and stores all Jira issues by Status for the prior calendar day. All data is stored in ./$dataPath/*.json files with the Status and date in the filename.
  • get*.js: Query (and store) Jira issue details (counts or data)
    • getIssueCounts* only return a total number
    • getIssues* return the full Jira issue data
  • jira-stats.sql: Table definition for local jira stats

Dependencies

  • Node modules
    • jira-client: Main Jira client tool
    • commander: For parsing command line options
    • restify: For simple-server.js
    • debug: For logging
    • supports-color: For debug
    • date-fns: For date manipulation
    • ava: For testing
    • istanbul: For test coverage
    • rando.js: For random chart IDs
    • node-config: Manages configuration
    • node-cache: Manages general cache
  • Working QuickChart server

License

Distributed under the MIT license. See LICENSE for more information.

https://github.com/jolewis-ddn/

About

Restify server to retrieve, cache, consolidate, and reformat Jira issue status

Topics

Resources

License

Packages

No packages published

Languages