Modernize Existing UCC Sites

The modernization scripts upgrade existing UCC A Unified Contact Center, or UCC, is a queue of interactions (voice, email, IM, etc.) that are handled by Agents. Each UCC has its own settings, IVR menus and Agents. Agents can belong to one or several UCCs and can have multiple skills (competencies). A UCC can be visualized as a contact center “micro service”. Customers can utilize one UCC (e.g. a global helpdesk), a few UCC’s (e.g. for each department or regional office) or hundreds of UCC’s (e.g. for each bed at a hospital). They are interconnected and can all be managed from one central location. sites to use the modern SPFx-based UCC Dashboard. This is required for compliance with Microsoft's MC1117115 Linking the Microsoft 365 Message Center Archive on Merrill.net (maintained by a Principal Product Manager at Microsoft) for easier public reference of the Microsoft announcement. The official Message Center is accessible only to Microsoft 365 administrator accounts. announcement, which deprecates classic SharePoint publishing features.

This script can be run during normal operation of a UCC, without technical downtime of the UCC. Only an end user who needs access to the UCC configuration page will need to adjust to the new interface exposed after modernization.

When to Use These Scripts

Use the modernization scripts when you have:

• Existing UCC sites created with older versions of UCC Site Creator
• Sites using the classic portal.aspx homepage
• Sites that need to be upgraded to the modern UCC Dashboard

Before You Begin

Ensure you have:

• Completed the Prerequisites
• Deployed the UCC Dashboard (Deploy UCC Dashboard)
• PowerShell 7.4.6+ installed
• A list of site URLs to modernize

Available Scripts

Single Site Modernization

Basic Usage Example

# Store password securely in temporary memory
$certPassword = Read-Host -AsSecureString -Prompt "Enter certificate password"

# Modernize a single site
.\Modernize-UccSite.ps1 `
    -SiteUrl "https://contoso.sharepoint.com/sites/ucc-sales" `
    -Mode Modernize `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com" `
    -PreserveLegacyScripts

With Interactive Authentication

.\Modernize-UccSite.ps1 `
    -SiteUrl "https://contoso.sharepoint.com/sites/ucc-sales" `
    -Mode Modernize `
    -Interactive `
    -ClientId "your-client-id"

Parameters

Parameter	Required	Description
-SiteUrl	Yes	Full URL of the site to modernize
-ClientId	Yes	Entra ID Formerly known as Azure Active Directory (or Azure AD, or AAD) application (client) ID
-Mode	Yes	Analyze or Modernize
-CertificatePath	No*	Path to the .pfx certificate file
-CertificatePassword	No*	Certificate password as SecureString
-Tenant	No*	Tenant domain name (e.g., contoso.onmicrosoft.com) or the TenantId GUID GUID stands for Globally Unique Identifier (format is always like 2ed153b4-f632-4766-b846-5b2a769b36d1) and is a pseudo random number used in software applications that is assumed to be unique. The total number of unique keys (2<sup>128</sup> of 3.4028×10<sup>38</sup>) is very large and the probability of the creating the same GUID twice is very small, though not 100% guaranteed. The term GUID is generally used by developers working with Microsoft technologies, while UUID is used everywhere else. Read More -Tenant accepts either the tenant's .onmicrosoft.com name (e.g. contoso.onmicrosoft.com) not your primary domain (e.g. contoso.com) or the tenant ID GUID (e.g. 8aa909d4-7854-4423-b49c-8933a1492408). The GUID format can be found in the Entra ID portal under Overview. If you are unsure of your .onmicrosoft.com name, using the GUID is the more reliable option.
-Interactive	No*	Use browser-based authentication
-Force	No	Re-modernize even if already modernized
-Analyze	No	Analyze only, don't make changes
-PreserveLegacyScripts	No	Keep legacy JavaScript/CSS and files in Style Library (for testing a single subsite) Read more Preserve legacy Script Link custom actions during modernization. Use this when testing modernization on a few subsites while other subsites still run on v8.3.0.1 or earlier. The legacy scripts and files are needed for older UCC dashboards to function properly. Once all sites are modernized, re-run without this parameter to complete the cleanup.
-UseSiteCollectionAppCatalog	No	Installs the UCC Dashboard app from the site collection app catalog Available since v8.4.1.8

*Either -Interactive OR certificate parameters (including -Tenant) are required.

Preserving Legacy Scripts (for testing single subsite modernization)

By default, the modernization process removes legacy JavaScript and CSS files from the Style Library that were used by the classic portal.aspx page. These files are no longer needed when using the modern SPFx UCC Dashboard for the entire Site Collection (i.e. parent site and all subsites).

However, in some scenarios you may want to keep these files:

