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.
- 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
- 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
- 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.
- 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.
- 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:
The root directory will contain the files and folders
- Common: The ‘Common’ directory contains common scripts to load reusable objects. The current version of the implementation has the following files
- Load-Assemblies.ps1: Reads the configuration file and loads assemblies required for the execution.
- Register-Functions.ps1: Adds reusable functions and objects to the current PowerShell execution session and makes them available to be called by other scripts.
- Taxonomy: The ‘Taxonomy’ folder is the directory containing all the scripts, configuration files, logs and exported files relevant to the taxonomy operations.
- 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.
- Execute-Scripts.ps1: The ‘Execute-Scripts.ps1’ is the master script which reads the configuration file ‘Configuration.xml’ and executes other scripts.
- 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.
- 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.
- 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.
- 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).
- 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.
- 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.
This section describes about the various files used in the implementation.
- Master Configuration File: Configuration.xml
This configuration file is utilized by the ‘Execute-Script.ps1” script and has the information as below.
- Element configuration/dependency: Contains information about the dependency scripts to be executed and assemblies to be loaded.
- Element configuration/executables: Contains information about which scripts are executed for export or import.
- 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.
- 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.
- Configuration file: Taxonomy/configuration.xml
This is the configuration file utilized by term store export or import operation related scripts.
- Element: configuration/context: Web context information for retrieving taxonomy session.
- Element: configuration/credentials: Credentials to be used for export and import.
- 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.
- 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.
- 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
- 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.
This section describes the procedures how to set up the configuration files and start execution.
- Set your PowerShell working location to where the scripts are located.
For example: if you have saved the scripts to the location “D:\Scripts”, set the location by executing the following command:
Set-Location -Path D:\Scripts
This should change the location in the PowerShell console accordingly. See the screenshot below.
- Edit the Taxonomy configuration file “.\Taxonomy\configuration.xml”
- Specify the “weburl” and “environment” to be used for execution. The “weburl” can be the URL of any existing site collection in the particular environment from which term stores are being exported. Specify “environment” as “on-premise” or “online” as applicable.
- Specify the credentials to be used for connecting to SharePoint sites. The “username“ can be in the form of an email id or in “domain\userid” format.
Also make sure:
- The username specified for export has read access to the term store.
- The username specified for import has read-write access to the target term store.
- Specify the site collection mappings. This mapping information is utilized when term groups from a particular site collection in the source environment is migrated to another particular site collection in the target environment.
- Execute at source: Run the export operation with the following command -
PS D:\Scripts> .\Execute-Scripts.ps1 -Operation export
While the export operation is running, you should see the PowerShell console output as the below screenshot.
Once the execution is completed, the output file “taxonomy.xml” will be created inside the “Taxonomy/Exports” directory. If a file with the same name already exists, it will be renamed with Date-Time and a GUID appended to. See the screenshot below.
- Execute at target:
If the source and target environments not in same network and the target environment is not accessible from the system the running the scripts, copy the entire script directory (including the exported ‘taxonomy.xml’ file) to the target environment. And then execute from the target environment itself.
Note: Before you start executing at target, make sure you have made necessary changes in the configuration file as mentioned earlier. Also make sure this time the “Exports” directory already exists with “taxonomy.xml” file inside it. The import script reads the “taxonomy.xml” which was generated by the export operation.
Run the import operation with the following command -
PS D:\Scripts> .\Execute-Scripts.ps1 -Operation import
While the import operation is running the console will display messages as below.
# Sequence of object creation:
The import operation will add the objects in a hierarchical manner. See the diagram below. The numbers in parentheses indicates the sequence of object creation.
All the execution time messages and errors are logged in the log files inside “Taxonomy/Logs” directory. Detailed error messages are not displayed in the PowerShell console. To see details of any warning or error the log files can be referred.
The logs files are created with the script name and time-stamp. The time-stamp is the date-time when the script execution was started.
Every log item contains information in the following format. Also see the screenshot below.
Timestamp: Date and time of log
Type: Type of log (Generic, Warning, Error, Export etc.)
Location: The function name where the log was generated from
Message: Message regarding the log
Detail: Detailed information about the log
This script has certain limitations as per the current implementation
- 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.
- 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.
- The “Group Managers” and “Contributors” properties of term groups are not imported.