OnePlan and Azure DevOps: Epics - how the integration works


This article explains the main use case and out-of-box capabilities for the integration between OnePlan and Azure DevOps: Epics, using the OneConnect integration platform.


OneConnect for Azure DevOps offers a seamless approach to exchange critical information between development teams and project teams using OnePlan and Azure DevOps. 

This integration specifically synchronizes plans from OnePlan as Epic work items (typically stories, tasks, and bugs) and synchronizes work items back to OnePlan as backlog items.

Agile Project Visibility in Oneplan

Synchronize key data between OnePlan and Azure DevOps to establish enterprise level portfolio level visibility. Regardless of team execution methodology (i.e. waterfall or agile), projects are centrally visible for analysis and reporting.

  • "Epics": OnePlan plans sync as Epics under a selected Team Project & Area Path.

Epics Process

This is the high level process flow for using the integration.

  1. As Epics reside beneath a parent Azure DevOps Team Project & Area Path, the Team Project & Area Path(s) must first exist in Azure DevOps before creating the plan in OnePlan.
  2. Create a new plan in OnePlan.  When the integration is configured, a new field will be created in OnePlan. The field is "TeamProjectsArea," which is a lookup table populated with the Team Projects & Area Paths from Azure DevOps. Select an Area Path under the Team Project.
  3. Teams may use their normal process for project approval, portfolio analysis, etc.  
  4. When a project is active and ready to execute using Azure DevOps with an agile methodology, the PM synchronizes the project to Azure DevOps by clicking on the synchronize button. A new Epic is created with the same plan name under the earlier selected Team Project & Area Path.
  5. The PM builds out the project's agile plan under the epic - the features, user stories, task & bugs.
  6. The PM puts work items (stories, tasks, and bugs) into an iteration.  This is important, as only items noted into an iteration will sync back to OnePlan.
  7. Team members work using Azure DevOps as usual. They update status on work items (stories, tasks, and bugs).
  8. Updates sync back to OnePlan. 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 OnePlan and click Sync. This will pull in the changes/updates from Azure DevOps.
  9. Back in OnePlan, the plan is updated with the Azure DevOps work items as Backlog Items in the plan.

Important Notes

  • The backlog item sync is bi-directional even after the initial sync. You can create or edit data in OnePlan or Azure DevOps and then sync to the other system. The only fields that are not editable in OnePlan are the ones you choose to only sync from DevOps to OnePlan
  • Sprints are synced into OnePlan.
  • The integration is also supported on Team Foundation Services (On-Premise), but only for the following versions: 2015, 2017, and 2018.
  • Must have full admin privileges/accounts in both OnePlan & Azure DevOps to configure the integration.
  • The default Azure DevOps Work Item types are Tasks and Bugs.  These sync to the OnePlan work plan list as type: Backlog.  Other types can be configured to also come over, such as Features, User Stories, etc. but they will still come in as plan backlog items, in a flat hierarchy.
  • Mapping projects from OnePlan to Azure DevOps work item (Projects -> Epics): 
    • Able to assign the mapped work item’s area path in Azure DevOps. (Support multi-level area path)
    • User entered the field over in OnePlan’s projects field and specify its area path. When the scheduler runs, the projects synched over to Azure DevOps will get assign to the correct area path.
    • User can update the area path of the work item that has been mapped, when the scheduler is run at future time. (Only area path within the same level of team area project assigned to the work item type at first synched to Azure DevOps)
    • Able to generalize mapping work item type to Azure DevOps. (Not specifically for Epics only)
  • User can enter their valid desired work item type over in the connector GUI, and specify the work item type (Epic, Bug, Feature, etc..)
    • User can update/change the work item’s type that has been mapped, when the scheduler is run at future time.
    • Able to link the work item type to its corresponding parent item type when synchronizing the item from OnePlan to Azure DevOps.
    • User will specify in the OnePlan’s projects field its parent item type, and when the scheduler runs, the item type being synchronized will be linked to its corresponding parent item type.
  • Mapping items from Azure DevOps to OnePlan tasks (Tasks -> Items):
    • Able to select the work item type in Azure DevOps below the parent item and it will be mapped as task schedule table in OnePlan.
  • Mapping team area projects from Azure DevOps to OnePlan lookup table (Lookup_Team Projects Area -> Team Projects Areas)
    • Able to synchronized team area project level (Currently support up to 100 levels) to a Team Projects Area lookup table in OnePlan.


  • Basic mapping rule: Make sure to map fields that are required by the other side of the connector (in this case is Azure DevOps), if the fields are required by Azure DevOps, then map the fields of that item to get synchronized from OnePlan to Azure DevOps.
  • Empty Team Projects Area field in OnePlan is not allowed. (*Has to have an area path for the project)
  • To support multi-level area path in OnePlan’s lookup table, user need 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 Azure DevOps 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 “Epic” work item type.
  • Invalid input work item type will not let current new item being synched gets created in Azure DevOps.
  • Invalid input on work item type will not let current item being synched gets updated on its item type field in Azure DevOps, 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 Azure DevOps (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: Azure DevOps Work Item Type)
  • When a user deletes an item in Azure DevOps, the next time the scheduler runs, it will still synchronize (recreate) that item from OnePlan to Azure DevOps. Unless the item is also deleted in OnePlan, then that item will never be synchronized back to Azure DevOps.
  • Changing area path to a different team project is not allowed by Azure DevOps.  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 OnePlan lookup table need 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 Azure DevOps. 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 OnePlan, delete the item from Azure DevOps, and assigned the correct parent item to the field in OnePlan, and have it synchronized back to Azure DevOps/wait for the scheduler to run.
  • Sample of the input for work item type to be synched to Azure DevOps and work item type that will be synched to OnePlan as Task: (Same rule regarding work item type case sensitivity when getting input in the GUI, explained above)
  • Work item types in Azure DevOps that will be synched to OnePlan as Task schedule needs to be at the same project area path with its parent project area path. For instance, from the picture below, a user want to synched work items that are below “Azure DevOps Test Hans Epic” as Task in OnePlan, with this specified work items type only: Feature, Task, and Bug. So these items need to have the same area path as “Azure DevOps Test Hans Epic” which is shown in the second picture below.
  • Work item types need to be at an iteration to get synched to OnePlan. 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 OnePlan as Tasks.
  • Azure DevOps Synchronize Button Functionality Expectation:
    • Create a newly created project in OnePlan to Azure DevOps work item type.
    • If the item has already been created/synched to Azure DevOps before through the button, the next time the button is clicked, it will only update back to OnePlan from Azure DevOps. Any updates in OnePlan to Azure DevOps will never be made through the button (Therefore, the “ProjectPublish” strategy is needed to synch over updates from OnePlan to Azure DevOps).
Previous Article OnePlan and Microsoft 365 Planner
Next Article OnePlan and Azure DevOps: Epics - how to set up the integration