Configure hybrid SharePoint taxonomy and hybrid content types

APPLIES TO: yes-img-132013 yes-img-162016 yes-img-192019 yes-img-seSubscription Edition yes-img-sopSharePoint in Microsoft 365

In this article, we look at how to configure hybrid SharePoint taxonomy and hybrid content types.

Hybrid SharePoint taxonomy allows you to have a shared taxonomy between SharePoint Server and SharePoint in Microsoft 365. Hybrid content types allow you to have a shared set of content types between SharePoint Server and SharePoint in Microsoft 365.

Before you follow the procedures in this article, be sure to read Plan hybrid SharePoint taxonomy and hybrid content types.

This feature is available in SharePoint Server 2013 and SharePoint Server 2016 with the following SharePoint updates:

  • Hybrid taxonomy requires the November 2016 public update or later.

  • Hybrid content types require the June 2017 public update or later.

The functionality and configuration procedures are the same for both versions of SharePoint Server.

Video demonstration

This video shows a walkthrough of configuring hybrid taxonomy and hybrid content types.

Video: Configure hybrid taxonomy and content types

Migrate your taxonomy from SharePoint Server

If you have an existing taxonomy in SharePoint Server, the best practice is to copy any term groups you want to be part of the shared taxonomy to SharePoint in Microsoft 365 before you configure hybrid SharePoint taxonomy. You can migrate more taxonomy groups from SharePoint Server to SharePoint in Microsoft 365 to add to the shared taxonomy later, but if you do, you may need to run the Hybrid Configuration Wizard again to include them in the shared taxonomy.

The migration process copies taxonomy groups from SharePoint Server to SharePoint in Microsoft 365 by using the Copy-SPTaxonomyGroups PowerShell cmdlet.

Active Directory groups

While the copy process preserves most user information associated with term sets - such as owner and stakeholders - note, that the copy process doesn't work with Active Directory groups. If you use Active Directory groups in your term sets, there are two options for copying your taxonomy groups:

  • You can replace the Active Directory groups with individual users within your taxonomy groups. The individual users are copied when you copy your taxonomy groups.

  • You can copy your taxonomy groups with the Active Directory groups in place. You'll see a PowerShell warning and the Active Directory group assignments are lost if you proceed. You can then assign a Microsoft 365 group in place of the Active Directory group after you've copied the taxonomy groups.

Copying taxonomy groups

