Integrate PPM tasks with Jira projects

The integration between PPM tasks and JIRA projects enables project managers, program managers, portfolio managers, or project stakeholders to view real-time status and progress of agile projects that are run in JIRA from within PPM projects.

This section details on how to set up and use the integration.

Add a Jira agile instance

A JIRA agile instance is an environment where the JIRA connector conveys the data from JIRA to PPM.

What integrations does a Jira instance support?

When you add a JIRA instance, you can see several icons shown next to the instance name. They are indicative of what kind of integrations a JIRA instance can support.

Icon	Meaning
TS	The agile instance supports time sheet integration: you can import effort from JIRA to PPM time sheets.
WP	The agile instance supports work plan integration: you can link a JIRA project with a PPM work plan task.
PE	The agile instance supports portfolio epic integration: you can push a PPM portfolio epic to a JIRA project for execution.
RA	The agile instance supports request-agile entity integration: you can manage JIRA agile entities through managing mapped requests in PPM.

Add a JIRA instance as an administrator

Note: PPM supports Jira 9.0 for the request-agile entity integration. If you want to use other integrations, use an earlier Jira version.

To add a Jira instance:

Click the Administration button in the masthead.
From the Administration menu, click Integrations > Agile Tool Integration.
In the Instances area, Atlassian JIRA line, click the Create Instance button +.

Click the General tab and provide the required information as described in the table below:

Field (*Required)	Description
*Instance Name	Specify a unique name for the instance. The instance name should not exceed 50 characters. Do not contain such special characters as `<>`.
*Base URL	URL of the JIRA server you want to integrate with PPM. Format of the URL: `http(s)://<server_address>`. Do not end the base URL with a slash. If you have customized the JIRA server, make sure you include the port number in the URL as well: `http(s)://<server_address>:<port>`
Proxy Host	Host name of the proxy if you have configured a proxy for the PPM Server to access the Internet.
Proxy Port	Port of the proxy if you have configured a proxy for the PPM Server to access the Internet.
Admin account information
Admin account information	Provide the admin account used to retrieve agile data and portfolio epic from agile projects in JIRA. You can use either of the following: To use username and password authentication, provide the username and password in the Admin Username and Admin Password fields. To use Personal Access Token, provide the PAT information in the Admin PAT field. The account information decides which agile projects you can select in the Advanced tab. Note: If you do not use portfolio epics for JIRA agile projects, you can just enter invalid account information.
Request Mapping (Request-Agile)
*Enable " " Jira Project Mapping in Request Agile Mapping**	Select this option to allow selecting a wildcard JIRA project to match all the JIRA projects when mapping PPM request types with JIRA entity types. This frees you from creating the same request-agile mapping for each JIRA project.
Work Plan Integration Options
Users must use a PAT (Personal Access Token) instead of username/password on Work plan & Timesheet screens	If you restrict users to use the PAT authentication when linking PPM work plan tasks with a Jira project and importing effort from Jira to PPM time sheets, select this option.
Sync Story Points to	For each imported issue, its story points is synchronized to the selected task user data field.
Sync Epic Content Story Points to	For each imported issue, the sum of story points of its epic's contents is synchronized to the selected task user data field. The sum does not include story points of sub-tasks or of the epic's contents that are not imported to the PPM work plan.
Name of the Epic issue type	If you've renamed the Epic issue type in Jira, provide the custom issue type name in this field. PPM will retrieve data from the custom issue type and sync it with work plan tasks.
Use Admin Account to Map Work Plan Tasks	If you select this option, the admin account is used to retrieve the agile projects and portfolio epics that can be mapped to PPM work plan tasks.
Import Jira assigned Users to work plan tasks when emails match	For each imported issue, whether or not to import the resource assigned to it to the resource field of the mapped PPM task. By default it is checked.
Map following Jira issues statuses to PPM Task Status
Ready In_Progress Completed Cancelled Unknown (Auto from %Complete, default status)	Map Jira issue status with PPM task status Note: Only the statuses of PPM leaf task are supported for mapping. The statuses of PPM summary task are not supported. In each field of the PPM leaf task status, fill the mapped issue status in Jira. Use semicolons to separate if there are more than one mapped Jira status. Any statuses in Jira that are not listed here are automatically mapped to Unknown in PPM.

