Syncing JIRA projects to Forecast projects

This article details the sync options available within the JIRA for Forecast integration. How to synchronize Forecast projects with JIRA, definitions of the various sync settings available and how each impacts the integration are explained below.

This article includes:

Overview of the JIRA for Forecast integration sync
JIRA for Forecast integration sync settings
Synchronizing existing projects with JIRA (Settings > Integrations)
Synchronizing existing Forecast tasks and phases with JIRA (Move to JIRA)
Creating new projects from JIRA Projects or Epics (Admin > Integrations)
Additional JIRA sync settings
Synchronization error logs

Overview of the JIRA for Forecast integration sync

It is possible to sync new and existing projects between Forecast and JIRA.

Forecast projects may be synced to a single JIRA project or one or more JIRA epics. Both sync types (projects or epics) include various settings allowing customization over how the data is synced with JIRA and how that synced data will appear in Forecast.

JIRA for Forecast integration sync settings

The following sync settings appear for both sync types, Sync to Jira project and Sync to Jira epics.

Sync Setting	What it does	Setting options	Action/Result
Synchronize Sprints	Syncs sprint data across platforms	Yes No	If Yes: Select the JIRA board from the dropdown.
Synchronize Remaining time	Syncs remaining time across Forecast tasks and their corresponding JIRA issues.	Yes No	If Yes: The Forecast project will be set to use manual remaining. The remaining values of your tasks will be synchronized with their JIRA issues.
Synchronize the Jira items from a specific day onwards	Also known as JIRA Cut-off date, enables data sync as of a certain date forward.	Yes No	If Yes: Select the date from the calendar. Sprints, versions and worklogs occurring after the Jira cut-off date will be synced. Issues without a due date or with a due date occurring after the Jira cut-off date will be synced.
Estimate Type	The format of task/issue estimates.	Time Original Estimate Story Points / Custom field	For Story Points/Custom field: Select the custom field from the dropdown. Custom field values will be synchronized to Forecast as story points.
Select between Jira Versions or Epics to sync as Forecast Phases (for the sync type: Sync to Jira project ONLY)	Determines if Forecast Phases will sync to JIRA Epics or Versions/Releases.	Epics Versions / Releases	Epics: Jira Epics will sync to Forecast as Phases. For Versions / Releases: Jira Versions/Releases will sync to Forecast as Phases.
Create Jira sub-tasks as	Determines how JIRA subtasks will sync.	Tasks or subtasks To-do	Tasks or subtasks: Syncs task to subtask hierarchy To-do: Syncs subtasks as to-dos on the parent task

Synchronizing existing Forecast projects with JIRA (Settings > Integrations)

Once the integration is live, users with Manager permission or above may configure a project's sync with JIRA using the project's Settings > Integrations page.

How to synchronize an existing Forecast project with JIRA

If you haven’t done so already, set up the Jira integration following the Setting up the JIRA Cloud for Forecast integration article.
Click Projects in the top bar.
Select All Projects from the dropdown.
Click on the project you wish to sync.
In the left side panel, click Settings.
Select Integrations.
Click on Sync to Jira project or Sync to Jira epics.
From here, continue configuring the sync by selecting the appropriate sync settings for the project.

A list of all sync settings and the expected result are outlined in the JIRA for Forecast integration sync settings section of this article.

Synchronizing existing Forecast tasks and phases with JIRA (Move to JIRA)

Existing Forecast projects may contain tasks that do not exist in JIRA. Once the project's sync is configured, it is possible to create new issues in Jira from existing Forecast tasks using the project's Scoping page. If you are looking to move existing Forecast tasks to JIRA see Synchronizing existing Forecast tasks and phases with JIRA (Move to JIRA).

Creating new projects from JIRA Projects or Epics (Admin > Integrations)

Alternatively to syncing projects already existing in Forecast with JIRA, new Forecast projects may also be created from existing JIRA projects. This action is available to Forecast Administrators only as it is done within the Company's Integrations page.

Creating a new Forecast project using Sync Project

If you haven’t done so already, set up the Jira integration following the guide found here, Setting up the JIRA Cloud for Forecast integration.
Click Admin in the top bar.
Select Integrations from the dropdown.
Click on the JIRA icon corresponding to your JIRA instance (JIRA Cloud/JIRA Server).
Scroll down and select the tab for Projects.
1. Projects returns a list of all Not synced Jira projects while Epics returns a list of all Not synced Epics.
In Sync Jira project, Forecast Project Name defaults to the JIRA project name. This can be changed as needed.

Note: Project Name is not included in the data flow and any changes made in in one platform will need to be made manually in the other, as needed.
Select a project color, assign Start and End dates and Client.
Expand More Settings to complete the project budget details.
The remaining settings apply to the project's sync with JIRA.
1. To select the appropriate sync settings, see JIRA for Forecast integration sync settings.
Click Sync Project.
1. synchronization complete will appear once the sync is complete and the new Forecast project has been created.
  1. Select Sync more Projects to create another project and configure its sync with Jira.
  2. Select Go to Project to access the newly created project in Forecast.

