Start-SPMigration/README.md

Start-SPMigration

PowerShell-Skript fuer die Migration von SharePoint On-Premise Inhalten ueber das serverseitige Objektmodell.

Das Skript kann:

• Dokumentbibliotheken exportieren
• Dateien inklusive Metadaten exportieren
• normale SharePoint-Listen und deren Eintraege exportieren
• exportierte Inhalte wieder in ein Ziel-Web importieren
• beim Export automatisch eine JSON-MappingTable fuer Feld-, Listen- und Bibliotheks-Mappings erzeugen
• beim Import dieselbe MappingTable fuer Container- und Metadaten-Mappings verwenden

Voraussetzungen

• SharePoint On-Premise Server
• Ausfuehrung auf einem Server mit installiertem SharePoint PowerShell-Modul
• Berechtigungen auf Quell- und Ziel-Web
• PowerShell mit Zugriff auf SharePointServer

Das Skript laedt intern:

Import-Module SharePointServer

Dateien im Projekt

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

Exportierte Struktur

Beim Export entsteht unter -OutputPath folgende Struktur:

OutputPath
|-- Files
|   |-- <Bibliothek>
|   |   |-- Unterordner
|   |   |   |-- Dokument.pdf
|   |   |   |-- Dokument.pdf.properties.json
|-- Lists
|   |-- ListeA.json
|-- MappingTable.json
|-- manifest.csv

Dateien

• Die Originaldatei wird in Files\<Bibliothek>\... gespeichert.
• Die Metadaten liegen direkt daneben als Sidecar-Datei: Dateiname.ext.properties.json
• manifest.csv enthaelt ausserdem Container-Eintraege fuer Listen und Dokumentbibliotheken

Listen

• Pro Liste wird genau eine JSON-Datei unter Lists\ erzeugt.
• Die Eintraege enthalten insbesondere:
  • ContentTypeId
  • FieldValues
  • FieldTextValues
  • Fields

Wichtige Metadaten

Fuer den Import sind vor allem diese Informationen relevant:

• FieldValues
• FieldTextValues
• ContentTypeId
• interne Feldnamen (InternalName)

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

MappingTable.json

Beim Export wird automatisch eine MappingTable.json erzeugt. Diese Datei enthaelt:

• LibraryMappings: Mapping von Quellbibliothek auf Zielbibliothek
• ListMappings: Mapping von Quellliste auf Zielliste
• MetadataColumnMappings: Mapping der Metadaten-Spalten je Liste/Bibliothek

Beispiel:

{
  "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

• 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

Importparameter

• 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

Hinweis:

• Wenn weder ImportFiles noch ImportLists gesetzt sind, werden beim Import beide Bereiche verarbeitet.
• Wird MappingTable nicht angegeben, verwendet das Skript standardmaessig OutputPath\MappingTable.json.
• Die alte CSV-Variante wird fuer reines Feldmapping weiterhin als Fallback gelesen.

Beispiele

Nur Export

.\Start-SPMigration.ps1 `
  -SourceUrl "http://sharepoint/sites/Quelle" `
  -Export `
  -IncludeHiddenLists `
  -IncludeHiddenLibraries

Nur Import

.\Start-SPMigration.ps1 `
  -TargetUrl "http://sharepoint/sites/Ziel" `
  -Import `
  -MappingTable "C:\Temp\SP-Export\MappingTable.json"

Export, MappingTable anpassen, dann Import

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

Danach MappingTable.json bearbeiten und dort TargetTitle sowie TargetInternalName anpassen.

Anschliessend:

.\Start-SPMigration.ps1 `
  -OutputPath "C:\Temp\SP-Export" `
  -TargetUrl "http://sharepoint/sites/Ziel" `
  -Import `
  -MappingTable "C:\Temp\SP-Export\MappingTable.json"

Nur Dateien importrelevant ausfuehren

.\Start-SPMigration.ps1 `
  -TargetUrl "http://sharepoint/sites/Ziel" `
  -Import `
  -MappingTable "C:\Temp\SP-Export\MappingTable.json" `
  -ImportFiles `
  -OverwriteFiles

Nur Listen importrelevant ausfuehren

.\Start-SPMigration.ps1 `
  -TargetUrl "http://sharepoint/sites/Ziel" `
  -Import `
  -MappingTable "C:\Temp\SP-Export\MappingTable.json" `
  -ImportLists

Aktuelles Verhalten beim Import

Dokumentbibliotheken

• Dateien werden in die per MappingTable.json aufgeloeste Zielbibliothek importiert.
• Unterordner werden bei Bedarf angelegt.
• Metadaten werden anschliessend ueber die MetadataColumnMappings gesetzt.

Listen

• Listeneintraege werden neu angelegt.
• Feldwerte werden ueber FieldValues, FieldTextValues und MetadataColumnMappings gemappt.

Bekannte Einschraenkungen

• 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.
• Sehr spezielle Feldtypen koennen je nach Farm-Konfiguration zusaetzliche Anpassungen benoetigen.
• Das Skript ist fuer SharePoint On-Premise mit serverseitigem Objektmodell gedacht, nicht fuer SharePoint Online.

Empfehlung

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.