• Gradual migration where you're modernizing sites in phases
• Troubleshooting to compare classic vs modern behavior

Beware

Not adding this parameter while modernizing a single subsite in a site collection of UCC sites will break the visibility of legacy menu's of all other subsites in that site collection. In other words, use this parameter when testing a single (or a few) subsite modernization.

Read more

The below screenshot illustrates the effect if ommitted. This is non-reversible as the files (mentioned below) get deleted.

Using PreserveLegacyScripts

Add the -PreserveLegacyScripts switch to retain the Style Library files:

# Single site - preserve legacy scripts
.\Modernize-UccSite.ps1 `
    -SiteUrl "https://contoso.sharepoint.com/sites/ucc-sales" `
    -Mode Modernize `
    -PreserveLegacyScripts `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com"

# Batch modernization - preserve legacy scripts
.\Batch-ModernizeUccSites.ps1 `
    -InputCsv ".\UccSites.csv" `
    -Mode Modernize `
    -PreserveLegacyScripts `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com"

What Gets Preserved

When using -PreserveLegacyScripts, the following files are retained in the Style Library:

Output Difference

Without -PreserveLegacyScripts (default):

Info : Cleaning up legacy portal pages...
Info : Removed portal.aspx from Pages
Info : Cleaning up Style Library files...
Info : Removed Style Library/Anywhere365 folder

With -PreserveLegacyScripts:

Info : Cleaning up legacy portal pages...
Info : Removed portal.aspx from Pages
Info : Preserving legacy scripts in Style Library (PreserveLegacyScripts specified)

Note: The portal.aspx page is always removed regardless of this setting, as it will not render correctly after Microsoft's classic experience deprecation on March 15, 2026.

Navigation and Page Comments Inheritance

When modernizing a single UCC subsite, two visual elements cannot be removed at the subsite level: the left-side navigation menu and the page comments section. Both of these are inherited from the parent site collection and are controlled at that level, not at the individual subsite. This means that even after a successful modernization — including the removal of legacy branding, the creation of the modern Home.aspx page, and the deployment of the UCC Dashboard web part — the side navigation and comments section will remain visible until the parent site collection itself is modernized. Once the full site collection is modernized using the same process, these inherited settings are updated at the root level and will no longer appear on any of the subsites beneath it. This is expected behaviour and is not an indication that the subsite modernization was incomplete.

Limited UCC Dashboard Layout on Modernized Classic Subsites

When a classic UCC subsite is modernized, the UCC Dashboard SPFx web part is hosted on a modern SharePoint page (Home.aspx) that runs inside a classic subsite. While SharePoint allows modern pages to be created inside classic subsites, full-width page sections are not available in this context. This is a platform-level restriction documented by Microsoft: full-width column layouts are exclusively available on pages that are part of Communication Sites and are not supported on Team Sites or subsites of any kind, regardless of whether those subsites host modern pages. As Microsoft's own SharePoint Framework documentation states, the full-width column layout — which spans the entire width of the page without any horizontal margin or padding — is a feature of the Communication Site architecture and cannot be made available through scripting, web part configuration, or any other supported customisation method. See: Add sections and columns on a SharePoint modern page

and Use web parts with the full-width column.

