Creating a OneUCC Site 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.

Read More

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 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 (easy to manage but very secure)

• Using PnP.PowerShell instead of SPO_ManagementShell (these are 2 distinctly different products)

• No manual creation of apps, permissions and sites through SharePoint Admin portal (more steps can be done as sequential Powershell tasks)

• 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 Announcement 2 (late 2023): Microsoft SharePoint Azure-ACS retirement: ).

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 permission to Sites.Selected in your tenant (added as a newer permission type to SharePoint in Microsoft 365) instead of the previous only option Sites.FullControl.All.

In short, 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, see: https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows

• Latest PnP PowerShell module, see: https://pnp.github.io/powershell/articles/installation.html

• A Microsoft 365 Administrator user/account with permissions to create an App Registration in your Microsoft Entra ID, goto - https://entra.microsoft.com/

• A Microsoft Entra Id Application created to allow PnP.PowerShell access to Microsoft 365, see: https://pnp.github.io/powershell/index.html

• 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:

1. Copy and Run the Microsoft provided PowerShell script to generate your private X.509 certificate. When asked for:

   • CommonName (we suggest "AnywhereAppOnly", or adhere to your IT naming conventions)

   • 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. Create New PnP.PowerShell Application

Time to execute: approx. 1 min.

Run the following command (adapted from: https://pnp.github.io/powershell/articles/registerapplication.html) and populate the <your-tenant> variable:

Register-PnPEntraIDAppForInteractiveLogin -ApplicationName "AnywhereNow-OneUCC-PnPApp" -Tenant <your-tenant>.onmicrosoft.com -Interactive

3. 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
  or
  Find Application with name "AnywhereNow-OneUCC-PnP-App"

• As a name for a new App registration we suggest something like "AnywhereNow Ucc Site Creator AppOnly".
  or

  Select Application with name "AnywhereNow-OneUCC-PnP-App"

  or

• Goto API permissions -> Add a Permission -> SharePoint -> Application permissions -> Sites.Selected -> Add permissions

  or

• click Grant admin consent for <tenant-name>

  or

• 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

4. Create and Prepare Site using PnP.Powershell

Time to execute: approx. 10 min.

• Step 1: Start PowerShell 7
  

• Step 2: Connect to your SharePoint Online tenant

  Copy

  PnP.PowerShell

  Connect-PnPOnline -Url https://<tenant-name>.sharepoint.com/ -Interactive -ClientId <Your-AnywhereNow-OneUCC-PnPApp-Id>

  Example:
  
  

• Step 3: Create a SharePoint site (formerly known as site collection) for a UCC

  Copy

  PnP.PowerShell

  New-PnPSite -Type TeamSiteWithoutMicrosoft365Group -Title <ucc-name> -Url https://<tenant-name>.sharepoint.com/sites/<ucc-name> -Lcid <4-Digits>

  Example:
  
  

  Note

  1: 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.
  

  2: The Country Code parameter (-Lcid) defines the default localization (language) of this SharePoint site. It cannot be changed afterwards! It should match the localization in which you want to create and present the UCC site to your end-users. (i.e. it should be the same language selected in Step 3: Add UCC Name -> DisplayName -> Language to UCC creator list in the Ucc site )

  List of LCID codes (Languages) supported by Anywhwere365 Ucc.Creator

  Danish - 1030

  Dutch - 1043

  English - 1033

  French - 1036

  German - 1031

  Italian - 1040

  Norwegian - 1044

  Portuguese - 2070

  Spanish - 3082

  Swedish - 1053

  For more information on PnP parameters see: New-PnPSite.html
  

• Step 4: Enable custom scripting on the created UCC site

  Copy

  PnP.PowerShell

  Set-PnPSite -Identity https://<tenant-name>.sharepoint.com/sites/<ucc-name> -NoScriptSite $false

  Example:
  

• 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.

  Copy

  PnP.PowerShell

  Grant-PnPAzureADAppSitePermission -AppId <Guid> -DisplayName "<String>" -Permissions Write -Site https://<tenant-name>.sharepoint.com/sites/<ucc-name>

  Example:
  

• Step 6: Elevate permission of the App-only App for the UCC site to FullControl.

  Copy

  PnP.PowerShell

  Set-PnPAzureADAppSitePermission -PermissionId <LongString> -Permissions FullControl -Site https://<tenant-name>.sharepoint.com/sites/<ucc-name>

  Example:
  

5. 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)
    

  Example:
  

• Step 2: Run Ucc.SiteCollection.Creator.ps1 script in PowerShell

  Example:
  

• Step 3: Add UCC Name -> DisplayName -> Language to UCC creator list in the Ucc site

  (Timezone, CDR Call Detail Records (CDR) are the meta data of a converstation: who talked to whom, at which time, for how long and with which identity among other things (skill, optional classification, etc) which gets stored in your SQL (analytical) database. Database Connectionstring and LineURI are optional)

  • 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

  Example:
  

• The UCC site is now created and populated with all required ucc.creator template assets and is ready for further configuration.

How to 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.