In this article, we will review how to set up a two-way integration between PPM Express and Azure DevOps.
The two-way integration provides significantly more flexibility compared to standard linking or one-way synchronization.
With two-way integration, you can:
- Sync selected items instead of entire projects.
- Aggregate items from multiple Azure DevOps projects into a single PPM Express project.
- Create items in both directions. You can create work items in Azure DevOps from PPM Express tasks, as well as create tasks in PPM Express based on Azure DevOps work items.
- Keep items up to date in both systems without manual updating. The two-way integration automatically detects where changes were made, whether in Azure DevOps or in PPM Express, and guides you through syncing those changes, eliminating the need to manually duplicate updates.
To use this functionality, the PMO Aggregator ADO must first be configured by the PPM Express team for your PPM Express tenant. This functionality is available only for the Enterprise Ultra plan. To request this setup, please contact our Customer Success team at customersuccess@ppm.express.
As part of the configuration, the PPM Express team will set up two extensions that enable access to PMO Aggregator ADO and allow task creation in Azure DevOps from PPM Express. Once the extensions are ready, you can start using two-way integration.
Setting up Azure DevOps Connection
To start using two-way integration, perform the following:
1. Open the Tasks page of the PPM Express project where you want to create and sync tasks with Azure DevOps.
2. In the Tasks section, Actions menu, open Extensions -> PMO Aggregator ADO to set up a connection with Azure DevOps.
3. Provide your Azure DevOps Site URL and Personal Access Token.
When creating a token, specify its access scope. The following permissions are required:
- Graph: read
- Identity: read
- Project and Team: read
- Work Items: read and write
Click Save Settings.
4. After connecting to your Azure DevOps instance, there are two scenarios to start task synchronization between PPM Express and Azure DevOps:
1. Work Item exists in Azure DevOps and needs to be created and later synced to PPM Express.
2. Task exists in PPM Express and needs to be created and later synced to Azure DevOps.
On the PMO Aggregator ADO page, you can perform the following actions:
- Sync updates: Sync work item values once you have tasks in PPM Express associated with work items in Azure DevOps. Syncing is available to both Azure DevOps or PPM Express.
- Settings: Update the Azure DevOps site URL or refresh the authentication token if it has expired.
- Field Mapping: Add, remove, or update field mappings between PPM Express and Azure DevOps.
On the right, there are filters that let you narrow the list of items. Here you can select the project in Azure DevOps, a specific Team, an Iteration, a Query, or a Work Item.
Creating PPM Express Tasks from Azure DevOps items
To create PPM Express tasks from Azure DevOps items, perform the following:
1. Open the PPM Express Project -> Tasks page -> Actions menu under the Tasks section -> Extensions -> PMO Aggregator ADO.
2. On the PMO Aggregator ADO page, select the project from Azure DevOps and apply additional filters if required. Select the item or items that need to be created as tasks in PPM Express.
3. Click Create in PPM Express.
When creating items in PPM Express, you can control how much of the hierarchy is created by selecting one of the available options.
The Create in PPM Express option creates the selected item only, without including any child items.
If you select an item at a higher level, such as an Epic, Feature, or User Story, additional options become available, allowing you to include related child items.
The following options are available in this case (Epic is taken as an example):
- If you select Create with all subentities, the selected item and all related Features, and all User Stories under those Features with their child items will be created.
- If you select Create with all sub features, the selected item with related Features will be created in PPM Express.
- If you select Create with all sub features and user stories, the selected item and all related Features, and all User Stories under those Features will be created.
Creating Azure DevOps items from PPM Express Tasks
To create Azure DevOps items from PPM Express tasks, perform the following:
1. Open the PPM Express project -> Tasks page -> Actions menu of the necessary tasks.
2. Choose Extensions -> Create item in ADO.
3. On the Create in ADO page, select the Azure DevOps project where the item needs to be created, and its Parent if the item should be created as a child. Select the Work Item Type.
Click Create.
4. Once the item is created, you’ll see the Item name as a link to open the created work item in Azure DevOps.
Synchronization between linked tasks/items
Once work items are created as tasks in PPM Express or as Work Items in Azure DevOps, all linked items will be displayed on the PMO Aggregator ADO page. Items that are linked between PPM Express and Azure DevOps have the PPM Express icon next to the task title.
The Sync Updates option becomes available.
When items from PPM Express and Azure DevOps are linked, any updates to the PPM Express task or Azure DevOps item, or vice versa, will display a warning on the PMO Aggregator ADO page next to the corresponding field value.
When synchronizing data between systems, there are two distinct types of changes that can be processed:
- Field value changes
- Hierarchy changes
These change types are handled independently to give you better control over what is updated.
The first type of change relates to updates of field values. These occur when specific values are modified, in PPM Express or Azure DevOps, for example:
- Start or finish dates
- Effort, work, or duration
- Other task or work item field values
To update the field values, open the PMO Aggregator ADO and click the Sync Updates button. Choose whether to sync updates to PPM Express or Azure DevOps, then click Sync updates.
If no specific items are selected, updates will be applied to all items that are synced in the current project.
When processing field value changes, only the field values are updated. The hierarchy and structure of items remain unchanged.
The second type of change relates to hierarchy mismatches between systems. This can happen when the structural relationships between items differ, for example:
- An item is linked as a child of an Epic in one system
- The same item does not have the same parent–child relationship in the other system
A warning is displayed on the PMO Aggregator ADO page next to the item affected by the hierarchy change.
To update the hierarchy changes, open the PMO Aggregator ADO, select the necessary items, and click the Resolve hierarchy mismatch button. Choose whether to perform updates to PPM Express or Azure DevOps.
Custom fields mapping
PPM Express Aggregator allows you to map custom fields and change the default mapping for data synchronization.
To set up the fields mapping, perform the following:
1. Open the PPM Express Project -> Tasks page -> Actions menu under the Tasks section -> Extensions -> PMO Aggregator ADO.
2. Choose the Fields Mapping option.
On the Field mapping page, the following options are available:
- Edit existing mapped fields
- Delete the mapping for any field
- Change the order of the fields (re-order columns in the grid view).
- Add Field Rule (to map new fields).
- Reset custom mapping to the default one
To add new fields for mapping, perform the following:
- On the mapping page, click Add Field Rule.
- Provide the Azure DevOps field
- Provide the PPM Express field
- Set the Active toggle to On (allows you to set if the mapping rule will affect sync/tasks creation)
- Click Save Rule.
