In this article we will review important details as for Project Online <> Azure DevOps data synchronization and known limitations for this scenario.
Basic info about Sync between Azure DevOps and Project Online
An application allows to migrate data in both directions - from Project Online to Azure DevOps and vice versa. For cooperation between these two systems and correct data migration some settings should be pre-defined.
Data will be migrated from Project Online to Azure DevOps in case when:
- “VSTS Project” Project Online custom fields need to be pre-populated with an appropriate project name from Azure DevOps.
- In Project Online “Sync with VSTS” custom fields should be set to “Yes” for the items that should be synchronized.
- Data will be migrated if task marked as sync = yes and names of the projects in Project Online and in Azure DevOps are the same.
Data will be migrated from Azure DevOps to Project Online in case when:
- “Sync with Project Online” flag is set to “YES”.
- Data will be migrated if task marked as sync = yes. Also, if Project Online project and Azure DevOps projects have different names, an appropriate Azure DevOps work item field should contain the exact name of the Project Online project for the synchronization to work.
All these settings are set during the configuration of the Project Online <> Azure DevOps scenario. Each step is described in the Configuring Project Online <> Azure DevOps scenario article.
Details of Azure DevOps and Project Online integration
Fields Mapping
|
ProjectServerOnline |
Meaning | VSTS |
| Custom field: Project.“VSTS Project Field” | ⇒ | System field: Project.Name |
| System field: Project.Name | ⇐ | Custom field: WorkItem.“PO Project Name” |
| Custom field: Task.“VSTS” | = | Custom field: WorkItem.“Sync To PO” |
| Custom field: Task.”VSTS work item type” | = | System field: WorkItem.Type |
| System field: Task.Name | = | System field: WorkItem.Title |
| System field: Task.Work | = | System field: WorkItem.OriginalEstimate |
| System field: Task.ActualWork | = | System field: WorkItem.CompletedWork |
| System field: Task.RemainingWork | = | System field: WorkItem.RemainingWork |
| System field: Task.Assignment | = | System field: WorkItem.Assignment |
| System field: Task.ParentTaskId | = | System field: WorkItem.ParentTaskId |
Integration
Please take a look which entities are synced and updated during bi-directional integration when the sync takes place.
Direction: from Project Online to Azure DevOps
a) Task originally created in Project Online
- Task Name;
- Work;
- Actual Work;
- Remaining Work;
- Assignments (One assignment in Project Online equals to one separate Work Item in Azure DevOps);
- Azure DevOps Work Item Type (Bug, Task, Epic, Feature, Issue, Test Case, User Story);
- Hierarchy structure.
b) Work Item originally created in Azure DevOps (then transferred with a sync to Project Online and now is transferred with the following field updates back to Azure DevOps)
- Original Estimate;
- Completed Work;
- Remaining Work;
- Assignment;
- Azure DevOps Work Item Type;
- Hierarchy structure.
Direction: from Azure DevOps to Project Online
a) Work Item originally created in Azure DevOps
- Work Item Title;
- Original Estimate;
- Completed Work;
- Remaining Work;
- Assignment;
- Azure DevOps Work Item Type;
- Hierarchy structure (Only during the first sync, updates are not supported).
b) Task originally created in Project Online (then transferred with a sync to Azure DevOps and now is transferred with the following field updates back to Project Online)
- Original Estimate;
- Completed Work;
- Remaining Work;
- Assignment;
- Azure DevOps Work Item Type;
- Hierarchy structure (Only during the first sync, updates are not supported).
Please note: Task name update depends on where the task was originally created:
If the task was originally created in Azure DevOps and the name changed in Azure DevOps, the name will be updated in Project Online on data synchronization. However, if the name was changed in Project Online for such a task, it will NOT be updated in Azure DevOps.
If the task was originally created in Project Online and its name was changed in Project Online, the name will be updated in Azure DevOps on data synchronization. However, if the name was changed in Azure DevOps, it will NOT be updated in Project Online on data sync.
Important notes and Limitations
Before starting your first integration please review a list of important notes and limitations to make sure your integration will run smoothly and correctly.
Please note: Master Projects are not supported for integrations.
Please note: Dependencies are not supported for integrations.
One to one integration. One project from Project Online is synced with one project from Azure DevOps. We do not recommend syncing of several projects to one project in any of the integrated systems since the data will not be transferred properly.
Projects are matched by their name or by “VSTS Project” and “PO Project” custom fields. By default, projects are matched by their names, so the project names in Azure DevOps and Project Online must be identical. If you would like to have different names on your projects, you can use “VSTS Project” and “PO Project” custom fields and use one of the fields or both of them for specifying the name of your project.
Assignments are matched by Emails. Assignments are matched by email so the emails in Azure DevOps and Project Online should be identical for successful synchronization of the assignments. In both integration directions email of a resource assigned to a Task in Project Online must match with an email of Azure DevOps user account. For successful migration of the assignments, the resource with the correct email should exist on the PWA. If resource exists on the PWA it will be added to the project team automatically and will be assigned to task during task synchronization.
Please note: For assignments to migrate correctly to Azure DevOps, the assigned user must be added to any project team.
Use Azure DevOps connection with Personal Access Token for big integrations. If you have an integration where execution time approximately equals 1 hour or items quantity is about 500, we recommend using Azure DevOps connection with Personal Access Token instead of OAuth authorization. Please refer to this article from Microsoft on how to create Personal Access Token for Azure DevOps connection.
Do not unassign resources from manually scheduled tasks where the field “Sync To VSTS” = Yes. In Project Online if you remove assignment from a task the task progress will be automatically deleted. Therefore, we do not recommend removing assignments from tasks marked for synchronization since it will cause loss of task progress in Project Online.
Do not assign same Resource on Siblings in Azure DevOps.
As an example, in Project Online you have Task 1 to which Resource 1 and Resource 2 are assigned. After integration from Project Online to Azure DevOps, in Azure DevOps two work items will be created, Work Item 1 with an assigned Resource 1 and Work Item 2 with an assigned Resource 2. These work items that relate to the same Task but have different assignments are called siblings. Work hours will be allocated between two Resources according to Project Online resources settings. We recommend not re-assigning Siblings in Azure DevOps to one resource (e.g. Work Item 2 to Resource 1) since in this case, Task 1 in Project Online will be updated with data from only Work Item 2 with assigned Resource 1 from Azure DevOps. This means that data for Work Item 1 with Resource 1 will be lost.
In case you have more than one assignment on the same Task which has been already synced to Azure DevOps and remove assignments on this task in Project Online, an appropriate Azure DevOps sibling work item will be marked as “Deleted”. The sibling work item will not be removed from Azure DevOps and will be kept with the text “Deleted” in Title and its synchronization will be turned off.
You can not track time efforts in synchronizable Work Item which has child work items in Azure DevOps. Time tracked in Azure DevOps work item with child items will always be overwritten by values from Summary Task in Project Online during synchronization.
Do not change authentication type of the connections in the integration scenario. Create a new connection instead.
Changes in hierarchy structure can only be synced from Project Online to Azure DevOps. Changes in hierarchy structure from Project Online to Azure DevOps are transferred both for tasks created in Project Online and Azure DevOps. This rules applies if the "Allow to sync work items partial hierarchy" option is not enabled when the synchronization scenario is configured. However, if not all work items are part of the sync, it is recommended to enable this setting. With this setting enabled, work items selected for integration will retain their parent items during synchronization from Project Online to Azure DevOps. However, if the hierarchy in Project Online changes, it will still remain as initially set in Azure DevOps.
Changes in hierarchy structure from Azure DevOps to Project Online are transferred only during the first sync, any further updates are not supported.
Do not change work item type from “Test Case” to any other work item type in Project Online since Azure DevOps does not support such change and the task will not be transferred properly.
Do not change work item type from “Issue” to any other work item type in Project Online since Azure DevOps does not support it due to the absence of states “New” and “Resolved” on the “Issue” work item type.
Deletion of the syncable entities: If you would like to remove the task completely from both systems, you should turn off synchronization on these tasks in both systems and run integration. After one integration in both directions you can manually remove the tasks in both systems.
Task mode on tasks in Project Online must be always set to manual. For successful data transfer we do not recommend changing task mode to auto-schedule.
Work Item Type “Task” is a default setting for tasks in Project Online. If you haven’t specified a Work Item Type of a task in Project Online but selected it for synchronization, the task will be transferred to Azure DevOps as a Task.
Work, Actual Work and Remaining Work are transferred from Project Online to Azure DevOps only for Work Item Types “Bug” and “Task”.
Please note: If the task start and finish dates from Project Online are mapped to Azure DevOps date fields during the scenario configuration, then actuals will not be synchronized properly to Project Online, they will be changed according to the Project Online calculation logic.
If the "Only allow task updates via Tasks and Timesheets" option is activated in Project Online, the integration will not work. If you are using the Integration Hub to synchronize Actual hours from Azure DevOps to Project Online, you will need to switch off the "Only allow task updates via Tasks and Timesheets" option before the integration and switch it back on manually after the integration is completed.
Do not clear the cache. When the data is transferred via Integration Hub, the app stores the data in the cache and uses the cache for subsequent syncs. We recommend not clearing the cache. Otherwise, after the next synchronization all tasks marked for synchronization will be transferred again as new tasks.
Start/Due dates are not migrated for sub-tasks.