Click Save.
Click Test Connection to test the connection with the instance.

If a message appears stating that connection failed, click OK on the message, and then resolve the connection issue.

Set PPM project as hybrid project

Only tasks in a hybrid project where only part of the project uses agile methodology can be linked to JIRA projects.

For details, see Set PPM project as hybrid project.

Link a PPM task with a JIRA project

When you link a PPM task with a JIRA project, the JIRA project becomes a sub-project of the PPM hybrid project.

To link a PPM task with a JIRA project as a project manager:

Open the hybrid project work plan.
Open a target task.

Tasks that can be linked with a JIRA project must meet the following requirements:
- The task is a leaf task.
- The task is not a milestone.
- The task has no manually entered actuals. Tasks with actuals only synced from time sheets can be linked with a JIRA project.
- The task is not already linked to an RFC in Service Manager.
- If the project is already integrated with Microsoft Project using an MSP plug-in or MPP file, the work plan should be fully controlled by PPM (under PPM-controlled mode) if you want to map the project tasks to JIRA projects.
In the Hybrid Project tab, click Start Mapping.
In step 1, select a JIRA instance, and click Next.

In step 2: User Configuration, provide the following information to decide what to import to the linked task, and click Next.

Field (*Required)	Description
Username/ Password	Provide the authentication information you use to log on to Jira. Depending on the integration settings, you will see either of the following fields, not both. Username / Password: The user name and password you use to log on to the Jira server. PAT (Personal Access Token). The Personal Access Token you use to log on to Jira. This option is available in 23.3 and later versions and appears only when your administrator selects the Users must use a PAT (Personal Access Token) instead of username/password on Work plan & Timesheet screens option. For details, see Work Plan Integration Options.
PAT (Personal Access Token)
*Project	Select a JIRA project to map.
*Import Selection	Select what you want to import into PPM. Available options are: All project issues: imports issues that belong to the project. One Epic: imports issues of a specific epic. One Version: imports issues of a specific version. One Board: imports issues of a specific board (Scrum or Kanban board).
*Import Selection Details	It works together with the Import Selection field: If you select All project issues in Import Selection, this field displays the option All project issues. If you select One Epic in Import Selection, this field displays all the epics you have access to. Select an epic. If you select One Version in Import Selection, this filed displays all the versions you have access to. Select a version. If you select One Board in Import Selection, this filed displays all the boards you have access to. Select a board.
*Group Issues by	Group imported issues by: Sprint: all the imported issues are grouped by sprint, for example, PROJ Sprint 1 and PROJ Sprint 2. Status: all the imported issues are grouped by issue status, for example, In Progress, To Do, and Done. Epics: all the imported issues are grouped by epic name. Each epic name has a prefix [Epic] when imported to the PPM work plan, for example, [Epic] Re-branding.
Select which types of issues are imported	Select the type of issues to import. Epics and Stories are selected by default. For example, if you select Stories, Tasks, and Features, only stories, tasks, and features are imported to the work plan. Imported issues are prefixed with the issue types: [Epic], [Story], [Task], [Feature], and [Bug]. When an Epic is inserted as a summary task (for example when grouping issues by Epic), the work logged against the epic is entered in a new leaf task created under that Epic with the prefix [Work]. Note: If you select All project issues in the option Import Selection, it does not mean the issues of all types are imported. You still should use this option to select among all the issues linked with the project, which types of issues are imported.
Issues Progress and Effort
*% Complete of Summary Tasks	What to base on when calculating % complete of summary tasks. % Work Complete: PPM calculates % complete of a summary task based on the amount of work logged on each issue. % complete of a summary task = [sum of (work logged on all imported issues)] / [sum of (work logged on all imported issues) + sum of (remaining work of all imported issues)] % Story Points Done: PPM calculates % complete of a summary task based on the story points of each issue. % complete of a summary task = [sum of (story points of imported Done issues)] / [sum of (story points of all imported issues)]
Effort Sync	Whether or not the issue effort is imported to PPM as scheduled effort and how the effort is imported. Logged work: Work logged against the issues is imported to PPM as scheduled effort. Convert story points to effort: Story points of the issues are converted to hours by a ratio and then imported to PPM as scheduled effort and as actual effort if the issue is done. Do not sync effort: Issue effort is not imported to PPM as scheduled effort.
Number of Hours per Story Point	If story points of issues are imported to PPM as scheduled effort (in hours), how many hours one story points is equal to.
Task Options
Include issues that do not belong to any group (Sprint/Status/Epic)	Some issues in the JIRA project do not belong to any sprint or epic or do not have status. If you select this option, you can import all these issues to the work plan. When you select to group imported issues by sprint, the belong-to-no-group issues are grouped under the summary tasks "Backlog". When you select to group imported issues by status, the belong-to-no-group issues are grouped under the summary tasks "No Status Defined". When you select to group imported issues by epic, the belong-to-no-group issues are grouped under the summary tasks "No Epic Defined".
Add one root task to ensure accurate % complete roll up to linked task	If you select this option, PPM creates a virtual root task (with the name Root Task) right under the linked task. Expand the root task to see all the imported issues grouped by sprint, status, or epic. The virtual root task exists to make sure % complete values of all its underlying tasks (the imported issues) are rolled up to it (and to the linked task) correctly.
Insert Epic Milestones?	Whether or not the imported epics are added as milestones under the summary task "Epic Milestones". No milestone: the imported epics are not added as milestones. As major milestones: the imported epics are added as major milestones. As minor milestones: the imported epics are added as minor milestones.

