Gravity Union

View Original

How to Create Custom Column Filters for PnP Search

Anthony Salopek

Custom columns are powerful tools for tailoring your SharePoint environment to meet specific needs.

In this comprehensive guide, we will share details and instruction on how to create custom filters for the PnP Filters Web Part by leveraging custom SharePoint columns, including:

  • key concepts

  • overview of the 3 steps

  • pre-setup requirements

  • how to find and map crawled properties (+ why it’s necessary!)

  • and how to add the custom column as a filter.

This is the third installment of a 3-part series on PnP Search. Be sure to check out Part 1: How to Add PnP Search to Your Tenant and Part 2: How to Configure PnP Search on a SharePoint Site.

Key Concepts

  • Crawled Property: Metadata or content extracted from an item, such as a document or URL, during a search crawl. Examples include properties like author, title, or subject. Crawled properties are created automatically once a metadata column is used. These properties must be mapped to managed properties to be included in the search index.

  • Managed Properties: Attributes that determine how the contents are shown in search results. Some crawled properties automatically have a refinable managed property created, such as the out-of-the-box create date column, but custom SharePoint columns do not.

  • Refinable Properties: Built-in managed properties that allow you to refine and filter search results. New custom managed properties cannot be designated as refinable, so we map existing crawled properties to the built-in refinable blank properties. Examples include RefinableStrings, RefinableDates, and more.

    For more details, see article on SharePoint Search Schema.

Steps Overview

Three steps are required to utilize custom SharePoint columns for filtering PnP Search results:

  1. Map the Crawled Property: map the crawled property of your custom SharePoint column to an empty refinable managed property.

  2. Add to Search Box: add the mapped refinable managed property to the selected properties of the PnP - Search Results Box.

  3. Add to Filters Web Part: add the mapped refinable managed property to the PnP – Filters Web Part.

Each of these steps will be outlined in this blog post so you can leverage the power of filtering search results based on metadata applicable to your organization or department!

Pre Setup

  • Create a custom SharePoint column of type string/choice/managed metadata, etc.

  • Add the column to a document library on your SharePoint Online site.

  • Add files and populate the metadata field with values.

  • Create a PnP search page with filters, search box, and search results. If you need help creating PnP, refer to our previous article here for an overview of how to configure a simple PnP search page in SharePoint Online.

Finding and Mapping Crawled Properties

To fully utilize custom columns within PnP Filters, we must take a preemptive step: mapping the crawled properties generated by our custom columns to Microsoft's blank, usable refinable string managed properties. This mapping is crucial as it allows us to refine and filter data effectively within the PnP Filters Web Part, making it an indispensable technique for creating a dynamic and user-friendly SharePoint experience.

Let’s get into the tutorial:

For this example, we will use a column called “Account Number,” a single line of text column to track account numbers for files.

The first thing we will need to do is find the crawled property name for the Account Number Column. Afterwards, we may map it to a empty out of the box RefinableString managed property to make refinable and added to the SharePoint search index.

To find the crawled property, (1) we will click on the settings gear for our SharePoint Online site and then (2) select Library settings.

Then we will click on More library settings to access the settings page.

From the settings page, scroll down to the Columns section and click on the name of the column you would like to see the crawled property name for. In this case, we will click on the Account Number column.

Now from the URL of this page, the value after Field= is the crawled property name of our column. For Account Number our crawled property name is Account_x0020_Number. We will copy this value to your clipboard.

*Note* Microsoft encodes spaces as x0020. To avoid seeing x0020 try creating columns without any spaces in their name and then rename them. Renaming a column will NEVER change the crawled property name.

For more details, please see article on SharePoint Naming Guidelines.

Next, we will navigate to site settings. We will once again click on the gear settings symbol from the document library settings page and then select Site settings.

From Site settings, we’ll click on Search Schema.

The Search Schema defines how the data in SharePoint is indexed and retrieved through search queries.

This where we will be able to:

  • map crawled properties to managed properties

  • create new managed properties

  • review existing managed and crawled properties

Let’s confirm the crawled property of our column exists. (1) Click the crawled property tab, and then (2) search for the name of our crawled property which in this case is ACCOUNT_X0020_NUMBER.

