Create a custom column and use it as a filter in Search

Atlas supports adding your own custom columns to specific Lists or Libraries in specific Workspaces to support custom scenarios. In this article we explain how to add custom columns, have them indexed by Microsoft Search, and use the indexed data to add them as custom refiners to In Focus web parts.

Please carefully read the following caveats before continuing:

• Due to the way Microsoft Search works, you may need to do this over more than one day to allow the search schema to generate the necessary "Managed Property" data.
• To create custom columns in a Workspace you'll need to be an Owner of that Workspace
• To set up the Search configuration you'll need to be a SharePoint Administrator
• Custom columns will not be shown in Add It without custom configuration
• Custom columns need to be added individually to every List or Library in every Workspace where they are required
  • If you need to use the same custom column in multiple workspaces you must create it with the exact same name in each workspace so that the Search configuration will apply to all
• If your scenario is related to a specific type of document that needs additional metadata you should create a custom Content Type as a child of the Atlas "File Item" content type and add your custom columns to it so that the items can still be returned in Atlas searches.

In this article:

• Create a custom column
• Add your column(s) to a List or Library
• Create an item and populate the custom column
• Configure the Search schema to make the column usable as a filter
• Use your column as a Filter in Atlas Search
  • Create a one-off filter for a single web part
  • Add your filter to an In Focus Filters web part

Create a custom column

To get started, you need to create a custom column from the Site Settings of the relevant Workspace. If you plan to add the column to multiple Workspaces you'll need to follow these steps for each one.

1. Navigate to the Workspace and click Site information from the "cogwheel" in the top right, then click View all site settings in the panel that appears:
                
2.  Under the Web Designer Galleries heading click Site columns:
   
3. Click Create at the top of the page to start defining your new column:
   
4. On the creation screen you can define the column you wan to create, which will be subject to your specific requirements. We have some recommendations here:
   • Create the column initially without any spaces or special characters in the name. Once the column is created you should then edit it to add any spaces or other characters, but the internal name of the column will not change, so for example a column called "Item Value" should be created as "ItemValue" and then renamed.
   • Prefix all your custom columns with your company name or something to do with the custom scenario - so for example instead of "ItemValue" your should give the internal name "ClientNameItemValue". The prefix also makes it easy to find the Crawled Properties later.
   • Create a new Column Group for your column such as "{Client} Custom Columns" so it is obvious that these are custom columns rather than part of Atlas.
5. Repeat this for each Workspace where you intend to use the column, making sure you give it the same internal name in each Workspace.
6. If you need to add multiple columns, repeat the steps above for each column in each workspace where you'll need it.

Add your column(s) to a List or Library

Now that you have created your column(s) in the workspace you can add them to the lists and/or libraries where you need that additional metadata. Here we explain how to add the column to a list or library, but you do have another option to add it to your own custom Content Type and then add the new Content Type to the list or library.

If you're not sure which approach to use feel free to ask your CSM for advice.

1. Click Site contents from the "cogwheel" in the top right, then click the ellipsis (...) next to the list or library you want to add the column to and click Settings
2. Scroll down past all the existing columns in the Columns section, then underneath click the link Add from existing site columns
   
3. Choose the custom column you created in the Available site columns and click Add to move it over to the Columns to add section. You can add multiple columns at once here if needed.
4. Click OK at the bottom of the screen to add the column(s) you chose.
5. Repeat this for each list or library in the workspace where you need to use the column.

Create an item and populate the custom column

Once you have added the column to a list or library, you need to populate the column with content for at least one item so that the Search service will crawl it and generate us a Crawled Property.

1. Open a list or library which includes your custom column
2. Create a new item (in a list) or upload a document (in a library) and when setting the metadata, ensure you set a value in your custom column
3. Save your item or document with the custom column populated and if you're using Publishing features in the list or library, Publish the item or document too.

Now you'll need to wait a little while for the Microsoft Search to generate the Crawled Property.

Configure the Search schema to make the column usable as a filter

Usually after less than 15 minutes the item you created will be crawled by the Search service and a Crawled Property will be generated. Sometimes this can take longer but unfortunately there is no way to monitor or control it - you simply have to be patient.

The final step is to tell the Search service to link our Crawled Property to a Managed Property which can then be used as a filter (refiner) in Search.

This step requires a user with SharePoint Administrator permissions to manage the Search schema. If you are not a SharePoint Administrator you will need to seek the help of one in your organisation to complete this step.

1. As a SharePoint Administrator, go to the SharePoint Admin centre via the Microsoft 365 Admin centre
2. On the left hand rail click More features, then under Search click Open:
   
3. On the next page click the first option Manage Search Schema:
   
