Prerequisite

Ektron version 9.10 SP1 or higher

Obtaining Find indexes

Upon creating a developer account, you can use a free development index for testing. This index has a 10,000 document limit, a 90-day lifespan, and a maximum file size of 5 MB.

After completing testing, if you want to move into a production environment, obtain a production index. See http://www.episerver.com/orderfind.

Installing Optimizely Search & Navigation

1. Create an Optimizely Search & Navigation developer service.
   1. Go to http://find.episerver.com/.
   2. Create an account and verify it.
   3. Click Add Developer Service. The Create Developer Service screen appears.
   4. Enter an index name, choose languages to support, accept the terms and conditions, and click Create Service. The Index Details screen displays your information.

      Tip — Save this page with your browser favorites so you can quickly open it in the future.

2. Prepare the Ektron website in Visual Studio.
   1. Open the Ektron site as a website.
   2. Save a solution file for the site.
   3. Set the site's Target Framework to .NET Framework 4.5.
3. Update the Ektron web.config file with snippets from the Create Service screen.
   1. From the Optimizely Search & Navigation Create Service screen, copy the web.config snippet within the <configSections> tag.
       

      

   2. Open your Ektron siteroot\web.config file.
   3. Find the closing configSections tag (</configSections>).
   4. Paste the copied text above the closing </configSections> tag.
   5. From the Optimizely Search & Navigation Create Service screen, copy the web.config snippet below the closing </configSections> tag and above the closing </configuration> tag.
       

      

   6. Within the Ektron siteroot\web.config file, find the closing configuration tag (</configuration>).
   7. Paste the copied text above that tag.
4. Create an Optimizely Search & Navigation package source.
   1. In Visual Studio, choose Tools > Library Package Manager > Package Manager Settings. The Options screen appears.
   2. Under Package Manager, choose Package Sources.
   3. Add a new source called Episerver Find. Assign it a URL of http://nuget.episerver.com/feed/packages.svc/
5. Install the Ektron.Cms.Find Nuget package.
   1. In Visual Studio, open Solution Explorer.
   2. Right-click the Ektron website project.
   3. From the context menu, choose Manage NuGet Packages...
   4. In the left panel, choose Online.
   5. In the Search field, enter Ektron.cms.find.
   6. Click the Ektron.Cms.Find package's Install button.
6. Update the Global.asax file with a reference to bootstrapper file.
   1. Open yoursiteroot\Global.asax.

      NOTE: If your siteroot folder does not contain a Global.asax file, create one.

   2. Find the following method:

      void Application_Start(object sender, EventArgs e)
      {
      }

   3. Between the curly brackets ({}), insert the following code.

      Ektron.Cms.Find.AspNetBootstrapper.EktronFindBootstrapper.Start();

7. To update the Find index with content changes created by Ektron eSync, follow these steps.
   1. Stop the Ektron Windows Service.
   2. Copy the Ektron.Cms.Find.EsyncNotification.dll file from the bin folder. Paste it to the C:\Program Files (x86)\Ektron\EktronWindowsService40 folder.
   3. Open the C:\Program Files (x86)\Ektron\EktronWindowsService40\objectFactory.config file.
   4. Find the following section of the file.

      <add name=”ESyncNotification”>
        <strategies>
        </strategies>
      </add>

   5. Within the <Strategies> tags, insert the following line.
      

      <add name="FindStrategy" type="Ektron.Cms.Find.EsyncNotification.FindStrategy, 
      Ektron.Cms.Find.EsyncNotification"/>
      

   6. Save the objectFactory.config file.
   7. Restart the Ektron Windows Service.

Prerequisites

• You completed all installation steps. See Installing Optimizely Search & Navigation.
• You are a member of the Ektron Administrators Group.

Using Find to query HTML content

You can used FIND APIs to query and filter published HTML content by the following properties.

• Title
• Body
• Summary
• Taxonomy category
• Creation date
• Modification date
• Last editor
• Folder
• Content ID
• Language
• Quicklink

