Refactor parameter names and enhance mapping functionality in migration script

2026-04-15 18:14:51 +02:00
parent 25428ccce2
commit 0525206707
2 changed files with 432 additions and 129 deletions
--- a/README.md
+++ b/README.md
@@ -8,8 +8,8 @@ Das Skript kann:
 - Dateien inklusive Metadaten exportieren
 - normale SharePoint-Listen und deren Eintraege exportieren
 - exportierte Inhalte wieder in ein Ziel-Web importieren
- Feldwerte ueber eine Mapping-CSV von Quell- auf Ziel-InternalNames abbilden
- Listen- und Bibliotheksnamen ueber `manifest.csv` auf Zielnamen abbilden
+- beim Export automatisch eine JSON-`MappingTable` fuer Feld-, Listen- und Bibliotheks-Mappings erzeugen
+- beim Import dieselbe `MappingTable` fuer Container- und Metadaten-Mappings verwenden

 ## Voraussetzungen

@@ -27,7 +27,7 @@ Import-Module SharePointServer
 ## Dateien im Projekt

 - `Start-SPMigration.ps1`: Hauptskript fuer Export und optionalen Import
- `FieldMapping.sample.csv`: Beispiel fuer das Feldmapping
+- `FieldMapping.sample.csv`: altes CSV-Beispiel fuer Feldmapping, weiterhin als Fallback lesbar

 ## Exportierte Struktur

@@ -42,6 +42,7 @@ OutputPath
 |   |   |   |-- Dokument.pdf.properties.json
 |-- Lists
 |   |-- ListeA.json
+|-- MappingTable.json
 |-- manifest.csv
 ```

@@ -72,67 +73,85 @@ Fuer den Import sind vor allem diese Informationen relevant:

 Der Name des Inhaltstyps wird bewusst nicht als fuehrende Importinformation verwendet, da er sich im Zielsystem unterscheiden kann.

-## Mapping-CSV
+## MappingTable.json

-Format:
+Beim Export wird automatisch eine `MappingTable.json` erzeugt. Diese Datei enthaelt:

-```csv
-SourceInternalName;TargetInternalName
-DHS2016Persdat;Persdat
-DHS2016Dienstgrad;Dienstgrad
-DHS2016SecurityClearance;SecurityClearance
-```
-
-Bedeutung:
-
- `SourceInternalName`: interner Feldname aus dem Export
- `TargetInternalName`: interner Feldname im Zielsystem
-
-## manifest.csv fuer Listen- und Bibliotheksmapping
-
-Beim Export wird fuer jede Liste und jede Dokumentbibliothek eine Container-Zeile in `manifest.csv` geschrieben.
-
-Wichtige Spalten:
-
- `RecordType`
- `ObjectType`
- `SourceTitle`
- `TargetTitle`
- `BaseTemplate`
-
-Fuer das Mapping ist insbesondere `TargetTitle` gedacht:
-
- leer: das Skript sucht im Ziel mit dem Quellnamen
- gesetzt: das Skript sucht im Ziel mit dem Wert aus `TargetTitle`
+- `LibraryMappings`: Mapping von Quellbibliothek auf Zielbibliothek
+- `ListMappings`: Mapping von Quellliste auf Zielliste
+- `MetadataColumnMappings`: Mapping der Metadaten-Spalten je Liste/Bibliothek

 Beispiel:

-```csv
-RecordType;ObjectType;SourceWebUrl;SourceTitle;TargetTitle;BaseType;BaseTemplate;RootFolderUrl;SourceServerRelativeUrl;FileName;FileUniqueId;FileLength;LocalFilePath;LocalMetadataPath;ExportedAtUtc
-Container;DocumentLibrary;http://clshp001/;Documents;Dokumente;DocumentLibrary;101;/Documents;/Documents;;;;;;
-Container;List;http://clshp001/;TestListe;ZielTestListe;GenericList;100;/Lists/TestListe;/Lists/TestListe;;;;;;
+```json
+{
+  "SchemaVersion": 1,
+  "GeneratedAtUtc": "2026-04-15T08:00:00.0000000Z",
+  "SourceWebUrl": "http://sharepoint/sites/Quelle",
+  "LibraryMappings": [
+    {
+      "ObjectType": "DocumentLibrary",
+      "SourceTitle": "Documents",
+      "TargetTitle": "Dokumente",
+      "BaseType": "DocumentLibrary",
+      "BaseTemplate": 101,
+      "RootFolderUrl": "/Documents",
+      "Hidden": false
+    }
+  ],
+  "ListMappings": [
+    {
+      "ObjectType": "List",
+      "SourceTitle": "TestListe",
+      "TargetTitle": "ZielTestListe",
+      "BaseType": "GenericList",
+      "BaseTemplate": 100,
+      "RootFolderUrl": "/Lists/TestListe",
+      "Hidden": false
+    }
+  ],
+  "MetadataColumnMappings": [
+    {
+      "ObjectType": "DocumentLibrary",
+      "ContainerSourceTitle": "Documents",
+      "SourceInternalName": "DHS2016Persdat",
+      "TargetInternalName": "Persdat",
+      "DisplayName": "Personaldaten",
+      "TypeAsString": "Text",
+      "Hidden": false,
+      "ReadOnly": false,
+      "Sealed": false
+    }
+  ]
+}
 ```

