HawkSearch WebsiteHawkSearch DashboardHawkSearch User Guide
Guides

For Users

Suggest Edits

Manage indexes

Goal

This article will show you how to create index mapping which can be selected from the Hawksearch widgets.

Prerequisites

Installed Kentico connector

Creating index mappings

  1. Open the application side menu (F2 or button top left), scroll to the bottom and open Custom/Hawksearch.
  2. Select the Indexes category on the left.
  3. Click New index mapping.
  4. For Display Name choose the name you’d like to see in the Hawksearch widgets, e.g. “Main”.
  5. For Hawksearch Name you can either choose an existing index name from Hawksearch or leave it empty. It will be populated and updated whenever this index gets reindexed

Next steps

Kentico: Working with widgets

Event tracking

Goal

This article describes how to configure Event Tracking in the Kentico connector and how it functions.

Prerequisites

Configured connector - Kentico: System Settings Setup

Steps to configure Event Tracking

  1. From the application selector side menu (F2 or button top left) choose the Settings application.
  2. Go to Integration / Hawksearch where you’ll find the settings for the connector.
  3. Find the Tracking url and update it.
  4. Save the changes.
  5. Navigate to a page containing either a Hawksearch search box or a Hawksearch search results widget.
  6. Open the settings for the widget.
  7. Choose which events you’d like to track.
  8. Save the widget.

How it works

Each time one of the Events that you have selected in widget settings occurs, a request is sent to the Hawksearch Tracking API. The request contains information about the event and the visitor that performed the action. This information is then used to populate data in the Hawksearch reports. Furthermore, the Hawksearch Recommendation service also makes use of Event Tracking as it can display personalized content depending on the information gathered from the tracking.

Events Tracking API Integration

File Export overview

Goal

The purpose of this article is to show you how to configure the File Export indexing.

The main purpose of the file export:

Hawksearch can work on the following two environments: Elastic and Lucene. The exporter takes a major role in the second one. Тo index the items that we want the customer to search through, we need first to export in separate files the whole information about these content types and records. This information must then be uploaded and indexed so it can be visible on the page where the Hawksearch search result widget is placed.

Prerequisites

Configured connector

Steps to configure File Export settings

  1. From the application selector side menu (F2 or button top left) choose the Settings application.
  2. Go to Integration / Hawksearch and make sure under Indexing settings the Indexing type is set to File Export.
  3. On the same page you’ll find the File Export settings under the category File Export settings.
  4. Build Landing Pages - Whether landing pages will be built.
  5. Landing Pages Base Path - The base path for landing page urls, added as a prefix to the landing page url while generating landing pages if that feature is enabled.
  6. Output Path - This path is relative to the CMS project folder. This is where the Hawksearch feed files will be generated at, e.g. /HawksearchFeed. Make sure that this folder exists beforehand.
  7. Item types - a semicolon separated list of page / module class code names, used to determine what gets included in the items.txt file.
  8. Attribute types - a semicolon separated list of page / module class code names, used to determine what gets included in the attributes.txt file.
  9. Content types - a semicolon separated list of page / module class code names, used to determine what gets included in the content.txt file.
  10. Hierarchy types - a semicolon separated list of page / module class code names, used to determine what gets included in the hierarchy.txt file.

Creating items.txt mappings

  1. Open the application selector side menu (F2 or top left button) and go to Custom/Hawksearch.
  2. Expand the File Export and go to Items mapping.
  3. Click New item mapping.
  4. Choose the predefined field you want to make a mapping for. Some are optional, some are required for every item. The required ones are: Unique identifier, Name, URL to detail page, Image, Price retail, Price sale. You can also choose Add custom field which lets you define the Hawksearch field name as well.
  5. If you have chosen Url to detail page, you’ll see a checkmark for Use culture prefix which lets you append the culture prefix before the url.
  6. If you have chosen Add custom field, write the name of the field in the Field name text box. This needs to correspond to a field in Hawksearch.
  7. Destination field name - The database column name from which you want to obtain the value for this mapping.
  8. Type name - choose the type predefined in the settings that you want the mapping to be for.
  9. Is required - Is this mapping required. If it's required and it's missing a value from the Destination field name, the whole row will be skipped and not written to the text file.
  10. Click save.

