Jira Timeline Report

The Jira Timeline Report creates easy-to-understand 🧠, power-point-ready 🖥️ timeline reports!

It can:

• Show how your timeline has changed 📈
• Break out work by "dev", "qa" and "uat" timelines 📊
• Roll up timing data from stories, sprints, epics, initiatives and releases 📶

Privacy Policy

This project does NOT save any JIRA data. In fact, other than transporting an access token to the browser, no JIRA data even flows through our servers.

All the code is open source in Github so you can verify this yourself or host it yourself.

Need Help or Have Questions?

This project is supported by Bitovi, an Agile Project Management consultancy. For bugs or feature requests, please submit a Github Issue.

You can get help or ask questions on our:

• Discord
• Twitter

Getting Started

Bitovi's Agile Project Management with Jira - Reporting training walks through configuring the tool.

Configuration

The following documents how to configure the tool.

Issue Source

Specify a JQL that loads all issues you want to report on and help determine the timeline of your report. The report will load faster the fewer issues you load.

Examples:

• The following loads all Epics and Stories in your jira instance:

  issueType in (Epic, Story) order by Rank
  

  NOTE: Specifying order by Rank will list items in Rank order. This can be useful if you are using Rank to prioritize your issues.

• The following loads all children of the issue PROJ-1.

  issuekey in portfolioChildIssuesOf("PROJ-1") order by Rank
  

  NOTE: portfolioChildIssuesOf is only available with advanced roadmaps.

Primary Timeline

The primary timeline settings configure the main chart. It has two parts.

What Jira artifact do you want to report on?

This configures the primary Jira artifact that be reported in the main chart.

What timing data do you want to report?

This configures the type of report. The options:

• Start and due dates - Create a chart that shows the start and due date for each of the primary Jira artifacts.
• Due dates only - Create a chart that shows only the due dates of the primary Jira artifacts.
• Work breakdown - Create a start and due date chart, but show the start and due dates for work identified as "dev", "qa" or "uat". See Understanding Work Breakdown for more info.

Timing Calculation

The timing calculation section allows you to specify:

• How timing is "rolled up" across issue hierarchy.
• What issue type releases should report on

Old Stuff

Note, your epics and initiatives will need the following statuses for the tool to work:

• Idea, To Do, or Open representing ideas that you might not want on the report.
• QA or In QA - represending work that is in QA.
• Partner Review or UAT - representing work that is in user acceptance testing.
• Blocked - represending work that can not move forward.
• Done or Cancelled - Work that is complete and will be hidden from the report.

The Agile Project Management with Jira - Continuous Exploration training has videos on how to create an initiative type with the right statuses.

How Timing is Calculated

Initiative timing is calculated from epic Start date and Due date fields. Initiative dates are ignored. If the epic does not have a Start date or End date, the stories within the epic can be used to determine the timing of the epic. In this case, the latest story's end date will be used as the epic's End date and the earliest story's start date will be used as the epic's Start date.

Story timing itself is determined from:

• The Start date and End date of the story; or if these don't exist
• The story's sprints

NOTE: To use story timing, you must use a JQL that includes stories.

Labeling epics as QA or UAT

To label epics as part of an initiative's QA or UAT timing, add a Label that includes the characters QA or UAT.

Contributing

Clone the application into your local machine.

git clone https://github.com/bitovi/jira-integrations.git
cd jira-integrations

Getting Environment Variables

The next step is to fill in your environment variables. You can use the .env.example to create your .env in your root folder

cp .env.example .env

Your environment variables can be gotten from Jira following the steps below

• Open Jira developer console. https://developer.atlassian.com
• Navigate to the developer console, it can be found on the top right corner of the screen.
• Create your app and choose OAuth2.0, put in the app name and accept the terms.
• Click Permissions, add the Jira API scope then configure it. Ensure to include the scopes you want and save.
• Click Authorization, input the callback url, as default for this application locally, use http://localhost:3000 (be sure to match the PORT in the server if you changed it) and save.
• Find Settings and scroll down to copy your CLIENT_ID and CLIENT_SECRET.
• The CLIENT_JIRA_API_URL is https://api.atlassian.com.

Note: All environment variables that start with CLIENT will be sent to the client side and exposed.

Navigating the Files

• The server folder contains a server.js which bootstraps an express application that renders the application
• It has an endpoint that fetches the access token from Jira and refreshes the access token when expired.
• The pages folder contains the html files that are rendered.
• The public folder contains the javascript files that are included in the html files.
• The jira-oidc-helpers is a javascript file with all the helpers required to interact with Jira and save your access and refresh tokens to localStorage.
• You will make changes to the main.js files based on your use case. Everything you need to make your request has been layered in jira-oidc-helpers.
• Call the jiraFetch helper with the url path you want from your main and handle the data how you see fit. e.g

const issue = await jiraHelper.jiraFetch(urlPath);