+Fuer das Mapping ist vor allem relevant:
+
+- `TargetTitle`: Zielname von Liste oder Bibliothek
+- `TargetInternalName`: Zielfeld fuer die exportierte Metadatenspalte
+
 Wenn eine Ziel-Liste oder Ziel-Bibliothek nicht existiert, gibt das Skript eine Warnung aus, dass dieser Container manuell angelegt werden soll.

 ## Parameter

 ### Pflichtparameter

- `WebUrl`: Quell-Web fuer den Export
- `OutputPath`: Ausgabeordner fuer den Export
+- `SourceUrl`: Quell-Web fuer den Export
+- `TargetUrl`: Ziel-Web fuer den Import
+
+`OutputPath` ist optional. Standard ist `.\SPMigrationOutput` im aktuellen Verzeichnis.

 ### Exportparameter

+- `Export`: fuehrt den Export aus
 - `IncludeHiddenLibraries`: exportiert auch versteckte Bibliotheken
 - `IncludeHiddenLists`: exportiert auch versteckte Listen
- `ExportOnly`: fuehrt nur den Export aus
- `ImportOnly`: fuehrt nur den Import aus einem vorhandenen Exportordner aus

 ### Importparameter

- `TargetWebUrl`: Ziel-Web fuer den Import
- `MappingCsvPath`: CSV fuer Feldmapping
+- `Import`: fuehrt den Import aus einem vorhandenen Exportordner aus
+- `MappingTable`: JSON-Datei mit Listen-, Bibliotheks- und Spalten-Mappings
 - `ImportFiles`: importiert nur Dateien/Bibliotheken
 - `ImportLists`: importiert nur Listen
 - `OverwriteFiles`: ueberschreibt vorhandene Dateien beim Import
@@ -140,8 +159,8 @@ Wenn eine Ziel-Liste oder Ziel-Bibliothek nicht existiert, gibt das Skript eine
 Hinweis:

 - Wenn weder `ImportFiles` noch `ImportLists` gesetzt sind, werden beim Import beide Bereiche verarbeitet.
- Wenn `ExportOnly` gesetzt ist, wird kein Import gestartet.
- Wenn `ImportOnly` gesetzt ist, wird kein neuer Export gestartet.
+- Wird `MappingTable` nicht angegeben, verwendet das Skript standardmaessig `OutputPath\MappingTable.json`.
+- Die alte CSV-Variante wird fuer reines Feldmapping weiterhin als Fallback gelesen.

 ## Beispiele

@@ -149,50 +168,49 @@ Hinweis:

 ```powershell
 .\Start-SPMigration.ps1 `
-  -WebUrl "http://sharepoint/sites/Quelle" `
-  -OutputPath "C:\Temp\SP-Export" `
-  -ExportOnly
+  -SourceUrl "http://sharepoint/sites/Quelle" `
+  -Export `
+  -IncludeHiddenLists `
+  -IncludeHiddenLibraries
 ```

-### Export und danach Import
+### Nur Import

 ```powershell
 .\Start-SPMigration.ps1 `
-  -WebUrl "http://sharepoint/sites/Quelle" `
-  -OutputPath "C:\Temp\SP-Export" `
-  -TargetWebUrl "http://sharepoint/sites/Ziel" `
-  -MappingCsvPath ".\FieldMapping.sample.csv"
+  -TargetUrl "http://sharepoint/sites/Ziel" `
+  -Import `
+  -MappingTable "C:\Temp\SP-Export\MappingTable.json"
 ```