Using Find with a PageBuilder page

Optimizely Search & Navigation returns search results for all searchable content on a published PageBuilder page. Text that appears on such a PageBuilder page is indexed, along with the page's title. For example, if a PageBuilder page includes a collection widget, and each collection item's teaser is displayed, the teaser text is searchable.

Indexing PageBuilder master layouts

Indexing PageBuilder master layouts

Pagelayout pages are indexed. Master layouts are not indexed, but PageBuilder pages based on a master layout are indexed. See also: Creating a PageBuilder master layout.

Suppressing page elements from search results

Suppressing page elements from search results

You may want to suppress certain page elements from search results. For example, you want to exclude navigation menus or footers. The following Knowledge Base article explains how to do this: How to hide an element on a PageBuilder page from showing up in search results.

NOTE: Any text that is not visible to the builtin user is not indexed.

Using Find with Ektron Smart Forms

NOTE:
* If you want a Smart Form to be indexed, you must select its Content Searchable checkbox.
* The Indexed checkbox on Smart Form configuration field's dialog has no effect on whether the field’s content is searchable. Any property specified in your custom Smart Form class and populated by serialization logic is searchable.

You can query Smart FormAn Ektron-defined Web page that contains XML (hidden from the end user) to display content, and receive, verify, and save user input.s using the content type Smartform. For example: SearchResults<Ektron.Cms.Find.Models.SmartForm> results;

If you use this approach, Episerver Find returns Smart Form content as a single string. To extract field data, developers must use a string split technique.

If you want to query data stored in Smart Form fields, use a type mapper to store a custom content type. This type lets you convert each field in Smart Form configuration to a field in a custom object. You can then use Find to query that object using this syntax.

var results = client.Search<customclassname>().Filter(…).GetResult(); 

For example, if the class created for your Smart Form configuration is OurTeam, you would use this.

var results = client.Search<OurTeam>().Filter(…).GetResult();

To learn how to use a type mapper to store a custom content type, see Converting a Smart Form configuration to a class.

Converting a Smart Form configuration to a class

Converting a Smart Form configuration to a class

Complete these steps for each Smart Form configuration that you want to convert into a class. After you complete the procedure, Optimizely Search & Navigation indexes registered configurations when a Smart Form is edited or added.

NOTE: To learn about updating Find upon deleting, see Updating Find index upon deletion of a Smart Form.

Part 1: Analyze the Smart Form configuration

Part 1: Analyze the Smart Form configuration

1. Obtain the Smart Form configuration’s ID. You use this information in later steps.
    

   

2. Analyze the configuration’s XML structure: its root class and subclasses. These appear on the View Smart Form Configuration screen's Display Information tab. Consider the following example.
    

   

This Smart Form configuration has the following structure. You use this information in later steps

Root class: Ourteam Subclass: Employee profile Subclass: Image Subclass: img

Part 2: Create class and move .dll to bin folder

Part 2: Create class and move .dll to bin folder

1. In Visual Studio, create a class library.
2. Save the Smart Form configuration schema as an XSD file, then generate a class from it. This procedure is explained in steps 1 (Save Schema XSD File) and 2 (Generate Class from XSD) in the Ektron Knowledge Base article "Generate Class for Smart Form.
3. Move the .cs file created in step 2 to the Visual Studio class library.
4. Build your Ektron solution. This action creates a .dll file in your Visual Studio project's bin\Debug folder. For example: C:\Users\jedit\Documents\Visual Studio 2012\Projects\MySmartFormClassLibrary\MySmartFormClassLibrary\bin\Debug.

   The file name matches the Smart Form configuration name.

5. Copy the .dll file to your Ektron website's bin folder.

Part 3: Register the class

Part 3: Register the class

1. In Visual Studio, open your Ektron website solution.
2. Open the findbootstrapper.cs file, located in C:\Users\user name\Documents\Visual Studio version\Projects\yoursitename\packages\Ektron.Cms.Find.1.0.0\content\App_Code\CSCode\.

