Deploying highlight queries

New, production deployments of i2 Analyze have a set of automatically generated highlight queries that retrieve records with simple relationships to a subject record. To replace this set with custom queries that reflect the structure of your data and the needs of your users, you must write your own highlight queries configuration file.

Before you begin

The highlight queries configuration is one of a group of configuration files that you can modify and send to the i2 Analyze server without the need for system downtime. These files are stored in the toolkit\configuration\live directory. The default highlight-queries-configuration.xml file instructs the server to generate the automatic highlight query set.

To enable updating the server without the need to restart it, ensure that you have a command-line tool such as postman or curl.

About this task

The procedure for writing a new highlight queries configuration file starts with a download of two files from the server. Through a pair of REST endpoints, you can retrieve an XML file that defines the same set of highlight queries that the server generated automatically, and an XSD file that validates it. With these files as a guide, you can develop your own highlight queries, replace the default file, and upload it to the i2 Analyze server.

Highlight queries are closely aligned with the Information Store schema. You create and edit the highlight queries configuration file in your configuration development environment, alongside Visual Queries and search results filters.

Note: As described in Example highlight queries, example deployments of i2 Analyze receive an example set of highlight queries instead of the automatically generated set. To replace the example set with an automatically generated set, replace the highlight queries configuration file in toolkit\configuration\live with its equivalent from a configuration\live directory under the toolkit\examples directory. Then, pick up the procedure below at Update the deployment with your changes.

Procedure

The first part of the process is to fetch the XSD file that corresponds to the Information Store schema from the server.

Open a web browser and connect to the i2 Analyze server at http://<host_name>/opal/doc to view the REST API documentation.
If you are not logged in to the server, you are prompted to do so. The user must be a member of a group that has the i2:Administrator permission under command access control.
Note: This requirement is in addition to the other requirements on i2 Analyze users, all of whom must be members of groups that confer an access level for at least one dimension value in each security dimension.
Navigate to the GET /api/v1/admin/highlightqueryconfig/xsd method, and click TRY to request the XSD file from the server.
The file is displayed in the RESPONSE field.
Save the contents of the field to a file named highlight-queries-configuration.xsd in the toolkit\configuration\live directory.

Next, you need a highlight queries configuration file to edit. To start from scratch, you can use the highlight-queries-configuration.xml file from the live directory. Alternatively, you can download the file that defines the automatically generated highlight queries.

Navigate to the GET /api/v1/admin/highlightqueryconfig/automatic method, and click TRY to request the XML file from the server.
The file is displayed in the RESPONSE field.
Save the contents of the field to a file named highlight-queries-configuration.xml in the toolkit\configuration\live directory, replacing the existing file.

Now, edit the configuration file.

If you do not already have one, obtain and configure an XSD-aware XML editor, as described in Setting up your XSD-aware XML editor.
In the XML editor, open the toolkit\configuration\live\highlight-queries-configuration.xml file.
Using the reference and example information, modify the file to define the highlight queries that your users require.

Update the deployment with your changes. The following method deploys your changes without stopping the server by using a POST request to a REST endpoint.

Note: To redeploy your changes by using the deployment toolkit only, see Redeploying Liberty. You must use the deployment toolkit if you are in a deployment with high availability or you are deploying in your production environment.

At the command line, navigate to the toolkit\scripts directory.
Update the server with your configuration file:
```
setup -t updateLiveConfiguration
```
Update the running application by using the reload endpoint:
```
curl -i --cookie-jar cookie.txt -d j_username=<user_name>
                                -d j_password=<password>
                                http://<host_name>/<context_root>/j_security_check

curl -i --cookie cookie.txt -X
    POST http://<host_name>/<context_root>/api/v1/admin/config/reload
```
Warning: The reload method updates the configuration without requiring a server restart, but any logged-in users are logged out from i2 Analyze when you run it.
The server validates your highlight queries as it loads them and returns any errors in its response.
If the configuration is invalid, modify the highlight-queries-configuration.xml file, and then repeat the process to update the deployment.

Test the new and updated highlight queries.

In your web browser, view the highlight panes for a record with a number of connections that test your highlight queries.