Enable the roadmap

Are you on the right help page?

The following information only applies to next-gen projects.

To check which type project you need help with, look at the bottom of your project’s left-hand sidebar:

  • If you see an icon stating You’re in a next-gen project with Give feedback and Learn more menu items, you're in a next-gen project.

  • If you don't, you're in a classic project. Check out our classic project documentation.

The roadmap is where you can create, manage and visualize your team's epics. Roadmaps are useful for planning large pieces of work several months in advance, and planning large groups of stories across different sprints.

Learn more about the benefits of roadmaps.

Enable/disable the roadmap

  1. Navigate to your next-gen Jira Software project.

  2. From your project's sidebar, select Project settings > Features.

  3. Enable or disable the Roadmap feature.

Understand your roadmap

The roadmap comes with the following features:

An annotated image of the roadmap in a next-gen project.
  1. Filters - Use the assignee and type filters to specify which issues are displayed on your roadmap. These filters will automatically appear when you add an assignee to an issue or create more than one type of issue.

  2. Date ranges: Hover on an epic to view its date range. Drag its left and right edges to adjust the date range, or click the epic to open it and edit its details.

  3. Views settings: A collection of settings that allow you to adjust your personal view of the roadmap. The settings only apply to you and although we remember your preference, you can change your view at any time.

  4. Add issues to epics: Click an epic to open its details and add child issues. They'll automatically appear on your board and backlog (if you've enabled the backlog feature).

  5. Timeline: Change the zoom level of your roadmap to view upcoming weeks, months, or quarters by selecting this dropdown.

Customize your view

The roadmap has built-in filters to help with issue management and make things run faster. For now, your roadmap will display 300 epics and 3000 issues. The roadmap also excludes any issues that are considered complete.

Complete issues on the roadmap

Issues in a Jira Software next-gen project are considered resolved when they’re moved from the In progress to Done status category. This is an automatic behavior in next-gen.

The roadmap, however, refers to a different field – the Status category change date – to define completed issues. This makes sure the roadmap always refers to a consistent field and doesn’t get muddled by different workflows. Learn more about the resolution field in Jira Software.

The roadmap uses the Status category change date to filter out:

  • Issues that were Marked as Done over a year ago.

  • Issues that were resolved with a due date from over a year ago.

This logic always applies to the roadmap, even if you adjust your view settings.

Adjust your view settings

The View settings will let you specify which epics to display, with the exclusions mentioned above applied. You can refine your view so the roadmap displays All, Complete, or Incomplete epics.

A cropped screenshot of the view settings panel on the roadmap. A dropdown is selected with different display options

Incomplete epics, even those created more than a year ago, will always be available on your roadmap.

To include dependencies and progress on your roadmap, tick the relevant checkbox. To exclude them, just untick the checkbox.

A cropped screenshot of the view settings panel, displaying the extra details available on a roadmap

The refined roadmap will automatically refresh to display your selections.

Apply filters on top of your custom view

You can add additional filters to get a really focused view of the roadmap.

Display epics and issues from a specific status category, or particular issue type. Just keep in mind how your view settings and filters work together. For example, the roadmap won’t be able to display issues with the Done status category, if your view settings are set to display Incomplete epics.

Share your roadmap

Export your roadmap

You can share your roadmap with offline users by exporting it as an image (PNG format) to use in a presentation, attach to project documentation, or even to print as a poster for your team's wall. 

To export a roadmap to an image:

  1. While viewing your roadmap, select Export

  2. Choose the Timeline view, Start date and End dates, then select Export

The export roadmap dialogue, with a timeline dropdown menu, and start/end date selector.

Your browser automatically downloads the image.

Add your roadmap to a Confluence Cloud page

You can add your team's roadmap to a Confluence Cloud page using the Jira Roadmap macro. Roadmaps you add to a Confluence Cloud page will update in real-time, and you can interact with it just as you would in Jira.

There are 3 ways to add your roadmap to a Confluence Cloud page.

Option 1: Paste a URL

  1. Go to your next-gen Jira Software project and view the Roadmap.

  2. Copy the URL from your browser.

  3. Paste that URL directly into your Confluence page.

It will automatically be transformed into a Jira Roadmap macro.

Option 2: Macro shortcut menu

  1. Bring up the macro shortcuts menu with either '/' (in the new Confluence Cloud editor) or '{' (in the classic editor). 

  2. Search for Jira Roadmap.

Cropped image of a the Jira Roadmap macro in Confluence.

Option 3: Macro menu

  1. Select the macro menu ().

  2. Select Jira Roadmap

A plus symbol (+) represents the macro dropdown menu. The Jira Roadmap macro is listed, among several other macros.

Troubleshoot your roadmap

Sometimes a project, or the epics and issues it contains, can prevent you from accessing the roadmap.

Project exceeds issue or epic limit

If your project contains more than 3000 issues or 300 epics, the roadmap won’t display.

There’s a filter built into the roadmap, and it automatically exclude epics, if:

  • The epic was moved to the Done status category more than a year ago.

  • The epic was moved to the Done status category, and it has a due date from more than a year ago.

It's good practice to set due dates on your epics, so you’re reminded to mark them as done or adjust the due date. You can find the Due date field within the issue view of the epic.

No epic issue type

If your project doesn't have an epic issue type, the Roadmap won't display. Note that the issue type must be a high-level issue type, so a regular issue type that happens to be called "Epic" still won't work. To fix this, you can navigate to the Roadmap to either create a new epic issue type, or select an existing issue type and designate it as the epic issue type.

No date fields on epic issue type

Epic issue types must have a Start date and Due date field to display on the Roadmap. If these are deleted, you can navigate to the Roadmap to have them re-added.

Accidentally converted a story-level issue type to an epic

If you've mistakenly converted an issue type to an epic, and your issues no longer display on the board and backlog, you can restore these issues to their original state with the following steps:

  1. Create a new story-level issue type.

  2. Delete the 'wrong' epic type (that was converted).

  3. As part of the issue type deletion process, you'll be asked which new issue type you'd like to move all your issues to.

  4. Select the new issue type you created.

  5. Rename this new issue type to your old one, if you want to.

Manage corrupt issues

An issue's considered corrupt if certain details, like the issue type, status, status category, or rank settings are invalid. The details might have been missing when the issue was created or something might have gone wrong with a bulk import.

The roadmap won’t display until the details in the corrupt issue are fixed.

To fix a corrupt issue, you must raise a support ticket. Our team will help fix the issue so you can continue using your roadmap.

Learn more

Last modified on Oct 9, 2020
Cached at 2:24 AM on Oct 30, 2020 |

Additional Help

Ask the Community