Renaming SharePoint List URLs and Titles with PnP PowerShell in Docker Containers

SharePoint Online lists often have URLs that include the “/Lists/” path segment. Users may want to rename the URL and update the title of a list without losing this segment to maintain a clean structure and avoid breaking links. Traditional PowerShell scripts often move the list to a new path, which might not be desirable. The goal is to rename a list while retaining the “/Lists/” segment in the URL and updating its title.

Solution

We can use PnP PowerShell scripts to rename SharePoint list URLs and update their titles. To execute these scripts in a consistent and isolated environment, we will use Docker containers. This approach ensures that the required dependencies are always available, and the script runs in a predictable environment. Additionally, we will pass necessary parameters such as the SharePoint site URL, client ID, secret, list title, and new URL name to the PowerShell script.

Context and Importance

Users often face difficulties in modifying URLs for SharePoint lists, as highlighted in various community forums and support threads. This solution addresses such common problems effectively and provides a clear, replicable method.

Prerequisites

Before you begin, ensure you have the following:

• Docker: Installed on your machine. You can download and install it from Docker’s official website.
• PnP PowerShell Module: Included in the Docker image we will be using.
• SharePoint Online: Access with administrative privileges to the site containing the list you want to rename.
• Client ID and Client Secret: Created in Azure AD for authentication. Follow these instructions to create and configure the Client ID and Client Secret.
• PowerShell Script: Prepared with the necessary parameters to rename the list URL and update the title.

Step-by-Step Solution

Prepare the PnP PowerShell Script: Create a PowerShell script to rename the SharePoint list URL and update its title, allowing parameters to be passed. Here is an example script (rename-list.ps1):

param (
    [string]$SiteURL,
    [string]$ClientId,
    [string]$ClientSecret,
    [string]$CurrentListTitle,
    [string]$NewListTitle,
    [string]$NewListPath
)

# Connect to the SharePoint site
Connect-PnPOnline -Url $SiteURL -ClientId $ClientId -ClientSecret $ClientSecret

# Get the current list
$CurrentList = Get-PnPList | Where-Object { $_.Title -eq $CurrentListTitle }

if ($null -eq $CurrentList) {
    Write-Host "Error: List with title '$CurrentListTitle' not found."
    exit 1
}

Write-Host "Current List ID: $($CurrentList.Id)"
Write-Host "Current List URL: $($CurrentList.RootFolder.ServerRelativeUrl)"

# Set the new title for the list
Set-PnPList -Identity $CurrentList.Id -Title $NewListTitle

Write-Host "List title updated successfully."

# Rename the root folder (change the URL)
$CurrentList.RootFolder.MoveTo("Lists/$NewListPath")
$CurrentList.RootFolder.Context.ExecuteQuery()

Write-Host "List URL updated successfully."

Map Current Working Directory: When running the Docker container, we need to ensure that the script file is accessible inside the container. This is achieved by mapping the current working directory (pwd) on the host machine to a directory inside the Docker container (/home). This allows the container to access the script file from the host machine.

For Linux/WSL/Mac OS:

docker run --rm -v "$(pwd):/home" -w /home m365pnp/powershell pwsh rename-list.ps1 -SiteURL "https://tenant-name.sharepoint.com/teams/team-site-name/" -ClientId "xxxxxxx" -ClientSecret "xxxxxxx" -CurrentListTitle "Old List Title" -NewListTitle "New List Title" -NewListPath "new-list-path"

For Windows OS:

docker run --rm -v "${pwd}:C:\workplace" -w C:\workplace m365pnp/powershell pwsh rename-list.ps1 -SiteURL "https://tenant-name.sharepoint.com/teams/team-site-name/" -ClientId "xxxxxxx" -ClientSecret "xxxxxxx" -CurrentListTitle "Old List Title" -NewListTitle "New List Title" -NewListPath "new-list-path"

Conclusion

Using PnP PowerShell scripts within Docker containers provides a robust solution for renaming SharePoint list URLs and updating their titles while maintaining the desired URL structure. By passing parameters such as the SharePoint site URL, client ID, secret, current list title, new list title, and new list path, we ensure flexibility and ease of use. Mapping the current working directory to a directory within the Docker container ensures that the necessary files are accessible, providing consistency and reliability in script execution. This approach reduces the potential for environment-related issues and makes the method an effective tool for SharePoint administrators.