How to Configure Teams Upgrade and Coexistence Policies in PowerShell Using CsTeamsUpgradePolicy

In enterprise unified communications architectures transitioning from legacy Skype for Business deployments to modern Microsoft Teams, managing coexistence and client routing is paramount. Without precise policy definitions, incoming voice calls, instant messages, and meeting invites can land unpredictably across disparate desktop clients, causing communication breakdowns and missed notifications. The Teams Upgrade Policy framework governs how Skype for Business and Microsoft Teams coexist, dictating which client receives incoming chats, which platform schedules collaboration meetings, and when users transition permanently to Teams Only mode.

While Microsoft 365 administrators can configure basic upgrade settings through the Teams Admin Centre, tenant-wide migrations and granular per-user transitions require the Microsoft Teams PowerShell module. Using the Get-CsTeamsUpgradePolicy, Grant-CsTeamsUpgradePolicy, and Set-CsTeamsUpgradeConfiguration cmdlets, engineers can inspect built-in coexistence modes, assign custom migration profiles, and control legacy client deprecation.

Understanding Teams Coexistence Modes and Routing Logic

Teams Upgrade Policy defines the operational coexistence mode for a user or tenant. Microsoft provides five distinct coexistence profiles:

• Islands: Both Skype for Business and Microsoft Teams run simultaneously side-by-side as independent platforms. Messages originating in Skype land in Skype; messages originating in Teams land in Teams. There is no cross-client interoperability.
• Skype for Business Only (SfBOnly): Users communicate exclusively via Skype for Business for chat, calling, and meeting scheduling. The Teams client operates strictly in read-only mode to join external Teams meetings.
• Skype for Business with Teams Collaboration (SfBWithTeamsCollab): Users maintain Skype for Business for chats and calls, but use Teams for channel conversations, file sharing, and app integration.
• Skype for Business with Teams Collaboration and Meetings (SfBWithTeamsCollabAndMeetings): Users utilize Teams for channel collaboration and scheduling all online meetings, while one-to-one chats and voice calls remain anchored in Skype for Business.
• Teams Only (TeamsOnly): The final migration state. Microsoft Teams handles all chats, VoIP/PSTN voice calling, and meeting scheduling. The Skype for Business client is disabled for active communications.

Connecting to the Microsoft Teams PowerShell Module

To manage coexistence policies, launch an elevated PowerShell console and authenticate with Microsoft 365 tenant administrator credentials:

# Import and connect to the Microsoft Teams module
Import-Module MicrosoftTeams
Connect-MicrosoftTeams

Ensure your account possesses the Teams Administrator or Global Administrator role in Microsoft Entra ID.

Enumerating Built-in Upgrade Policies

Microsoft maintains predefined, immutable upgrade policy instances within every tenant. To list all available upgrade policies and their underlying configuration properties:

# Retrieve all built-in Teams upgrade policies
Get-CsTeamsUpgradePolicy

To inspect policy names alongside their coexistence modes in a clean table:

# Display policy identities and associated coexistence modes
Get-CsTeamsUpgradePolicy | Select-Object Identity, Mode, NotifySfBUsers

The resulting output lists standard policy templates:

Identity                                 Mode                             NotifySfBUsers
--------                                 ----                             --------------
Global                                   TeamsOnly                        False
Tag:UpgradeToTeams                       TeamsOnly                        False
Tag:Islands                              Islands                          False
Tag:SfBOnly                              SfBOnly                          False
Tag:SfBWithTeamsCollab                   SfBWithTeamsCollab               False
Tag:SfBWithTeamsCollabAndMeetings        SfBWithTeamsCollabAndMeetings    False
Tag:UpgradeToTeamsWithNotifications      TeamsOnly                        True

Checking Tenant-Wide Upgrade Configuration

Tenant-level upgrade settings govern general behaviour, including whether users receive notification banners inside their legacy Skype client alerting them that Teams is ready. Query the global upgrade configuration:

# Query tenant-wide upgrade configuration
Get-CsTeamsUpgradeConfiguration

Key parameters include:

• DownloadTeams: When set to $True, prompts legacy Skype for Business clients to automatically download and stage the Microsoft Teams desktop client in the background.
• SfBToTeamsUserOptIn: Governs whether end users can manually initiate their personal upgrade to Teams through client UI prompts.

To enable background client downloads across the entire organization:

# Enable automatic background download of Teams client
Set-CsTeamsUpgradeConfiguration -DownloadTeams $True

Assigning Coexistence Policies to Individual Users

During staged migration pilots, administrators often keep the global default mode intact while moving specific pilot groups to Teams Only mode. Assign policies to individual users using Grant-CsTeamsUpgradePolicy:

# Assign Teams Only mode to a specific user
Grant-CsTeamsUpgradePolicy -Identity "[email protected]" -PolicyName "UpgradeToTeams"

To notify the user inside their Skype for Business client that their account has migrated to Teams:

# Assign Teams Only mode with in-client migration notifications
Grant-CsTeamsUpgradePolicy -Identity "[email protected]" -PolicyName "UpgradeToTeamsWithNotifications"

To revert a user back to inheriting the tenant-wide global upgrade policy:

# Revert user to global tenant policy inheritance
Grant-CsTeamsUpgradePolicy -Identity "[email protected]" -PolicyName $Null

Bulk Migrating User Cohorts to Teams Only Mode

For staged organizational rollouts, export a user cohort list from a department or Active Directory group and batch assign the Teams Only policy:

# Bulk migrate user accounts from CSV list
$UserList = Import-Csv -Path "C:\Migration\PilotUsers.csv"

foreach ($User in $UserList) {
    Write-Host "Migrating user $($User.UserPrincipalName) to Teams Only..." -ForegroundColor Cyan
    try {
        Grant-CsTeamsUpgradePolicy -Identity $User.UserPrincipalName -PolicyName "UpgradeToTeams" -ErrorAction Stop
        Write-Host "Successfully migrated $($User.UserPrincipalName)" -ForegroundColor Green
    }
    catch {
        Write-Warning "Failed to migrate $($User.UserPrincipalName): $_"
    }
}

Auditing Effective Coexistence Mode for Users

Because policies can be assigned directly or inherited globally, check an individual user’s effective coexistence mode using Get-CsOnlineUser:

# Query effective Teams upgrade policy and coexistence mode
Get-CsOnlineUser -Identity "[email protected]" | Select-Object UserPrincipalName, TeamsUpgradePolicy, TeamsCoexistenceMode

If TeamsUpgradePolicy is empty, the user inherits the tenant’s Global policy. If an explicit policy tag is displayed, the user is bound directly to that profile.

Troubleshooting Common Migration and Routing Errors

When transitioning users between coexistence modes, several common operational barriers can arise:

• On-Premises Skype for Business DNS Conflicts: If a user’s SIP domain points to an on-premises Skype for Business Server environment rather than Microsoft 365, assigning UpgradeToTeams will fail with a validation exception. The user must first be moved from on-premises to Skype for Business Online via Move-CsUser before applying the Teams Only policy.
• Cached Credentials in Skype Client: After applying UpgradeToTeams, legacy Skype clients may take up to 24 hours to refresh policy tokens. To force an immediate refresh on client machines, clear the local SIP profile cache located at %localappdata%\Microsoft\Office\16.0\Lync\.
• Routing Loops during Islands Mode: While running Islands mode, federated external communications always land in Skype for Business unless the external organization is already Teams Only. Moving both organizations to Teams Only resolves federation routing discrepancies.

By using PowerShell to manage Teams Upgrade and Coexistence policies, administrators can execute clean, structured, and predictable user migrations to modern Microsoft Teams collaboration.