THIS IS ARCHIVED DOCUMENTATION

Understanding the coveoPostItemProcessingPipeline Pipeline

This is for:

Developer System Administrator

The coveoPostItemProcessingPipeline can be used with items indexed by the Sitecore Search Provider to alter or duplicate them before they’re sent to the Coveo index. Adding a processor in the coveoPostItemProcessingPipeline pipeline is often an alternative to creating a computed field for an item (see Creating Computed Fields).

This article explains how you can add a processor to the pipeline, followed by a code example.

Adding a Processor

You need to create a class that implements the IProcessor<CoveoPostItemProcessingPipelineArgs> interface and its Process method. This method receives a CoveoPostItemProcessingPipelineArgs object.

CoveoPostItemProcessingPipelineArgs objects encapsulate a Sitecore item and the corresponding Coveo index representation of the item (that is, a CoveoIndexableItem). The CoveoPostItemProcessingPipelineArgs class allows you to change the values of fields. You can also use the CoveoPostItemProcessingPipelineArgs class to index many items for a single Sitecore item, which can be required when using wildcard items in Sitecore (see Wildcards and Data Driven URLs).

If you want to add fields to the CoveoItem in the coveoPostItemProcessingPipeline pipeline, make sure to add them in the fieldMap section of Coveo.SearchProvider.Custom.config. If you don’t already have one, create it under defaultIndexConfiguration. It should follow the same syntax as the fieldMap section of the Coveo.SearchProvider.config file. If you fail to do this, your fields won’t be created in the index. Never modify the Coveo.SearchProvider.config directly, as doing so may cause unforeseen upgrading issues.

To know how to add fields to the fieldMap, see Understanding the Coveo Search Provider’s Configuration File.

Finally, to have your code executed, you need to add a <processor> node that references your class in the <coveoPostItemProcessingPipeline> element of the Coveo.SearchProvider.Custom.config file.

CoveoPostItemProcessingPipelineArgs Properties

The CoveoPostItemProcessingPipelineArgs class has the following properties:

Name Type Description
Item IIndexable The original Sitecore item. It's typically used to retrieve field values.
CoveoItem CoveoIndexableItem The Coveo item currently processed by the pipeline.
IndexConfiguration CoveoIndexConfiguration The configuration of the index which defines how Coveo accesses its platform, targets its sources and indexes items. You shouldn't have to modify this property.
OutputCoveoItems List<CoveoIndexableItem> The list of items that will be indexed by Coveo, as Coveo for Sitecore only considers this list, and *not* the `CoveoItem` itself, after the pipeline is done. The list is initialized with `CoveoItem`. An empty list means that no items will be indexed, but this won't delete an existing item from the index.

CoveoIndexableItem Properties

The following properties can be edited on the CoveoIndexableItem type.

Name Type Description
BinaryData Byte[] The item body, represented in binary.
BinaryDataMimeType string The MIME type of the item binary data.
ClickableUri string The ClickableUri used to open a specific location when a search result is clicked.
FileName string The item filename, if the item is representing a file.
HasSubItems bool Whether the item has sub items or not.
Id string The item ID (string representation).
Metadata Dictionary<string, object> A dictionary containing all the item metadata, for example, all the fields values.
ModifiedDate DateTime The item last modified date. You shouldn’t edit this.
Parent CoveoIndexableItem The item parent, if available.
ParentId string The item parent ID.
Path string The item path, for example, /sitecore/content/Home.
Permissions AccessRulesHierarchy Data structure containing the security of the item. You should only edit this if you know what you’re doing.
PrintablePath string The PrintablePath used to show a friendly URL in a search result UI.
Title string The item title (also known as display name).
UniqueId string The item unique ID, when available.
Uri string The item Uri.

You want to create a custom processor to duplicate a CoveoItem. To do so, you would add a new CoveoIndexableItem to the OutputCoveoItems list, using a code snippet such as the following:

CoveoIndexableItem duplicateItem = new CoveoIndexableItem();
duplicateItem.Uri = p_Args.CoveoItem.Uri + "/copy";
duplicateItem.Permissions = p_Args.CoveoItem.Permissions;
duplicateItem.Title = String.Format("Duplicate of {0}", p_Args.CoveoItem.Title);

p_Args.OutputCoveoItems.Add(duplicateItem);

Upstream processors may have created copies of the original Sitecore item already. Prior to adding a code snippet like the one above, use the Re-Index Tree option on a target item in Sitecore and subsequently browse your indexed items by Indexed date to verify if copies of the targeted item are already being created in an upstream processor.

An Example Processor

This example lives in the context of the Jetstream Sitecore demo, a travel aggregation website offering flights. Several flight items are available in the database and were indexed by Coveo for Sitecore.

The default output in a basic search results list looks like this:

For each result, you can see the name of the item in Sitecore, which is the flight number followed by the cabin class (for example, first class, business class, or economy class).

Out of context, the item title doesn’t tell much. However, by leveraging Flight item field values, you can easily create a custom processor that displays a better item title.

Data Structure

The Flight items shown above are all issued from the Flight template. The template contains a few fields such as:

  • flight number: Integer
  • class: Single-Line-Text
  • departure airport: Droplist with source on Airport Template
  • arrival airport: Droplist with source on Airport Template

The Airport template contains Airport items with this single field:

  • City: Single-Line-Text

