This article describes OnePlan's recommendations and best practices for the Azure DevOps integration.
Manual vs. Scheduled Data Synchronization
The Azure DevOps integration support both manual and scheduled data synchronization between Azure DevOps and OnePlan.
By default the integration is installed to import/export data to/from the OnePlan schedule manually.
If you don't want to use the schedule in OnePlan and/or you want to run the integration at a set time automatically, then please review this article.
In OnePlan, the default Plan Types include: Portfolio, Program, Project, Epic, Objective, Idea, and Key Result. If the Work Item Type differs from these specified values, the plan will be imported but not accurately. Consequently, it might be perceived as 'missing' from the My Portfolio page.
While in OnePlan, navigate to Config > General > Plan Types > Add Type. Add the Work Item Type to the desired hierarchy level. Once complete, feel free to run the OnePlanUpdate strategy against a single plan to verify it worked.
Note
This field is case sensitive, if the values do not match exactly, the plan type field will remain blank.
To verify the import status of your plan, navigate to Home > Plans > All Plans. Search for the plan by its name. If the plan appears, check the 'Plan Type' column. If it's empty, you'll need to manually assign a valid plan type. To do this, use the Reorganize button located within the hamburger menu on the left side of the plan name.
- Enable the option Allow creation & editing of work items in OnePlan to be brought into Azure DevOps.
- Verify that the field mappings for both directions are accurately set. Avoid modifying any fields marked as Required in the Field Mappings section. To adjust mappings, click on the arrows connecting the saved options.
- For values that differ between Azure DevOps and OnePlan, particularly with Choice fields, add Value Mappings to ensure proper synchronization.
Each integration will be connected to a single Azure DevOps Organization.
It is highly recommended to allocate a distinct OnePlan Authentication Key for each integration. This practice enhances security and ensures clear identification for each integration.
To facilitate synchronization and differentiation among the Azure DevOps organizations, assign a unique name to each integration. This name serves as a distinguisher when exporting data from OnePlan. To set the Unique Name:
- Access Additional Options within OneConnect Integration section.
- Locate and complete the Button Name field, specifying the name that signifies the Azure DevOps organization being synched to.
- Click Save.
Complete the next steps only if Azure DevOps is already connected/installed into your OnePlan group.
- Access Reinstall within OneConnect Advanced section of the integration.
- Click Start.
Note: Reinstalling the integration will reinstall the events into the OnePlan integration section. If previously removed, please delete the event again.
Predecessors and Successors in Azure DevOps
Azure DevOps provides the capability to create predecessor and successor type links between work items.
For this relationship to be imported into OnePlan, the Task Dependencies/Dependencies field combination must be mapped.
In order to use this feature, setup the following mapping:
Exporting relationships from OnePlan to Azure DevOps is not supported.
Multi-Choice Fields in Azure DevOps
Azure DevOps has an extension called Multivalue Control that allows for multiple options to be set for a field for a work item.
When a multi select choice field in OnePlan is mapped to a field in Azure DevOps, the integration will treat the ADO field as it would be configured with the Multivalue Contol extension.
To avoid any mapping issues for the options that can be selected, run the SyncLookup strategy to synchronize lookup values between Azure DevOps and OnePlan.
Setting Parent Plans Using Custom Fields
By default, the integration establishes parent/child relationships based on the hierarchy of work items in Azure DevOps. However, there are scenarios where the desired parent plan is not represented within Azure DevOps itself. For example, you may have an "Application" plan type managed in OnePlan that should serve as the parent for certain Azure DevOps work items related to that application.
To support these use cases, you can configure a custom field mapping that automatically assigns a parent plan in OnePlan based on a custom field value in Azure DevOps.
Setup Instructions
1. Create a custom field in Azure DevOps
- Add a single-line text field in Azure DevOps that will represent the desired parent plan name as it exists in OnePlan.
2. Configure the field mapping in OneConnect
- In OneConnect, map the OnePlan field named "Parent Plan Name" to your custom Azure DevOps field. This must be configured as a plan-level field mapping.
How It Works
Populate the custom field in Azure DevOps with a valid, exact plan name from OnePlan.
When the OnePlanUpdate strategy runs, it will reference this field:
- If the value matches a unique plan name in OnePlan, that plan will be set as the parent.
- If the field is empty or the name does not match an existing plan, no changes will be made.
Rules and Behavior
- Duplicate Plan Names: If multiple plans in OnePlan share the same name, the integration will use the first match found.
- Mismatched Plan Types: If the identified parent plan’s type does not align with the expected hierarchy, the parent will not be set. A warning will be logged.
- Updating Parent Plans: Changing the parent plan name in Azure DevOps will update the parent in OnePlan during the next sync.
- Removing Parent Plan Name: Clearing the custom field in Azure DevOps will not remove the parent in OnePlan. The existing parent will remain unchanged.
- Non-Existent Plan Names: If the value entered does not match any plan in OnePlan, no changes will occur.
- Exact Match Required: The plan name must exactly match an existing plan name in OnePlan case-sensitive and whitespace included.