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.
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.
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.
- 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:Administratorpermission 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.
- Open the section for the
GET v1/admin/highlightqueryconfig/xsdmethod, and click Try it out! to request the XSD file from the server.The file is displayed in the Response Body field.
- Save the contents of the field to a file named highlight-queries-configuration.xsd in the toolkit\configuration\live directory.
- Open the section for the
GET v1/admin/highlightqueryconfig/automaticmethod, and click Try it out! to request the XML file from the server.The file is displayed in the Response Body 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.
- 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 analysts require.
The following method deploys your changes without stopping the server by using a POST request to a REST endpoint.
To redeploy your changes by using the deployment toolkit only, see Redeploying Liberty. You must deploy your changes by using 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/reloadWarning: TheThe server validates your highlight queries as it loads them and returns any errors in its response.
reloadmethod updates the configuration without requiring a server restart, but any logged-in users are logged out from i2 Analyze when you run it.
- If the configuration is invalid, modify the highlight-queries-configuration.xml file, and then repeat the process to update the deployment.
- In your web browser, view the highlight panes for a record with a number of connections that test your highlight queries.