Creating attributes.txt mappings

  1. Open the application selector side menu (F2 or top left button) and go to Custom/Hawksearch.
  2. Expand the File Export and go to Attributes mapping.
  3. Click New attribute mapping.
  4. Choose the Name of the mapping. Both Identifier & Data are required.
  5. Type - choose the type predefined in the settings that you want the mapping to be for.
  6. Use hierarchy map field - If Data is selected as name, this is available. If enabled, it will map the attribute with a hierarchy id field name for the Hawksearch field name.
  7. Hawksearch field name - The name of the field in Hawksearch.
  8. Destination field name - The database column name from which you want to obtain the value for this mapping.
  9. Use custom array data - If checked, the exporter will attempt to get the value from a class that you must have previously defined that inherits BaseInfo in some way (TreeNode for example inherits BaseInfo a few levels down) and implements the interface IHawksearchCustomData located in the namespace Hawksearch.Kentico.Xperience.CMS.Feeds.Contracts.
  10. Is reference field - The value of the field will be split by a semicolon and new attributes will be added for each split subvalue.
  11. Is required - Is this mapping required. If it’s required and it’s missing a value from the Destination field name, the whole row will be skipped and not written to the text file.
  12. Click save.

Creating content.txt mappings

  1. Open the application selector side menu (F2 or top left button) and go to Custom/Hawksearch.
  2. Expand the File Export and go to Content mapping.
  3. Click New content mapping.
  4. Choose the Name of the mapping. Some are optional and some are required. The required ones are: Identifier, Name & Url.
  5. Destination field name - The database column name from which you want to obtain the value for this mapping.
  6. If you have chosen Url, you’ll see a checkmark for Use culture prefix which lets you append the culture prefix before the url.
  7. Type - choose the type predefined in the settings that you want the mapping to be for.
  8. Is required - Is this mapping required. If it’s required and it’s missing a value from the Destination field name, the whole row will be skipped and not written to the text file.
  9. Click save.

Creating hierarchy.txt mappings

  1. Open the application selector side menu (F2 or top left button) and go to Custom/Hawksearch.
  2. Expand the File Export and go to Hierarchy mapping.
  3. Click New hierarchy mapping.
  4. Choose the Name column of the mapping. Some are optional and some are required. The required ones are: ID, Name, Parent ID.
  5. Destination field name - The database column name from which you want to obtain the value for this mapping.
  6. Type - choose the type predefined in the settings that you want the mapping to be for.
  7. Is required - Is this mapping required. If it’s required and it’s missing a value from the Destination field name, the whole row will be skipped and not written to the text file.
  8. Click save.

How to run an Export?

The export is run by the scheduled task that is added for each specific index. Kentico: Creating the Indexing Scheduled task .

Once you have added and configured the scheduled task, it will run automatically on the predefined timing that you have set. If you want to run it manually, find the created task and press the green play button in order to execute it now regardless of its scheduling settings.

After the task finishes, you can find your text files inside the folder that you have specified in the settings.

Indexing API Overview

Goal

The goal of this article is to show how to create field mappings which drive the Indexing Api indexing as well as give you some information on how it works.

Overview

The way the Indexing API indexing works is you define field mappings which contain all the information necessary to map your database information to a Hawksearch index. When you specify which index mapping you want the field to be on, whenever that index gets recreated and rebuilt the Hawksearch Name for it will be updated to match the newly created index.

Prerequisites

Steps to configure Web API settings

  1. From the application selector side menu (F2 or button top left) choose the Settings application.
  2. Go to Integration / Hawksearch and make sure under Indexing settings the Indexing type is set to Indexing API.
  3. On the same page you’ll find the settings for Indexing Api indexing under the category Indexing Api settings.
  4. Base indexing API Url - This is the base Hawksearch indexing API url, e.g. https://indexing-dev.hawksearch.net/api/v2/indexing
  5. Use deferred indexing - Whether deferred indexing will be used or not. Deferred indexing delays the deletion and swapping of the index until after the new index has been created and rebuilt.
  6. Use multisource indexing - Whether multisource indexing will be used or not. Multisource indexing queries a predefined set of data sources to begin indexing alongside the local source. Kentico: Multisource indexing: Setup
  7. Use permission filtering - Whether permission filtering will be used when generating the index and when searching. If enabled, a new field called permissions is added to each document that is made from a page node while indexing. When searching using the widgets, the current authenticated user’s role ids are sent to Hawksearch so only authorized results are brought back. Kentico: Filter by permissions: Setup
  8. Enable index trace logging - Whether trace logging will be enabled for indexing requests. If enabled, a message is logged in the event log for each request and response.
  9. Enable search trace logging - Whether trace logging will be enabled for search requests. If enabled, a message is logged in the event log for each request and response.
  10. Field types - a semicolon separated list of page / module class / custom table code names, used to determine what gets included in the index.

