Syncing Roadmaps with Jira date fields

This guide explains how date syncing works in Easy Agile Roadmaps and how to configure it.

Date syncing is optional. If you don’t set up date syncing, you can schedule issues on the roadmap without changing dates on the issues in Jira.

What does date syncing do?

Date syncing keeps the plans you make in Easy Agile Roadmaps in sync with your Jira data. It uses the date fields on the Jira issues to read and write the schedule of each issue.

When you schedule an issue on the Roadmap, the dates will be updated on the issue in Jira.
If your issues already have dates set, they’ll automatically appear on the Roadmap (in the “Issues without themes” swimlane at the bottom).

How can I tell if date syncing is enabled?

If date syncing is not yet fully configured, a blue “bell” button will show in the app header.

This includes if date syncing is configured for some but not all issue types.

If the button is missing, that means date syncing is working correctly.

The Roadmaps app header showing a blue button with a white bell icon

Configuring date syncing with Jira

You’ll need Jira Administrator permission to configure this.

There are 2 steps to set up date syncing:

Select start and end date fields to use with Easy Agile Roadmaps.
Add the date fields to the Issue screens for relevant Jira projects.

Select date fields

Select a pair of date fields in the global Configuration page for Easy Agile Roadmaps.

This page can be found in Jira’s “Manage apps” settings.

Finding the "Manage apps" settings in Jira Cloud or Jira Data Center

Use the settings button in the top right-hand corner of Jira to open the global Settings dropdown on Jira Cloud or Jira Data Center.

The Jira cloud global settings menu opened from the gear button in the top right, with the Apps item in the dropdown highlighted

Jira Data Center Administration page open to Manage apps tab and Easy Agile Roadmaps Configuration page open and highlighted in the left navigation panel. The global settings dropdown in the top right has been opened from the gear dropdown, with the Manage apps option highlighted.

Missing the settings button?

If the Settings button doesn’t show in the top right-hand corner or the “Apps” / “Manage apps” option isn’t in the list, this means you don’t have “Jira Administrator” permission.

You’ll need to contact your Jira Administrator or internal IT support team to configure date syncing.

Find the “Easy Agile Roadmaps” section in the sidebar to open the “Configuration” page.

The Easy Agile Roadmaps Configuration page open in Jira Cloud's global Apps settings, with the Configuration link to this page highlighted in the left sidebar

Existing date fields will be available to select from the dropdown. This includes:

Custom fields with type “Date picker” (Custom field types in Jira Cloud or Jira Data Center)
“Target start” and “Target end” fields used by Plans for Jira Cloud Premium or Advanced Roadmaps for Jira Data Center

If there is no existing “Start date” field, the app can create it once. If you delete the field, the app will not create any further fields.

If you choose “Disable synchronizing this field”, date syncing will be disabled for Roadmaps on all boards on this Jira site.

Add date fields to Issue screens

Use the “Click Here” link under each dropdown to go directly to the “Associate field to screens” page. This lets you select existing Issue screens to quickly add the field to.

The Associate field Start date to screens configuration page in Jira Cloud. PLAT is entered in the search bar and 2 screens are listed. The checkbox next to both is ticked.

Jira Cloud only: in team-managed projects, you’ll find issue field configuration in Project settings instead.

Tips:

By default, Issue screens are named with the Project key.
Easy Agile Roadmaps can be used on multi-project boards. In this case, you’ll need to add the custom fields to the Issue screens for all the projects.
On Data Center, there are different issue screens for Create, Edit, and View operations by default. The date fields need to be on both Create and Edit screens.

How do Issue screens work in Jira?

Jira uses Issue screens to configure which fields are shown on Jira issues.

Issue Screens are applied using Screen schemes and Issue type screen schemes.
Each Jira project is configured to use an Issue type screen scheme for issues in that project.

Field configuration for both Jira Cloud and Jira Data Center is described by this Atlassian diagram on Configuring issues:

A flow chart showing how Fields and Screens are associated with Projects through 8 configuration relationships

Learn more about configuring issue screens on Jira Cloud or Jira Data Center.

Troubleshooting date syncing

On multi-project kanban boards

Date syncing can fail on kanban boards if there are more than 10 Jira projects in the board and the Kanban backlog is disabled.

When a board includes issues from more than 10 Jira projects, Jira doesn’t show the projects in the “Projects in board” list.

Filter query saying status category not equal to Complete ORDER BY Rank ASC and Projects in board in Jira settings saying The projects in this board cannot be listed because of the complexity of the board filter

When Easy Agile Roadmaps fetches data about this board from Jira, Jira fails to return the full list of projects/issues. This stops the app from fetching all the issues from the board for date syncing.

To resolve this, enable the Kanban backlog on your Jira board in Jira Cloud or Jira Data Center.