Problem of using TermStores.getByName()

This post is a contribution from Aaron Miao, an engineer with the SharePoint Developer Support team

We recently still see customers open support cases because code for fetching term store stopped working, especially from SharePoint Online customers.

Fetching term store by name is bad idea. The term store name is not actually persisted anywhere. It’s a calculated value and it changes. From the code like below, you probably can see the name of the term store passed to getByName() looks like a random value.

 var termStore = termStores.getByName("Taxonomy_Dmxzz8tIBzk8wNVKQpJ+xA==");

The term store name could change due to various reasons, such as failover, tenant move, DB move, etc. events happened on SharePoint server side.

However, this is not your fault. There’re no published official documents on this. Even worse, SharePoint client-side APIs provide the getByName(). So, of course, customers start fetching their term store using that name in their custom code. Stop using getByName() method!

The correct way to fetch term store, like many good samples out there, is to use the following (CSOM) APIs are:

 TaxonomySession.GetDefaultSiteCollectionTermStore
TaxonomySession.GetDefaultKeywordsTermStore

Both methods above return TermStore object. The DefaultSiteCollectionTermStore is a term store that has metadata local to the site collection, while the DefaultKeywordsTermStore is a global term store that contains enterprise keywords, as shown in TaxonomySession class

Please be aware that both methods may return null value, as remarked in each API document, depends on your term store settings.

Here’re the JSOM APIs:

 getDefaultSiteCollectionTermStore
getDefaultKeywordsTermStore

This document discusses difference between global and local (site collection specific) term stores.