Deploy UCC Dashboard

The Deploy-UccDashboard.ps1 script deploys the Dashboard SPFx package to your tenant's App Catalog. This is a one-time setup that makes the UCC Dashboard web part available to all SharePoint sites in your tenant.

When to Run This Script

  • Once per tenant - Run this before modernizing or creating your first UCC site
  • After package updates - Run with -Force when upgrading to a new version of UCC Site Creator

Prerequisites

Before running this script, ensure you have:

  • Completed the Prerequisites
  • PowerShell 7.4.6+ installed
  • app with Sites.FullControl.All permission
  • Certificate file (.pfx) and password

Basic Usage

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

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

With Interactive Authentication

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

Parameters

Parameter Required Description
-TenantUrl Yes Your SharePoint tenant URL (e.g., https://contoso.sharepoint.com)
-ClientId Yes Entra ID application (client) ID
-CertificatePath No* Path to the .pfx certificate file
-CertificatePassword No* Certificate password as SecureString
-Interactive No* Use browser-based authentication
-Force No Re-deploy even if already deployed
-SkipTenantWide No Don't deploy tenant-wide (not recommended)
-UseSiteCollectionAppCatalog No Installs the UCC Dashboard app from the site collection app catalog
Available since v8.4.1.8

*Either -Interactive OR certificate parameters are required.

What the Script Does

  1. Connects to Tenant Admin - Establishes connection to your SharePoint admin center
  2. Locates App Catalog - Finds your tenant's App Catalog site
  3. Enables Scripting - Temporarily enables scripting on the App Catalog (required for deployment)
  4. Uploads SPFx Package - Uploads ucc-dashboard-spfx.sppkg to the App Catalog
  5. Deploys Tenant-Wide - Makes the web part available to all sites without per-site installation
    • Alternatively deploys to a Site Collection App Catalog per site collection if parameter is used.
  6. Creates Marker File - Creates .tenant-setup-complete to track deployment status

Expected Output

A successful deployment looks like this:

PowerShell
============================================================
  AnywhereNow UCC - Tenant Setup v8.3.0.6
============================================================

Info : Found SPFx package: ...\SPFx\sharepoint\solution\ucc-dashboard-spfx.sppkg
Info : Derived tenant admin URL: https://contoso-admin.sharepoint.com
Info : Loading bundled PnP.PowerShell module...
Info : Connecting to tenant admin: https://contoso-admin.sharepoint.com
Success : Connected to tenant admin
Info : Getting tenant App Catalog URL...
Info : Tenant App Catalog: https://contoso.sharepoint.com/sites/appcatalog
Info : Connecting to App Catalog...
Success : Connected to App Catalog
Info : Deploying SPFx package to tenant App Catalog...
Info :   Package: ...\ucc-dashboard-spfx.sppkg
Info :   Tenant-wide: True
Success : Package uploaded successfully
Info :   App ID: b6a6a24f-a81a-4d75-89be-3db0dc7464c0
Info : Verifying deployment...
Success : Package deployed and available!
Info :   Tenant-wide: Yes (available to all sites automatically)

============================================================
  Tenant Setup Complete!
============================================================

The SPFx package has been deployed to your tenant App Catalog.

The solution is available TENANT-WIDE, which means:
  - No need to install the app on each site
  - The UCC Dashboard web part is automatically available

Or go to the App Catalog in your Tenants SharePoint site.

Re-deploying (Upgrades)

When upgrading to a new version of UCC Dashboard, use the -Force flag to re-deploy the SPFx package:

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

Troubleshooting

No App Catalog Found

Error: "Could not get tenant App Catalog URL"

Solution: Create an App Catalog site in your tenant:

  1. Go to SharePoint Admin Center
  2. Navigate to More features → Apps
  3. Click App Catalog
  4. Create a new App Catalog site if prompted
Permission Denied

Error: "Access denied" or "Insufficient privileges"

Solution: Ensure your Entra ID app has:

  • Sites.FullControl.All application permission
  • Admin consent granted
Certificate Error

Error: "The specified certificate could not be read"

Solution:

  • Verify the certificate path is correct
  • Ensure the password is correct
  • Check that the certificate hasn't expired
  • Verify the certificate is uploaded to the Entra Id App.
  • Make sure your are referencing the .pfx file in your PowerShell commands, not the .cer file.

Next Steps

After deploying the UCC Dashboard:

Media Gallery

Videos

Deploy-UccDashboard, interactive authentication

Dashboard already deployed

Dashboard re-deployed (with '-Force' parameter)

Deploy-UccDashboard, certificate authentication.

Dashboard re-deployed (with '-Force' parameter)

Screenshots

Deploy-UccDashboard, interactive.

Preview Dashboard Before & After

1 / 2