Overview

If you’ve ever updated or changed the index profile in ESP, you are very familiar with the Matching Engines page in the ESP Admin GUI which allows you to upload a new index profile.

Uploading a new index profile using this page is very easy but this method of uploading an index profile is not very practical in everyday scenarios. If your index profile has very minor changes which do not conflict with the current index profile configuration, then this is a quick and easy way to upload the new index profile. However, in my experience, most changes to an index profile will result is some sort of conflict with the existing configuration which necessitates having better control of the index profile upload process than what is provided by the Admin GUI. In my opinion, there is a better way to upload a new index profile in FAST ESP.

The bliss command line utility

FAST ESP comes with a rich set of command line tools. I prefer to use the command line tools most of time because it gives me better control of the operational tasks in ESP. One such tool is the bliss program which allows you to upload a new index profile. Bliss performs the same tasks as the “Upload new index profile” functionality on the Matching Engines page in the ESP Admin GUI. However, the Admin GUI performs all the steps behind the scenes without giving you a lot of control in managing the process of changing the index profile. If something in your new index profile is going to cause an issue, you won’t know till the GUI attempts to upload the index profile. For example, if the XML in your new index profile is malformed or doesn’t match the index profile DTD, you’d want to know this before you attempt to upload the new index profile. Likewise, if your index profile changes would result in a cold update, you’d want to know this before you attempted to upload it. Another advantage to using bliss instead of the Admin GUI is that the deployment to other ESP webclusters (environments) can be scripted without having someone go through the GUI on each of these environments. This makes deploying an index profile from your development environment to your QA, pre-production, and production environments much easier.
NOTE: This blog post is written for a Windows Server environment. Therefore, any path or environment variable referenced here is Windows specific. However, the bliss commands work exactly the same way in UnixLinux as they do in Windows.
Before we get into bliss, I want to go over some prerequisites.

• All ESP components must be running, including the admin server and QRServer(s)
• You will have to be logged into the ESP admin server
• The new index profile file must be copied into the %FASTSEARCH%index-profile directory. This is important because one of the steps we are going to perform with bliss is the validation of the index profile. The validation step will use the index profile DTD file that’s present in the %FASTSEARCH%index-profile directory and therefore expects the index profile file to be in the same directory.
• An index profile file with the current index profile configuration must be present in the %FASTSEARCH%index-profile directory. If you don’t have this file, you can create one by clicking on the link on the ESP Admin GUI’s Matching Engine page. Once you are viewing the current index profile in the browser, copy the XML text into a text file and save it to the %FASTSEARCH%index-profile directory. As a best practice, I always keep a copy of the current index profile in the %FASTSEARCH%index-profile directory in a file named current-index-profile.xml.

The Process

The IT Leader's Guide to Multicloud Readiness

This guide provides practical key insights and important factors to consider to make informed decisions in your multicloud journey.

Download the Guide

The steps outlined below using bliss are recommended as a best practice for uploading a new index profile. The entire process will be performed from the command prompt.

1. Open a Command Prompt window.
2. Change the active directory to the %FASTSEARCH%index-profile directory. By default the %FASTSEARCH% environment variable references the esp directory. On my system, %FASTSEARCH% points to C:esp
3. Use bliss with the -V (uppercase V) option to validate the new index profile file. The bliss command syntax is as follows: bliss -V <new index profile file>

   Example: bliss -V rem-index-profile.xml

   In the example below, I set up my index profile file to fail the validation step so that the validation message would be displayed. I set up one of my fields with an incorrect attribute of indexing instead of index which will fail the validation. Before my second validation attempt, I edited the file and changed the attribute to index so that the index profile would pass validation.

   

4. Check if the new index profile is compatible with the current index profile. This step will let you know if the new index profile configuration has conflicts with the currently deployed index profile as well as if the new index profile will result in a cold update. In order to do the compatibility test, we need to have a copy of the currently deployed index profile. We will be using bliss with the -c (lowercase C) option to perform the compatibility check. The command syntax is as follows: bliss -c <new index profile file> <current index profile file>

   Example: bliss -c rem-index-profile.xml current-index-profile.xml

   The example below shows the results of a compatibility check when the new index profile is compatible with the current index profile.

   

   In the example below, I set up my index profile to be incompatible with current index profile in order to capture an example of the messages from bliss listing the incompatibilities which will require a cold update. In this particular example, I changed a field’s index attribute from its current setting of index=”no” to index=”yes”.

   

   ESP has 2 types of index profile updates: cold and hot. A cold update will require the removal of all the documents in the index and the re-feeding of all the content. A hot update will not require an index purge and document re-feeding. Most index profile changes will result in a cold update. The ESP Configuration Guide provides a list of changes that can be applied as a hot update in the Index Profile Features section of the document. The hot update list is rather short. Any change that’s not in the hot update list is considered a cold update change.

   The compatibility check is really useful during the development stage of a project and helps the project planning process. It gives you an idea of whether the changes to the index profile will require a cold update and a full reload of the content. You can then use this information to notify the project team, QA, configuration management, the application stakeholders, and anyone else in your organization about the index profile changes requiring a cold update. This gives everyone involved time to plan for such an event. In many organizations, a cold update will require significant down time for the FAST servers which will likely have a pretty large impact to the availability of the application(s) that utilize FAST. In my experience, modifications of the index profile are usually requested by people who are not involved with ESP on a regular basis and they often (by no fault of their own) don’t understand the impact that the change has to the FAST environment. The compatibility check is a way for you to inform the requestor of the impact to FAST so that they can make a decision on whether to go through with the change.

5. Once you are satisfied that your new index profile is correct and it’s time to upload the new index profile, use bliss with the -C -i option (uppercase C followed by a lowercase i). The -i option instructs bliss to ignore any compatibility issues and upload the index profile. If the -i option is left out, the upload will not occur because bliss will complain about the compatibility issues. The command syntax is as follows: bliss –C -i <new index profile file>

   Example: bliss -C -i rem-index-profile.xml

   

   As a good practice, once my new index profile has been uploaded, I copy the new index profile file to a file named current-index-profile.xml in the FASTSEARCH%index-profile directory. This allows me to use this file for compatibility checks against the next change to the index profile.

6. Once the index profile has been successfully uploaded, it’s a good practice to refresh and redeploy the search views. This can be accomplished by using the view-admin command. Execute the following commands in the Command Prompt window.

   view-admin –m refresh

   view-admin –m deploy –a

Summary

Using bliss to upload a new index profile is simple and easy. You could certainly upload the index profile using the ESP Admin GUI but you lose the control and flexibility that bliss provides. Using bliss gives you the flexibility to go through the individual steps of validation, compatibility check, and upload process and react to possible issues at each of the steps. The ESP Admin GUI performs the upload as a single process without giving you the opportunity to deal with potential issues at each of the steps. Bliss also allows you to deploy the index profile to other ESP webclusters without the need to go through the ESP Admin GUI.
If you have any questions regarding this blog post, please feel free to email me at rem@pointbridge.com. I welcome feedback on this content and also greatly appreciate suggestions for grammatical and/or spelling errors.