Handling exceptions

The Sterling Search Index has some built-in exception handling capabilities.

As Order Service is deployed outside Sterling™ Order Management System Software, you might encounter problems over time. For example, Order Service may be down or unreachable. There may be Order Search validation errors or Elasticsearch specific problems as well, such as some of the index shards may be unavailable or the node ‘master’ may not have been elected yet. These can result in failure of index operations.

This brings up the following considerations:
  • As Search Index Server is primarily used for faster search and data visibility, its unavailability or index failures should not have any functional impact. For this reason, Sterling Search Index is made robust enough to work around these problems to provide seamless business functionality.
  • Failed or lost index updates need to be tracked and re-attempted.
  • Failed index updates should be reported to you so that you can take corrective actions, if needed.

Handling failed or lost index updates

As briefly explained in the previous section, YFS_Awaiting_Index stores a reference to each or every indexing attempt due to which the following scenarios arise:
  1. JVM crash - Since the index-update operation is done asynchronously through the PeriodicBatchIndexer service, if JVM crashes or is forcibly killed, some of the updates are lost.
  2. Intermittent indexing failures - Indexing operation fails intermittently due to problems with the Search Index Server, network, and so on.
  3. Consistent indexing failures: Due to some issues, indexing operation fails continuously and reproducibly.

In scenarios 2 or 3, the exception is notified to you. Depending on the problem, you might need to take a corrective action to fix the problem. In any of these cases, records in the YFS_Awaiting_Index table tracks the entity record that needs to be re-indexed. Re-indexing is performed by the SSI_DELAYED_SYNC agent, which is automatically triggered periodically.

Exception notification

Any exception that occurs during an index operation needs to be notified to you. Other than the exception scenarios as already discussed, Sterling Search Index has other pre-emptive mechanisms as well. For example, upon continuous index failures, it disables the corresponding operation altogether until you take corrective actions. Furthermore, if any change has been made to the index outline template, the index in Search Index Server might potentially be in an inconsistent state with old data do not have the attributes added now in the outline template. Such decisions taken automatically by Sterling Search Index may require you to take a corrective action. In the first example, you need to fix the underlying problem and re-enable the index operation. In the second case, you need to evaluate if the SSI_MASS_SYNC agent needs to be run. If needed, mark the index to be in a synchronized state. Therefore, these messages need to be notified as well.

Such exceptions or warnings can be broadly categorized as follows:
  • Index status messages
  • Index operational warnings
  • Unexpected errors
  • Connectivity issues
Note: Some of the exceptions, mainly exceptions that occur during the index build process are logged against the name of either IndexManager or PeriodicBatchIndexer. This is because, indexing operations are not performed by the user who created or modified the order in the system, but are triggered from Java classes with IndexManager or PeriodicBatchIndexer name in a separate thread in the JVM.

The exceptions and warnings from the Sterling Search Index are published in any of the following ways:

  • By raising an alert
  • By raising an event

Raising alerts

The alerts raised from Sterling Search Index are like any other alerts raised for operational exceptions. All exceptions are logged with ExceptionType=’IndexException’ and warnings are logged with ExceptionType=’Warning_Message’. They are created in the YFS_Inbox table in the same database shard as the corresponding entity record. These alerts are neither directed to a user nor any alert queue, and not consolidated.

You can list the alerts in the Alert console by specifying the Alert Type as IndexException or Warning_Message. These alerts might not be enterprise specific, and therefore, it is best to avoid the use of ‘EnterpriseCode’ as a search criteria.

Raising events

The operational exceptions and status transitions from Sterling Search Index can be published by enabling the ON_FAILURE event defined for the SSI_INDEX_NOTIFICATION transaction that is present under the General Process Type Repository.

If you enable this event, it can publish the information as shown in the following template:

Index IndexName="" EnterpriseCode="" SearchWorking="" IndexWorking="" ErrorCode="" ErrorDescription="" Reason="" Comments="" ReferenceName="" ReferenceValue="" SearchCriteria=""> <StackTrace/> </Index>

This is configurable. The SSI_INDEX_NOTIFICATION.ON_FAILURE.xml event template is present in the<NSTALL_DIR>/repository/xapi/template/merged/event directory.

Sterling Order Management System Software does not provide any event handlers such as conditions, actions, or services to trigger a process when this event is raised. However, it provides the following condition builder attributes that helps you to create a condition for the data published by the event.

Condition builder attributes Use this attribute to create a condition
EnterpriseCode For a specific EnterpriseCode
IndexName For a specific IndexName
IsIndexingWorking To track the transition of the IndexWorking attribute

To customize the condition builder attributes for other attributes that are published by the event, use the {Enter Your Own Attribute} facility.

You can define actions to publish the event output to a database, create an alert, send an email and so on. You can define event handlers by providing conditions that determine the types of actions that are performed when this event is raised.

The following table describes the attributes that are published for the exceptions from Sterling Search Index:

Attributes Description
IndexName The name of the index, for example Order.
EnterpriseCode The EnterpriseCode published, if available when an exception occurred.
IndexWorking Setting this as N indicates that IndexWorking is flipped to N by the system and no further indexing is done on the index.
ErrorCode The error code for the error.

You can view the description and cause of these errors, as well as the actions to troubleshoot them in Sterling Order Management System Software.
ErrorDescription The error description of the error code.
Reason If an error is displayed from Search Index Server, this field provides detailed information about the failure. In case of notification, this field provides the notification message.
Comments Provides additional information about the scenario, whether an exception scenario or a notify scenario.
ReferenceName Provides additional information. Usually, it contains the name of the reference entity. For example, YFS_ORDER_HEADER or YFS_AWAITING_INDEX.
ReferenceValue Provides additional information. Usually, it contains the value of the reference entityKey. For example, the value of OrderHeaderKey or AwaitingIndexKey. It indicates that an exception occurred when processing the corresponding key.
StackTrace The entire stack trace of the exception. This is not present in the application-provided template for the ON_FAILURE event. You can extend the template to publish stack trace also in the output of the event.