3. Find these comments.

   // Register type mappings below to translate Smart Forms
   // to custom models.
   // Example:
   //  ektronMessaging.Types.Register(content => new MySmartFormModel { ... })
   //     .For(content => content.XmlConfiguration.Id == ...);

4. Below the comments, register the class you created in Part 2: Create class and move .dll to bin folder. To do that, use this syntax:

   ektronMessaging.Types.Register(SmartForm configuration name.Create)
   .For(SmartForm configuration name.CanCreate);

   For example:

   ektronMessaging.Types.Register(OurTeam.Create).For(OurTeam.CanCreate);

   NOTE:
   * The Ektron Messaging class’s Types property configures how Ektron indexes content.
   * Register converts Ektron content data to an object that Optimizely Search & Navigation can query.
   * As an argument, the Register method takes a delegate, which receives content data and returns an object. This object is pushed to the Find index.
   * The .For statement enables you to map only content data that satisfy a criterion. .For takes a delegate, which returns a Boolean. Content is only converted to the registered class if Ektron content data matches this criterion. Without a .For statement, the type mapper applies to all content passed through the system.
   * The CanCreate method is defined in your configuration's .cs file. See step 10 later in this section.
   

5. Open the .cs file that you created in step 2 of Part 2: Create class and move .dll to bin folder. It contains your configuration's XML structure. For example:

   namespace MySmartFormClassLibrary
   {
   	public class Image
   	{
   	     public img img { get; set; }
   	}
   	public class EmployeeProfile
   	{
   		public string Name { get; set; }
   		public string Title { get; set; }
   		public string Summary { get; set; }
   		public string LinkedIn { get; set; }
   		public string Twitter { get; set; }
   		public string Bio { get; set; }
   
   		public Image Image { get; set; }
   }					

6. Find the following section. The sample below continues using the OurTeam configuration.

   [XmlRoot("root")]
     public class OurTeam
     {
   

7. Under that section, insert the following code. It creates a unique identifier for the Smart Form configuration.

   public long Id { get; set; }
   public int LanguageId { get; set; }
   public string Title { get; set; }

   IMPORTANT: Repeat steps 8 through 10 for each subclass directly below /root/ in your Smart Form configuration.

8. Declare the first subclass in your configuration. (This was discovered in Part 1: Analyze the Smart Form configuration.)
   

   public EmployeeProfile EmployeeProfile { get; set; }

9. Add the following code to set property values for the OurTeam configuration. Replace references to OurTeam with your Smart Form configuration name.
   

   NOTE: Ektron Smart Forms store rich text HTML as valid XML. This code deserializes rich text HTML into an encoded XML string, which Find can consume.

   public static OurTeam Create(ContentData content)
   {
      XmlSerializer serializer = new XmlSerializer(typeof(OurTeam));
      OurTeam oTeam = (OurTeam)serializer.Deserialize(new StringReader
        (content.Html)); 
      oTeam.Id = content.Id;
      oTeam.LanguageId = content.LanguageId;
      oTeam.Title = content.Title;
      return oTeam;
   }

10. Define the CanCreate method, which is referenced in the findbootstrapper.cs file's registration method, which returns the config ID for registering the type (see step 4 above).
    
11. Replace the ID number with your configuration ID, which you obtained in Part 1: Analyze the Smart Form configuration.

    public static bool CanCreate(ContentData content)
    {
       return content.XmlConfiguration.Id == 8;
    }

Here is the complete sample file, OurTeam.cs.

OurTeam.cs sample file

using Ektron.Cms;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Xml.Serialization;

namespace MySmartFormClassLibrary
{

    public class Image
    {
        public img img { get; set; }
    }

    public class EmployeeProfile
    {
        public string Name { get; set; }
        public string Title { get; set; }
        public string Summary { get; set; }
        public string LinkedIn { get; set; }
        public string Twitter { get; set; }
        public string Bio { get; set; }

        public Image Image { get; set; }
    }

    [XmlRoot("root")]
    public class OurTeam
    {

        public long Id { get; set; }
        public int LanguageId { get; set; }
        public string Title { get; set; }

        public EmployeeProfile EmployeeProfile { get; set; }

        public static OurTeam Create(ContentData content)
        {
            XmlSerializer serializer = new XmlSerializer(typeof(OurTeam));
            OurTeam oTeam = (OurTeam)serializer.Deserialize(new StringReader(content.Html));

            oTeam.Id = content.Id;
            oTeam.LanguageId = content.LanguageId;
            oTeam.Title = content.Title;

            return oTeam;
        }

        public static bool CanCreate(ContentData content)
        {
           return content.XmlConfiguration.Id == 8;
        }
    }
}

Updating Find index upon deletion of a Smart Form

Updating Find index upon deletion of a Smart Form

If you delete a Smart Form configuration, its content remains in the Find index. To remove the custom type entries of a Smart Form from the index, remove the type mapper by not registering it. Then, clear the index and reindex. These actions index the Smart Form contents as the default Smart Form type.

Alternatively, you can delete individual documents from the Find index using the following article: http://world.episerver.com/documentation/Items/Developers-Guide/Episerver-Find/9/DotNET-Client-API/Deleting-documents/.

Smart Form indexing guidelines

Smart Form indexing guidelines

When you create a Smart Form configuration, no indexing occurs because there is nothing to index at this point. If Smart Form content is published before the configuration is converted to a class, it is indexed as HTML content. If you later convert the configuration to a class, you should clear the index and reindex your site to make Smart Form content available to Optimizely Search & Navigation.

Similarly, if you modify a class, you should clear the index and reindex your site.

Using Find to search by taxonomy

Taxonomy and category information is updated in the Find index whenever any of these events occurs.

• A taxonomyA content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors go content independent of the folder structure. category is assigned to content.
• A taxonomy category is removed from content.
• A taxonomy category is updated.
• A taxonomy category is removed.

Find divides taxonomy paths into individual taxonomies, indexes each category, and returns the following string-based properties.

• Id. the taxonomy ID.
• Path. the taxonomy path using category titles.
• IdPath. the taxonomy path using IDs.

For example:

Root taxonomy

"Id$$string":"154",
"Path$$string":"\Food",
"IdPath$$string":"\154",

Child taxonomy

"Id$$string":"155"
"Path$$string":"\Food\Chinese"
"IdPath$$string":\154\155

IMPORTANT: All properties are stored as strings.

Taxonomy-based search and parent/child nodes

Taxonomy-based search and parent/child nodes

When a search query uses a taxonomy filter, the results include content assigned to child categories even if the query only specifies the root taxonomy. Similarly, if a query specifies a child category, parent taxonomy categories are available, so users can find content by searching any category in the tree.

Consider the following example.

• Content title. General Guidelines for Cooking
  • ID. 68
  • Taxonomy path. \Food

• Content title. Grilled Asian Chicken
  • ID. 231
  • Taxonomy path. \Food\Chinese
    

Search query 1

IClient client = Client.CreateFromConfig(); //A client retrieved from config or injected into the method
client.Search<Ektron.Cms.Find.Models.Content>()
           .Filter<Ektron.Cms.Find.Models.Content>(c => 
c.Categories.MatchContained<TaxonomyCategory>(tax => tax.Path, @"\Food"))
           .GetResult();

When executed, this code returns content assigned to the Food and Chinese categories. So, content IDs 68 and 231 are returned even though 231 is not assigned to the Food category.

Search query 2

client.Search<Ektron.Cms.Find.Models.Content>()
	.Filter<Ektron.Cms.Find.Models.Content>(c => 
c.Categories.MatchContained<TaxonomyCategory>(tax => tax.Path, @"\Food\Chinese"))
	.GetResult();

When executed, this code returns content assigned to the Chinese and Food categories. So, content IDs 231 and 68 are returned.

Using Optimizely Search & Navigation to search assets

Episerver Find can retrieve search results from assets as it does with HTML content.

• Maximum file size. Developer index: 5 MB; Production index: 50 MB.

  NOTE: Indexed files are sent base 64 encoded, which increases their size by roughly 1/3.

• Supported file types. See http://world.episerver.com/documentation/Items/Developers-Guide/Episerver-Find/9/DotNET-Client-API/File-attachments/.
• Text-based documents. You can search text inside PDFs, Word documents, and so on.
• You can search and filter by the following criteria:
  • Ektron title
  • summary
  • path
  • searchable metadata

Using Optimizely Search & Navigation to search Ektron metadata

If you want to query data stored in Ektron metadataInformation about a content item, such as its title and language. Some types of metadata are [Searchable.] Can be found by the search. [Meta tag.] Resides in a content’s source code, helping search engines find it. [HTML tag.] Information about content used by a Web browser. [Content tags.] Keywords that can be assigned to content and library items. * Simple Dublin Core. 15 standard fields that cover useful information about content., use a type mapper to store a custom content type. This type lets you convert selected metadata definitions to a field in a custom object. You then can use Optimizely Search & Navigation to query that object using this syntax.

var results = client.Search<custommetadataclassname>().Filter(…).GetResult(); 

For example, if the class created for your metadata definition is UnstructuredContentModelWithMetadata, you would use the following code.

var results = client.Search<UnstructuredContentModelWithMetadata>().Filter(…).GetResult();

To convert a metadata definition to a class, use the following steps.

Prerequisite

Prerequisite 

Your Ektron CMS has metadata definitions that are applied to content and to which values are entered. The definitions must be of the Searchable Property type, publicly viewable, and active. See also Metadata types.

1. Create a class for each group of Ektron metadata definitions that Find will query. Within the class, create a property that maps to each metadata definition. The class's type must match the metadata definition's type. For example:

   public class UnstructuredContentModelWithMetadata : UnstructuredContent
   {
       public string SearchTextMetadata { get; set; }
       public List<string> SearchSelectionMetadata { get; set; }
       public DateTime SearchDateMetadata { get; set; }  
       public int SearchNumberMetadata { get; set; 
       public string mymeta { get; set; }
       public UnstructuredContentModelWithMetadata()
       {
           SearchSelectionMetadata = new List<string>();
       }
   }      
   

   This example illustrates the following metadata definitions and their types.

   • SearchTextMetadata. type:string
   • SearchSelectionMetadata. type:List<string> (user can select one or several string values)
   • SearchDateMetadata. type:datetime
   • SearchNumber. type:integer
2. To enable Optimizely Search & Navigation to search a class, register it in the EktronFindBootstrapper file, located in siteroot\App_Code\CSCode\. Enter the register statement below applicationBuilder.App.Start(); as shown in the following example:

   ektronMessaging.Types.Register(CreateMyUnstructuredContentModelWithMetadata)
           .For(content => (content.XmlConfiguration.Id == 0 &&
                                (content.SubType == 
   Common.EkEnumeration.CMSContentSubtype.Content && content.Type == 1)
                                        ));

   • Register specifies how to convert Ektron ContentData to an instance of the new type created in Step 1. It accepts a condition that selects eligible CMS content to be indexed as this type. The CreateMyUnstructuredContentModelWithMetadata method is described in step 3.
   • .For is a filter that determines which Ektron ContentData can be mapped. In this example, only HTML content is eligible.
3. Create a function that accepts an Ektron ContentData object and converts it to a type defined in step 1. This type is indexed by Find for content matching the .For filter condition specified in step 2 .

   You define the function (CreateMyUnstructuredContentModelWithMetadata in this example) under your site's AppCode directory or in a separate class library/dll.

   In the following example, the function populates UnstructuredContentModelWithMetadata with Ektron metadata for the Find index.

   private static UnstructuredContentModelWithMetadata CreateMyUnstructuredContentModelWithMetadata(
   ContentData data)
   {
      UnstructuredContentModelWithMetadata contentWithMeta = new UnstructuredContentModelWithMetadata();
      if (data.MetaData == null || data.MetaData.Length <= 0)
             return contentWithMeta;
   IEnumerable<ContentMetaData> eligibleMetadata = GetMetadataForContent(data.MetaData.ToList(), 
   data.FolderId, data.LanguageId);
   							   
   \\ See note #1 below
   ContentMetaData cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchText");       
   if (cm != null)
   {
       string metaValue = (string)cm.Text;
       if (!String.IsNullOrWhiteSpace(metaValue))
       {
          contentWithMeta.SearchTextMetadata = metaValue;
        }
   }
   \\ See note #2 below
   cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchNumber");
   if (cm != null)
   {
      int value;
      if (Int32.TryParse(cm.Text, out value))
          contentWithMeta.SearchNumberMetadata = value;
   }
   \\ See note #3 below
   cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchDate");
   if (cm != null)
   {
     DateTime mydate;
     if (DateTime.TryParse(cm.Text, out mydate))  
         contentWithMeta.SearchDateMetadata = mydate;
   }      	
   \\ See note #4 below 
   cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchSelection");
   if (cm != null)
   {
        string metaValue = (string)cm.Text;
        if (!String.IsNullOrWhiteSpace(metaValue))
        {
           string[] metaValues = metaValue.Split(new string[] { ";" }, StringSplitOptions.RemoveEmptyEntries);
   
           if (metaValues != null && metaValues.Length > 0)
           {
              contentWithMeta.SearchSelectionMetadata = metaValues.ToList();
           }
         }
   } 

   Notes on the above sample

   • #1 The following snippet uses the find-extension method to select only SearchText metadata from ContentData. This type is a string, as defined in the class and the Ektron metadata definition. If this metadata exists, apply it to the SearchTextMetadata property of your class.

     ContentMetaData cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchText");       
     if (cm != null)
     {
         string metaValue = (string)cm.Text;
         if (!String.IsNullOrWhiteSpace(metaValue))
         {
            contentWithMeta.SearchTextMetadata = metaValue;
          }
     }
     

   • #2 In the following snippet, the SearchNumber metadata is an integer in the class and the Ektron metadata definition.

     cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchNumber");
     if (cm != null)
     {
        int value;
        if (Int32.TryParse(cm.Text, out value))
            contentWithMeta.SearchNumberMetadata = value;
     }
     

   • #3 In the following snippet, the SearchDate metadata is a DateTime object in the class and the Ektron metadata definition.

     cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchDate");
     if (cm != null)
     {
       DateTime mydate;
       if (DateTime.TryParse(cm.Text, out mydate))  
           contentWithMeta.SearchDateMetadata = mydate;
     }

   • #4 In the following snippet, SearchSelection metadata is a list of strings (List<string>) in the class, and multiple selections in the Ektron metadata definition. Ektron stores values as a single string, and each value is separated by a delimiter (in this case, a semicolon (;)). For example, if metadata definition stores transportation methods, its value might look like this: train;bus;automobile.

     cm = eligibleMetadata.ToList().Find(m => m.Name == "SearchSelection");
     if (cm != null)
     {
          string metaValue = (string)cm.Text;
          if (!String.IsNullOrWhiteSpace(metaValue))
          {
             string[] metaValues = metaValue.Split(new string[] { ";" }, 
     StringSplitOptions.RemoveEmptyEntries);
     
             if (metaValues != null && metaValues.Length > 0)
             {
                contentWithMeta.SearchSelectionMetadata = metaValues.ToList();
             }
           }
     }

     The string[ ] line separates the multiple selection string into individual values that Find can query.

How Find manages archived content

Content that has expired and is set to Archive and remove from site or Archive and remain on site is not automatically removed from the index. Such content is removed upon the next full reindexing. Until then, to exclude expired content from search results, use the Find Client API's EndDate and EndDateAction properties to filter results.

NOTE: Content that has expired but is set to Add to CMS Refresh reports is considered live content, so remains in the Find index.