Enable the roadmap

Are you on the right help page?

The following information only applies to team-managed projects.

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

The roadmap is where you can create, manage and visualize your team's issues. 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 team-managed Jira Software project.

  2. From your project's sidebar, select Project settings > Features. (NOTE: This requires admin permissions.)

  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 team-managed project.
  1. Filter by issue summary, assignee, status category, versions, label, or type: Use the text filter, assignee, status, versions, label, or type filters to specify which issues display on your roadmap. The filters automatically appear when you add an assignee to an issue, create more than one type of issue, or add a label to an issue on your roadmap. The text field is always available, and all filters apply to epics and child issues. Learn more about filters on the roadmap.

  2. Schedule bars: Each bar represents how long your tasks are scheduled to take. To see the exact dates of an epic, hover over its schedule bar. Sprints that have both start and end dates, and are associated with the board will be listed at the top of the roadmap, along with the months. Schedule bars for child issues are only currently available for scrum teams.

  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 team-managed project are considered resolved when they’re moved from the In progress to Done status category. This is an automatic behavior in team-managed.

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.

  • Filter by issue summary: Find and refine your roadmap by searching for keywords. As you start typing in the text field, the filter narrows down your roadmap as it matches the text to the summary field on an issue. The filter applies to epics and child issues.

  • Filter by assignee: Use this filter to focus on your own (or someone else's) work. This filter will automatically appear when you add an assignee to an issue. If your roadmap is filtered by assignee, any new issue created on the roadmap will be assigned to the most recent selection.

  • Filter by status category: This filter allows you to filter by a status category, either To do (represented as a grey status), In progress (represented as a blue status), or Done (represented as green status). The filter applies to the epic and its child issues.

  • Filter by versions: This filter shows or hides issues based on the fix version to which they are assigned. Only versions that apply to at least one item on your roadmap will appear in the dropdown menu, excluding archived versions.

  • Filter by label: Any label added to an issue on your roadmap will show up in this filter. Select one or more labels from the list to refine your view. If your roadmap is filtered by a label, then any new issue created on the roadmap will inherit the same label.

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 team-managed 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 Jul 12, 2021
Cached at 7:29 AM on Jul 28, 2021 |

Additional Help

Ask the Community