Summary: This page explains how to manage the Search indexes used in the Engineering Dashboard.

Introduction

The CAST Engineering Dashboard has two search options available for use:

Basic search, providing search on items in the Assessment Model (i.e. rules) and on object names. Results are dependent on the location the search is made.
Advanced search, providing search for objects based on a list of violations. Results are not location dependent.

Each search option is governed by a separate index which produces the results. An explanation of the indexes for each search option is provided below.

Basic Search

The Basic Search feature in the Engineering Dashboard uses the open source Lucene search software. Lucene relies on the existence of an index which is generated automatically when the application server is started.

Where is the index located?

The Lucene search index is generated automatically in the following location on disk - the folder and its contents will not exist until the web application server is started for the first time:

WAR 1.x / 2.x
CATALINA_HOME\webapps\<dashboard>\indexesDirectory

ZIP ≥ 2.x
<unpacked_zip>\configurations\indexesDirectory

What governs whether the search index is generated?

By default the Engineering Dashboard is set to automatically generate the search index every time the web application server is started. This is governed by the rebuildComponentsSearchIndexesOnStart setting in the following file:

WAR 1.x
CATALINA_HOME\webapps\CAST-Engineering\WEB-INF\web.xml

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties

ZIP ≥ 2.x
<unpacked_zip>\configurations\application.properties

The setting is set to true by default:

web.xml

<context-param>
	<param-name>rebuildComponentsSearchIndexesOnStart</param-name>
	<param-value>true</param-value>
</context-param>

application.properties

# Rebuild Lucene components index on start if outdated (true or false)
rebuildComponentsSearchIndexesOnStart=true

How to disable the automatic search index generation

To disable the automatic search index generation, edit the following file:

WAR 1.x
CATALINA_HOME\webapps\CAST-Engineering\WEB-INF\web.xml

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties

ZIP ≥ 2.x
<unpacked_zip>\configurations\application.properties

Change the setting from true to false:

web.xml

<context-param>
	<param-name>rebuildComponentsSearchIndexesOnStart</param-name>
	<param-value>false</param-value>
</context-param>

application.properties

# Rebuild Lucene components index on start if outdated (true or false)
rebuildComponentsSearchIndexesOnStart=false

Following any changes you make, save the file and then restart your application server so that the changes are taken into account. The index will no longer be generated when the web application is started.

How to manually generate the search index

If you have chosen not to have the search index generated automatically when the web application is started, or you want to update the search index without stopping the Engineering Dashboard, you can do so as follows:

all methods described below require the ADMIN role - see User authentication.
the index will only be updated if the data in it is not up-to-date (e.g. a new snapshot has been computed since the last index build)

RestAPI PUT request

Use the RestAPI client:

WAR 1.x / 2.x
http://<server>:<port>/<dashboard>/static/default.html

ZIP 2.x
http://<server>:<port>/static/default.html

You can run the following PUT request to update the index, where My_Domain is equal to the domain you have defined when installing and configuring the Engineering Dashboard - in most circumstances the domain will be "AED" or "AED1":

My_Domain/components-index

Using the Diagnostic page

Browse to following location:

WAR 1.x / 2.x
http://<server>:<port>/<dashboard>/static/diagnostic.html

ZIP 2.x
http://<server>:<port>/static/diagnostic.html

Click the Create/Update Index button for the Components index status option (click to enlarge) - If the button is greyed out, then the index is already up-to-date:

CAST Dashboards > Managing the Engineering Dashboard search indexes > update_index.jpg

Advanced search

Enabling the Advanced Search feature

"Out of the box", the Advanced Search feature is not enabled and the following message will be displayed:

CAST Dashboards > Managing the Engineering Dashboard search indexes > message.jpg

This indicates that a "violations index" (on which the feature relies) has not yet been generated. To generate the index the following methods are available:

Note that following the generation of a new snapshot, the violations index status will change to toUpdate, therefore CAST recommends regenerating the index to take into account the data available in the new snapshot.

