UCC Site Creator - Quick Start Guide

This guide provides step-by-step instructions for some common scenarios. For detailed information, see the individual documentation pages.

Before You Begin

Ensure you have completed the Prerequisites:

  • PowerShell 7.4.6+ installed
  • app registered with the following Application permissions:
    • Microsoft Graph: Sites.FullControl.All
    • SharePoint: Sites.FullControl.All
  • Certificate created and uploaded to Entra ID

Scenario 1: Modernize Existing UCC Sites

This is the most common scenario. Use this workflow when you have existing sites that need to be upgraded to the modern SPFx-based dashboard for MC1117115 compliance.

Step 1: Extract the Package

Extract UCC_Site_Creator_v8_4_0_1.zip to a folder, for example:

PowerShell
C:\Install\UCC_Site_Creator_v8_4_0_1

Step 2: Open PowerShell 7

PowerShell
pwsh
cd "C:\Install\UCC_Site_Creator_v8_4_0_1"

Step 3: Store Your Certificate Password (in temporary running memory)

PowerShell
$certPassword = Read-Host -AsSecureString -Prompt "Enter certificate password"

Step 4: Deploy UCC Dashboard (One-Time per each Catalog selected)

PowerShell
.\Deploy-UccDashboard.ps1 `
    -TenantUrl "https://contoso.sharepoint.com" `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword

Wait for the "Tenant Setup Complete!" message.

Step 5a: Modernize a Single Site

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

Step 5b: Modernize Multiple Sites (Batch)

Create a CSV file (like UccSites.csv, but any name is possible) with your site URLs:

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

Run the batch modernization:

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

Step 6: Verify

Open your browser and navigate to your modernized site. You should see the new UCC Dashboard displaying your contact center configuration.

Scenario 2: Analyze Before Modernizing

Before making changes, you can analyze your sites to see what will be updated:

Single Site Analysis

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

Batch Analysis

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

Scenario 3: Create New UCC Sites

Use this workflow when deploying UCC to a new tenant or adding new UCC sites.

Step 1: Deploy UCC Dashboard (If Not Already Done)

PowerShell
.\Deploy-UccDashboard.ps1 `
    -TenantUrl "https://contoso.sharepoint.com" `
    -ClientId "your-client-id" `
    -CertificatePath "C:\Certs\cert.pfx" `
    -CertificatePassword $certPassword

Step 2: Create Your UCC Site

PowerShell
.\UCC.Site.Creator.ps1 `
    -paramUccName "ucc-sales" `
    -paramUccTitle "Sales Contact Center" `
    -paramSiteCollectionUrl "https://contoso.sharepoint.com/sites/ucc-sales" `
    -paramSiteOwner "admin@contoso.onmicrosoft.com" `
    -paramCertificateAppId "your-client-id" `
    -paramCertificateTenantId "your-tenant-id" `
    -paramCertificatePath "C:\Certs\cert.pfx" `
    -paramCertificatePassword $certPassword

Wait for the "UCC Site Creator Complete" message.

Scenario 4: Interactive Authentication (Testing)

For testing purposes, you can use interactive (browser-based) authentication instead of certificates:

Deploy Dashboard Interactively

PowerShell
.\Deploy-UccDashboard.ps1 `
    -TenantUrl "https://contoso.sharepoint.com" `
    -Interactive `
    -ClientId "your-client-id"

Modernize Site Interactively

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

A browser window will open for you to sign in.

Common Issues

"Certificate could not be read" Error

Cause: Certificate password is incorrect or not provided.

Solution: Ensure you're passing the password as a SecureString:

PowerShell
$certPassword = ConvertTo-SecureString -String "YourPassword" -AsPlainText -Force

"Access Denied" or Permission Errors

Cause: The Entra ID app is missing required permissions.

Solution: Ensure your app has both permissions granted:

  • Microsoft Graph: Sites.FullControl.All (Application)
  • SharePoint: Sites.FullControl.All (Application)

Go to Azure Portal → App registrations → Your app → API permissions and verify both are listed with "Granted" status.

UCC Dashboard Web Part Not Available

Cause: The SPFx package wasn't deployed tenant-wide.

Solution: Run Deploy-UccDashboard.ps1 with the -Force flag:

PowerShell
.\Deploy-UccDashboard.ps1 ... -Force

Site Already Modernized

Message: "Site is already modernized!"

Solution: This is informational - your site is already using the modern dashboard. Use -Force to re-run modernization if needed.

Next Steps

For detailed information on each script: