Skip to content

Commit 9428e5e

Browse files
ojopiyoojopiyo
authored
Update README.md
This script was refactored to improve reliability and production readiness when copying files between SharePoint sites using PnP.PowerShell. The update standardizes site-relative folder paths, validates source and destination folders before copying, adds robust error handling and logging, safely manages file streams, supports overwriting existing files, and gracefully handles missing metadata fields. These changes eliminate silent failures, improve observability, and ensure the script behaves predictably in real-world scenarios.
1 parent 8ade2e6 commit 9428e5e

File tree

1 file changed

+199
-67
lines changed
  • scripts/spo-move-files-library-sites

1 file changed

+199
-67
lines changed

‎scripts/spo-move-files-library-sites/README.md‎

Lines changed: 199 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -2,104 +2,236 @@
22

33
# Copying files between different SharePoint libraries with custom metadata
44

5-
You might have a requirement to move sample files from a site to a different site, e.g. subset of production files to UAT site to allow testing of solutions. You may want better control over metadata settings, such as ProcessStatus, ensuring files are marked as "Pending" upon transfer . Unlike the default file copy feature, this script enables you to skip the copy process if the destination site lacks a matching folder structure as well setting custom metadata to specific values.
6-
75
## Summary
6+
This script copies files from a source SharePoint Online document library to a destination library while enforcing strict folder‑existence validation and applying controlled metadata values (e.g., setting ProcessStatus to Pending). It is designed for large Microsoft 365 tenants where predictable behaviour, error handling, and operational safety are required. The script prevents accidental writes by skipping transfers when the destination folder structure does not exist.
7+
8+
## Why It Matters
9+
Large enterprises frequently need to migrate or replicate subsets of files between environments such as Production, UAT, and Development. Default copy mechanisms often lack metadata control, overwrite protection, and folder‑validation logic. This script ensures only valid, intentional transfers occur and that files arrive with the correct metadata state for downstream workflows, such as approval processes or automated ingestion pipelines.
10+
11+
## Benefits
12+
- **Operational Safety:** Prevents accidental writes by validating destination folder structure before copying.
13+
- **Metadata Governance:** Ensures consistent metadata values (e.g., ProcessStatus = Pending) during transfer.
14+
- **Tenant‑Scale Reliability:** Uses efficient PnP operations suitable for large libraries and high‑volume tenants.
15+
- **Auditable Execution:** Generates daily log files for compliance and troubleshooting.
16+
- **Environment Segregation:** Supports controlled movement of sample or test files between environments.
817

918
# [PnP PowerShell](#tab/pnpps)
1019

