SharePoint: Managed Metadata: The term is not a valid term
The main point of this post is to create awareness around the fact that you can use the CreateTerm PowerShell method on a TermSet object to create a new managed metadata term with a specified Term ID.
You'll have to read to the end to understand why that's a big deal, and to see it in action.
Problem:
When viewing the properties of documents with Managed Metadata columns, some terms are shown in red and underlined. Hovering over the invalid term shows this error message:
"The term is not a valid term"
Trying to save the document properties results in this error message:
"Creating a new value is not allowed in this field, please select from the existing terms."
Cause:
The document has been tagged with terms that no longer exist within the Term Set that is currently used by the problematic document library Managed Metadata column.
This can happen in one of three ways:
1. Documents are tagged with certain terms, and then those terms are moved to a different Term Set by using the "Move Term" option within the Term Store Management Tool.
2. Documents are tagged with certain terms, and then the Managed Metadata column within the document library is assigned to a different Term Set by editing the Managed Metadata field within the document library settings.
For example, in this case, my "Term1" term exists in the "Document Terms" term set, but my document library column has been changed to use the "Other Terms" term set.
3. Documents are tagged with certain terms, and then those terms are deleted from the Managed Metadata Service Application (MMS), effectively "orphaning" the term.
In any of the above cases, the end result is the same: The Managed Metadata column within the document library is pointed to a Term Set that no longer contains the term that was used to tag the document. Therefore, the term cannot be resolved.
Resolution:
For the first two issues above, the term still exists within the MMS, so we can use the "Reuse Terms" option to create a term that is "linked" between both Term Sets.
That way, the same term (ex: "Term1") can be resolved from both the Term Set it was moved from, and the Term Set it was moved to.
The third issue (term has been deleted) is a little more complex. You could create a new term with the same label, eg: "Term1", but it would have a different term ID (GUID). Since the terms within the document library are linked by the term ID, it would not be seen as the same term and would remain unresolved ("the term is not a valid term").
You could edit each library item and resolve it to the new term that has the same name, but that is tedious, and does not work when versioning is enabled within the document library. In the case of versioning, only the current version would be updated and previous versions would still be using the "orphaned" term.
Here's the main driver behind this blog post:
There's a little-known way to use PowerShell to create a term with a specified Term ID.
That's right, you get to pick the GUID it uses. The idea here is that you re-create the term, not only with the same name, but also with the previous Term ID.
All we need to do is grab the previous Term ID, along with a few other pieces of information.
Note: In the procedure I show below, I focus on a single document "stuff.xlsx", but the steps will actually fix every document within every library that was using the "orphaned" term ("Term1").
Here's an example where I have the problem with my "stuff.xlsx" file within my "Documents" library, and the Managed Metadata column containing the orphaned term is called "Topic".
It's orphaned because it's been deleted from my "Document Terms" term set.
I can run this PowerShell to get the term ID GUID that my problem document (and all previous versions) had been using:
Add-PSSnapin Microsoft.SharePoint.PowerShell -ea SilentlyContinue
#Specify site, list, MMS column, and document name
$web = get-spweb https://j16 #Site URL
$list = $web.lists["Documents"] #Document Library Name
$column = "Topic" #MMS Column Name
$it = $list.Items | ?{$_.name -match "stuff.xlsx"} #Item Name
foreach($Ver in $it.Versions)
{Write-host "Version#: " $ver.versionlabel
Write-host "Term Label:" $ver[$column].label
Write-host "Term ID:" $ver[$column].termguid}
The above PowerShell shows the term ID GUID for orphaned term: "Term1" is "072b1eb2-ce24-4d91-8fcd-9bfc9b63f040"
Then, I can use this PowerShell to create a new term within the Managed Metadata Service Application with label (name) "Term1" and GUID (Term ID) "072b1eb2-ce24-4d91-8fcd-9bfc9b63f040" to match the name and Term ID that my document is expecting:
# Set your desired Term label and ID
$TermLabel = "Term1"
$TermGUID = "072b1eb2-ce24-4d91-8fcd-9bfc9b63f040"
# Set your Term Store, Term Group, Term Set, and language
$mms = "MMS" #Managed Metatadata Service App name
$tg = "Terms" #Term Group name
$tsName = "Document Terms" #Term Set name
$language = 1033 #This is a US English term
# Get the Site for context
$siteUrl = "https://j16"
#Change nothing below this line
Add-PSSnapin Microsoft.SharePoint.PowerShell -ea SilentlyContinue
$site = Get-SPSite $siteUrl
# Start a taxonomy session
$ts = Get-SPTaxonomySession -Site $site
#Get the Term Store
$termStore = $ts.TermStores[$mms]
#Get the Term Group
$termGroup = $termStore.Groups[$tg]
#Get the Term Set
$termset = $termGroup.TermSets[$tsName]
#Create a term with specific GUID within the term set
$termset.CreateTerm($TermLabel, $language, $TermGUID)
#Make it so
$termStore.CommitAll()
Now "Term1" is back in my MMS:
And more importantly, it has the same term ID GUID that it previously had (072b1eb2-ce24-4d91-8fcd-9bfc9b63f040), so my document (and every version of it that was using that term) is fixed.
"Term1" once again resolves within my document properties.
