Integrate PPM tasks with Azure DevOps projects

The integration between PPM tasks and Azure DevOps 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 Azure DevOps from within PPM projects.

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

In this topic:

Add an Azure DevOps agile instance

An Azure DevOps agile instance is an environment where the Azure DevOps connector conveys the data from Azure DevOps to PPM.

What integrations does an Azure DevOps instance support?

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

Icon	Meaning
WP	The agile instance supports work plan integration: you can link an Azure DevOps project with a PPM work plan task.
RA	The agile instance supports request-agile entity integration: you can manage Azure DevOps agile entities through managing mapped requests in PPM.

Add an Azure DevOps instance as an administrator

To add an Azure DevOps instance:

1. From the PPM menu, select Open > Administration > Integrations.
2. Navigate to the Enterprise Agile pane.
3. In the Instances section, Azure DevOps line, click +.

4. 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 <>.
   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.
   Azure DevOps Organization	The Azure DevOps organization you want to integrate with PPM.
   Authentication Settings
   PAT (Personal Access Token)	Provide the Personal Access Token used to retrieve agile data from agile projects in Azure DevOps. The account information decides which agile projects you can select on the Advanced tab of a PPM work plan task.
   Work plan sync settings
   Following Work Item types can be imported in the work plan	Specify the work item types that can be imported to a linked task in PPM work plan.
   Following statuses are considered "In Progress"	Specify the work item statuses that are classified as In Progress when the status data is synced with the PPM work plan.
   Following statuses are considered "Closed"	Specify the work item statuses that are classified as Closed when the status data is synced with the PPM work plan.
   Never include work items with these statuses	When the work items are in the specified statuses, they are not imported to the PPM work plan.
   Following work item types (and their children) can be individually imported in the work plan	Specify which Azure DevOps items can be imported into the PPM work plan. If no value is specified, the default value Epic is used.

5. Click Save.

6. 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.

Back to top

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 Azure DevOps projects.

For details, see Set PPM project as hybrid project.

Back to top

Link a PPM task with an Azure DevOps project

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

To link a PPM task with an Azure DevOps project:

1. Open the hybrid project work plan.

2. Open a target task.

   Tasks that can be linked with an Azure DevOps 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 an Azure DevOps 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 Azure DevOps projects.
3. On the Hybrid Project tab, click Start Mapping.
4. In step 1, select an Azure DevOps instance, and click Next.

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

   In step 2: User Configuration, select the Azure DevOps project and specify the types of work items that need to be imported to the linked task, as described below:

   Field (*Required)	Description
   *Project	Select an Azure DevOps project to import the relevant work items to the linked task.
   Select what specific work items to import	Select which work items to import to the linked task: All work items in the Azure DevOps project. A specific epic and items included in it. If you want to select a specific epic, make sure it is selected during the Azure DevOps instance configuration. For details, see Following work item types (and their children) can be individually imported in the work plan.
   Group Work Items by	Group imported work items by: Work Items Hierarchy. The imported work items are grouped by the hierarchy. Sprint. The imported work items are grouped by sprint, for example, PROJ Sprint 1 and PROJ Sprint 2. Status. The imported work items are grouped by work item status, for example, Doing and To Do.
   Include closed work items	Select this check box if you want to import the closed work items to the work plan.
   Following work items will be imported in the work plan	Select the type of work items to import to the work plan.

6. 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 Azure DevOps logo is added in front of the PPM task, indicating that it is linked to an Azure DevOps project.

Back to top

Sync agile data into PPM

After the PPM task is linked with an Azure DevOps agile project, you wait for the background service to sync 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

Schedule information of external data is controlled in agile and synched to PPM. For data mapping between PPM and agile, see Data mapping between Azure DevOps 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 allowed 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 External Work Plan Sync background service 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 External Work Plan Sync background service .

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

Data mapping between Azure DevOps and PPM

Data in PPM	Data in Azure DevOps
Task name	Work item name.
Schedule start	For work items of the Issue or Task type, it is the start date of the assigned sprint. For work items of the Epic type, it is the epic's Start Date.
Schedule finish	For work items of the Issue or Task type, it is the end date of the assigned sprint. For work items of the Epic type, it is the epic's Target date.
Actual start	The work item's schedule start date.
Actual finish	The work item's schedule finish date.
Scheduled effort	For work items of the Issue type, it is the work item's Effort value. For work items of the Task type, its Remaining Work is synced to PPM as Estimated Remaining Effort. Scheduled effort = Estimated Remaining Effort / 50%. For work items of the Epic type, it is empty.
Percent complete	If the work item is done, it is 100%. If the work item is in progress, it is 50%. If the work item is not started, it is 0%.
Status	See Work plan sync settings.

Back to top

Unlink Azure DevOps project from PPM task

You can unlink an Azure DevOps project from a PPM task.

To unlink an Azure DevOps project from a PPM task:

1. Open the Task Details page of the linked task, and go to the Hybrid Project tab.

2. Next to the Azure DevOps instance information, click Unlink.

3. Click OK to confirm.

   The link between the Azure DevOps project and PPM task is canceled immediately.

Back to top

See also:

• Integrate PPM requests with Azure DevOps work items