This article explains the main use case and out-of-box capabilities for the OnePlan integration between Project Online and Visual Studio Team Services (VSTS): Areas, using the OneConnect integration platform. There is an integration for "Areas" and an integration for "Areas with Items." They are similar, but the "Areas with Items" integration has some additional data that sync over (VSTS Work Items to Project Online Tasks). Refer to the process steps to see the specific process for how these two integrations work.
OneConnect for Visual Studio Online offers a seamless approach to exchange critical information between development teams and project teams using Project Online and Visual Studio.
This integration specifically synchronizes projects from Project Online to VSTS as Areas. VSTS work items (typically tasks & bugs) synchronize back to ProjectOnline as project Tasks.
Key Capabilities
Synchronize key data between Project Online and Visual Studio to establish enterprise level portfolio level visibility. Regardless of team execution methodology (i.e. waterfall or agile), projects are centrally visible for analysis & reporting.
These two integrations synchronize Project Online Projects to VSTS Areas.
-
"Areas": Project Online projects sync as Areas under a selected Team Project.
-
"Areas with Items": Project Online projects sync as Areas under a selected Team Project . Additionally, Project tasks sync to two levels as work items, typically Features & User Stories.
Build better forecasts and gain greater insight into capacity & demand, taking into account all types of projects when optimizing your portfolio of projects. See all work assigned (project online workload and VSTS workload).
Resources are mapped via same email address in both Project Online & VSTS, typically their Active Directory (AD) account.
This is the high level process flow for using the integration.
-
As Areas reside beneath a parent VSTS Team Project & Area Path, the Team Project must first exist in VSTS before creating the project in Project Online.
-
Create a new project in Project Online. When the integration is configured, a new field get created in Project Online. The field is "TeamAreaProject," which is a lookup table populated with the Team Projects from VSTS. Select the Team Project.
-
Teams may use their normal process for project approval, portfolio analysis, etc.
-
When a project is active & ready to execute using VSTS with an agile methodology, the PM synchronizes the project to VSTS by clicking on the synchronize button. A new Area is created with the same project name under the earlier selected Team Project.
-
The PM builds out the project's agile plan under the area path - the epics, features, user stories, task & bugs.
-
The PM puts work items (tasks & bugs) into an iteration. This is important, as only items noted into an iteration will sync back to Project Online.
-
Team members work using VSTS as usual. They update status on work items (tasks & bugs), enter hours (remaining, etc).
-
Updates sync back to Project Online. The data that syncs back is based on the configuration settings mapped fields. This can be done on a scheduled timed-basis or on-demand. The schedule is part of the configuration settings (hourly, daily, etc.). If syncing on-demand, you must go into Project Online & click Sync. This will pull in the changes/updates from VSTS.
-
Back in Project Online, the project is updated with the VSTS work items as Tasks in the project schedule. Note: the tasks come in flat rather than with a WBS (work breakdown structure) hierarchy.
This is the high level process flow for using the integration. The "Epics with Items" process is similar, with some additional notes as follows.
-
As Areas reside beneath a parent VSTS Team Project & Area Path, the Team Project must first exist in VSTS before creating the project in Project Online.
-
Create a new project in Project Online. When the integration is configured, a new field get created in Project Online. The field is "TeamAreaProject," which is a lookup table populated with the Team Projects from VSTS. Select the Team Project.
-
Teams may use their normal process for project approval, portfolio analysis, etc.
-
Build out the project plan. The summary tasks and child tasks will sync to VSTS as two levels, based on how the integration is configured. Typically, summary tasks would be synced to Epics and the child tasks would be synced to Features. To govern which tasks will sync, there's a new field in the Tasks list called "VSTS Task Item." In the plan, select the VSTS task item for the tasks to synchronize.
-
When a project is active & ready to execute using VSTS with an agile methodology, the PM synchronizes the project to VSTS by clicking on the synchronize button. A new Area is created with the same project name under the earlier selected Team Project. The project tasks get created as Epics & Features (or the configured levels, if different).
-
The PM builds out the project's agile plan under the new Area with the Epics, Features, User Stories, Tasks & Bugs.
-
The PM puts work items (tasks & bugs) into an iteration. This is important, as only items noted into an iteration will sync back to Project Online.
-
Team members work using VSTS as usual. They update status on work items (tasks & bugs), enter hours (remaining, etc).
-
Updates sync back to Project Online. The data that syncs back is based on the configuration settings mapped fields. This can be done on a scheduled timed-basis or on-demand. The schedule is part of the configuration settings (hourly, daily, etc.). If syncing on-demand, you must go into Project Online & click Sync. This will pull in the changes/updates from VSTS.
-
Back in Project Online, the project is updated with the VSTS work items as Tasks in the project schedule. Note: the tasks come in flat rather than with a WBS (work breakdown structure) hierarchy. They come in at the bottom of the plan. Note: the tasks do not sync into the project plan under the "features" tasks.
-
If Areas are created first in VSTS, they are not automatically synced to Project Online as a new project.
-
The integration is also supported on Team Foundation Services (On-Premise), but only for the following versions: 2015, 2017, & 2018.
-
Must have full admin privileges/accounts in both Project Online & VSTS to configure the integration.
-
The default VSTS Work Item types are Tasks and Bugs. These sync to the Project Online Tasks list. Other types can be configured to also come over, such as Features, User Stories, etc. but they will still come in as project tasks, in a flat hierarchy.
-
Basic mapping rule: Make sure to mapp fields that are required by the other side of the connector (in this case is VSTS), if the fields are required by VSTS, then mapped the fields of that item to get synchronized from Project Online to VSTS.
-
Empty TeamAreaProject field in Project Online is not allowed. (*Has to have a VSTS Team Project for the project)
-
To support multi-level area path in Project Online’s lookup table, user needs to adjust the code mask section in the lookup table settings based on the number of level the user need. (eq. 4 level = *.*.*.*. )
-
User can only enter a single work item type in the VSTS Work Item Type column in the connector GUI.
-
If user does not enter/leave empty the work item type column, it will by default be “Area” work item type.
-
Invalid input work item type will not let current new item being synched gets created in VSTS.
-
Invalid input on work item type will not let current item being synched gets updated on its item type field in VSTS, if this work item has ever been mapped before.
-
When user enter a single work item type in the GUI, it must be very specific to the work item type shown in VSTS (They are case-sensitive). Take an example from the below picture, when mapping “Epic” work item type, the value entered on the GUI of the connector must follow the same key word “Epic”, see the highlighted part below. (Column name: VSTS Work Item Type)
-
When a user deletes an item in VSTS, the next time the scheduler runs, it will still synchronize (recreate) that item from Project Online to VSTS. Unless the item is also deleted in Project Online, then that item will never be synchronized back to VSTS.
-
Changing area path to a different team project is not allowed by VSTS. Only changing area path level within the same team project that has been initialized at the first time the work item is synchronized is allowed.
-
Parent item name declared in Project Online lookup table needs to be in this specific format: “parent name - parent id”, where the parent id is placed at the very end after “-“.
-
Attempting to change the parent item of the already mapped item is not currently supported. Parent item will be linked to the current item being mapped only during the first creation of this item to VSTS. The later the scheduler runs, any updates related to parent item will not get updated. *If user did not enter/wrong input the parent item in the project field in PJO, delete the item from VSTS, and assigned the correct parent item to the field in PJO, and have it synchronized back to VSTS/wait for the scheduler to run.
-
Sample of the input for work item type to be synched to VSTS and work item type that will be synched to PJO as Task: (Same rule regarding work item type case sensitivity when getting input in the GUI, explained above)
-
Work item types need to be at an iteration to get synched to Project Online. Only tasks and bugs need to be in an iteration; other work item types (Non-Bug and Non-Task) will just be brought over to Project Online as Tasks.
-
VSTS Synchronize Button Functionality Expectation:
-
Create a newly created project in Project Online to VSTS work item type.
-
If the item has already been created/synched to VSTS before through the button, the next time the button is clicked, it will only update back to Project Online from VSTS. Any updates in Project Online to VSTS will never be made through the button (Therefore, the “ProjectPublish” strategy is needed to synch over updates from Project Online to VSTS).
-
-
Mapping projects from Project Online to VSTS Team Area (Projects -> Areas):
-
Able to create a team area in VSTS from a project in project online.
-
-
Mapping items from VSTS to Project Online tasks (Tasks -> Items):
-
Able to select the work item type in VSTS below the Area item and it will be mapped as task schedule table in Project Online.
-
-
Mapping team area projects from VSTS to Project Online lookup table (Lookup_TeamAreaProject -> TeamAreaProjects)
-
Able to synchronized team area project level (Currently support up to 100 levels) to a TeamAreaProject lookup table in Project Online.
-