Changes for the upcoming March release

Author: jansenbe

docs/toc.yml

@@ -1399,6 +1399,8 @@
           href: transform/modernize-userinterface-site-pages-usermapping.md
         - name: URL mapping
           href: transform/modernize-userinterface-site-pages-urlmapping.md
+        - name: Term mapping
+          href: transform/modernize-userinterface-site-pages-termmapping.md
         - name: Page layout mapping
           href: transform/modernize-userinterface-site-pages-layout.md
     - name: SharePoint Modernization scanner

docs/transform/modernize-userinterface-site-pages-configuration.md

@@ -1,7 +1,7 @@
 ---
 title: Options to control the page transformation process
 description: Explains how to configure the page transformation process
-ms.date: 01/03/2020
+ms.date: 03/06/2020
 ms.prod: sharepoint
 localization_priority: Normal
 ---
@@ -582,6 +582,50 @@ PublishingPageTransformationInformation pti = new PublishingPageTransformationIn
 };
 ```
 
+## TermMappingFile option (as of March 2020 release)
+
+Type | Default value if not specified
+-----|----
+String | empty
+
+You can optionally specify a file with custom term mappings. See the [Term mapping](modernize-userinterface-site-pages-termmapping.md) article to learn more.
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    TermMappingFile = @"c:\temp\termmappingfile.csv",
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    TermMappingFile = @"c:\temp\termmappingfile.csv",
+};
+```
+
+## SkipTermStoreMapping option (as of March 2020 release)
+
+Type | Default value if not specified
+-----|----
+Bool | false
+
+The standard behavior is to perform default term mapping. In case you don't want any term mapping to happen then set this property. See the [Term mapping](modernize-userinterface-site-pages-termmapping.md) article to learn more.
+
+```Csharp
+PageTransformationInformation pti = new PageTransformationInformation(page)
+{
+    SkipTermStoreMapping = true,
+};
+```
+
+```Csharp
+PublishingPageTransformationInformation pti = new PublishingPageTransformationInformation(page)
+{
+    SkipTermStoreMapping = true,
+};
+```
+
 ## HandleWikiImagesAndVideos option
 
 Type | Default value if not specified

docs/transform/modernize-userinterface-site-pages-powershell.md

@@ -1,7 +1,7 @@
 ---
 title: Transform classic pages to modern pages using PowerShell
 description: Explains how to transform classic wiki and web part pages into modern pages using the SharePoint PowerShell
-ms.date: 01/16/2020
+ms.date: 03/06/2020
 ms.prod: sharepoint
 localization_priority: Priority
 ---
@@ -64,6 +64,8 @@ LDAPConnectionString (as of November 2019 release, version 3.15.1911.*) |  | All
 SkipUserMapping (as of November 2019 release, version 3.15.1911.*) | $false  | All page types | Skips the user mapping. For SPO transformations user mapping is off unless you specify a mapping file, for on-premises SharePoint user mapping is always on unless you set this flag. See the [User mapping](modernize-userinterface-site-pages-usermapping.md) article to learn more.
 DelveBlogPage (as of December 2019 release, version 3.16.1912.*) | $false | Delve blog pages | Set the `-DelveBlogPage` parameter if you're transforming a Delve blog page. For wiki,web part, classic blog and publishing pages this parameter must be omitted or set to false.
 DelveKeepSubtitle (as of December 2019 release, version 3.16.1912.*) | $false | Delve blog pages | When the `-DelveKeepSubtitle` parameter is set then the sub title of a Delve blog page will be used for the modern page topic header. This value will be truncated at 40 characters.
+TermMappingFile (as of March 2020 release, version 3.19.2003.*) |  | Cross site transformation | File with custom term mapping definitions allow you to do more than just the default term mapping. See the [Term mapping](modernize-userinterface-site-pages-termmapping.md) article to learn more.
+SkipTermStoreMapping (as of March 2020 release, version 3.19.2003.*) | $false | Cross site transformation | During page transformation terms are mapped to be valid in the target site collection, but using the `-SkipTermStoreMapping` parameter you can disable the term mapping. See the [Term mapping](modernize-userinterface-site-pages-termmapping.md) article to learn more.
 
 (`*`) Mandatory command line parameter / (`**`) Mandatory when the `-PublishingPage`, `-BlogPage` or `-DelveBlogPage` parameter was set (either `-TargetWebUrl` or `-TargetConnection`)
 

docs/transform/modernize-userinterface-site-pages-termmapping.md

@@ -0,0 +1,47 @@
+---
+title: Term mapping during cross site page transformation
+description: Explains how to the default term mapping works when transforming pages + also explains how to use a custom term mapping file
+ms.date: 03/06/2020
+ms.prod: sharepoint
+localization_priority: Priority
+---
+
+# Term mapping during page transformation
+
+Term mapping is the mechanism that translates managed metadata terms in the source environment to an applicable term in the target environment. The cases in where term mapping applies are:
+
+- You're transforming from on-premises SharePoint to SharePoint Online
+- You're doing a cross site transformation (e.g. from classic publishing portal to a modern intranet) in SharePoint Online
+
+Term mapping will not be used when:
+
+- The source and target are pointing to the same termset id
+- When you're doing an in-place transformation (source and target page live in the same site)
+
+## How does term mapping work
+
+Term mapping will automatically try to find the equivalent term in SharePoint Online for the term used in the source page and it can do this in two manners:
+
+- Automatic mapping: term mapping will try to find an equivalent term by checking if the same term group, termset and term path can be found in the target term store
+- Custom mapping based upon a file: using a mapping file you can specify a target term for a given source term
+
+## Turning off the automatic mapping
+
+If you don't want term mapping to happen you can disable it via the `-SkipTermStoreMapping` flag in PnP PowerShell or via the `SkipTermStoreMapping` attribute of the .Net page transformation configuration objects (`PageTransformationInformation` and `PublishingPageTransformationInformation`).
+
+## Custom term mapping
+
+If you don't like or cannot use the automatic term mapping then there's the option to specify a term mapping file. A term mapping file is a simple CSV file listing source term and target term as shown in below snippet
+
+```Text
+SourceTermGroup|SourceTermSet|SourceTerm,TargetTermGroup|TargetTermSet|TargetTerm
+SourceTermGroup|SourceTermSet|SourceTerm|SourceChildTerm1|SourceChildTerm2,TargetTermGroup|TargetTermSet|TargetTerm|TargetChildTerm1|TargetChildTerm2
+f0b1b6aa-b00b-4198-b8dd-ef4393e3ad05,fec05391-6a39-4ad5-a2a1-a01020d94efd
+```
+
+Some things to note:
+
+- You can either choose a mapping based upon a path (a | delimited string of term labels) or choose to define the mapping based upon source and target term id's
+- If you're transforming from SharePoint 2010 then you'll need to specify **DEFAULT** as source term group name
+
+Creating the mapping file is the first step, to actually use it you need to specify the file via the `TermMappingFile` parameter to the `ConvertTo-PnPClientSidePage` cmdlet if you're using PnP PowerShell. If you're using .Net then you can specify the file via the  `TermMappingFile` attribute of the .Net page transformation configuration objects (`PageTransformationInformation` and `PublishingPageTransformationInformation`).