Confirm the user configuration and click Submit.

The one-to-one mapping is established, and the mapping information is displayed under the PPM task.

The JIRA logo is added in front of the PPM task, indicating that it is linked to a JIRA project.

Synchronize agile data into PPM

After the PPM task is linked with an agile project, you wait for the background service to synchronize the agile project work items (external tasks) into PPM. Alternatively, you can click the agile icon in the front of the linked task to trigger immediate running of the service.

The data control of external tasks depends on whether the project enables Time Management to track actuals.

When the project enables Time Management

Schedule information of external data is controlled in agile and synched to PPM

For data mapping between PPM and agile, see Data mapping between JIRA and PPM

Exceptions

If an external task has time logged in PPM but was deleted in agile, PPM still keeps the task in the work plan, adds the prefix [Deleted in Agile] in the task name, and change the task status to Cancelled. This is to make sure time spent on the task is included in cost calculation and the task is no longer possible to be added into time sheets.
If an external task owner has logged time in PPM but was removed in agile, PPM keeps the previous resource and adds the new resource for the task.

Actual information of external data is tracked in PPM using time sheets

Actual information of external data is tracked in PPM using time sheets.

Every time when the background service External Work Plan Sync runs, PPM checks whether there is time logged on the external tasks.

If yes, PPM does not import actual data including actual effort, and actual start/finish date from agile to PPM. Instead, the PM-TM sync background service synchronizes these actual data with time sheet data.
If no, PPM imports status and actual start/finish date from agile to PPM, but does not import actual effort. This way, you can see consistent task status in agile and in PPM.

When the project does not enable Time Management

Both scheduled and actual information of external tasks are controlled in agile and synched to PPM by the background service External Work Plan Sync.

For task data mapping between agile and PPM, see the following table.

Data mapping between JIRA and PPM
Data in PPM	Data in JIRA
Task name	Sprint, status, or epic name > issue name
Schedule start	For an issue that has sprint assigned to it and the sprint has start time, it is sprint's start time. For an issue that does not have sprint assigned to it, or the sprint assigned to the issue does not have start time: If the issue is completed, it is the time when the issue was last updated. If the issue is not completed, it is the time when the data was synchronized.
Schedule finish	Sprint's finish time
Actual start	Sprint's actual start
Actual finish	Sprint's actual finish time
Scheduled effort	Logged work + remaining work
Percent complete	For leaf task: For summary task, see % Complete of Summary Task.
Status	See Map following Jira issues statuses to PPM Task Status.

Unlink JIRA project from PPM task

Go to the Hybrid Project tab of the Task Details page for the linked task.
Next to the JIRA instance information, click Unlink.

A warning message pops up.
Click OK.

The link between the JIRA project and PPM task is cancelled immediately.