Enabling the Sterling search index implementation

IBM® Sterling Selling and Fulfillment Foundation’s Sterling Search Index provides a facility to get transactional data, spread across multiple database shards.

When enabled, a transactional data created or updated in the system is also indexed in the Sterling Search Index with it's most commonly used searchable attributes and it's colonyId. The attributes to be indexed are based on a pre-defined template, but this template is configurable. The colonyId is an indicator of the physical database shard where the data is present. When a user searches for transactional data in Sterling Selling and Fulfillment Foundation by passing one or more of these attributes, the attributes are queried against the Sterling Search Index, which returns colonyIds of the matching documents in the index. The data is retrieved by invoking the search API on all the database shards corresponding to the colonies returned from the Sterling Search Index.

Starting in Release 9.2.1 of Sterling Selling and Fulfillment Foundation, the entities Order and Shipment are enabled for indexing. Perform the following steps to enable the Sterling Search Index Implementation for these entities. At a high level, this includes the following tasks:

Assess the out-of-the-box attributes enabled for indexing and the APIs enabled for search against the index.
Add new attributes to the index or enable new APIs to search against the index to meet your search expectations.
Install and configure Elasticsearch servers with the recommended settings.
Run the <INSTALL_DIR>/bin/deployer.sh -t generate-entity-indexconfig command.
Set the properties related to Sterling Search Index in both yfs.properties_ysc_ext and elasticsearch.properties.
Note: The cluster.name and discovery.zen.ping.unicast.hosts properties must be set in elasticsearch.properties when yfs.ssi.enabled is set to Y in yfs.properties_ysc_ext. Otherwise, server startup or deployment will fail with SSI921_0021 (‘Failed to initialize search subsystem’). Additionally, in case of a non-NodeClient setting, ensure that the necessary properties that are described in Configuring Elasticsearch are also set.
Generate the index mapping file (a JSON file), and copy it to the Elasticsearch installation area.
Create an ALERT service and attach it to the ON_FAILURE event on the SSI_INDEX_NOTIFICATION transaction so that indexing and search failures are notified the way you prefer.
Note: When associating an action with the ALERT service to the ON_FAILURE event of the SSI_INDEX_NOTIFICATION transaction, the action to the event handler can be enabled to either send notification to the alert console using the "Send to Alert Console" option or can be published to the export table using the "Publish Data" option. Selection of both options is not supported.
Start the Elasticsearch server nodes in the cluster.
Deploy Sterling Selling and Fulfillment Foundation.
Configure and run the SSI_MASS_SYNC agent in ‘unindexed’ mode for all enterprises (including DEFAULT) that have pre-existing orders or shipments. Monitor the alert console and/or the agent terminal to ensure that the agent ran successfully. In case of any exceptions, fix the problem and re-run the agent. Proceed to the next step only if all pre-existing orders/shipments are indexed successfully.
Log in to the System Management Administrator (SMA), select Index Management, and verify the Index status and synchronization status. Perform the required actions to enable indexing and search-related operations in the system.
Mark the index as synchronized for the Enterprises whose existing Orders and Shipments are indexed.
Configure the time-triggered transaction, SSI_DELAYED_SYNC, to trigger automatically so that it can attempt the momentarily indexing failures again. Start SSI_DELAYED_SYNC as an agent.

When configured as described above, whenever an Order or Shipment is created or updated in Sterling Selling and Fulfillment Foundation, it is also indexed in the Elasticsearch. The search operations on Order or Shipment entities using APIs such as getOrderList or getShipmentList will query against the index first, get the matching colonyIds, and then process on these colonies.

Note: Sterling Selling and Fulfillment Foundation does not provide any script to explicitly create an index in the search index server. An index will be created automatically by the search index server when the first order is indexed. However, if you have existing orders in your system and you have enabled indexing but have not run the SSI_MASS_SYNC agent, an "index is missing" exception will be thrown when you try to search for an order, and the API will always search in all shards. In such situations, run the SSI_MASS_SYNC agent and then perform your search on the index.

Important: The Elasticsearch JestClient refers to the Java classes in the Apache HttpComponents Client package, Version 4.5 to make an HTTP connection to the Elasticsearch server. The necessary libraries of the Apache HttpComponents Client that are used to establish this connection and provide communication with the Elasticsearch server are shipped in Sterling Order Management, Version 9.5.

WebSphere® Application Server, Version 8.5.5.0 and higher, also ships some of the classes in the Apache HttpComponents Client package as a plugin (for example, AppServer/plugins/com.ibm.ws.prereq.jaxrs.jar). The classes shipped in WebSphere Application Server plugins and the corresponding classes in the Apache HttpComponents Client, Release 4.5 are of conflicting versions and this leads to FATAL failures when Sterling Order Management is being deployed with Elasticsearch JestClient enabled.

To solve this problem:

Log in to the WebSphere Application Server Admin Console.
Navigate to Applications > WebSphere enterprise applications > (YourApplication) > Class loading and update detection.
Change Class loader order to parent last.
Restart the application.

This forces the WebSphere Application Server to give preference to the libraries that are shipped in the Sterling Order Management application instead of what is bundled within WebSphere Application Server plugins.