Like Sync project, Admins may also create new Forecast projects from one or more JIRA epics from the Company's Integrations page.

Creating a new Forecast project using Sync Epics

If you haven’t done so already, set up the Jira integration following the guide found here, Setting up the JIRA Cloud for Forecast integration.
Click Admin in the top bar.
Select Integrations from the dropdown.
Click on the JIRA icon corresponding to your JIRA instance (JIRA Cloud/JIRA Server).
Scroll down and select the tab for Epics.
1. Projects returns a list of all Not synced Jira projects while Epics returns a list of all Not synced Epics.
Tick the box for the JIRA epic/s.
1. The multi-select drawer appears indicating the count of selected epics.
If multiple epics are selected, Click Sync Epics in the drawer.
1. If a single epic is selected, Sync epic may also be selected on the right of the selected epic.
In Sync Jira epics, confirm the selected Jira epics.
1. If additional epics are required, but not selected in the previous multi-select, they may be selected here.
Review the count of Phases, Tasks and Subtasks that will be synced.
Enter the Forecast Project Name, Project Color, and assign Project Start and End Date and Client.
Expand More Settings to complete the project budget details.
The remaining settings apply to the project's sync with JIRA.
1. To select the appropriate sync settings, see JIRA for Forecast integration sync settings.
Click Sync Project.
1. synchronization complete will appear once the sync is complete, displaying the count of successfully synced Jira epics and confirmation the new Forecast project has been created.
  1. Select Sync more Projects to create another project and configure its sync with Jira.
  2. Select Go to Project to access the newly created project in Forecast.

Setting a Jira Cutoff Date

JIRA Cutoff date allows users to select how much data will sync from JIRA to Forecast. A Cutoff Date can be set during initial sync configuration or it may be applied to an existing project already synced with JIRA. When a cutoff date is set, issues, versions and/or sprints with dates on or after the cutoff date will sync with Forecast. Issues, versions and/or sprints with occurring before the cutoff date will not sync. Issues, versions and/or sprints without dates in JIRA will be included in the cutoff date sync.

How to set a JIRA Cutoff date during sync configuration

To set a JIRA cut off date during initial sync configuration, see the JIRA for Forecast integration sync settings section of this article and What is a JIRA Cutoff Date?

How to add a JIRA Cutoff Date for an existing project already synced with JIRA

Projects that are already synced with Jira can also have a cutoff date enabled. Changing the cutoff date on a project will immediately initiate a sync of the project with the new setting, and the fields will be disabled while this sync is in progress.

Click Projects in the top bar.
Select All Projects from the dropdown
Open the project you wish to sync.
On the left side panel, click Settings.
Select Integrations.
Under the Jira section there will be a checkbox and date field.
Click the box next to Exclude items with due date before.
Click the calendar icon and select the date from which to sync from.
The project sync will immediately initiate to reflect the new cutoff date settings and a message will appear in red, "The options cannot be changed while the data sync is in progress. Please check back later" indicating the sync is in progress.

Additional JIRA sync settings

There are additional JIRA sync settings available within the Admin panel. Here is it possible to change JIRA prefix settings, synchronize start date fields and manage the Tempo Timesheets for JIRA add-on.

Changing JIRA prefix settings

Once the Jira integration setup is completed, it is possible to set the Jira prefix settings to determine how the task title will appear in Forecast. By default, the prefix setting will be set to None.

How to access and change Jira prefix settings

Click Admin in the top bar.
Select Integrations from the dropdown.
Select Jira Cloud.
In Settings, select the desired prefix: None, Simple, or Full.

None:
Simple:
Full:

Synchronizing JIRA issue date fields with Forecast

It is possible to synchronize start dates on existing Forecast tasks with the start dates from JIRA issues. If dates are not identical, the start date in JIRA will override the start date on Forecast tasks. It may take up to 24 hours for the change to become visible in Forecast

How to change the start date

Click Admin in the top bar.
Select Integrations from the dropdown.
Select Jira Cloud.
Click on the Change button under the Start Date Settings.
Select one of the three available options.

Click on change. This will set the start date of tasks (issues) in the Jira synced Forecast projects to start based on the field of your choosing.

Configuring and managing Tempo Timesheets tokens

Within JIRA it is possible to track time using the native application or by Tempo Timesheets. In order to synchronize time registrations from Tempo to Forecast, a token must be authorized and configured within the Company's Integrations page.

To learn how to configure a Tempo token see How to sync time registrations from Tempo to Forecast and Using OAuth 2.0 Authentication within the Tempo Timesheets Help Center.

Synchronization error logs

If a project sync fails, the details of the errors will appear in the project's Settings > Integrations page. If you see or suspect data may not have synchronized with JIRA, check the project's error logs for more information. Any errors occurring within the last week will be displayed.

Accessing synchronization error logs

Click Projects in the top bar.
Select the project you wish to review.
Click Settings in the left side panel.
Select Integrations.
Scroll to the very end of the JIRA section.
Any synchronization errors will appear here inclusive of the reason/s why.

What can we help you with?