Exploring Taxonomy Mapping in PnP Page Transformation

In the March 2020 release of PnP Modernization tooling, in this version, a new feature now allows you to map your taxonomy terms from a source site such as SharePoint 2013 to Modern site in SharePoint Online.

Where does this fit in modernization projects?

For those classic portals, that have metadata terms used in the page content - with the requirement, to preserve this in your modernization projects, this new feature can now preserve these values.

The transformation tool cannot simply copy and paste of the field values to get this to work, as the source and target term stores are different instances and term paths/GUIDs need to be identical in both locations.

You could consider cloning your terms and ensuring both the paths and GUIDs are identical, quite often modernization projects include an element of re-organizing content to fit a flatter architecture. Thus it may no longer be relevant to keep the terms in the same groupings.

Getting to know the feature

The PnP Page transformation is part of PnP PowerShell, although you can use this in ASP.NET projects, it’s simpler (for me) to get going with PowerShell. With this new cmdlet parameters have been introduced:

TermMappingFile - this specifies a CSV file, with the source and target terms.
SkipTermStoreMapping - there is a default mechanism to resolve terms based on their term paths if these have been replicated in source/target term stores. This option disables this automatic resolution.

Below is an example script fragment of running with this command options:

ConvertTo-PnPClientSidePage -Identity "Our-New-IT-Suite-Is-Mint.aspx" `
    -PublishingPage `
    -TargetConnection $spOnlineConn -Connection $sp13Conn `
    -Overwrite `
    -PageLayoutMapping C:\temp\Demo\onprem-news-mapping.xml `
    -TermMappingFile C:\temp\Demo\termmapping.csv `
    -LogType Console

The mapping file

The mapping file, follows the same format, as the other mapping files, with a SOURCE,TARGET format, so the source or target can be either a GUID of the term or the term path in this format:

Term Path

if you are using SharePoint 2010 to Modern (Yes, this is supported!), the source term needs DEFAULT instead of the TermGroup. E.g.

The keyword is necessary is to reduce the number of web service calls to the taxonomy service, as the Page Transformation tool, falls back to web service calls on older versions of SharePoint where there are gaps in the CSOM API.

You can get the GUID for the term - located at the bottom of the “General” tab.

Finding the Term GUID

Note: In SharePoint 2010 this term is NOT shown in this screen which makes this harder, you can either grab the information from the API or the HTML DOM on the page.

Example of grabbing the GUID in SharePoint 2010

Example Transformation

Once you have the mapping file ready, let’s show an example of this, to set the stage we have:

SharePoint 2013 Classic Publishing Portal. With a news page that contains metadata for the page content category, which for the example “Our new IT Suite is mint” page has terms set to “Announcements” and “Press Release”. The multi-valued managed metadata field has an internal field name of “IntranetContentCategory”
SharePoint Online Modern Portal with a Content Category Multi-valued Managed Metadata field. This has an internal field name of “IntranetContentCategoryMulti”.

Example Source Page with the terms set

Before you can transform, you need to reference the metadata field within the page layout mapping file, for example Line 10 on the fragment below.

<MetaData>
  <Field Name="Title" TargetFieldName="" Functions="" />
  <Field Name="IntranetKeywords" TargetFieldName="" Functions="" />
  <Field Name="PublishingIsFurlPage" TargetFieldName="" Functions="" />
  <Field Name="IntranetContentAuthor" TargetFieldName="" Functions="" />
  <Field Name="IntranetContentPublishingDate" TargetFieldName="" 
      Functions="" />

  <!-- Managed Metadata field -->
  <Field Name="IntranetContentCategory" 
    TargetFieldName="IntranetContentCategoryMulti" Functions="" />

  <Field Name="IntranetContentLanguage" TargetFieldName="" 
    Functions="" />
  <Field Name="IntranetContentAssociationKey" TargetFieldName="" 
    Functions="" />
  <Field Name="IntranetContentType" TargetFieldName="" Functions="" />
  <Field Name="IntranetIsNewsOnTop" TargetFieldName="" Functions="" />
  <Field Name="IntranetContact" TargetFieldName="" Functions="" />
  <Field Name="IntranetAllowPageComments" TargetFieldName="" 
    Functions="" />

  <!-- Publishing Page as Thumbnail-->
  <Field Name="PublishingPageImage" TargetFieldName="BannerImageUrl" 
    Functions="ToPreviewImageUrl({PublishingPageImage})" />
</MetaData>

The mapping entry is required to instruct the tool to include the field when transforming the page. If you need to generate the mapping file, run the following command against the source page:

$sp13Conn = Connect-PnPOnline http://portal2013/en -ReturnConnection

Export-PnPClientSidePageMapping `
    -CustomPageLayoutMapping `
    -PublishingPage "Our-New-IT-Suite-Is-Mint.aspx" `
    -Folder "C:\temp\Blog" `
    -Connection $sp13Conn

Finally, transform the page with the following fragment, and these terms are now included.

ConvertTo-PnPClientSidePage -Identity "Our-New-IT-Suite-Is-Mint.aspx" `
    -PublishingPage `
    -TargetConnection $spOnlineConn -Connection $sp13Conn `
    -Overwrite `
    -PageLayoutMapping C:\temp\Demo\onprem-news-mapping.xml `
    -TermMappingFile C:\temp\Demo\termmapping.csv `
    -LogType Console

The final result

Viola! You can now include terms along with your pages. :-)

If you have any feedback or have discovered an issue, please post to the issues list on GitHub: https://github.com/pnp/pnpframework/issues

Update: The modernization tooling is now integrated into PnP Framework, thus please report bugs there as above. For further information about the updates to Modernization tooling, please go to the Blog - Modernization lives on in PnP Framework

Further resources

Some resources to help you on your modernization journey:

Term Mapping during transformation - https://docs.microsoft.com/en-us/sharepoint/dev/transform/modernize-userinterface-site-pages-termmapping
Configuring the page layout mapping file -https://docs.microsoft.com/en-us/sharepoint/dev/transform/modernize-userinterface-site-pages-model-publishing

Enjoy!