Troubleshooting Lucene Knowledgebase

Version 6

    Verified Product Versions

    Service Desk 7.7.xService Desk 2017.x


    This guide was written for version 7.3.1 of Service Desk but many points also apply to later versions.  We have marked differences when they are spotted.

    The Architecture:

    Lucene is a knowledge indexing system used exclusively in Web Desk (version 7.3).  The index data can be stored wherever the User requires it.  By default it is in the same location as the tps.config of the Touchpaper Framework that the Background Processing service logs in to.  Unlike Verity, Lucene knowledge builds are managed by the Background Processing service.  In version 7.3 Lucene knowledge can only be searched in Web Desk, Verity is still used for Console and Service Portal.  Lucene and Verity should always return the same result for any given search String. 

    The Lucene data is stored in a folder called ‘index’.  This folder should contain one file called ‘segments’ and then a number of other files, mainly consisting of ‘.cfs’ extensions. 

    When a data change occurs or a full knowledge rebuild is requested a new queue entry is created.  This is stored in the table ‘km_knowledge_message’.  There is a new Boolean column on the table called ‘km_search_engine’ which determines whether the Background Processing service should trigger a Lucene update or not. 

    It is assumed you have read Configuring Lucene for WebDesk knowledge searching (version 7.3.2 and lower) before continuing.


    1)      Decide where you want your Lucene index to go.  Having decided that you will need to ensure that the path to your required location is specified in the tps.config for both the TPS that Background Processing logs in to and Web Desk. The key to update is called “FreeTextSearchIndexPath”.  The tps.config to edit is located at C:\Documents and Settings\All Users\Application Data\Touchpaper\WebDesk.

    2)      Ensure that all your tps.configs have the key “KnowledgeSearchEngine” with a value of “Verity, Lucene” unless there is a particular reason why you want some Users to not trigger knowledge updates for one of those.  NOTE: From 7.3.2 Lucene is the only search engine so this key is no longer required.

    3)      Ensure that for Console installations where a full knowledge rebuild could be triggered the console.exe.config file also has the above value for the ‘KnowledgeSearchEngine’ key. If the Console is running on a 64 bit system the consolex64.exe.config needs to be updated with the above value.

    4)      Ensure that both Background Processing (Lucene) and Knowledge Builder (Verity) services are running without errors.  NOTE: From 7.3.2 Lucene is the only search engine so the Knowledge Builder service is no longer required.


    That’s it!  There really isn’t anything else that needs to be done to ensure smooth running of your Lucene knowledge index.


    If Lucene doesn’t seem to be behaving still then there is some troubleshooting that can be done. 


    1)      Do all your tps.configs (particularly the one Background Processing logs in to) contain the correct key for which search engine’s to use? – see point 2 above.

    2)      Has the index folder been created in the location specified in the tps.config that Background Processing logs in to (see point 1 above)?  If not there’s probably a problem with Background Services.  See step 6.

    3)      Is there more than one ‘segments’ file in your system?  If so then you’ve got your tps.configs pointing at different locations.  Delete the unwanted index folders and ensure all your tps.configs point to the same location for free text searching. 

    4)      Does the index file contain one or more *.cfs files?  If so then it is (or has been) building something. 

    5)      Are updates to Lucence being generated?  If you stop Background Processing and Knowledge Builder services then trigger a full rebuild or make a data change you should see two rows entered in the km_knowledge_message table.  One of them will have a km_search_engine value of 0 which means it will be processed by Knowledge Builder, the other will have a value of 1 which means that Background Processing service will read it.  If you don’t get both rows then revisit steps 1 and 2 above as the configuration files aren’t quite right.

    6)      Is Background Processing running without errors?  The event log will have details of any Problems that Background Processing is encountering.  These may be stopping it from carrying out all its normal tasks and therefore Lucene isn’t getting updated.  Further Background Processing debugging can be done by turning on TPS Diagnostic logging with a value of BackgroundProcessing.  See the TPS Diagnostic Logging manual for more information.

    7)      If you have got to this point you should be sure that Lucene is being updated by Background Services when new data is to be indexed/re-indexed and that the tps.config files are all pointing at the right place.  There is a further TPS logging that can be carried out, FreeTextSearch – see the TPS Diagnostic Logging manual for more information about turning this on.

    Please Note: Active Knowledge functionality is not included in Web Desk searching in 7.3