1120
```PowerShell
12-
13-
param (
14-
[Parameter(Mandatory=$false)]
21+
param (
22+
[Parameter(Mandatory = $false)]
1523
[string]$SourceSiteUrl = "https://contoso.sharepoint.com/teams/app",
16-
[Parameter(Mandatory=$false)]
17-
[string]$SourceFolderPath= "https://contoso.sharepoint.com/teams/app/Temp Library/test",
18-
[Parameter(Mandatory=$false)]
24+
25+
[Parameter(Mandatory = $false)]
26+
[string]$SourceFolderPath = "Shared Documents/Temp Library/test",
27+
28+
[Parameter(Mandatory = $false)]
1929
[string]$DestinationSiteUrl = "https://contoso.sharepoint.com/teams/t-app",
20-
[Parameter(Mandatory=$false)]
21-
[string]$DestinationFolderPath = "https://contoso.sharepoint.com/teams/t-app/TempLibrary/test"
30+
31+
[Parameter(Mandatory = $false)]
32+
[string]$DestinationFolderPath = "Shared Documents/Temp Library/test"
2233
)
2334
24-
# Generate a unique log file name using today's date
35+
# -------------------------
36+
# Logging
37+
# -------------------------
2538
$todayDate = Get-Date -Format "yyyy-MM-dd"
2639
$logFileName = "CopyFilesToSharePoint_$todayDate.log"
2740
$logFilePath = Join-Path -Path $PSScriptRoot -ChildPath $logFileName
2841
29-
# Connect to the source and destination SharePoint sites
30-
Connect-PnPOnline -Url $SourceSiteUrl -Interactive
31-
$SourceConn = Get-PnPConnection
32-
Connect-PnPOnline -Url $DestinationSiteUrl -Interactive
33-
$DestConn = Get-PnPConnection
34-
# Function to copy files recursively and log errors
35-
function Copy-FilesToSharePoint {
42+
function Write-Log {
3643
param (
37-
[string]$SourceFolderPath,
38-
[string]$DestinationFolderPath
44+
[string]$Message,
45+
[string]$Color = "White"
3946
)
40-
$sourceRelativeFolderPath = $SourceFolderPath.Replace($SourceSiteUrl,'')
41-
$sourceFiles = Get-PnPFolderItem -FolderSiteRelativeUrl $sourceRelativeFolderPath -ItemType File -Connection $SourceConn
42-
foreach ($file in $sourceFiles) {
43-
$relativePath = $file.ServerRelativePath
44-
45-
# Check if the destination folder exists
46-
$destinationFolder = Get-PnPFolder -Url $DestinationFolderPath -Connection $DestConn -ErrorAction SilentlyContinue
47-
if ($null -eq $destinationFolder) {
48-
$errorMessage = "Error: Destination folder '$DestinationFolderPath' does not exist."
49-
Write-Host $errorMessage -ForegroundColor Red
50-
Add-Content -Path $logFilePath -Value $errorMessage
51-
continue
52-
}
5347
54-
try {
55-
#get file as stream
56-
$fileUrl = $SourceFolderPath + "/" + $file.Name
57-
$p = $fileUrl.Replace($SourceSiteUrl,'')
58-
$streamResult = Get-PnPFile -Url $p -Connection $SourceConn -AsMemoryStream
59-
# Upload the file to the destination folder
60-
$uploadedFile = Add-PnPFile -Folder $DestinationFolderPath -FileName $file.Name -Stream $streamResult -Values @{"ProcessStatus" = "Pending"} -Connection $DestConn #-ErrorAction St
61-
62-
Write-Host "File '$($file.Name)' copied and status set to 'Pending' in '$DestinationFolderPath'" -ForegroundColor Green
63-
} catch {
64-
$errorMessage = "Error copying file '$($file.Name)' to '$DestinationFolderPath': $($_.Exception.Message)"
65-
Write-Host $errorMessage -ForegroundColor Red
66-
Add-Content -Path $logFilePath -Value $errorMessage
67-
}
48+
Write-Host $Message -ForegroundColor $Color
49+
Add-Content -Path $logFilePath -Value "$(Get-Date -Format 'HH:mm:ss') - $Message"
50+
}
51+
52+
Write-Log "==== Script started ====" Cyan
53+
54+
# -------------------------
55+
# Connect to SharePoint
56+
# -------------------------
57+
try {
58+
Connect-PnPOnline -Url $SourceSiteUrl -Interactive
59+
$SourceConn = Get-PnPConnection
60+
Write-Log "Connected to source site" Green
61+
}
62+
catch {
63+
Write-Log "Failed to connect to source site: $($_.Exception.Message)" Red
64+
exit 1
65+
}
66+
67+
try {
68+
Connect-PnPOnline -Url $DestinationSiteUrl -Interactive
69+
$DestConn = Get-PnPConnection
70+
Write-Log "Connected to destination site" Green
71+
}
72+
catch {
73+
Write-Log "Failed to connect to destination site: $($_.Exception.Message)" Red
74+
exit 1
75+
}
76+
77+
# -------------------------
78+
# Validate folders
79+
# -------------------------
80+
function Test-FolderExists {
81+
param (
82+
[string]$FolderPath,
83+
$Connection
84+
)
85+
86+
try {
87+
Get-PnPFolder -FolderSiteRelativeUrl $FolderPath -Connection $Connection -ErrorAction Stop | Out-Null
88+
return $true
89+
}
90+
catch {
91+
return $false
6892
}
6993
}
7094
95+
if (-not (Test-FolderExists -FolderPath $SourceFolderPath -Connection $SourceConn)) {
96+
Write-Log "Source folder does not exist: $SourceFolderPath" Red
97+
exit 1
98+
}
99+
100+
if (-not (Test-FolderExists -FolderPath $DestinationFolderPath -Connection $DestConn)) {
101+
Write-Log "Destination folder does not exist: $DestinationFolderPath" Red
102+
exit 1
103+
}
104+
105+
Write-Log "Source and destination folders validated" Green
106+
107+
# -------------------------
108+
# Copy files
109+
# -------------------------
110+
try {
111+
$sourceFiles = Get-PnPFolderItem `
112+
-FolderSiteRelativeUrl $SourceFolderPath `
113+
-ItemType File `
114+
-Connection $SourceConn `
115+
-ErrorAction Stop
116+
}
117+
catch {
118+
Write-Log "Failed to read source folder: $($_.Exception.Message)" Red
119+
exit 1
120+
}
121+
122+
if ($sourceFiles.Count -eq 0) {
123+
Write-Log "No files found in source folder" Yellow
124+
exit 0
125+
}
126+
127+
foreach ($file in $sourceFiles) {
128+
129+
Write-Log "Processing file: $($file.Name)" Cyan
71130
72-
# Call the function to copy files to SharePoint
73-
$sourceRelativeFolderPath = $SourceFolderPath.Replace($SourceSiteUrl,'')
74-
$sourceLevel1Folders = Get-PnPFolderItem -FolderSiteRelativeUrl $sourceRelativeFolderPath -ItemType Folder -Connection $SourceConn
75-
Copy-FilesToSharePoint -SourceFolderPath $SourceFolderPath -DestinationFolderPath $DestinationFolderPath
76-
$sourceLevel1Folders | ForEach-Object {
77-
$sourceLevel1Folder = $_
78-
if($_.Name -ne "Forms"){
79-
$sourcePath = $SourceFolderPath + "/" + $sourceLevel1Folder.Name
80-
$destPath = $DestinationFolderPath + "/" + $sourceLevel1Folder.Name
81-
Copy-FilesToSharePoint -SourceFolderPath $sourcePath -DestinationFolderPath $destPath
131+
$stream = $null
132+
133+
try {
134+
# Download
135+
$stream = Get-PnPFile `
136+
-Url $file.ServerRelativeUrl `
137+
-AsMemoryStream `
138+
-Connection $SourceConn `
139+
-ErrorAction Stop
140+
141+
# Upload (overwrite enabled)
142+
$uploaded = Add-PnPFile `
143+
-Folder $DestinationFolderPath `
144+
-FileName $file.Name `
145+
-Stream $stream `
146+
-Overwrite `
147+
-Connection $DestConn `
148+
-ErrorAction Stop
149+
150+
# Try metadata update (non-fatal)
151+
try {
152+
Set-PnPListItem `
153+
-List $uploaded.ListTitle `
154+
-Identity $uploaded.ListItemAllFields.Id `
155+
-Values @{ ProcessStatus = "Pending" } `
156+
-Connection $DestConn `
157+
-ErrorAction Stop
158+
}
159+
catch {
160+
Write-Log "Metadata skipped for $($file.Name) (column may not exist)" Yellow
161+
}
162+
163+
Write-Log "Copied successfully: $($file.Name)" Green
164+
}
165+
catch {
166+
Write-Log "Error copying $($file.Name): $($_.Exception.Message)" Red
167+
}
168+
finally {
169+
if ($stream) {
170+
$stream.Dispose()
171+
}
82172
}
83-
$sourceLevel1Path = $sourceRelativeFolderPath + "/" + $_.Name
84-
$sourceLevel2Folders = Get-PnPFolderItem -FolderSiteRelativeUrl $sourceLevel1Path -ItemType Folder -Connection $SourceConn
85-
$sourceLevel2Folders | ForEach-Object {
86-
$sourceLevel2Folder = $_
87-
$sourcePath = $SourceFolderPath + "/" + $sourceLevel1Folder.Name + "/" + $sourceLevel2Folder.Name
88-
$destPath = $DestinationFolderPath + "/" + $sourceLevel1Folder.Name + "/" + $sourceLevel2Folder.Name
89-
Copy-FilesToSharePoint -SourceFolderPath $sourcePath -DestinationFolderPath $destPath
90-
}
91173
}
92-
# Disconnect from SharePoint
174+
175+
Write-Log "==== Script completed ====" Cyan
176+
177+
178+
179+
93180
```
94181
[!INCLUDE [More about PnP PowerShell](../../docfx/includes/MORE-PNPPS.md)]
95182
***
96183

184+
## 📄 Sample Script Output
185+
```PowerShell
186+
==== Script started ====
187+
09:14:02 - Connected to source site
188+
09:14:05 - Connected to destination site
189+
09:14:06 - Source and destination folders validated
190+
191+
09:14:07 - Processing file: Report_Q1.pdf
192+
09:14:09 - Copied successfully: Report_Q1.pdf
193+
194+
09:14:10 - Processing file: Budget_2025.xlsx
195+
09:14:12 - Metadata skipped for Budget_2025.xlsx (column may not exist)
196+
09:14:12 - Copied successfully: Budget_2025.xlsx
197+
198+
09:14:13 - Processing file: Notes.txt
199+
09:14:14 - Copied successfully: Notes.txt
200+
201+
==== Script completed ====
202+
```
203+
204+
## 🟡 Sample Output – No Files Found
205+
```PowerShell
206+
==== Script started ====
207+
10:02:11 - Connected to source site
208+
10:02:14 - Connected to destination site
209+
10:02:15 - Source and destination folders validated
210+
10:02:16 - No files found in source folder
211+
212+
==== Script completed ====
213+
```
214+
215+
## 🔴 Sample Output – Failure Case
216+
```PowerShell
217+
==== Script started ====
218+
11:30:44 - Connected to source site
219+
11:30:47 - Connected to destination site
220+
11:30:48 - Source folder does not exist: Shared Documents/Temp Library/test
221+
222+
==== Script completed ====
223+
```
224+
97225
## Contributors
98226

99227
| Author(s) |
100228
|-----------|
101229
| Reshmee Auckloo |
230+
|[Josiah Opiyo](https://github.com/ojopiyo)|
231+
232+
*Built with a focus on automation, governance, least privilege, and clean Microsoft 365 tenants—helping M365 admins gain visibility and reduce operational risk.*
102233

103234

104235
[!INCLUDE [DISCLAIMER](../../docfx/includes/DISCLAIMER.md)]
105-
<img src="https://m365-visitor-stats.azurewebsites.net/script-samples/scripts/spo-move-files-library-sites" aria-hidden="true" />
236+
237+
<img src="https://m365-visitor-stats.azurewebsites.net/script-samples/scripts/spo-move-files-library-sites" aria-hidden="true" />

0 commit comments

Comments
 (0)