New method for OneUCC Site Install using PnP.PowerShell.
Introduction
This is the preferred method for creating sites for new 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.'s or when an update from an older version of the Ucc.creator template is required.
This is the new instruction for a complete 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 Anywhere365 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 installation with more up-to-date technology to create sites authorization methods. Specifically:
-
App-only + certificate access
-
using PnP.Powershell instead of SPO_ManagementShell
-
No manual creation of apps, permissions and sites through SharePoint Admin portal
-
no ClientSecrets are created or needed in this install scenario (client secrets can still be added and used for legacy tasks, but Microsoft is retiring their use, see Supplemental Anouncement 2 ).
Use this method for:
-
The OneUCC deployment model which is required for your UCC SharePoint sites (will also work with subsites, but they are increasingly discouraged by Microsoft), and
-
To leverage the more up-to-date PnP PowerShell (Learn More - GitHub) instead of the legacy SPO-ManagementShell , and
-
To use an App and self-signed certificate (no purchase involved) for Microsoft Entra ID Formerly known as Azure Active Directory (or Azure AD, or AAD)App-only access to create and update all your UCC SharePoint sites, and
-
To grant the App-only app permission to Sites.Selected only in your tenant (a recently added permission to SharePoint in Microsoft 365) instead of Sites.FullControl.All.
The below instruction is a procedure to create and build UCC SharePoint sites with no interaction to the SharePoint-admin portal, minimal access to the Microsoft Entra ID Formerly known as Azure Active Directory (or Azure AD, or AAD) App portal and most interactions via PnP.Powershell.
Prerequisites
-
Latest PowerShell 7, goto - https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows
-
Latest PnP Powershell, goto - https://pnp.github.io/powershell/articles/installation.html
-
A Microsoft 365 Administrator account with permissions to create an App Registration in Microsoft Entra ID, goto - https://entra.microsoft.com/
-
Latest Bundle Ucc.Creator template scripts, see - Bundle Release Notes
1. Generate Certificate
Time to execute: approx. 10 min.
Follow Microsoft's instructions on generating a private certificate (no cost involved, just PowerShell) for your Entra ID App-only access, Learn More - Microsoft
In summary:
-
Copy and Run the Microsoft provided PowerShell script to generate your private X.509 certificate. When asked for:
-
CommonName (we suggest "Anywhere365AppOnly")
-
StartDate (we suggest your current date)
-
EndDate (we suggest you adhere to your IT policy for certificate renewal dates)
-
Password (we suggest you adhere to your IT policy for password formats)
Output should be similar to (but could be different if you run the script with parameters for these values)
-
2. Add a Microsoft Entra App Registration for "Sites.Selected" only
Time to execute: approx. 5 min.
Add a new App Registration to your Microsoft Entra admin center, visit - https://entra.microsoft.com/
-
Goto Applications -> App registrations -> + New registration
-
When a name is asked for your App registration we suggest something like "Anywhere365 Ucc Site Creator AppOnly".
-
Goto API permissions -> SharePoint -> Application permissions -> Sites.Selected -> Add permissions
-
click Grant admin consent for <tenant-name>
-
Goto Certificates & secrets -> Certificates -> Upload certificates -> select your local .cer certificate file -> enter Description -> Add
-
Goto Overview to verify and collect your ID's to use in the PnP.PowerShell scripts and commands
-
Remember to copy and safeguard the Application (client) ID
-
Remember to copy and safeguard the Password you entered during certificate creation (.pfx and .cer file).
-
Remember to copy and safeguard the certificate .pfx and .cer file.
-
You should know your Microsoft 365 Directory (tenant) ID
3. Create and Prepare Site using PnP.Powershell
Time to execute: approx. 10 min.
Tip: You may need to wait a couple of minutes in between each PowerShell command below to allow the change to be permeated in your Microsoft 365 tenant.
-
Step 2: Connect to your SharePoint Online tenant
-
Step 3: Create a SharePoint site (formerly known as site collection) for a UCC
CopyPnP.PowerShellNew-PnPSite -Type TeamSiteWithoutMicrosoft365Group -Title <ucc-name> -Url https://<tenant-name>.sharepoint.com/sites/<ucc-name>
Note: In this example a site of type "TeamSiteWithoutMicrosoft365Group" is selected. Other types are possible like "CommunicationSite" or a regular "TeamSite" but they may create additional resources not typically used for a UCC site, like an email address or a Team Group.
- Learn More - PnP.Github -
Step 4: Enable custom scripting on the created UCC site
CopyPnP.PowerShellSet-PnPSite -Identity https://<tenant-name>.sharepoint.com/sites/<ucc-name> -NoScriptSite $false
-
Step 5: Grant "write" permissions to the site for the App Registration created. (This is needed prior to elevate the permission to FullControl)
The output of this command will provide an ID string needed in the next step.CopyPnP.PowerShellGrant-PnPAzureADAppSitePermission -AppId <Guid> -DisplayName "<String>" -Permissions Write -Site https://<tenant-name>.sharepoint.com/sites/<ucc-name>
-
Step 6: Elevate permission of the App-only App for the UCC site to "FullControl".
CopyPnP.PowerShellSet-PnPAzureADAppSitePermission -PermissionId <LongString> -Permissions FullControl -Site https://<tenant-name>.sharepoint.com/sites/<ucc-name>
4. Run Ucc.Creator template scripts
Time to execute: approx. 20 min.
-
Step 1: Populate the configuration.xml file of the Ucc.Creator package with
- SiteCollectionUrl
- CertificateAppId
- CertificateTenantId
- CertificatePassword (if encrypted="true", please encrypt with the encryptpassword.ps1 script in the Ucc.Creator package)
- CertificatePath (the local path to where the .pfx file is stored)
-
Step 2: Run Ucc.SiteCollection.Creator.ps1 script in PowerShell
-
Step 3: Add UCC Name -> DisplayName -> Language to UCC creator list in the Ucc site (optional for now is Timezone, CDR Database Connectionstring and LineURI)
-
Navigate to the created site https://<tenant-name>.sharepoint.com/sites/<ucc-name>/SitePages/default.aspx
-
-
Step 4: Run Ucc.Creator.ps1 script in Powershell
-
The UCC site is now created and populated with all required ucc.creator template assets and is ready for further configuration.
Next Steps
-
Repeat the steps in heading 3 and 4 for every UCC you want to create or request.
-
Enable the Anywhere365 (regional) Enterprise Application App-Only with certificate for access to all your UCC sites, see: SharePoint Online Authentication for Anywhere 365 Dialogue Cloud Microsoft Entra ID App-Only
-
to set the permission on all your UCC Sites using an easy PowerShell script and private App Registration, Granting permission to Multiple Sites - Powershell Script
Update Sites
- To update a UCC site to a higher version (if and when it becomes available in a bundle), enter the site and certificate details in the configuration.xml file and run Ucc.Update.ps1 script, for every site you need to update.