Steps to create a field mapping

  1. From the application selector side menu (F2 or button top left) go to Custom/Hawksearch.
  2. Go to Indexing Api/Field mapping.
  3. Click New field mapping.
  4. Index name - Here you can choose the index previously defined in Kentico: Manage indexes. This is the index on which the field will be created on.
  5. Type codename - Here you can choose the associated Kentico type for which you want this field to be. Previously defined in Kentico: System Settings Setup.
  6. Field type - Here you can choose the type of the field. You can choose between Unique Identifier, Text, Number, Boolean, Date, GeoPoint. Each indexed object needs to have exactly one Unique Identifier.
  7. Hawksearch field - This is the name of the field as seen in Hawksearch. When you write the field name for a Unique Identifier field type, make sure the field type already exists in Hawksearch and is marked as a primary key. By default the Hawksearch field name “id” is set as a primary key.
  8. Source column name - This is the name of the database column from which you want to take the value from. For example if you’re indexing a page type you can write “DocumentID” for the Unique Identifier field. Keep in mind though, if you’re indexing multiple different types of objects (documents, module classes and tables) it’s better to use their respective GUID values instead of the table row ID since there can be overlaps and they need to be unique.
  9. Include in results - This indicates whether the field will be included in result responses from Hawksearch.
  10. JSON Property - For the designated field, if it contains a JSON object, you can pinpoint a specific property. Only valid properties that are one level deep will be stored as a string; otherwise, the entire JSON object will be stored.
  11. Ex: For a field being sent to HawkSearch in the format {“a“ : ”A value”, “b“ : “B value“}, if you specify “a” in the JSON Property Field setting, only the “A value” will be transmitted to HawkSearch for that particular field.
  12. Click save.

How to run an Indexing API reindexing?

The reindexing is run by a scheduled task that is added for each specific index. Learn how to add and configure it here - Kentico: Creating the Indexing Scheduled task .

Once you have added and configured the scheduled task, it will run automatically on the predefined timing that you have set. If you want to run it manually, find the created task and press the green play button in order to execute it now regardless of its scheduling settings.

You will be notified when the indexing has finished in the event log along with any errors that may have occurred.

Multilingual Overview

Goal

This article aims to give an overview of the multilingual indexing functionality, to explain the main specifics and what the benefits of using it are. It will explain when it is appropriate to use this functionality and what is the expected behaviour when using it.

Overview

Multilingual is a feature that Hawksearch provides to make searching and finding information in multilingual environments more convenient and systematic. Most platforms have the option to change the language and translate the articles to reach a larger audience. This is something that also happens with the help of Kentico, where we can translate and develop content in different languages. This has led to the need for the connector to allow its users to filter and group their content according to the languages in which it is created.

Specifics of multilingual functionality

Indexing

Indexing API

When indexing with the multilingual functionality enabled, the connector will add another field to each document called “language” which will include the culture code for that specific document.

File Export

The file export doesn’t perform that conversion out of the box, but you can add an attribute called “language” that gets its value from the “DocumentCulture” column from the database. That information is stored in the CMS_Document database table.

Searching

The results the user sees when the page is loaded are the ones from the Default culture. If English is the default one then loading the page will show results in English. Changing the default language will also change the results that appear when the results page loads.

Which language is selected can be easily distinguished from the page URL. You can see a language query parameter with the currently selected culture code. For example “http://localhost/home?language=en-us“.

📘

Note

We can see which is the default language for our site by going to the “Sites” application and seeing the default culture for your site.