*Note* remember the crawled property will not exist until the column is actively used on the site.

*Note* OWS “Office web server” is a prefix commonly used in SharePoint search to denote Out-of-the-box properties. These are properties that are automatically created by SharePoint when a list or document library is created.

Now after confirming the existence of our crawled property, click the (1) Managed Properties tab and search (2) RefinableString. In this instance, we will select (3) RefinableString100 to do the mapping.

If a RefinableString is currently being used, you’ll see the names of the crawled properties mapped to it in the Mapped crawled properties column. Pick an empty RefinableString or map your crawled property to one currently in use, but remember when mapping multiple crawled properties to 1 managed property that multiple values can be returned in the search index.

Once inside the managed property, you’ll see you are unable to change any configuration except mapping crawled properties.

If desired, we can give our RefinableString an Alias to call upon when running search queries, but note the Alias does not work for Purview KQL queries. In this instance, we will give our RefinableString100 the alias of AccountNumber.

Scroll down to the bottom of the page and click Add a Mapping.

This will open a pop up where you will be able to search for the crawled property you would like to map. Here we will search the crawled property name (1) ACCOUNT_X0020_NUMBER and then (2) click the Find button. (3) Then we will click our crawled property’s name (should appear highlighted) and then (4) click the OK button.

Review that the mapping has taken affect and then click the OK button to save these changes.

We will now see the mapping saved.

Also note that RefinableStrings are not searchable.

This means that once the text value of a crawled property is mapped to a RefinableString managed property, it will be no longer searchable unless you follow the search format of:

RefinableStringXX:”Value” or using the RefinableString’s alias which is AccountNumber:”Value” for our example.

Therefore, to maintain a seamless end user experience, we will have to create a brand new custom managed property and designate it as being searchable and map it to our crawled property ACCOUNT_X0020_NUMBER.

Therefore, our crawled property will be mapped to 2 different managed properties:

  1. An out of the box RefinableString.

  2. A custom managed property we create.

To map to a custom managed property, we will click the New Managed Property button.

When creating a new managed property, (1) give it a name with MP to designate managed property. We will name ours Accountnumbermp. Then (2) select text as the type and (3) checkmark the managed property as searchable. Then scroll down and repeat the process to map your crawled property.


After mapping, be sure to click the OK button to save these changes.

Now, the search schema component is complete!

Adding the Custom Column as a Filter

Next, we will add our custom column Account Number as a filter for our PnP search

Navigate to the page where your PnP Search web parts live and click Edit on the page.

Once editing the page, navigate to the PnP Search results web part and click on the Edit properties button.

From the right-hand configuration panel, scroll down on the first page and expand the Selected properties section.

What we are going to do is scroll through the list of searchable properties and we are going to checkmark the one that matches the name of our refinable string managed property that we mapped our crawled property to. In this instance, it is RefinableString100 mapped to ACCOUNT_X0020_NUMBER.
*Note* we must select the RefinableString managed property, not the custom new one we created.

Next, we are going to navigate to the PnP Search Filters web part (1) click Edit properties and from the right-hand configuration panel. Then we will (2) click on the Edit button for customizing the search filters.

Now, we will add Account Number as a Search filter. (1) We will give our filter a name, (2) select our RefinableString100 as our filter field, (3) select our template for the filter’s appearance and (4) click on the Save button.

*Note* Your RefinableString managed property will NOT be selectable unless you have added it as a selected property in the PnP Search Results web part.

Finally, republish the page and verify that your search filter works!

The steps outlined in this guide provide a straightforward method to implement and configure custom filters, optimizing your SharePoint environment for more efficient search functionality. For a comprehensive understanding of PnP Search, be sure to check out Parts 1 and 2 of our series to learn how to add PnP Search to your tenant and configure a PnP Search on a SharePoint site.

For more valuable tips and insights on search, SharePoint, and M365, visit the Gravity Union Blog. And if your organization needs additional support, our team of M365 experts at Gravity Union are ready to assist. Contact us to learn how we can help you achieve your goals.