Synchronizing PSA Project Tasks to Jira Issues

The synchronization between project tasks and issues is controlled by fields on the PSA Direct for Jira Settings tab.

If you enable Sync PSA Project Tasks to Jira Issues, eligible project tasks are synchronized to Jira. A project task is eligible for synchronizing if all of the following are true:

  • The Jira Issue Type Category and Jira Issue Type fields are populated.
  • The related project is linked to a Jira project or Jira issue.
  • If the project task is a child task, its parent task must be linked to a Jira issue.
  • The Sync with Jira checkbox is selected.

When you create a project task in PSA, the integration creates a new Jira issue with the information listed below. Similarly, when you edit an eligible project task in PSA, the integration updates the related issue in Jira.

Key: * – Mandatory field.

PSA Project Field

Jira Issue Field

Project Task Name * Summary
Estimated Hours Original Estimate
Long Description Description
Priority Priority

When the issue is created in Jira, the Jira Correlation ID of the project task is automatically populated with the issue key.

Note:

Before you can create Jira Epics from PSA, you must update the PSA to Jira Issue Fields custom metadata. The field IDs for Epic Name and Epic Link are specific to your Jira environment. PSA Direct for Jira provides default metadata records but you must update these with the specific Jira custom field details for your environment.

The issue is created in Jira with the default status defined for that issue type and project. For more information on statuses in Jira, see the Atlassian documentation.

Notes:
  • The Priority and Status values defined for the project task in PSA are not directly copied to the Jira issue. This is because Jira and PSA have different values for the Priority and Status fields. You can configure how PSA priorities and statuses are converted to Jira or vice-versa. For more information, see Customizing the Value Mappings.
  • If you don't define a priority for a project task in PSA, the Jira issue is created with the default priority. Note that if you are using Jira Server, the default priority might vary between different projects, depending on the priority schemes defined. For more information about priorities and priority schemes, see the Atlassian documentation.
  • After an issue is created in Jira, you cannot update the related project task's Jira Issue Type Category and Jira Issue Type fields in PSA. If you want to change the issue type in Jira, you must delete the project task in PSA, create a new project task with the correct type, and sync it with Jira.

If you create a project task hierarchy in PSA, it is reflected in Jira. Because PSA and Jira establish hierarchy in different ways, the following limitations apply:

  • You must first sync the parent level project tasks before you can sync its children project tasks.
  • Standard issue types, such as stories and tasks, are linked to epics using the Epic Link field in Jira. In all other cases, the hierarchy is established through the Parent Link Field mapping.
  • Sub-task issue types can be created for all standard issue types.
  • Sub-task issue types cannot be used for parent projects tasks.
  • If you are mapping projects to issues, a top-level project task can be a sub-task issue type. If you are mapping projects to projects, only standard issue types can be top-level project tasks.

When you delete a project task in PSA, the related issue is automatically deleted from Jira. If the project task has child tasks that are linked to sub-task type issues in Jira, the child tasks are deleted from PSA and the sub-task issues are deleted from Jira.

Note:

Issues are not deleted from Jira if you deselect the Sync with Jira field or remove the value of the Jira Correlation ID field on the related project task in PSA before deleting it.

If an error occurs during the synchronization, the PSA user who created, updated, or deleted the project task receives an email notification and a Foundations error message is created. For more information, see Viewing Project Task to Issue Synchronization Errors.

When you undo the delete on the project task, then the related task-time is restored automatically. If the project task has child tasks linked to sub-task type issues in Jira and you undo the delete on the project task, then the Jira issue with the work logs and time cards value are lost and fail to sync with Jira.

After your project tasks are synced with Jira issues, the related project task's status is updated when a Jira user moves a synchronized issue to another status. This allows you to monitor the progress of project tasks linked to Jira issues directly from PSA Direct for Jira.

The Status values defined for the issue in Jira are not directly copied to the project task in PSA Direct for Jira. This is because Jira and PSA Direct for Jira have different values for the respective Status fields. To configure how Jira statuses are converted to PSA Direct for Jira statuses you must create a data transformation table. There source value in Jira is the status value in Jira, and the target value is the PSA Direct for Jira project task status value in PSA Direct for Jira. For more information, see Customizing the Value Mappings.

Additionally, to map project task status you must add a new mapping to the Issue Field to Project Task Mappings. For example, fields > status > Name.

If an error occurs while updating the status of a project task, the user-specified on the PSA Direct for Jira Settings tab receives an email notification, and a Foundations error message is created.