> For the complete documentation index, see [llms.txt](https://atlas.anywhere.now/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atlas.anywhere.now/operate/maintain-and-change/update-modernized-ucc-sites.md). # Update already-modernized UCC sites Update already-modernized UCC sites using the UCC Site Creator 8.4.2.1 procedure, not a first-time modernization guide. {% hint style="warning" %} This procedure applies to already-modernized UCC sites using UCC Site Creator 8.4.2.1, which introduces -SchemaOnly and -UpdateAppOnly. It is not the complete first-time modernization manual. Keep the existing app catalog model when using -UpdateAppOnly. A catalog-model change requires the full modernization flow, whose page and legacy-script removal risks are described below; have your partner review that separate flow before running it. Use the permissions, consent, and certificate prerequisites in the linked setup guide. For certificate examples, collect $certPassword securely with Read-Host -AsSecureString -Prompt "Enter certificate password" before running a script. Timings below are estimates, not guarantees. {% endhint %} ## Before You Begin Ensure you have: * Completed the [Prerequisites](https://atlas.anywhere.now/set-up-dialogue-cloud-neo/prerequisites/configure-sharepoint-sites) * Deployed the UCC Dashboard ([Deploy UCC Dashboard](https://atlas.anywhere.now/set-up-dialogue-cloud-neo/prerequisites/configure-sharepoint-sites/deploy-ucc-dashboard)) * PowerShell 7.4.6+ installed * A list of site URLs to modernize *** ### Parameters | Parameter | Required | Description | | ------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-SiteUrl` | Yes | Full URL of the site to modernize | | `-ClientId` | Yes | Entra ID 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
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**[Update Already-Modernized UCC Sites Callout 1](#update-already-modernized-ucc-sites-callout-1) | | `-SchemaOnly` | No |

Skip page recreation and SPFx app update. Applies list schema changes only (new columns, content types). Typical run time: \~10 seconds per site.
Update Already-Modernized UCC Sites Callout 2

| | `-UpdateAppOnly` | No |

Skip page recreation. Updates the SPFx app installation and applies schema changes. The existing Home.aspx and its web part are left in place. Typical run time: \~20–30 seconds per site.
Update Already-Modernized UCC Sites Callout 3

| #### Update Already-Modernized UCC Sites Callout 1 Source row: **-UseSiteCollectionAppCatalog**. {% hint style="info" %} Available since v8.4.1.8 {% endhint %} #### Update Already-Modernized UCC Sites Callout 2 Source row: **-SchemaOnly**. {% hint style="info" %} Available since v8.4.2.1.\ Use with `-Force` on already-modernized sites. {% endhint %} #### Update Already-Modernized UCC Sites Callout 3 Source row: **-UpdateAppOnly**. {% hint style="info" %} Available since v8.4.2.1.\ Use with `-Force` on already-modernized sites. {% endhint %} \*Either `-Interactive` OR certificate parameters (including `-Tenant`) are required. *** ## What the Scripts Do The modernization process performs these steps: The full modernization process (default, no mode switches) performs all steps below. When using `-SchemaOnly` or `-UpdateAppOnly`, steps 2–6 are skipped. 1. **Analyzes Site** — Checks current configuration and determines what changes are needed 2. **Creates Home.aspx** — Creates a fresh modern home page *(skipped with `-SchemaOnly` or `-UpdateAppOnly`)* 3. **Adds UCC Dashboard** — Adds the UCC Dashboard web part in full-width layout; classic subsites are limited to a single-column width *(skipped with `-SchemaOnly` or `-UpdateAppOnly`)* 4. **Sets Homepage** — Configures Home.aspx as the site's welcome page *(skipped with `-SchemaOnly` or `-UpdateAppOnly`)* 5. **Cleans Up Legacy Pages** — Removes old portal.aspx and related pages *(skipped with `-SchemaOnly` or `-UpdateAppOnly`)* 6. **Cleans Up Style Library** — Removes legacy scripts unless `-PreserveLegacyScripts` is used *(skipped with `-SchemaOnly` or `-UpdateAppOnly`)* 7. **Updates Navigation** — Hides left navigation for a clean full-width display (applies only when the full site collection is modernized) 8. **Sets Site Logo** — Applies the AnywhereNow logo 9. **Updates SPFx App** — Updates the UCC Dashboard app installation to the latest deployed version *(skipped with `-SchemaOnly`)* 10. **Applies Schema Updates** — Adds any new list columns and content types required by the current version 11. **Disables Comments** — Disables page comments for a cleaner UI (applies only when the full site collection is modernized) *** ## Upgrading Already-Modernized Sites Once a site has been modernized, subsequent upgrades (new UCC Dashboard release, new list columns) should be applied with as little impact as possible. Two switches make this fast and non-disruptive: | Switch | What it skips | What it does | Typical time | | ---------------- | -------------------------------- | ------------------------------------------------------------ | ------------------------ | | `-SchemaOnly` | Page recreation, SPFx app update | Applies new list columns and content types only | \~10 seconds per site | | `-UpdateAppOnly` | Page recreation | Updates the SPFx app installation and applies schema changes | \~20–30 seconds per site | Both switches require `-Force` when the site has already been modernized, as the script would otherwise report the site as up to date and exit. ### Schema Update Only Use when a new version introduces list columns or content type changes and you want to apply them to all existing sites as quickly as possible: PowerShell ``` # Single site - schema update only .\Modernize-UccSite.ps1 ` -SiteUrl "https://contoso.sharepoint.com/sites/ucc-sales" ` -Mode Modernize ` -SchemaOnly ` -Force ` -ClientId "your-client-id" ` -CertificatePath "C:\Certs\cert.pfx" ` -CertificatePassword $certPassword ` -Tenant "contoso.onmicrosoft.com" # Batch - schema update only .\Batch-ModernizeUccSites.ps1 ` -InputCsv ".\UccSites.csv" ` -Mode Modernize ` -SchemaOnly ` -Force ` -ClientId "your-client-id" ` -CertificatePath "C:\Certs\cert.pfx" ` -CertificatePassword $certPassword ` -Tenant "contoso.onmicrosoft.com" ``` ### SPFx App Update (with Schema) Use when a new UCC Dashboard SPFx package has been deployed to the app catalog and you want to update existing sites without touching the home page: PowerShell ``` # Single site - update SPFx app and schema .\Modernize-UccSite.ps1 ` -SiteUrl "https://contoso.sharepoint.com/sites/ucc-sales" ` -Mode Modernize ` -UpdateAppOnly ` -Force ` -ClientId "your-client-id" ` -CertificatePath "C:\Certs\cert.pfx" ` -CertificatePassword $certPassword ` -Tenant "contoso.onmicrosoft.com" # Batch - update SPFx app and schema .\Batch-ModernizeUccSites.ps1 ` -InputCsv ".\UccSites.csv" ` -Mode Modernize ` -UpdateAppOnly ` -Force ` -ClientId "your-client-id" ` -CertificatePath "C:\Certs\cert.pfx" ` -CertificatePassword $certPassword ` -Tenant "contoso.onmicrosoft.com" ``` *** ## 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 {% hint style="warning" %} 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 omitted. This is non-reversible as the files (mentioned below) get deleted. [![Release note illustration](https://840289663-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4DbjOdRSLcSzctdkuGJf%2Fuploads%2Fgit-blob-3856cf77241aeb4da913961a71508f4b0a7c4e49%2F931906d512ba17bd.png?alt=media)](https://github.com/AnywhereNow/atlas-docs/tree/main/operate-support/.gitbook/assets/931906d512ba17bd.png) {% endhint %} ### What Gets Preserved When using `-PreserveLegacyScripts`, the following files are retained in the Style Library: | Location | Contents | | ---------------------------------------------- | ----------------------- | | `Style Library/Anywhere365/` | A365.js, A365.css | | `Style Library/Anywhere365/Content/js/` | Custom JavaScript files | | `Style Library/Anywhere365/Content/css/` | Stylesheets | | `Style Library/Anywhere365/Content/resources/` | Language resource files | | `Style Library/Anywhere365/Images/` | Portal images and icons | ## 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. *** For current prerequisites, the latest package, and the two-step app deployment/update sequence, see [Configure SharePoint UCC sites](https://atlas.anywhere.now/set-up-dialogue-cloud-neo/prerequisites/configure-sharepoint-sites#updating-existing-modernized-sites). The [version-specific component overview](https://atlas.anywhere.now/release-notes/ucc-site-creator) retains the separate 8.4.2.1, 8.4.1.9, and 8.4.1.8 changes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://atlas.anywhere.now/operate/maintain-and-change/update-modernized-ucc-sites.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.