Configuration Examples for custom In Focus Verticals

For the main article on Verticals please go to this link: Configure custom In Focus Verticals

Configure a Vertical for "My Events"

In this example we will add a third vertical after Related Events called My Events based on Atlas User Preferences. This example has a more complex query template than the previous example but also meets a very different requirement.

Although we will configure this example in the Events Listing page we could actually use the same filter configuration on any type of Atlas content since we will match against the Atlas Global Metadata.

Edit the web part, then click the Configure search button. In the panel that appears click the Edit button towards the left side on the grey line at the bottom. Choose the Default language (unless you have requirements for other languages) and type the name for your vertical, so in our case we will type "My Events" then click Add and save:

In the Fluent UI icon name, you can type the name of a Fluent UI icon, or leave it blank to have no icon. You can find icon names here: https://www.flicon.io/

In the Data Source, you need to choose SharePoint Search or Microsoft Search. This will have an effect on how we configure things further down the line. Next you can choose the Result Source which best matches the content you want to return in this Vertical. In most cases all Verticals for one web part will use the same Result Source, but this is not a requirement.

Next, click the "pencil" icon next to the Query field. This is where you will write the code to restrict the search within your result source. You can always start by copying the Query from one of the default Verticals as a starting point for the one we are adding. Let's copy All Events:

The template we copied returns all items that have an Event End Date today or in the future, but does not return items where the Event End Date is in the past. Now we want to customise this for our specific requirement to match against the Atlas User Preferences.

Option 1: Use the full set of preferences

Regardless of the type of content, you can generally use the following parameters to match the metadata against the user preferences:

CPOverrideUserPrefOWSBOOL:1 OR ({|CPLocationGeographyTaxId:{User.CPGeography}}) OR ({|CPDepartmentsTaxId:{User.CPDepartment}}) OR ({|CPEntityTaxId:{User.CPEntity}}) OR ({|CPActivityTaxId:{User.CPActivity}}) OR ({|CPSubjectTaxId:{User.CPSubject}})

Option 2: Use only specific preferences

If you only wnat to match some of the preferences you can remove the ones you don't want. For example this query would only match the user's Location and Department preferences:

CPOverrideUserPrefOWSBOOL:1 OR ({|CPLocationGeographyTaxId:{User.CPGeography}}) OR ({|CPDepartmentsTaxId:{User.CPDepartment}})

These expressions have a number of parameters:

CPOverrideUserPrefOWSBOOL:1 means that any item which is set to Override User Preferences will be shown regardless of matching metadata
CPLocationGeographyTaxId:{User.CPGeography} means that any item with a Location metadata value that is also present in the user's preferences is shown
CPDepartmentsTaxId:{User.CPDepartment} means that any item with a Department metadata value that is also present in the user's preferences is shown.
CPEntityTaxId:{User.CPEntity} means that any item with an Entity metadata value that is also present in the user's preferences is shown.
CPActivityTaxId:{User.CPActivity} means that any item with an Activity metadata value that is also present in the user's preferences is shown.
CPSubjectTaxId:{User.CPSubject} means that any item with a Subject metadata value that is also present in the user's preferences is shown.

Combined with the query template from All Events, we now have a vertical which returns items matching the following criteria:

It is an Atlas Event Item,
The Event has not ended yet,
The specified tags matches the current user's Atlas preferences,
- Or if it does not match the preferences, it has been set to override preferences.

Your final query template should therefore look something like this depending which preferences you have chosen to match against:

{searchTerms} CPOverrideUserPrefOWSBOOL:1 OR ({|CPLocationGeographyTaxId:{User.CPGeography}}) OR ({|CPDepartmentsTaxId:{User.CPDepartment}}) AND AtlasRefEventEndDate>{Today-1}

NOTE: You could use the same query for types of content other than Events, by simply removing the AtlasRefEventEndDate>{Today-1} from the end of the query.