The advantages of multilingual functionality

  • Makes the searching easier
  • Gives another option to filter the results
  • Allows for more accurate targeting. For example, if the results are in German, one type of product should be published as a priority, and those in English as a secondary

Creating the Indexing Scheduled task

Goal

The goal of this article is to show you how to create the scheduled task from the Kentico backend application.

Prerequisites

Created field mappings - Kentico: Indexing API Overview

Steps to creating the scheduled task

  1. From the application selector side menu (F2 or button top left) choose Configuration/Scheduled tasks.
  2. Click New task.
  3. Write your desired display name in Task display name, for example “Hawksearch Indexing”.
  4. In Task provider choose Hawksearch.Kentico.Xperience.CMS for the assembly name.
  5. In Task provider choose Hawksearch.Kentico.Xperience.CMS.Tasks.IndexingTask for the class name.
  6. If you’re using the Indexing API indexing, there is one more thing you need to do. In the Task data field, you have to specify a JSON string which contains the Index display name that you would like to index with this task. It needs to match the display name defined in Kentico: Manage indexes . For example:
{
    "IndexDisplayName" : "Main"
}
  1. Choose your desired runtime frequency parameters, for example once per day.
  2. Click save.

Working with Widget

Configuring Hawksearch search box widget

Goal

The purpose of this article is to show you how to work with the Hawksearch search box widget.

Prerequisites

Steps to configure the widget

  1. Once you have set up a page builder supported page, click add widget and click Hawksearch search box.
  2. Hover over the widget and click the settings cogwheel to bring up the widget properties.
  3. Template - You can choose which widget template this widget uses.
  4. Index - You can choose which index this search box widget will use from the dropdown menu. Here you can see the previously created index mapping display names.
  5. Use permission filtering - Whether the widget uses permission filtering. If enabled, the widget will add the current user’s role ids to be checked against the permissions field on the previously indexed documents when sending autocomplete requests.
  6. Search page - Via the page selector, navigate to the page you wish to be redirected to when you search. If left empty, the search box will use the same page to display the search results (if the Hawksearch search results widget is also present on the page).
  7. Track search event - If selected, widget will send search event tracking updates to Hawksearch.
  8. Track autocomplete click event - If selected, widget will send autocomplete click event tracking updates to Hawksearch.

Configuring Hawksearch search results widget

Goal

This article will show you how to work with the Hawsearch search results widget.

Prerequisites

  • Configured Kentico connector - Kentico: System Settings Setup
  • Created Index mappings - Kentico: Manage indexes
  • Enabled page builder functionality - Page builder development | Xperience 13 Documentation

Steps to configure the widget

  1. Once you have set up a page builder supported page, click add widget and click Hawksearch search results.
  2. Hover over the widget and click the settings cogwheel to bring up the widget properties.
  3. Template - You can choose which widget template this widget uses.
  4. Index - You can choose which index this results widget will use from the dropdown menu. Here you can see the previously created index mapping names.
  5. Use permission filtering - Whether the widget uses permission filtering. If enabled, the widget will add the currently authenticated user’s role ids to be checked against the permissions field on the previously indexed documents when sending search requests.
  6. Track click event - If selected, widget will send click event tracking updates to Hawksearch.
  7. Track recommendation click event - If selected, widget will send recommendation click event tracking updates to Hawksearch.
  8. Track page load event - If selected, widget will send page load event tracking updates to Hawksearch.
  9. Track banner click event - If selected, widget will send banner click event tracking updates to Hawksearch.
  10. Track banner impression event - If selected, widget will send banner impression event tracking updates to Hawksearch.
  11. Data - This field is used to send additional parameters to Hawksearch in a JSON format. Example further below.

Associate with Landing Page

📘

Note

You can filter the search results elevating Hawksearch Landing page functionality.

You can find more information about setting Landing Pages in Hawksearch documentation - Landing Pages

  1. Configure Landing Page for the corresponding Hawksearch instance.
  2. Navigate to a Kentico page that has a placed ‘Hawksearch search results’ widget.
  3. Hover over the widget and click the settings cogwheel to bring up the widget properties.
  4. In the Data field enter the Url of your Landing Page in the following format: 
    {"CustomUrl":"landing-page-url"}
  5. Click Save.

Updated over 1 year ago