Deploy Managed Metadata fields using site designs and site scripts

(Notice: This post may show unsupported methods for provisioning fields)

You may be in a scenario where you want to create Managed Metadata columns using modern provisioning. This post is going to outline a method that can be used to provision Managed Metadata columns using site designs. Site designs are a new model for provisioning assets (fields,content types, lists, etc…) in modern SharePoint. Information on site designs and site scripts can be found here.

Multiple ways to create columns

Using a site script,  you can create both list and site columns using two different actions — “addSPField” and “addSiteColumn”. The first will deploy a list column and the second action will deploy a site column. However, these two actions only support basic field types in SharePoint. These field types include:

  • Text
  • Note
  • Number
  • Boolean
  • User
  • DateTime

Complex columns such as people fields and managed metadata fields need to be created using the Field Element definition. Using site designs and site scripts, we can provision complex fields using the Field definition with the addSPFieldXml and createSiteColumnXML actions.

There are many ways you can get the Field definition after they have been created in the SharePoint UI. Here are a couple options you could use to export out the schema XML for a list and get the field definitions.


You could also use PnP PowerShell to export out the schema

 $list = Get-PnPList -Identity "your list" -Includes SchemaXml
 $schema = $list.SchemaXml

Which complex fields are supported?

If look through the site script documentation you may notice, it doesn’t actually define which field types are supposed through XML. In regards to a complex field such as a Managed Metadata field, we took to twitter to see if Microsoft had any input. Sean Squires mentioned that currently they do not support Managed Metadata Fields, at least in an elegant way (which to me means, if it works great! if it doesn’t…it’s not officially supported).

How it can be achieved

Managed Metadata Fields are complex fields that actually require two fields to be deployed in order to function properly. One field is a TaxonomyFieldType and another is a Note field. This means we actually have to deploy two fields during the provisioning process.

When you export out a list schema and find your Managed Metadata field, you’ll notice it references the Note field using the ID of the Note field in the TextField node. You may also notice there are tokens for properties such as WebId, SiteId, ListId in your Field definition. In order for the deployment of the field to work we need to remove these token properties.

Secondly, we’ll need to update the <Property> nodes inside the <Customziation> node for the following properties.

  • SspId
  • TermSetId
  • AnchorId

By default, these properties may be using braces to identify the GUID for the Term store, Term set and Anchor. We need to remove the braces and leave the rest of the GUID string.

Here is an example of a cleaned up XML for a Managed Metadata field. Notice how I have removed the {braces} from around the GUIDs for SspdId, TermSetId and AnchorId (in bold).

<Field Type="TaxonomyFieldType" Name="MyTestMMD" SourceID="" StaticName="MyTestMMD" DisplayName="My Test Tax" Group="Test group" ShowField="Term1033" Required="FALSE" EnforceUniqueValues="FALSE" Mult="FALSE"> <Default /> <Customization> <ArrayOfProperty> <Property> <Name>SspId</Name> <Value xmlns:p4="" xmlns:q1="" p4:type="q1:string">1ba8a7c0-a373-4bb7-8ee0-2d130933743a</Value> </Property> <Property> <Name>GroupId</Name> <Value xmlns:p4="" xmlns:q2="" p4:type="q2:string">0e8f395e-ff58-4d45-9ff7-e331ab728beb</Value> </Property> <Property> <Name>TermSetId</Name> <Value xmlns:p4="" xmlns:q2="" p4:type="q2:string">487ba508-4fba-49f1-be4f-ceee2624da0a</Value> </Property> <Property> <Name>TextField</Name> <Value xmlns:p4="" xmlns:q6="" p4:type="q6:string">{44a5d269-ce40-4a8f-b0d6-6b7bcb95ff71}</Value> </Property> <Property> <Name>AnchorId</Name> <Value xmlns:p4="" xmlns:q3="" p4:type="q3:string">00000000-0000-0000-0000-000000000000</Value> </Property> <Property> <Name>IsPathRendered</Name> <Value xmlns:p4="" xmlns:q7="" p4:type="q7:boolean">false</Value> </Property> <Property> <Name>IsKeyword</Name> <Value xmlns:p4="" xmlns:q8="" p4:type="q8:boolean">false</Value> </Property> <Property> <Name>Open</Name> <Value xmlns:p4="" xmlns:q5="" p4:type="q5:boolean">false</Value> </Property> </ArrayOfProperty> </Customization> </Field>

A couple notes

If you fail to do this successfully, it may look like your column is working. However, SharePoint will not create managed or crawled properties correctly, thus making your column not searchable.

Final site script actions

The next thing we want to do is escape the XML so can we can use it inside a JSON site script. Then finally, we can add the Field definitions to our site script using the “createSiteColumnXml” action.