4. From here you can start to configure a suitable Managed Property. To find one, type "refinable" in the search box and press enter to search. You could also search based on the type of column you created:
   • For a Text column we want a RefinableString property
   • For a Date column we want a RefinableDate property
   • For Number columns there are a few options; RefinableDouble, RefinableInt and RefinableDecimal 
5. For this example we will assume that the column is a Text column which will need to use one of the RefinableString properties. The important thing is to use a property which is not already being used by Atlas. If you look at the list of properties you can see that some already have the Mapped Crawled Properties already populated:
   
   There will be many (tens or hundreds depending on type) that are not populated.
6. We recommend choosing a specific range of numbers for your own custom properties that are not too close to the Atlas properties, for example RefinableString100 to RefinableString109 are not used by Atlas. Once you have chosen an unmapped property, click the name of it in the left hand column to start mapping it to your column.
7. Once you have chosen a Managed Property which is not currently in use, click on the name of the property in the left-hand column to change its configuration. Scroll all the way to bottom of the configuration page and you'll see the Mappings to crawled properties section:
   
8. Next, click the Add a Mapping button. You'll see the screen get greyed out immediately, but you'll need to scroll back up or wait a few seconds to see the panel that loads at the top of the page. In the panel, type the name you gave to your custom column into the search box, click find, and wait 10 seconds or so to see the results. If you added a prefix to your columns as recommended you can simply search for the prefix to see all the custom columns you created.
   
9. You should see a crawled property with the name you gave to your custom column. Select it by clicking on it, then click OK at the bottom of the panel. You'll now see your Crawled Property listed in the Managed Property configuration:
   
10. Scroll down and click OK to save this configuration.

After completing these steps Microsoft Search will take some time to generate the data in the Managed Property, so it is usually best to leave it overnight. Unfortunately in SharePoint Online it is not possible to manage the schedule for this job and it usually takes several hours to propagate.

Use your column as a Filter in Atlas Search

Once a SharePoint Administrator has set up the Managed Property as explained in the previous section, anyone with Edit permissions in a workspace using the custom column can apply it as a filter in Atlas Search web parts known as In Focus web parts.

Create a one-off filter for a single web part

1. Edit your page, then edit the In Focus web part you want to filter by clicking the "pencil" icon to the left of the web part
2. A panel will appear on the right of the page which has all the configuration options. At the bottom of the panel, use the paging control to go to Page 2
3. On page 2 of the panel, scroll down to the Refinement Filters field. In this field you can use the Managed Property and a specific value to filter the items returned, for example:
   
4. The filter above will ensure the web part only returns items with a Department tag value of "Sales". Of course in your case you should use the specific Managed Property you configured and match to the value you need in that column.
5. To see the new set of results, click out of the Refinement Filters field and you should see the web part load the new results set. You may need to save the page as a draft to force the update.
6. Once you are happy with the results returned, make sure you publish your page to save your changes.

Add your filter to an In Focus Filters web part

First you should configure an In Focus and In Focus Filters web part on the same page and ensure they are linked together so that the Filters are populated.

1. To add your custom column as a filter, Edit the In Focus Filters web part and at the top of the first panel click the Edit refiners button:
   
2. Scroll down past the existing options until you find the grey line at the bottom of the table:
   
3. First, click into the dropdown box on the left (note that it may take a few seconds to load the content) then scroll down to the Refinable Strings and select the specific one you configured for your column. If you do not see it in the list it may not have been indexed yet, but you can type it into the box manually.
4. Next click the Edit button in the same line to add the filter label in the languages you need to support. Another panel will open - first choose "Default" from the drop down and set the default label (for any language not otherwise specified):
   
5. If you need to add translations click the + on the right hand side, then in the new row configure the next language, and so on. Once all required labels are configured click Add and save to confirm.
6. Back on the Edit refiners panel choose the Refiner Template best suited to your column:
   
   • Default refinement item - choose one filter only
   • Multi-value refinement item - choose multiple filters at once
   • Date range / Date range (fixed intervals) - for date fields
   • Persona - for user column filtering
   • File type - detects file type from the item
   • Multiple file type - choose multiple file types to filter
   • Container tree - not supported
   • Boolean refinement item - yes/no column filter
7. Next, choose the method to determine sort order for the values shown for the filter. You can use Alphabetical order or by Number of results.
8. In the final dropdown whether that should use Ascending or Descending sort order.
9. Usually, you will want to show your custom column as one of the first filter options, so use the numbered dropdowns on the far left to change the order, for example select 1 for the new column so it appears first.
10. Finally click Save at the bottom of the panel, then Save or Publish the page to ensure you don't lose your work.