Initial Setup for Elasticsearch

The following one-time set up is required to prepare STEP for using the Elasticsearch search engine to configure a modern faceted search experience.

Note: Elasticsearch can display product, entity, classification, and/or asset data only, based on configuration.

Important: Before starting the configuration outlined in this topic, contact your Stibo Systems account manager or partner manager for assistance. Activation and configuration for the faceted Search screen, Elasticsearch, and corresponding components / functionality should not be done without the assistance of Stibo Systems.

Configuration

  1. Using Elasticsearch with STEP requires an external installation process of Elasticsearch 8.8.2+, knowledge of JSON documents, and the API or other ingestion tool. For more information on Elasticsearch, search https://www.elastic.co/.

    Important: Stibo Systems exclusively supports the Elasticsearch cloud service distributed from Elastic.

  2. Review the Important note above and contact your Stibo Systems account manager or partner manager to enable the 'X.Elasticsearch' license on your system.

  3. Review the Important note above and activate the 'elasticsearch-integration' component. For on-premises systems, instructions for installing components can be found in the SPOT Program topic in the System Administration Guide found in Downloadable Documentation. For SaaS systems, contact Stibo Systems Support.

    Important: SaaS systems should automatically upgrade when new Elasticsearch versions are made available. However, on-premise systems will need to be manually upgraded to the new Elasticsearch version.

  4. Review the Important notes above and activate the 'ui-basket' component. For on-premises systems, instructions for installing components can be found in the SPOT Program topic in the System Administration Guide found in Downloadable Documentation. For SaaS systems, contact Stibo Systems Support.

  5. Add the Elasticsearch cluster name and port, separated by a colon (:), in the sharedconfig.properties file on the STEP application server using the case-sensitive Elasticsearch.Cluster.Nodes property as shown below:

    Elasticsearch.Cluster.Nodes=http://elasticsearch:9200

    In this example, 'http://elasticsearch' is the name of the cluster and '9200' is the port.

  6. In the sharedconfig.properties file on the STEP application server, the case-sensitive Elasticsearch.Query.CacheRetentionTime property determines the number of seconds it takes for changes to the Elasticsearch Configuration to be reflected in the Web UI. The default setting is 600 seconds (10 minutes), which is optimized for performance. Modify this setting to change the frequency of updates.

    Elasticsearch.Query.CacheRetentionTime=600

    In this example, the default has not been changed.

  7. In the sharedconfig.properties file on the STEP application server, the case-sensitive Elasticsearch.NumberOfReplicas and Elasticsearch.NumberOfShards properties make it possible to configure the replicas (default 0) and shards (default 2) to be used for the indexes created by STEP. Work with your Stibo Systems account manager or partner manager to configure these properties to match the Elasticsearch setup. For troubleshooting an event processor 'maximum shards open' error, refer to the Elasticsearch Publishing topic.

  8. If required, in the sharedconfig.properties file on the STEP application server, the case-sensitive Elasticsearch.TotalFieldLimit property allows you to increase the number of Elasticsearch facets above the 1,000 default. Prior to raising this value, consider and evaluate the performance and memory impact and contact your Stibo Systems account manager or partner manager for assistance. For existing solutions, to reflect the change in the Search Screen, Elasticsearch data must be republished (as defined in the Elasticsearch Publishing topic) or the database limit must be updated via a script in Kibana or REST.

  9. If required, in the sharedconfig.properties file on the STEP application server, the case-sensitive Elasticsearch.IncludeSearchScreen property allows you to define the Web UIs that include a faceted search icon on the Global Navigation Panel. By default, when the ui-search component is installed, all Web UIs include two search buttons () on the Global Navigation Panel. The faceted search button is at the top and the standard search button is next (refer to the Global Navigation Panel topic for details). To specify which Web UIs include the faceted search button, add a comma-separated list of those Web UI IDs to the property. Do not include spaces between the IDs, as shown below:

    Elasticsearch.IncludeSearchScreen=CustomerWebUI,BuySideSellSide_Supplier,GDSNReceiver

    In this example, only the Web UIs listed will include both the faceted search button and the standard search button. The Web UIs not specified in the property include only the standard search button.

  1. If required, in the sharedconfig.properties file on the STEP application server, the case-sensitive properties below will allow you to connect via proxy (the properties to the right of the equal sign are examples only):

    Elasticsearch.Proxy.Host=sample.stibo.com
    Elasticsearch.Proxy.Port=3248
    Elasticsearch.Proxy.User=username
    Elasticsearch.Proxy.Password=password
    
  1. For non-production systems: When using one Elasticsearch server instance for multiple non-production systems, you can add the Elasticsearch.IndexNameSuffix property to the sharedconfig.properties file. By default, it is empty. Because the users configuring the Elasticsearch instances must use different indexes, this property keeps users from overwriting indexes and production data by creating a specific index name for your environment.

    Elasticsearch.IndexNameSuffix=staging

    The index name is a combination of a prefix (defined in configuration), contextID, workspaceID and a suffix. The example above produces this index name: '{prefix}-{workspaceID}-{contextID}-staging'.

  2. Kibana is a tool for troubleshooting unexpected Elasticsearch results on the Search Screen. The installed Kibana version must be the same as the installed version of Elasticsearch. The latest versions supported are included in release notes. For more information, search the web.

Changes to the properties file, outlined above, are implemented when the server is restarted.

Note: In instances where the STEP system is set up with both an internal and an external address ( i.e., a load balancer or other network gateway between client and server), the System.ClientName property should be used to let the STEP system know that all external URLs, such as those used for image resources, need to be created with the external base URL.

Next, create an Elasticsearch object type as defined in the Creating an Elasticsearch Object Type topic.