Here is an example of the two site script actions required to deploy a Managed Metadata field using site designs.

   "verb": "createSiteColumnXml",  
    "schemaXml": "<Field ID=\"{44a5d269-ce40-4a8f-b0d6-6b7bcb95ff71}\" SourceID=\"http:\/\/\/sharepoint\/v3\" Type=\"Note\" Name=\"MyTestMMDTaxHTField\" StaticName=\"MyTestMMDTaxHTField\" DisplayName=\"MyTestMMDTaxHTField\" Group=\"Test group\" ShowInViewForms=\"FALSE\" Required=\"FALSE\" Hidden=\"TRUE\" CanToggleHidden=\"TRUE\" />"  
  "verb": "createSiteColumnXml",  
  "schemaXml": "<Field Type=\"TaxonomyFieldType\" Name=\"MyTestMMD\" SourceID=\"http:\/\/\/sharepoint\/v3\" StaticName=\"MyTestMMD\" DisplayName=\"My Test Tax\" Group=\"Test group\" ShowField=\"Term1033\" Required=\"FALSE\" EnforceUniqueValues=\"FALSE\" Mult=\"FALSE\"> <Default></Default> <Customization> <ArrayOfProperty> <Property> <Name>SspId</Name> <Value xmlns:q1=\"\" p4:type=\"q1:string\" xmlns:p4=\"\">1ba8a7c0-a373-4bb7-8ee0-2d130933743a</Value> </Property> <Property> <Name>GroupId</Name> <Value xmlns:q2=\"\" p4:type=\"q2:string\" xmlns:p4=\"\">0e8f395e-ff58-4d45-9ff7-e331ab728beb</Value> </Property> <Property> <Name>TermSetId</Name> <Value xmlns:q2=\"\" p4:type=\"q2:string\" xmlns:p4=\"\">487ba508-4fba-49f1-be4f-ceee2624da0a</Value> </Property> <Property> <Name>TextField</Name> <Value xmlns:q6=\"\" p4:type=\"q6:string\" xmlns:p4=\"\">{44a5d269-ce40-4a8f-b0d6-6b7bcb95ff71}</Value> </Property> <Property> <Name>AnchorId</Name> <Value xmlns:q3=\"\" p4:type=\"q3:string\" xmlns:p4=\"\">00000000-0000-0000-0000-000000000000</Value> </Property> <Property> <Name>IsPathRendered</Name> <Value xmlns:q7=\"\" p4:type=\"q7:boolean\" xmlns:p4=\"\">false</Value> </Property> <Property> <Name>IsKeyword</Name> <Value xmlns:q8=\"\" p4:type=\"q8:boolean\" xmlns:p4=\"\">false</Value> </Property> <Property> <Name>Open</Name> <Value xmlns:q5=\"\" p4:type=\"q5:boolean\" xmlns:p4=\"\">false</Value> </Property> </ArrayOfProperty> </Customization> </Field>"  

You can see a full site script in this Gist.

Caveats & “uh ohs”

Using the site script actions above, you should be able to successfully create Managed Metadata fields using site designs. Just be aware that if you see some negative impacts when provisioning these…they are not fully supported by Microsoft.

7 thoughts on “Deploy Managed Metadata fields using site designs and site scripts

  1. Prakash Ramasamy January 21, 2019 / 3:45 am

    I have tried the same way to create the managed metadata fields, it is creating all the fields successfully. But some times only the first column is failed to create, getting an error message Action failed. Do you have any idea about this?


  2. Michel Smit (@michelsmit) February 15, 2019 / 8:02 am

    Hi Beau, followed the above, but the field doesn’t appear in search results. I doublechecked the SourceID and …TaxHTField suffix… Any thought why they won’t show up?


    • Beau Cameron February 15, 2019 / 2:23 pm

      Hi Michel, are you able to send me the XML you are using for this? I’d be happy to review it for you.

      A couple other things to check / do.

      1. You can now generate the JSON/XML from a list from a newly created endpoint. You can create the column in a SharePoint list and then run Get-SPOSiteScriptFromList and it will create the JSON/XML perfectly for you. 🙂
      2. If the XML is right and it’s still not working, making sure you are a part of a SharePoint Group. There is a bug in Modern that won’t generate managed properties in modern sites


      • Michel Smit (@michelsmit) February 18, 2019 / 7:49 am

        Hi Beau, just sent you the json using the contact form. I did the Get-SPOSiteScriptFromList and this resulted in a json file. When adding this file as site script and adding this script to a design, it creates the column though no managed/crawled properties are created. Also this cmdlet doesn’t export the note field.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s