User manual — Roadmap App

1) Overview

The Roadmap app displays project milestones on a Gantt-like timeline. It shows milestones from:

Milestones are shown per project according to the current saved view or the default (no view). Saved views control:

Saved views can be either Everyone (visible to all users) or Only me (visible only to the current user).

2) Quick start

3) Important data requirement (milestones will show only when)

To display milestones for a project the project must have at least one of:

If neither exists for that project, the project cannot provide milestones and the timeline will not show bars for it. Create Epics with a duedate or create Versions with release dates in Jira to use the Roadmap for that project.

4) Saved views — behavior & scope

Save new view opens a modal where you enter a view name and choose scope:

The saved-views dropdown loads only two places: Everyone views (global) and your personal views (Only me).

Each view includes:

When a view loads:

5) Config modal — how to enable/disable project milestones

Toggling a button:

6) Ordering and new projects

7) Owner badge and visibility

8) Timeline controls (top bar)

9) Milestone details and release notes

10) Saving & updating views — notes

11) Troubleshooting — missing projects or missing buttons

If a project does not appear or a button is missing, check the following in order:

A) Are you viewing a saved view?

The app shows all projects, but only view-selected projects appear on top. If you expect a project to be pre-selected, ensure the saved view’s milestoneSelection includes it or update and save the view.

B) Does the project have epics or releases?

Epics must be of type Epic and have a duedate set. Releases must be created versions with releaseDate. If neither exists, the project cannot produce milestones.

C) Project availability saved in the view

If the view was saved before the project had epics/releases, the app won’t fetch details automatically unless projectAvailability marks it. Update the view (enable epics/releases or save new view) to record availability.

D) Permissions

You need Browse Projects permission to see project details. If the app cannot fetch getProjectData for a project due to missing permission, it will be excluded from the detailed list.

E) Invalid project key characters

Project keys containing unusual characters may get filtered by the server validation. Confirm the project key uses standard characters.

F) How to test via browser (quick debug URLs)

Useful endpoints for quick checks:

https://your-domain.atlassian.net/rest/api/3/project/search?maxResults=1000
https://your-domain.atlassian.net/rest/api/3/project/PROJECT_KEY/versions
https://your-domain.atlassian.net/rest/api/3/search?jql=project=PROJECT_KEY%20AND%20issuetype=Epic&fields=key,summary,duedate,status,issuetype&maxResults=200

If an endpoint returns 401/403/410, consult the server logs or contact the Jira admin to ensure the app/user has the necessary permissions.

12) Common workflows (step-by-step)

A) Create a shared view for the team that shows epics

  1. Open the configuration modal.
  2. Enable "Use Epics" for any project rows that have Epics with duedates.
  3. Re-order projects if needed.
  4. Click Save new view — name it and choose Everyone → Save.

B) Create a personal view (only you see it)

  1. Configure the modal as desired.
  2. Click Save new view — choose Only me → Save.

C) Add a new project to an existing view

  1. Open the configuration modal while the view is loaded.
  2. Find the new project in the list and click Use Epics or Use Releases (button is available only if projectAvailability is present or data exists).
  3. Click Save current view.

13) Known limitations & notes