Index

Introduction to the index in ConSol CM

ConSol CM stores most of its data in a relational database. In order to improve the performance of search operations, Apache Lucene indexes are used. For each data field that should serve as search criterion, an index is created. The indexes are stored on the file system, in a subdirectory of the data directory.

Concepts, terms and definitions

Concept	Other terms	Definition
indexer		ConSol CM component for index management
quick search		Simple free-text search using a search field in the upper right corner of the Web Client
detailed search		Advanced search on a specific page which allows combining several search criteria
autocomplete search		Context-dependent free-text search integrated into specific pages

Purpose and usage

The index is required to be able to search for objects in ConSol CM. The scope of the index is the entire ticket text, the attachments (can be configured in the system property cmas-core-index-common, index.attachment) and the data fields which are annotated with field-indexed. The data fields configured for the index are available as search criteria in the detailed search, and they can trigger an autocomplete search on customer and resource pages. The quick search shows the objects which contain the search term in an indexed field.

Available settings for the index

The configuration of the index is done in a number of different places. The items described in the following sections need to be configured for the index to work correctly. In addition, you can fine-tune the indexer in the system properties, see Fine-tuning the indexer.

Data directory

The indexes are stored in the file system, in a subdirectory of the data directory indicated during system setup. The path of the data directory is stored in the system property cmas-core-shared, data.directory.

The following requirements need to be fulfilled for the index to work correctly:

• The data directory is always available for the ConSol CM server, also if it was created on another server and is linked to or mounted on the application server.
• The data directory provides enough space for storing indexes.

Annotations

The data fields which should be available as search criteria need to be specified by assigning the annotation field-indexed to the respective field. This is done in the data field administration fo the Admin Tool.

Update mode

There are two kinds of changes which require index updates:

• Operative changes: Changes to tickets, customers, resources and engineers
• Administrative changes: Changes to the configuration

Operative changes are always processed directly. For the processing of administrative changes, there are two modes:

• Directly start processing: Administrative changes are processed directly. Deactivate the checkbox No automatic commit of administrative changes.
• Start processing manually: Administrative changes are processed when the user clicks the Commit administrative changes button on the Index page. Select the checkbox No automatic commit of administrative changes.

Direct processing of administrative changes can have a negative impact on the indexer performance if there are changes which require reindexing lots of objects, e.g. if a data field used in all tickets is added to the index.

See Technical background of the index for further details.

Advanced tasks

Fine-tuning the indexer

The behavior of the indexer can be fine-tuned using system properties. The relevant properties are located in the module cmas-core-index-common. These properties allow to adjust parameters to improve the indexer performance, e.g. the number of threads, or whether attachments should be indexed or not. The most important indexer properties are described in Indexer and Search Configuration.

Technical background of the index

Which changes require index updates?

There are two kind of changes relevant for the index:

• Operative changes

  These are changes to the runtime data:

  • Data field values: values of fields (ticket, customer and resource fields) which are configured for indexing using the field-indexed annotation
  • Engineer data: email, first name, last name
  • Ticket data: attachments (unless configured otherwise), creation date, assigned engineer, history, name, queue, additional engineers, subject, view

  The index is automatically updated when these changes are carried out.

• Administrative changes

  These are changes of certain configuration data:

  • scopes
  • queues
  • enum values
  • engineer functions
  • supported locales
  • roles
  • field-indexed annotation of ticket, customer or resource fields

  The processing of administrative changes depends on the setting No automatic commit of administrative changes:

  • If the checkbox is selected, the changes are processed automatically.
  • If the checkbox is not selected, the changes are stored in the database for deferred processing. Processing can be started by clicking the Commit administrative changes button.

How are index updates processed?

Two services are involved in index updates:

• Index changes notifier:
  Stores the entities which require an index update in the cmas_index_update_serialized table.

• Index changes receiver:
  Polls the cmas_index_update_serialized table for new entries and creates index tasks in the tables cmas_index_update_task and cmas_index_update_part. Administrative tasks are directly created in the database table cmas_index_administrative_task. The indexing server then executes the tasks from these tables and updates the Lucene files accordingly. If the execution of an update task fails, a new update task with the type Retry task is created and the index status is set to YELLOW. You need to execute the task by clicking the Repair index button in the Admin Tool.

  On clustered systems, the index is built on the master indexing server. The slave indexing servers download the index files from the master indexing server.

Do not stop the Index changes notifier service. If it is stopped and there is a change which requires an index update, the index status is set to RED and a rebuild is necessary. You can stop the Index changes receiver. After restart it will pick up all the missing changes from the respective table