Azure DevOps Integration - Recommendations and Best Practices

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.

Ensure Azure DevOps Work Item Types are Plan Types

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.

Set Up the Plan Type

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.

My Plan is Missing from My Portfolio

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 Two-Way Integration

OneConnect

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 configured correctly. Do not modify any fields marked as Required in the Field Mappings section. To update a mapping, select the arrow connecting the mapped fields and adjust the settings as needed. Be sure to click Save to lock in the new mappings.
For values that differ between Azure DevOps and OnePlan, particularly with Choice fields, add Value Mappings to ensure proper synchronization.

OnePlan

(Task/Backlog) Ensure that any backlog item going back into Azure DevOps has the appropriate Item Type selected.

Connecting Multiple Azure DevOps Integrations to OnePlan

Each integration will be connected to a single Azure DevOps Organization.

Authentication Keys & Personal Access Tokens

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.

Unique Naming Convention

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 supports predecessor and successor relationships between work items using dependency-based links.

To import these dependency relationships into OnePlan, the integration must be configured with the correct field mapping:

Task Dependencies (OnePlan)
Dependencies (Azure DevOps)

Both fields must be mapped together for predecessor and successor relationships to be imported successfully.

Required Configuration

To enable dependency imports, configure the Azure DevOps connector to map:

OnePlan – Task Dependencies → Azure DevOps – Dependencies

This mapping directly affects the Predecessor and Successor fields within the OnePlan Work Plan.

Scope and Limitations

This functionality applies only to task-level dependencies within the same plan.
Tasks that have dependencies on tasks in other plans are not supported and will not be imported.
Dependency relationships are not supported at the plan level—only individual tasks can participate in predecessor or successor relationships.
Exporting predecessor or successor relationships from OnePlan back to Azure DevOps is not supported. Dependency synchronization is one-directional, from Azure DevOps into OnePlan only.

Multi-Choice Fields in Azure DevOps

Azure DevOps does not natively support true multi-select picklist fields on work items. To enable this capability, Microsoft provides an extension called Multivalue Control, which allows users to select multiple values for a single picklist field on a work item form.

When a multi-choice field in OnePlan is mapped to an Azure DevOps multi-select field, the OnePlan integration assumes that the target Azure DevOps field is configured using the Multivalue Control extension. This ensures that multiple values can be stored, displayed, and synchronized correctly between the two systems.

Prerequisites

The Multivalue Control extension must be installed at the Azure DevOps Organization level.
Installing extensions typically require Azure DevOps Organization Administrator permissions.
Configuration of work item forms and processes required Process Administrator permissions.

Installing the Multivalue Control extension

This should be done by your company's Azure DevOps Organization Administrator:

In Azure DevOps, navigate to Browse Marketplace.
Select the Azure DevOps section and choose Extensions for Azure DevOps.
Locate Multivalue Control by Microsoft DevLabs.
Select Get it free.
Install the extension into the appropriate Azure DevOps organization.

.Configuring Multivalue Control on a Picklist Field

Once the extension is installed, you must configure it on each picklist field that should support multiple values.

Enable Custom Values on a Picklist Field

Navigate to:
- Organization Settings > Boards > Processes
Select the relevant Process.
Select the appropriate Work Item Type.
Locate and select the Picklist field you want to enable for multi-select. Click on the three dots (...) on the right of the field and select Edit.
In the Options section:
- Enable Allow users to enter their own values.
Save your changes.

Add the Multivalue Control to the Work Item Form

In the same Work Item Type form, click on Add custom control.
In the control configuration:
1. Under Options, select the picklist from the required dropdown
Save the form configuration by clicking OK.

At this point a new blank field will be created in your form to allow users to select multiple values within the Azure DevOps work item UI. Please ensure that the Multivalue field is next to the existing picklist to prevent confusion.

Synchronizing lookup values between Azure DevOps and OnePlan

When mapping a multi-select choice field between Azure DevOps and OnePlan, it is critical that both systems recognize the same set of allowable values.

To avoid mapping or synchronization issues:

Run the SynchLookup strategy to synchronize lookup values between Azure DevOps and OnePlan.
- Additional field mappings will have to be made for this functionality to work.
This ensures that all selectable options exist in both systems prior to data synchronization at the plan level.

Failure to synchronize lookup values may result in:

Missing values
Data not syncing as expected
Errors during integration runs

Special Behavior for Syncing data into the Work Plan

When data is flowing into the OnePlan Work Plan, the SynchLookup strategy is not required, provided the following conditions are met:

The fields are mapped at the Backlogs – Items table.
Values already exist on the Azure DevOps work items at the time of synchronization.

In this scenario:

Any value passed from Azure DevOps into OnePlan will automatically create the corresponding choice option in OnePlan.
If choice values appear to be missing in OnePlan, it indicates that those values were not selected on the Azure DevOps work items at the time they were synchronized.

Why can I not find my Azure DevOps "State" field in the TranslateLookups Table?

The TranslateLookups table is primarily used with the SynchLookups strategy to query choice and lookup fields in Azure DevOps. It retrieves the current list of selectable options for those fields and synchronizes them into corresponding OnePlan Choice or Multi-Choice fields.

However, the State field in Azure DevOps is different.

The Azure DevOps State field is a system-defined field that is implemented as a string/text field, not a true choice/lookup field. Because the TranslateLookups table only queries fields defined as choice or lookup types, the State field does not appear in the Azure DevOps dropdown within the TranslateLookups configuration.

This is expected behavior.

Recommended Configuration for State

To properly synchronize State values:

Map the Azure DevOps State field to a OnePlan Choice field in either the Plans - Plans or Backlogs - Items tables.
Use Value Mappings to translate the values into valid OnePlan options.
- Example: New (Azure DevOps) -> Not Started (OnePlan) and vice versa.

Please review the Value Mappings section within the Mappings article for more information.

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.