Copying taxonomy groups is done using the Copy-SPTaxonomyGroups PowerShell cmdlet. You need the following information to run the cmdlet:

  • The name of your managed metadata service application in SharePoint Server.

  • The URL of the SharePoint Server site where your taxonomy store is located.

  • The URL of the SharePoint in Microsoft 365 site where your term store is located (http://<TenantName>.sharepoint.com).

  • Taxonomy groups in SharePoint Server to be copied to SharePoint in Microsoft 365.

  • Your Microsoft 365 global admin credentials.

Note

If you receive an HTTP 400 error when attempting to use the Copy-SPTaxonomyGroups cmdlet with correct credentials, switch to a cloud-based global admin instead of an Active Directory synchronized account.

  • A list of the taxonomy groups that you want to copy.

Run the cmdlet as a farm admin from one of the servers in your SharePoint in Microsoft 365 farm.

Use the following syntax to copy your taxonomy groups:

$credential = Get-Credential
Copy-SPTaxonomyGroups -LocalTermStoreName "<ManagedMetadataServiceApplication>" -LocalSiteUrl "<OnPremisesSiteURL>" -RemoteSiteUrl "SharePointOnlineSiteURL" -GroupNames "Group1","Group2" -Credential $credential

For example:

$credential = Get-Credential
Copy-SPTaxonomyGroups -LocalTermStoreName "Managed Metadata Service" -LocalSiteUrl "https://sharepoint" -RemoteSiteUrl "https://contoso.sharepoint.com" -GroupNames "Engineering","Marketing" -Credential $credential

You can also run Copy-SPTaxonomyGroups and you'll be prompted for the needed parameters.

Copying content types

If you're planning to use hybrid content types, you can copy your SharePoint Server content types to SharePoint in Microsoft 365 by using the Copy-SPContentTypes cmdlet. For example:

Copy-SPContentTypes -LocalSiteUrl http://localsite/ -LocalTermStoreName "managed metadata service application proxy" -RemoteSiteUrl https://contoso.sharepoint.com/ -ContentTypeNames @("ContentTypeA", "ContentTypeB") -Credential $credential

The content types are copied into https://contoso.sharepoint.com/sites/contentTypeHub. If this site doesn't exist, it's created for you, and the Site Collection Feature Content Type Syndication Hub is enabled. The site URL is hard coded and can't be changed.

Configure hybrid SharePoint taxonomy

Configuration of hybrid SharePoint taxonomy is done using the Hybrid Configuration Wizard in the SharePoint admin center. The Hybrid Configuration Wizard has many prerequisites. Be sure to read Hybrid Configuration Wizard in the SharePoint admin center before you follow the procedures in this section.

We also recommend that you back up your term store before you proceed.

Make the timer service account a term store admin

For taxonomy replication to work properly, the account that runs the SharePoint Timer Service must be a term store admin in SharePoint Server. (To find this account, check the Log On As account for the SharePoint Timer Service on your server.) Use the following procedure to add this account as a term store administrator.

To add a term store admin

  1. In the Central Administration website, under Application Management, select Manage service applications.

  2. Select the link for the Managed Metadata service application.

  3. Add the timer service account to the Term Store Administrators box, and then select Save.

Configure hybrid SharePoint taxonomy using the Hybrid Configuration Wizard

The next step is to configure hybrid SharePoint taxonomy by running the Hybrid Configuration Wizard in the SharePoint admin center.

To configure hybrid SharePoint taxonomy

  1. Sign in a server in your SharePoint Server farm as the farm administrator.

  2. From your SharePoint Server computer, open a web browser.

  3. Go to More features in the SharePoint admin center, and sign in with an account that has admin permissions in Microsoft 365.

  4. Under Hybrid picker, select Open.

  5. Follow the wizard, and when prompted, select Hybrid Taxonomy.

  6. Provide the following information when prompted:

  • The URL of your SharePoint Server root site (for example, https://sharepoint).

  • The name of your SharePoint Server managed metadata service application (for example, Managed Metadata Service).

  • The names of the taxonomy groups that you want to replicate (for example, Engineering;Marketing).

    If you don't specify groups, then all groups except system and special groups are configured for replication.

After you've configured hybrid SharePoint taxonomy, the taxonomy replication timer job will poll SharePoint in Microsoft 365 on a daily basis for changes to the taxonomy.

Running the taxonomy replication timer job

Hybrid SharePoint taxonomy uses a timer job called Taxonomy Groups Replication to copy taxonomy information from SharePoint in Microsoft 365 to SharePoint Server. The SharePoint in Microsoft 365 APP Identity is used to authenticate to Microsoft 365. By default, this timer job replicates taxonomy on a daily basis.

Like other timer jobs in SharePoint in Microsoft 365, you can configure the Taxonomy Groups Replication job to run on a different schedule, or you can run it manually, by searching for it in the timer job list in Central Administration.

Stopping replication of taxonomy groups

If at any time you want to stop taxonomy replication between SharePoint in Microsoft 365 and SharePoint Server, you can do so by using PowerShell.

The Stop-SPTaxonomyReplication cmdlet stops taxonomy replication. For example:

$credential = Get-Credential
Stop-SPTaxonomyReplication -Credential $credential

The Stop-SPContentTypeReplication cmdlet stops content type replication:

Stop-SPContentTypeReplication

If you wish to reenable taxonomy replication again, you must run the Hybrid Configuration Wizard again.

If you simply want to reconfigure which taxonomy groups you're replicating, there's no need to stop replication. You can just run the Hybrid Configuration Wizard again and specify the new taxonomy groups that you want to replicate.

See also

Other Resources

TechNet Forums - Hybrid Taxonomy