HCL Commerce Version 9.1.10.0 or later

Migrating Query service customizations

If you have reviewed the recent release changes made to the Query service as described in Keeping Elasticsearch-based search up-to-date, you can proceed to migrate your customizations. Use the following guide.

Search profiles

Custom search profiles with the same profileName have higher priority than the default profiles. Therefore, custom profiles are loaded first if found in ZooKeeper, otherwise the default Query service profiles are loaded. This is to provide overriding functionality of search profiles.

The default profiles are present at below location inside query-service container: /opt/WebSphere/Liberty/usr/servers/default/apps/search-query.ear/search-query.war/WEB-INF/classes/profiles

To provide the functionality of inheritance with search profiles, the profile defined against attribute parentProfileName is pulled and its fields are merged with the current profile. While pulling the parent profile, the ZooKeeper priority rule mentioned above still applies.

For more information, see Setting up your custom search profile.

Configurations

The structure (format/notation) of the Color Matchmaker configuration has changed in HCL Commerce Version 9.1.7.0. However, the structure for all other configuration endpoint nodes (component, uoms, filter, etc.) remains the same. If you have added custom configurations to the colors configuration node, use the following steps to backup and merge custom changes and reapply these configurations:
  1. To backup the colors configuration before migration, use the Query service data-query API configuration endpoint for the colors node.
    GET http://QUERY_HOSTNAME:
                  QUERY_PORT/api/v2/configuration?nodeName=colors&envType=auth&locale=en_US 

    You can save the response of this GET call as colors_v916.json.

  2. After migration, use the same Query service data-query API configuration endpoint for the colors node to get the latest colors configuration.
    GET http://QUERY_HOSTNAME:
                  QUERY_PORT/api/v2/configuration?nodeName=colors&envType=auth&locale=en_US 

    You can save the response of this GET call as colors_v918.json.

  3. Compare both the JSONs to manually merge the changes. Apply it back using the PATCH method on the data-query API configuration endpoint for the colors node, providing the final merged JSON in the body.
    PATCH http://QUERY_HOSTNAME:
                  QUERY_PORT/api/v2/configuration?nodeName=colors&envType=auth&locale=en_US 
  4. Restart query-service container.
Note: The 9.1.6 version of the colors configuration will be in the format of "light salmon": "red_255", which provided the most significant value of the RGB spectrum. In 9.1.7, the format/notation has changed to "light salmon": "[[red],[255,160,122]]" to provide the complete RGB spectrum value to improve color matching accuracy. Therefore, when merging custom colors configuration changes, the complete RGB triad spectrum values must be supplied.
For more information, see Query service configuration
Note: When migrating from 9.1.8 to higher versions, import/export endpoints can be used to export all query-service configurations to import into new environments.

Custom expression providers and query processors

If you have extended the Query service by creating custom expression providers or pre- or post-processors, then ensure that you back up the extension JAR file before migration. Reapply the expressions after migration in the query-service extension directory as described in Extending the Query Service.

Note: Elasticsearch schema changes should not affect the V2 REST API, however, the index schema changes may affect custom query pre/post processors. They should be assessed based on the specific schema changes and may require some refactoring.

Attributes

To upgrade attributes, do the following:
  1. Inside your custom profile, change the responseField value from attributes.* to attribute.source.
  2. In post processing, parse the source string and assign the resulting values to the respective API response fields.
In addition, while searching or aggregation you can use fields other than source from attribute and facet field at the base level.