Migrate SharePoint Taxonomy Term Stores from SharePoint 2013 On-premise to On-premise or On-premise to Online

Introduction

When we migrate SharePoint lists and libraries from one environment to another and if the list uses managed metadata columns from global or site collection term store, they tend to lose the tagging information if the term stores are not migrated alongside or created manually. The goal of this implementation is to retain the global and local term tagging information after the migration.

To achieve that, conceptually, we should be creating the term stores and their child objects and properties maintaining the same GUIDs of individual objects. This implementation automates the migration of SharePoint term store objects – groups, term sets, terms etc. to another SharePoint environment ­- on-premise or online. 

Prerequisites 

1. This solution requires PowerShell 3.0 or higher installed on the machine to be executed from. Click the link for more information and installation guidance: https://www.microsoft.com/en-us/download/details.aspx?id=34595

2. SharePoint Client Components SDK. Please verify you have the SharePoint client assemblies installed. Visit the link for installing SharePoint client SDK: https://www.microsoft.com/en-us/download/details.aspx?id=35585

3. Permission Requirement: 
   • For the export operation, the specified user account must have access to the site read access to the term store.
   • For import operation, the specified user must have access to the site and must be in the “Term Store Administrators” group.

4. Server Connectivity Requirement:  The scripts can be executed remotely from any system. However, the source and target environments should be accessible from the network scripts are being run from.

Design Overview

• The base tool used in this implementation is PowerShell scripts. A set of scripts and configuration files are provided that can be utilized to automate the implementation. A master script which when executed shall read the configurations and execute other scripts based on the configurations and parameters.

• All reusable objects and common actions such as loading dependency modules etc. are separated from the main user scripts. These dependency scripts are called by the master script before any of the user scripts are called. Many of the functionalities are loaded via the dependency scripts which must be successfully executed. In case any dependency script fails to execute, the whole execution stops.

• The implementation leverages SharePoint CSOM capabilities to interact with the term stores, and other SharePoint objects.

Below is a brief about the file structure and their usages:

1. Base Directory

The root directory will contain the files and folders      

1. Common: The ‘Common’ directory contains common scripts to load reusable objects. The current version of the implementation has the following files: –

1. Load-Assemblies.ps1: Reads the configuration file and loads assemblies required for the execution.
2. Register-Functions.ps1:  Adds reusable functions and objects to the current PowerShell execution session and makes them available to be called by other scripts.

2. Taxonomy: The ‘Taxonomy’ folder is the directory containing all the scripts, configuration files, logs and exported files relevant to the taxonomy operations.

3. Configuration.xml: The ‘Configuration.xml’ file is the master configuration file. It is utilized by the master script ‘Execute-Scripts.ps1’ script to load configuration information. It will contain the dependency and user scripts information.

4. Execute-Scripts.ps1: The ‘Execute-Scripts.ps1’ is the master script which reads the configuration file ‘Configuration.xml’ and executes other scripts.

2. User Script Directory: “Taxonomy”

The ‘Taxonomy’ directory shall contain all scripts, configuration files, logs and export directories relevant to the taxonomy operations. The contents of this directory will look as below.

1. The ‘Exports’ directory shall contain a list of files (taxonomy.xml or taxonomy-<timestamp>-<GUID>.xml) exported upon execution of the scripts which contain the terms information.

2. The ‘Logs’ directory shall contain the list of log files (<script name>-<timestamp>.log) generated by the scripts (both failures and success messages are logged). Any execution time error, warning and message shall be logged inside file ‘<script name>-<timestamp>.log’ file inside ‘Logs’ directory.

3. The ‘configuration.xml’ file shall contain the configuration information required for the script to execute (Administrators are expected to make changes to this file based on the environment they are executing these scripts, see a later section which details the file sections).

4. The ‘Export-TermStore.ps1’ script shall read configuration from the ‘configuration.xml’ file and read the term stores and export all the information to a file ‘taxonomy.xml’ inside ‘Exports’ directory.

If a file with ‘taxonomy.xml’ is already present in the ‘Exports’ directory it shall be renamed as ‘taxonomy-<timestamp>-<GUID>.xml’ where the ‘timestamp’ is the date-time when the script execution was started and ‘GUID’ is a newly generated GUID.

5. The ‘Import-TermStore.ps1’ script shall read configuration from the ‘configuration.xml’ file and the taxonomy.xml’ from inside ‘Exports’ directory. It shall create the term store objects in the target environment.

Implementation Details

This section describes about the various files used in the implementation.

1. Master Configuration File: Configuration.xml

This configuration file is utilized by the ‘Execute-Script.ps1” script and has the information as below.

1. Element configuration/dependency: Contains information about the dependency scripts to be executed and assemblies to be loaded.
2. Element configuration/executables: Contains information about which scripts are executed for export or import.

2. Master Script:  Execute-Scripts.ps1

This is the master script to begin either export or export operation. It accepts the parameter called ‘collection’. The accepted values can be supplied are ‘source’ or ‘target’. The syntax to call the script is as below.

PS C:\> Execute-Scripts.ps1 –Operation <"export" or "import">

e.g. Execute-Scripts.ps1 –Operation export

Execute-Scripts.ps1 –Operation import

The same script can be used for both export and import. The value supplied to the “Operation” parameter (the values can be “export” or “import”) will choose to run export or import operation.

3. User Script Directory: Taxonomy

The “Taxonomy” directory inside root directory shall contain all files required for the term store related scripts to work. It shall also have the “Exports” and “Logs” directories to store exported results and logs generated by the scripts.

4. Configuration file: Taxonomy/configuration.xml

This is the configuration file utilized by term store export or import operation related scripts.

1. Element: configuration/context: Web context information for retrieving taxonomy session.
2. Element: configuration/credentials: Credentials to be used for export and import.
3. Element: configuration/sitemappings: Mapping information about source and target site collections. This data is utilizes when a site collection term stores are migrated to a different site collection.

5. Script: Taxonomy/Export-TermStore.ps1

This script reads through the term stores and export the term store information to the “taxonomy.xml” file which will reside in “Exports” directory. The syntax to execute the script is as below.

PS C:\> Export-TermStore.ps1

Note: If the “Exports” or “Logs” directories are not already available, they will be created by the scripts.

6. Script: Taxonomy/Import-TermStore.ps1

This script reads “taxonomy.xml” file inside “Exports” directory and create the term store objects in the target environment. The syntax to execute the script is as below.

PS C:\> Import-TermStore.ps1

7. File: Taxonomy/Exports/taxonomy.xml

This is the output file generated by the “Export-TermStore.ps1” script. It contains the hierarchical xml representation of different term store objects such as term store, term group, term set, term etc. below is a screenshot of how the taxonomy.xml file will look like.

Execution Guidance 

Set-Location -Path D:\Scripts

PS D:\Scripts> .\Execute-Scripts.ps1 -Operation import

Limitations

This script has certain limitations as per the current implementation

1. Object creation fails in case of missing users:

If any object (term group, term set, term etc.) has a user field and if the user is missing in the target environment, the object creation will fail.

For example: A term set may contain the ‘owner’ user field. If the same user does not exist at the target environment, importing of that particular term set will fail.

2. Existing objects are not overwritten:

If an object (term group, term set, term etc.) under with the same name already exists in target, it is not overwritten. Therefore, any associated property which is added or updated to an existing object will not be imported. To import with all the properties the object must first be deleted from target.

3. The “Group Managers” and “Contributors” properties of term groups are not imported.

Source Code

http://www.codeproject.com/KB/Articles/1099878/MigrateTermStore.zip