Using the "Diagnostic" GUI

This method requires that the user has the ADMIN role.

Use the following URL to access the Diagnostic page:

WAR 1.x / 2.x
http://<server>:<port>/<dashboard>/static/diagnostic.html

ZIP 2.x
http://<server>:<port>/static/diagnostic.html

This provides an indication of the violations index status based on the "domain":

N/A - the domain is mapped to a Measurement Service schema or the Dashboard Service schema was installed with CAST AIP < 8.3.3)
toCreate - no index has ever been created for this domain
toUpdate - an index exists for this domain, but it is outdated because a new snapshot has been computed since the index creation
upToDate - an index exists and is up-to-date. When this status is shown, the index for the Advanced Search feature is ready and available.

In the following example the index has never been generated since the status is set to "toCreate":

Click to enlarge

CAST Dashboards > Managing the Engineering Dashboard search indexes > index_status1.jpg

To generate the index, click the Create/Update Index button. During generation the status "Indexing" will be displayed and on completion, the status will change to "upToDate":

Click to enlarge

Using the RestAPI

This method requires that the user has the ADMIN role.

Use the RestAPI client:

WAR 1.x / 2.x
http://<server>:<port>/<dashboard>/static/default.html

ZIP 2.x
http://<server>:<port>/static/default.html

Using the following URI with a PUT will generate the index (where <domain> is more than likely set to AED, unless you have custom domains):

<domain>/violations-index

Then use the same URI with a GET will show the index status:

CAST Dashboards > Managing the Engineering Dashboard search indexes > index_status3.jpg

Generating the index when the web application starts

This method will force the violations index to be generated if its status is toUpdate (i.e. the index exists but is out-of-date because a new snapshot has been computed since the index creation) every time the web application is started.

CAST only recommends using this option if your Dashboard Service schema is small - since the index is generated during web application startup, this can impact performance.

Edit the following file with a text editor:

WAR 1.x
CATALINA_HOME\webapps\CAST-Engineering\WEB-INF\web.xml

WAR ≥ 2.x
CATALINA_HOME\webapps\<dashboard>\WEB-INF\classes\application.properties

ZIP ≥ 2.x
<unpacked_zip>\configurations\application.properties

Set the following configuration to true:

web.xml

<context-param>
<param-name>rebuildViolationsSearchIndexesOnStart</param-name>
<param-value>false</param-value>
</context-param>

application.properties

# Rebuild Lucene components index on start if outdated (true or false)
rebuildViolationsSearchIndexesOnStart=false

Save the file. Next time the web application is started the index will be generated.

Using custom batch files

This method requires that the user has the ADMIN role.

This method is to be used when you have a configuration in the domains.properties file - i.e. multiple "domains". The custom batch will generate the violations index for all the domains configured in the domains.properties file. Create the following batch files in the CATALINA_HOME\webapps\<dashboard>\WEB-INF (WAR file deployment) folder or the <unpacked_zip> (ZIP file deployment) folder and then run the launch.bat file to start the index generation:

@echo off
@echo Computing Violations Indexes ...

util.bat > util.log
@echo --------------------------------

@echo off
setlocal enableDelayedExpansion
@echo Automated Violations Indexes Creation
@echo -------------------------------------
 
for /F "delims== eol=#" %%D in (domains.properties) do (
	@echo Process %%D/violations-index
	start /B util2.bat %%D
	@echo.
)

In the following file (util2.bat), you need to modify the line starting curl to match your environment:

Replace user:pwd with a user that has the ADMIN role and their password.
Replace http://localhost:8080/CAST-Health-Engineering/rest/%domain%/violations-index with the URL to your dashboard.

@echo off
prompt $_
setlocal enableDelayedExpansion
set "domain=%~1"
 
@echo Start  %domain% !DATE!_!TIME!
curl -s -u user:pwd -X PUT http://localhost:8080/CAST-Health-Engineering/rest/%domain%/violations-index
@echo  is the response from %domain%
@echo Finish %domain% !DATE!_!TIME!