Template Metadata Configuration

Overview

Metadata Requirements within Block Editor Templates are used to enforce a set of rules for all pages that are created from a given template. This document will go over how to set up Metadata Requirements for a specific template, what options are available, and what it means for Content creators who want to create (or edit) a page using a Template with Metadata Requirements set.

Metadata Requirements are set up from the Block Editor Administration page.

You can navigate there via:

Application Settings > Control Panel > Block Editor > Templates

Note that while the Metadata Requirements can be added to existing or new templates, the Metadata Requirements will only be applied to newly created pages, after the template has been saved with the Metadata Requirements.

You can find the Metadata Requirements configuration under the Edit Configuration button of the desired template. It will appear at the bottom of the side panel under Metadata Requirements.

The Metadata Requirements to a template are applied via JSON configuration. The JSON structure depends on the desired restrictions to be applied to the fields (Page Settings of the Block Editor page).

In the next paragraphs, you will find information about supported types of configuration and fields where it can be applied.

Types of Configuration

There are two parameters that can be specified for each field in the Metadata Requirements:

EditMode that determines what restrictions (if any) apply to a field. There are four options available: Editable, Required, ReadOnly, and Append. (If not specified, the fields are Editable by default.)

Value that sets the initial value for a given field.

Note that the JSON properties and values are case-sensitive.

Editable

This option is supported for all fields.

By default, all fields are set to Editable and can be freely changed by the authors. This setting can be used in conjunction with Value if it is necessary to set initial placeholder values inside the Page Settings, that any author who uses the template can change.

Required

Note This is not supported on checkboxes and toggles, as they cannot be blank.

The Required state forces values to be supplied for the designated fields - they cannot be blank. This can be used together with a default value that is auto-populated which the author can change if they wish. As long as there is a value set, the required state will be satisfied and a page can be created.

ReadOnly

This is supported in all fields.

The ReadOnly state stops users from being able to make changes to these fields when creating or modifying a page. This also supports adding a specific default value that cannot be changed by the author (i.e. enforces all pages created from "HR Template" include a "High Confidentiality" Confidentiality Rating that cannot be changed or removed.)

Append

This is only supported on multi-select fields.

The Append state allows us to set a set of fixed pre-defined values that we want in a given Page Setting field for pages using this template with the option for the author to expand the list by add and remove their own additional options as well. The pre-defined values cannot be removed. As an example, this could be used to pre-assign the page with a list of topics that are always relevant to pages using this template, whilst allowing users to expand the list with own additions.

ℹ️

Note that this will need to be used in conjunction with the "Value" parameter. If "Value" is not used, the field will behave as if it was set to Editable (user can add and remove, and there are no pre-defined fixed values.)

Supported Fields

Below are example snippets that can be used to set up Metadata Requirements JSON configuration on your template. You can pick and choose which fields you want to apply restrictions to and combine them in a single snippet (example at the bottom.)

Note that the below table contains all fields currently supported via Metadata Requirements. Any field not included in this list is not supported at present.

Please let us know if there are additional fields you would like to see on here by contacting your Customer Success Manager.

Multiple snippets can be used together to create a tailored set of restrictions for your template. They have to be wrapped together in curly brackets { } with a comma separating of each snippet. The example below shows a snippet with both "Allow Comments" and "Is Key Page" set to ReadOnly (make note of the opening and closing brackets along with the separating comma):

{ "AllowComments": { "EditMode": "ReadOnly", "Value": true }, "IsKeyPage": { "EditMode": "ReadOnly", "Value": true } }

The above snippet will lock these fields and the author will not be allowed to set these two fields when creating their page based on this template. They will also have their default value set to true and therefore appear in the Page Settings as toggled on.

⚠️

Note that each field requirement can appear in the JSON configuration only once. There should never be more than one of each "AllowComments", "IsKeyPage", etc.

Example Metadata Requirements

Some commonly used / helpful sample JSON snippets to quickly start your metadata requirements.

All fields set to Editable

Naturally, where the values are numbers or lists of numbers, would need to be adjusted to the values in your intranet.

{  
  "Tags": {  
    "EditMode": "Editable",  
    "Value": [4203, 4206, 4207]  
  },  
  "ClassificationId": {  
    "EditMode": "Editable",  
    "Value": 2069  
  },  
  "ConfidentialityId": {  
    "EditMode": "Editable",  
    "Value": 2068  
  },  
  "BestBets": {  
    "EditMode": "Editable",  
    "Value": ["Leave of absence", "Parental leave", "Vacation"]  
  },  
  "IsPublic": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "DisplayAuthor": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "DisplayFacebookShare": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "DisplayLinkedInShare": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "DisplayTwitterShare": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "AllowComments": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "IsKeyPage": {  
    "EditMode": "Editable",  
    "Value": true  
  },  
  "Keywords": {  
    "EditMode": "Editable",  
    "Value": ["HR policy"]  
  },  
  "IsDiscoverable": {  
    "EditMode": "Editable",  
    "Value": true  
  }  
}