Both the Flight and Airport template names are unique. These templates could have more fields, but for this example we’ll only use those listed above.

Setting Up the Visual Studio Project

Before you can implement the custom processor itself, you need a suitable project to add it to. You’ll need a C# project that targets .NET framework 4. Once you have this project, add the following references to it:

  • Coveo.AbstractLayer.dll
  • Coveo.Framework.dll
  • Coveo.SearchProviderBase.dll
  • Sitecore.ContentSearch.dll
  • Sitecore.Kernel.dll

You’ll find those assemblies in the Sitecore website bin folder. This folder is located at <sitecore instance name>\website\bin for Sitecore 8 instances, and <sitecore instance name>\bin for Sitecore 9 instances.

Implementing the Processor Class

Now that your Visual Studio project is ready, you can move on to implement the custom processor.

Create a new class that implements the IProcessor<CoveoPostItemProcessingPipelineArgs> interface as in the code sample below.

Skeleton of the Custom Processor Class

using System;
using Coveo.Framework.Processor;
using Coveo.SearchProvider.Pipelines;
using Sitecore;
using Sitecore.ContentSearch;
using Sitecore.Data;
using Sitecore.Data.Items;

namespace Samples.Pipelines
{
    public class FlightTitleProcessor : IProcessor<CoveoPostItemProcessingPipelineArgs>
    {
        public void Process(CoveoPostItemProcessingPipelineArgs p_Args)
        {
            throw new NotImplementedException();
        }
    }
}

Implementing the Process Method

The hardest task is to implement the Process method. Here, we’ll alter the item title to include the flight number, the departure city, and the arrival city.

Therefore, the flight with the title 9981 - Business would become 9981 - From Paris to Los Angeles.

Here is the complete implementation of the class.

public class FlightTitleProcessor : IProcessor<CoveoPostItemProcessingPipelineArgs>
{
    public void Process(CoveoPostItemProcessingPipelineArgs p_Args)
    {
        if (p_Args.Item is SitecoreIndexableItem) {
            Item item = ((SitecoreIndexableItem) p_Args.Item).Item;

            // This processing only makes sense for instances of the "Flight" template.
            if (item != null && item.TemplateName.Equals("Flight", StringComparison.OrdinalIgnoreCase)) {
                // Get the flight number
                string flightNumber = item["flight number"];
                // Get the linked airport items
                string departureAirportId = item["departure airport"];
                string arrivalAirportId = item["arrival airport"];
                string departureCity = GetAirportCity(item.Database, departureAirportId);
                string arrivalCity = GetAirportCity(item.Database, arrivalAirportId);

                if (!String.IsNullOrEmpty(flightNumber) &&
                        !String.IsNullOrEmpty(departureCity) &&
                        !String.IsNullOrEmpty(arrivalCity)) {
                    // Set the new title on the Coveo item
                    p_Args.CoveoItem.Title = String.Format("{0} - From {1} to {2}", flightNumber, departureCity, arrivalCity);
                }
            }
        }
    }

    private string GetAirportCity(Database p_Database, string p_AirportId)
    {
        string city = "";
        Item airport = p_Database.GetItem(p_AirportId);
        if (airport != null) {
            city = airport["city"];
        }

        return city;
    }
}

First, the Sitecore.Data.Items.Item instance is retrieved, as the item needs to be an instance of the Flight template and the Item class allows you to access the TemplateName property.

Then, the flight number and the airports are retrieved. For each airport, the GetAirportCity method returns the city name for the given airport. The Item.Database property is used to ensure that you get the airport from the same database as the flight item itself.

Finally, the .NET Framework System.String class Format method is used to modify the Title property of the CoveoItem object.

p_Args.CoveoItem.Title = String.Format("{0} - From {1} to {2}", flightNumber, departureCity, arrivalCity);

The Title of certain search result items might not be altered using the example above, for example, if the Sitecore item has a populated and indexed Title field (see Understanding the Title Selection Sequence).

Enabling the Processor in Sitecore

The custom processor is ready to be used by Sitecore. Here is how you can add it to the configuration file.

  1. Copy the assembly containing the custom processor into the bin folder of the Sitecore website. Default location is <sitecore instance>\website\bin.
  2. Open the Coveo.SearchProvider.Custom.config file in a text editor. The default file location is <sitecore instance>\website\App_Config\Include\Coveo for Sitecore 8 instances, and <sitecore instance>\App_Config\Include\Coveo for Sitecore 9 instances.
  3. Find the coveoPostItemProcessingPipeline element.

  4. Add a processor element that maps the implementation of the custom processor in the pipeline. For example, if you’ve created a Samples.dll file, add the following node in the coveoPostItemProcessingPipeline element.

    <processor type="Samples.Pipelines.FlightTitleProcessor, Samples" />
  5. Save the file and reindex Sitecore items.

The New Search Result Item Titles

Now, the results page shows the customized titles. Since you changed the title on the indexed items, a search with the paris keyword returns the flight items with paris in their title.

Conclusion

In this example, you learned how to alter the item title for a specific item type in Sitecore. It’s also possible to alter item field values, URLs, and the Quick view, though the latter requires much effort. Almost any field/property on the item can be customized.

You can also add as many custom processors as you want, but remember that the more you add, the slower the indexing gets.