Finally, click Save and close the configuration panel on the right. You should now see your new vertical alongside the existing ones:

Make sure you Publish the page to finalise all your changes. If you leave the page in edit mode and your editing session expires you may lose your changes.

Use a Vertical to send the user to a different Listing Page

The example above only uses the first few options in the configuration panel. If we scroll to the right inside the panel we can see some additional options:

For the above examples we stayed in the same page and just changed the filters being used, but using the Is hyperlink toggle, we can instead send the user's search to a different page which is already set up to return the results they are looking for. In this case, the only field further left you need to fill in is the Tab name.

To get started, check the Is hyperlink box on the line for the Vertical you want to behave as a link. This will unlock the Link URL field to paste the Listing Page URL, the Open behavior dropdown where you can choose whether to open the link in a new browser tab, and the option to Show link icon on the Vertical so users have a visual clue that they will be sent to another page.

Configure a Vertical to highlight a specific refiner

In this example we will take a simple refinement filter and "promote" it as a Vertical. This does not provide any additional functionality since users could refine the results themselves, but it makes a particular refiner more obvious to the user. The specific refiner we will configure will show only Policy documents within the Documents Listing.

Start by clicking the Edit button on the grey line at the bottom. Choose the Default language (unless you have requirements for other languages) and type the name for your vertical, so in our case we will type "Policy Documents" then click Add and save:

Choose your Data Source and Result Source. Now click the "pencil" icon in the new (grey) row to edit the Query. First type {searchTerms} to ensure that any In Focus Search Box on the page can still be used:

Next, we need to add our additional filter. To find out the Managed Property you'll need, please refer to this article: Atlas Managed Properties for Search

So if we want to refine on the Information Type as we do in this example, we need to match items where RefinableString145 is equal to "Policy". To do this, simply add RefinableString145="Policy" including the quote marks after the {searchTerms}, so it looks like the following:

Click Save at the bottom of the editor.

You should also choose the Icon by typing or pasting the name of the icon from the Fluent UI icon library. If you want to see all possible icons you can refer to this website: https://www.flicon.io/, otherwise you could simply copy the icon from one of the existing verticals.

In this case we will use the icon "TextDocument" to differentiate from "Document" used for the existing All Documents vertical.

Finally, click Save to add your new vertical as configured. You will immediately be able to see it on the page, and test that it works:

Make sure you Publish the page to finalise all your changes. If you leave the page in edit mode and your editing session expires you may lose your changes.

If your new vertical does not return the results you expect, or returns no results at all, either you do not yet have any Atlas content matching your filter, or you should verify the Query you used and ensure you have the correct RefinableString number and the matching value is spelled correctly.

Notes for Advanced configuration

There are a lot of different scenarios that can be implemented using verticals, so we wanted to give some reference to the different ways that the Query Template can be written to get specific results.

Equals vs. Includes

Query Templates matching against metadata can be configured as equals or includes queries - for example where we used RefinableString145="Policy" in the example above, this means the metadata term must be exactly the term "Policy".

However, you should be aware that instead of an equals (=) you can use a colon (:) which instead of equals means includes, so if you have a number of tags all starting with the word "Policy" you can match against all of them using RefinableString145:"Policy".

Using brackets to apply AND / OR logic

Another thing to note is that you can combine multiple tagging requirements for your filter and use AND / OR logic to create more complex queries. So if we want to include all content with Information Type "Policy" OR "Procedure" in our previous query, we can write something like:

{searchTerms} (RefinableString145="Policy" OR RefinableString145="Procedure")

If instead we want to return only Policies, but only from the Finance department, we could write:

{searchTerms} (RefinableString145="Policy" AND RefinableString133="Finance")

If we want to return content matching Policy OR Procedure AND we only want content from the Finance department, we could write:

{searchTerms} ((RefinableString145="Policy" OR RefinableString145="Procedure") AND RefinableString133="Finance")

In this article:

Configure a Vertical for "My Events"