All fields set to ReadOnly

Naturally, where the values are numbers or lists of numbers, would need to be adjusted to the values in your intranet.

{
  "Tags": {
    "EditMode": "ReadOnly",
    "Value": [4203, 4206, 4207]
  },
  "ClassificationId": {
    "EditMode": "ReadOnly",
    "Value": 2069
  },
  "ConfidentialityId": {
    "EditMode": "ReadOnly",
    "Value": 2068
  },
  "BestBets": {
    "EditMode": "ReadOnly",
    "Value":["Leave of absence", "Parental leave", "Vacation"]
  },
  "IsPublic": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "DisplayAuthor": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "DisplayFacebookShare": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "DisplayLinkedInShare": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "DisplayTwitterShare": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "AllowComments": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "IsKeyPage": {
    "EditMode": "ReadOnly",
    "Value": true
  },
  "Keywords": {
    "EditMode": "ReadOnly",
    "Value": ["HR policy"]
  },
  "IsDiscoverable": {
    "EditMode": "ReadOnly",
    "Value": true
  }
}

All fields set to Required (where applicable)

Naturally, where the values are numbers or lists of numbers, would need to be adjusted to the values in your intranet.

{
  "Tags": {
    "EditMode": "Required",
    "Value": [4203, 4206, 4207]
  },
  "ClassificationId": {
    "EditMode": "Required",
    "Value": 2069
  },
  "ConfidentialityId": {
    "EditMode": "Required"
  },
  "BestBets": {
    "EditMode": "Required",
    "Value": ["Leave of absence", "Parental leave", "Vacation"]
  },
  "Keywords": {
    "EditMode": "Required",
    "Value": ["HR policy"]
  }
}

All fields set to Appendable (where applicable)

Naturally, where the values are numbers or lists of numbers, would need to be adjusted to the values in your intranet.

{
  "Tags": {
    "EditMode": "Append",
    "Value": [4203, 4206, 4207]
  },
  "BestBets": {
    "EditMode": "Append",
    "Value": ["Leave of absence", "Parental leave", "Vacation"]
  },
  "Keywords": {
    "EditMode": "Append",
    "Value": ["HR policy"]
  }
}

FAQs

What happens to existing pages if a change is applied to a Template's Metadata Requirements?

All pages will have their template's metadata requirements enforced even after the page has been created.

Template metadata applies both on page creation as well as on page edit. For example, if you make a change to the template and add a new required field then this will now be required on all existing pages the next time they are edited, as the pages remember which template they are associated with.

I changed my template and now I can't save some of my pages!

If you make a change to the template and make a change to make a field non-editable (eg. a field has now been made ReadOnly with a specific pre-defined value), you will need to revert the template to the previous configuration. After this, you'll have to update the page(s) to comply with the new pre-defined value you are looking to enforce, save the page, and add the metadata requirement back into the template.

This should then allow you to make changes to existing pages going forward.

This is an expected behaviour to avoid unexpected/silent overrides to metadata due to template changes for existing content, and making sure the changes are reviewed by the author first.

What if one of the IDs I've used is wrong?

If you've used an incorrect ID in the Metadata Requirements you'll still be able to save the Template. However, when creating a page based on this template, the ID will be skipped, and it won't show anything and will allow page creation (even if it is non-editable.)

What if one of the IDs I've used gets deleted?

If one of the IDs gets deleted after creation, similar to the previous question, the ID will be skipped, and simply won't be shown and will still allow pages to be created. If this is a single select, nothing will be selected and if this is a multi-select, only the valid options will be pre-selected.

Best Bets is required but I can't find it

Best Bets is usually located at the bottom of the Page Settings tab. If you can't find the Best Bets, it's usually because it is hidden by the Discoverable toggle. Toggling Discoverability "on" will start showing the Best Bets box.

If you're unable to change the Discoverable toggle it may have an EditMode of ReadOnly in the template. In this case you will need to make a change to the template to either change Best Bets EditMode from Required or change the EditMode on Discoverable from ReadOnly.

Note that the Discoverable setting due to its nature of controling search visibility of content is tightly coupled with Best Bets, and setting the value to false will hide hide Best Bets from the page settings (if page is not visible in search, search rank influencing features don't apply and are therefore hidden.)

My JSON looks correct but it isn't working

Make sure to double-check the casing of each field (EditMode, Value) and the values of EditMode. They are case-sensitive and will not work if incorrect casing is used.

You can also use a free online JSON validator to check if your JSON configuration has any structural issues (eg. using wrong type of quotes, missing commas, etc.)

I've added Metadata requirements but some are not showing correctly

This is usually because there is a duplicate in the Metadata Requirements JSON. Each field setting in the JSON can appear only once, so including a field twice will result in an unexpected behavior.

If the field is specified in the Metadata Requirements twice or more, the first rule on the top of the JSON snippet will apply.