Updating the system match rules

This section describes an example of the process to update the system match rules of a deployment with the Information Store. Updating your match rules in your deployment includes the following high-level steps after you modify your system match rules file:

  • Removing the Liberty containers
  • Update the match rules file
  • Rebuilding the configured Liberty image with the modified match rules file
  • Running the Liberty containers
  • Upload the updated system match rules file to ZooKeeper
  • Create a standby match index with the new system match rules, and wait for a response from the server to say that the standby match index is ready
  • Switch your standby match index to live

The examples/pre-prod/walkthroughs/change-management/updateMatchRulesWalkthrough.sh script is a worked example that demonstrates how to update the system match rules in a containerized environment.

Note: Before you complete this walkthrough, reset your environment to the base configuration. For more information, see Resetting your environment.

Removing the Liberty containers

Before you update the match rules file, you remove the Liberty containers. To remove the containers, run the following docker commands:

docker stop liberty1 liberty2
docker rm liberty1 liberty2

See the Removing the Liberty containers section of the walkthrough script.

Updating your system match rules file

In the updateMatchRulesWalkthrough.sh script, the modified system-match-rules.xml is copied from the examples/pre-prod/walkthroughs/configuration-changes directory to the configuration/live/ directory. See the Updating system-match-rules.xml section of the walkthrough script.

For more information about modifying the system match rules file, see Deploying system match rules.

After you modify the match rules file, build a new configured liberty image with the updated match rules file.

The build_liberty_configured_image_for_pre_prod server function builds the configured Liberty image. For more information, see Building a configured Liberty image.

Running the Liberty containers

The run_liberty server function runs a Liberty container. For more information about running a Liberty container, see Liberty.
See the Running the Liberty containers section of the walkthrough script.

Note: You must run both Liberty containers.

The wait_for_i2_analyze_service_to_be_live common function ensures that Liberty is running.

Uploading system match rules to ZooKeeper

After you modify the system match rules file, use the update_match_rules function of the runIndexCommand.sh script to upload the match rules to ZooKeeper. For more information, see Manage Solr indexes tool.

The runIndexCommand function with the update_match_rules argument in the updateMatchRulesWalkthrough.sh script contains the docker run command that uses an ephemeral Solr client container to upload the match rules.

To use the tool in a Docker environment, the following prerequisites must be present:

  • The Docker toolkit and your configuration must be available in the container.

    • In the example, the toolkit and configuration are volume mounted in the docker run command. For example:

            -v "pre-reqs/i2analyze/toolkit:/opt/toolkit" \
      -v "examples/pre-prod/configuration:/opt/"

  • Environment variables

    • The tool requires a number of environment variables to be set. For the list of environment variables that you can set, see Manage Solr indexes tool.

  • Java

    • The container must be able to run Java executables. In the example, the container uses the eclipse-temurin image from DockerHub.

        eclipse-temurin:11-ubi9-minimal

Checking the standby match index status

When uploading match rules, the runIndexCommand.sh will wait for 5 minutes for a response from the server. If however, it takes longer to create the new match index a curl command can be run against liberty.

The wait_for_indexes_to_be_built client function makes a request to the api/v1/admin/indexes/status endpoint and inspects the JSON response to see if the match index is built.

Switching the standby match index to live

After the standby index is ready, you can switch the standby index to live for resolving matches. Use the switch_standby_match_index_to_live function of the runIndexCommand.sh script to switch the indexes.

The runIndexCommand function with the switch_standby_match_index_to_live argument in the updateMatchRulesWalkthrough.sh script contains the docker run command that uses an ephemeral Solr client container to switch the match indexes.

The tool outputs a message when the action is completed successfully and exit code 0 is returned. For example:

> INFO  [IndexControlHelper] - The server processed the command successfully:
> Switched the live Match index from 'match_index1' to 'match_index2'.

If there are any errors, the error is displayed in the console.