-### Export, manifest.csv anpassen, dann nur Import
+### Export, MappingTable anpassen, dann Import

 ```powershell
 .\Start-SPMigration.ps1 `
-  -WebUrl "http://sharepoint/sites/Quelle" `
+  -SourceUrl "http://sharepoint/sites/Quelle" `
  -OutputPath "C:\Temp\SP-Export" `
-  -ExportOnly
+  -Export
 ```

-Danach `manifest.csv` bearbeiten und `TargetTitle` fuer Listen oder Bibliotheken setzen.
+Danach `MappingTable.json` bearbeiten und dort `TargetTitle` sowie `TargetInternalName` anpassen.

 Anschliessend:

 ```powershell
 .\Start-SPMigration.ps1 `
  -OutputPath "C:\Temp\SP-Export" `
-  -TargetWebUrl "http://sharepoint/sites/Ziel" `
-  -MappingCsvPath ".\FieldMapping.sample.csv" `
-  -ImportOnly
+  -TargetUrl "http://sharepoint/sites/Ziel" `
+  -Import `
+  -MappingTable "C:\Temp\SP-Export\MappingTable.json"
 ```

 ### Nur Dateien importrelevant ausfuehren

 ```powershell
 .\Start-SPMigration.ps1 `
-  -WebUrl "http://sharepoint/sites/Quelle" `
-  -OutputPath "C:\Temp\SP-Export" `
-  -TargetWebUrl "http://sharepoint/sites/Ziel" `
-  -MappingCsvPath ".\FieldMapping.sample.csv" `
+  -TargetUrl "http://sharepoint/sites/Ziel" `
+  -Import `
+  -MappingTable "C:\Temp\SP-Export\MappingTable.json" `
  -ImportFiles `
  -OverwriteFiles
 ```
@@ -201,10 +219,9 @@ Anschliessend:

 ```powershell
 .\Start-SPMigration.ps1 `
-  -WebUrl "http://sharepoint/sites/Quelle" `
-  -OutputPath "C:\Temp\SP-Export" `
-  -TargetWebUrl "http://sharepoint/sites/Ziel" `
-  -MappingCsvPath ".\FieldMapping.sample.csv" `
+  -TargetUrl "http://sharepoint/sites/Ziel" `
+  -Import `
+  -MappingTable "C:\Temp\SP-Export\MappingTable.json" `
  -ImportLists
 ```

@@ -212,18 +229,18 @@ Anschliessend:

 ### Dokumentbibliotheken

- Dateien werden in die per `manifest.csv` aufgeloeste Zielbibliothek importiert.
+- Dateien werden in die per `MappingTable.json` aufgeloeste Zielbibliothek importiert.
 - Unterordner werden bei Bedarf angelegt.
- Metadaten werden anschliessend ueber das CSV-Mapping gesetzt.
+- Metadaten werden anschliessend ueber die `MetadataColumnMappings` gesetzt.

 ### Listen

 - Listeneintraege werden neu angelegt.
- Feldwerte werden ueber `FieldValues` und `FieldTextValues` gemappt.
+- Feldwerte werden ueber `FieldValues`, `FieldTextValues` und `MetadataColumnMappings` gemappt.

 ## Bekannte Einschraenkungen

- Die Zielaufloesung kann ueber `manifest.csv` mit `TargetTitle` ueberschrieben werden.
+- Die Zielaufloesung kann ueber `MappingTable.json` mit `TargetTitle` ueberschrieben werden.
 - Listenanhaenge werden derzeit noch nicht physisch mit importiert.
 - Ordner in normalen Listen werden beim Import derzeit uebersprungen.
 - Fehlende Ziellisten oder Zielbibliotheken werden derzeit nicht automatisch angelegt; das Skript gibt stattdessen eine Warnung zur manuellen Anlage aus.
@@ -232,4 +249,4 @@ Anschliessend:

 ## Empfehlung

-Zuerst immer mit `-ExportOnly` testen und die exportierten `*.properties.json` sowie die Listen-JSONs pruefen. Danach das Feldmapping vervollstaendigen und erst dann den kombinierten Export/Import gegen das Zielsystem laufen lassen.
+Zuerst immer mit `-Export` testen und die exportierten `*.properties.json`, Listen-JSONs und die `MappingTable.json` pruefen. Danach die Zielnamen und Feldmappings vervollstaendigen und erst dann den Import gegen das Zielsystem laufen lassen.