The UCC Dashboard web part itself fully supports full-width rendering — it has the required supports FullBleed property enabled in its manifest — but the host site must be a Communication Site for this to take effect. The UCC Dashboard remains completely functional within the standard column width on modernized classic subsites (of type BLANKINTERNET#0); only the visual full-width presentation is unavailable. Customers who require a full-width dashboard layout should deploy new UCC sites as modern Communication Site collections using the UCC Site Creator, rather than continuing to use the classic subsite architecture.

Batch Modernization

For modernizing multiple sites at once, use the batch script with a CSV file.

Step 1: Create a CSV File

Create a file like UccSites.csv (or whatever name you like or adheres to company standards) with your site URLs:

SiteUrl
https://contoso.sharepoint.com/sites/ucc-sales
https://contoso.sharepoint.com/sites/ucc-support
https://contoso.sharepoint.com/sites/ucc-hr
https://contoso.sharepoint.com/sites/ucc-finance

or (subsites)

SiteUrl
https://contoso.sharepoint.com/sites/hr
https://contoso.sharepoint.com/sites/hr/ucc-employee
https://contoso.sharepoint.com/sites/hr/ucc-reqruitment
https://contoso.sharepoint.com/sites/it
https://contoso.sharepoint.com/sites/it/ucc-support
https://contoso.sharepoint.com/sites/it/ucc-vendors

or (nested subsites)

SiteUrl
https://contoso.sharepoint.com/sites/hr
https://contoso.sharepoint.com/sites/hr/emea
https://contoso.sharepoint.com/sites/hr/emea/ucc-employee
https://contoso.sharepoint.com/sites/hr/emea/ucc-reqruitment
https://contoso.sharepoint.com/sites/hr/apac
https://contoso.sharepoint.com/sites/hr/apac/ucc-employee
https://contoso.sharepoint.com/sites/hr/apac/ucc-reqruitment
https://contoso.sharepoint.com/sites/it
https://contoso.sharepoint.com/sites/it/emea
https://contoso.sharepoint.com/sites/it/emea/ucc-support
https://contoso.sharepoint.com/sites/it/emea/ucc-vendors
https://contoso.sharepoint.com/sites/it/apac
https://contoso.sharepoint.com/sites/it/apac/ucc-support
https://contoso.sharepoint.com/sites/it/apac/ucc-vendors

Note: If you have parent sites with subsites, we advise to list parent sites first. The script then processes them in order to ensure proper navigation inheritance.

Step 2: Run the Batch Script

# Store password securely in temporary memory
$certPassword = Read-Host -AsSecureString -Prompt "Enter certificate password"

# Run batch modernization
.\Batch-ModernizeUccSites.ps1 `
    -InputCsv ".\UccSites.csv" `
    -Mode Modernize `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com"

Batch Parameters

Analysis Mode

Before modernizing, you can analyze sites to see what changes will be made:

Single Site Analysis

.\Modernize-UccSite.ps1 `
    -SiteUrl "https://contoso.sharepoint.com/sites/ucc-sales" `
    -Mode Analyze `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com"

Batch Analysis

.\Batch-ModernizeUccSites.ps1 `
    -InputCsv ".\UccSites.csv" `
    -Mode Analyze `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com"

The analysis will show:

• Current homepage configuration
• Whether the UCC Dashboard is present
• What changes would be made during modernization

What the Scripts Do

The modernization process performs these steps:

1. Analyzes Site - Checks current configuration and determines if modernization is needed
2. Creates Home.aspx - Creates a new modern home page (or updates existing)
3. Adds UCC Dashboard - Adds the UCC Dashboard web part in full-width layout (former classic subsites are limited to a SharePoint one column width)
4. Sets Homepage - Configures Home.aspx as the site's welcome page
5. Cleans Up Legacy Pages - Removes old portal.aspx and related pages
6. Cleans Up Style Library - Removes legacy scripts (unless -PreserveLegacyScripts is specified)
7. Updates Navigation - Hides left navigation for clean display (only gets disabled when full site collection gets modernized, not if a single subsite is modernized for test)
8. Sets Site Logo - Applies the AnywhereNow logo
9. Applies Schema Updates - Adds any new columns required by recent versions
10. Disables Comments - Disables page comments for cleaner UI (only gets disabled when full site collection gets modernized, not if a single subsite is modernized for test)

Expected Output

Successful Modernization

============================================================
  UCC Site Modernization Tool v8.3.0.6
============================================================

  Site: https://contoso.sharepoint.com/sites/ucc-sales
  Mode: Modernize

Info : Connecting to site...
Success : Connected to site

------------------------------------------------------------
  Site Analysis
------------------------------------------------------------
Info : Current homepage: Pages/portal.aspx
Warning : Classic homepage detected - needs modernization
Info : Found 78 lists on site
Info : Detected UCC site (Agents list found)

------------------------------------------------------------
  Modernizing Site
------------------------------------------------------------
Info : Creating Home.aspx...
Info : Adding UCC Dashboard web part (full-width)...
Success : UCC Dashboard web part added (full-width)
Success : Home.aspx published
Success : Homepage set to Home.aspx
Info : Cleaning up legacy portal pages...
Info : Removed portal.aspx from Pages
Success : Navigation settings applied
Success : Site logo set (AnywhereNow)
Info : Checking for schema updates...
Success : Schema updated: 4 column(s) added to Agents, Skills

============================================================
  Modernization Complete!
============================================================

  Site: https://contoso.sharepoint.com/sites/ucc-sales
  Homepage: SitePages/Home.aspx
  Type: UCC site

Already Modernized

------------------------------------------------------------
  Analysis Summary
------------------------------------------------------------

Success : Site is already modernized!
Info : Use -Force to re-run modernization anyway

Batch Output Report

The batch script generates a CSV report in the .\Reports\ folder:

Reports\Modernization-20260208-143520.csv

This report includes:

• Site URL
• Status (Success, Failed, Skipped)
• Any error messages

Re-running Modernization

To re-modernize a site that's already been modernized (e.g., after an upgrade or to cleanup the -PreserveLegacyScripts remnants):

# Single site
.\Modernize-UccSite.ps1 ... -Force

# Batch
.\Batch-ModernizeUccSites.ps1 ... -Force

Discovering existing UCC Sites in Your Tenant

Before modernizing, you can use the Discover mode to automatically scan your entire tenant and identify all UCC sites. This is the recommended starting point for large tenants where the full list of UCC sites is not known upfront.

Read More

The discovery process identifies UCC sites by checking for the presence of the core UCC lists (Agents, Skills, Endpoints, Businesshours). Any site containing these lists is classified as a UCC site and included in the output.

Prerequisites for Discovery

• -TenantUrl must point to your SharePoint admin URL (e.g. https://contoso-admin.sharepoint.com)
• The Azure app registration must have Sites.FullControl.All application permission, as discovery requires access to enumerate all site collections in the tenant

Usage

Interactive (delegated) authentication:

Copy

PowerShell

.\Batch-ModernizeUccSites.ps1 `
    -TenantUrl "https://contoso-admin.sharepoint.com" `
    -Mode Discover `
    -Interactive `
    -ClientId "your-client-id"

Certificate-based (unattended) authentication:

Copy

PowerShell

.\Batch-ModernizeUccSites.ps1 `
    -TenantUrl "https://contoso-admin.sharepoint.com" `
    -Mode Discover `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\your-cert.pfx" `
    -CertificatePassword $certPassword `
    -Tenant "contoso.onmicrosoft.com"

Output

The script generates a CSV file in the .\Reports folder, for example:

Copy

Example Output

Reports\UccSites-20260220-143000.csv

This CSV can serve as the input for the subsequent Analyze and Modernize steps.

Recommended Workflow

Running all three modes in sequence is the recommended approach for any tenant migration:

Copy

Example Order

Discover  →  Analyze  →  Modernize

Step 1 — Discover: Find all UCC sites and generate a site list CSV.

Step 2 — Analyze: Review the generated CSV, remove any sites you want to exclude, then run Analyze to assess modernization status without making any changes.

Step 3 — Modernize: Run Modernize against the reviewed CSV to apply changes.

This staged approach ensures you have full visibility and control before any modifications are made to production sites.

Troubleshooting

"UCC Dashboard web part is NOT present" After Modernization

Cause: The SPFx package may not be deployed or available.

Solution:

1. Verify the SPFx package is deployed: Run Deploy-UccDashboard.ps1 -Force
2. Clear browser cache and check again
3. Try opening the site in InPrivate/Incognito mode

"Could not remove existing Home.aspx"

Cause: The page is set as the welcome page and can't be deleted.

Solution: This is expected. The script will update the existing page instead.

Navigation Still Visible

Cause: Browser cache may be showing old navigation.

Solution: Clear browser cache or use InPrivate/Incognito mode.

Schema Update Warnings

Cause: New columns couldn't be added to lists.

Solution: This usually means the columns already exist. The warning can be safely ignored.

Subsite Navigation Issues

Cause: Subsites may inherit navigation from parent.

Solution: Ensure parent sites are modernized first. The batch script automatically sorts sites to process parents before subsites.

Best Practices

1. Always Analyze First

Run in Analyze mode before modernizing to understand what changes will be made:

.\Batch-ModernizeUccSites.ps1 -Mode Analyze ...

2. Process Parent Sites First

If you have sites with subsites, ensure parent sites are listed first in your CSV:

SiteUrl
https://contoso.sharepoint.com/sites/ucc-main
https://contoso.sharepoint.com/sites/ucc-main/sales
https://contoso.sharepoint.com/sites/ucc-main/support

3. Test on Non-Production First

Test the modernization on a development or test tenant before running on production.

4. Schedule During Off-Hours

For large batch operations, schedule the modernization during off-peak hours to minimize user impact.

5. Communicate with Users

Inform users that:

• The site will have a new modern look
• They should clear browser cache to see all changes
• Functionality remains the same

Rollback

The modernization process does not delete data (i.e. configuration data and settings of your UCC) - it only changes the homepage and navigation, rolling back is not supported as the classic features will be deprecated by Microsoft.

Next Steps

After modernizing your sites:

• Verify each site displays the UCC Dashboard correctly
• Test UCC functionality (agents, skills, queues)
• Update any documentation or training materials for the new interface

Media Gallery

Videos

Modernize UCC site, certificate authentication

UCC site (standalone or 'OneUCC Available since UCC.Creator v8.2.0.7. The model (preferred by Microsoft) in SharePoint on Microsoft 365 where no subsites are allowed. In this model each UCC will need its own separate SharePoint site (formerly known as site collection). This does allows for more granular user access and template updates per UCC.' site), modernized with script

Batch Modernize run, 6 sites with CSV file