User Principal Name (UPN) Handling with Azure DevOps

The OnePlan Azure DevOps integration includes built-in logic to automatically handle scenarios where a user's Microsoft 365 email address does not match their Azure DevOps User Principal Name (UPN).

In most environments, the Microsoft 365 email address and Azure DevOps UPN are identical. However, some organizations use different values for these identities due to domain migrations, hybrid identity configurations, alternate login domains, or legacy account structures.

To help prevent assignment and ownership synchronization failures in these scenarios, the integration automatically attempts both identity values during synchronization.

No additional configuration or settings are required to enable this behavior.

Supported Fields

This functionality applies only to the following fields:

• Shared With Owner (System field)
• Assigned To (Work Plan field)

All other user-related fields are outside the scope of this functionality.

How the Matching Logic Works

When synchronizing supported user fields from OnePlan to Azure DevOps:

1. The integration first attempts to resolve the user using the Microsoft 365 email address stored in OnePlan.
2. If Azure DevOps does not recognize or resolve the email address successfully, the integration automatically retries using the user's Azure DevOps User Principal Name (UPN).
3. If either identity matches successfully, the synchronization proceeds normally.

This process occurs automatically in the background and does not require manual intervention.

Example Scenarios

Example 1 - Matching Email & UPN

Result:

• The initial email lookup succeeds.
• No fallback logic is needed.

Example 2 - Different Email and UPN

Result:

• The initial email lookup fails. 
• The integration automatically retries using UPN lookup. 
• The user is resolved successfully in Azure DevOps.

Why This Matters

This functionality helps reduce synchronization failures caused by identity mismatches between Microsoft 365 and Azure DevOps.

Common scenarios include:

• Hybrid identity environments
• Domain migrations
• Multiple login domains
• Legacy Azure DevOps account structures
• Organizations using alternate UPN suffixes

By automatically attempting both identity formats, the integration improves assignment reliability without requiring additional administrative configuration.

Multiple User Behavior

The OnePlan Owner and Assigned To fields support multiple users within OnePlan. However, Azure DevOps supports only a single user value for the corresponding assignment fields.

When multiple users exist in these supported OnePlan fields:

1. The integration evaluates the available users.
2. The first successfully resolved user is sent to Azure DevOps.
3. Azure DevOps stores only that single resolved user.

If only a single user exists in the OnePlan field, synchronization behaves as expected without ambiguity.

If multiple users are present, the resulting Azure DevOps assignment may not always reflect the intended user, since Azure DevOps does not support multi-user assignments for these fields.

For best results, it is recommended to use a single user value when synchronizing these fields to Azure DevOps.

Important Notes

• This functionality is automatic and enabled by default.
• No mapping changes or additional settings are required.
• The fallback behavior applies only to the supported fields listed above.
• Other user-related fields continue to rely on their standard synchronization behavior.