Understanding Restartable Service in OMS

By | 10/17/2019
Service Suspended OMS Sterling

Understanding Restartable Service in OMS

Understanding Restartable Service in OMS : In this post we are going to learn new topic which is not used by many of us but really cool Sterling order management feature called ServiceSuspendException.

Use Case

Lets assume a scenario, When order created successfully in Order Management System needs to post Order Confirmation Message to Websphere Commerce (WCS) via HTTP.


On success event of order creation transaction, getOrderList() API called and Order Management System XML message posted to Internal Queue. Async Service (Integration Server) reads OMS XML message from queue, translate to WCS Sync order XML and makes HTTP call to Webshphere Commerce.


If Websphere Commerce (WCS) having issue or WCS not available, exception will be created in yfs_inbox and yfs_reprocess_error table will have record. These table records are created based on Configuration shown below screenshot. User can go to Exception Console and reprocess the error when WCS is available.

Is Reprocessable

In this above use case if WCS not available for 30 minutes, all the calls made during the 30 minutes time interval will fail and user has to reprocess the failure. How about when we make HTTP call and found WCS not available, suspend the service for particular time interval and retry after N minutes ? Does it make interesting ?


Out of the box, user can throw ServiceSuspendException when HTTP call fails. Which makes service to get suspended for N minutes and restart the service automatically.


How to Configure Suspend API ?

Create new Async Service with name TestRestartableApi

Configure Runtime tab values as shown below

Runtime Configuration

Created new server (RestartableapiTestServer)

Server Creation Configuration

Configure Suspend API and Suspend Wait time (Seconds)

Suspend API Configuration
Suspend API Select this field if a suspendable exception is returned by an extended API, the message is retained in the queue and the execution restarts after the Suspend Wait Time interval. For details regarding the exception to be thrown, see the YIFRestartableAPI interface.
Suspend Wait Time Enter the time to wait before attempting to reprocess the message. 300 seconds = 5 minutes

Configure the Extended API

Extended API

Sample Java Code

package com.oms94.util;

import org.w3c.dom.Document;

import com.yantra.interop.japi.ServiceSuspendException;
import com.yantra.yfs.japi.YFSEnvironment;

public class RestartableServiceTest {

	 * @param env
	 * @param inputDoc <Test ExternalSystemFailure='true' />
	 * @return Document
	 * @throws ServiceSuspendException
	 * @throws Exception
	public Document processMessage(YFSEnvironment env, Document inputDoc) 
			throws ServiceSuspendException, Exception {
		//Scenario 1: Making HTTP call to external server and returned 
		//internal error or system not available
		//Scenario 2: Sending email using SMTP failed with error
		//For testing purpose added attribute ExternalSystemFailure=true
		String isExternalSystemFailure = inputDoc.getDocumentElement().
		if(new Boolean(isExternalSystemFailure)) {
			throw new ServiceSuspendException("External System Failure so service "
					+ "will be halted for n minutes");	
		return inputDoc;

How to test the suspend API ?

Create new Sync Service which helps to post message to queue. If you have access to drop message directly into queue this step not required.

Post Message to Queue

Configure Runtime values as shown below

  • Export the custom jar
  • Build the ear and deploy
  • Start the Integration Server using command startIntegrationServer.cmd RestartableapiTestServer
  • Drop below message to queue by calling Sync Service (PostMessageToRestableTestQ) Via API Tester <Order ExternalSystemFailure=’true’ />

The server log shows, service went to suspended status for 5 minutes. The message what we posted to queue available in the queue. This message will be retry after 5 minutes automatically.

Server Log

getServerList() API shows RestartableapiTestServer status as Suspended


Points to remember

  • YIFRestartableApi interface is deprecated
  • We are not required to implement YIFRestartableApi interface in the extended API Java Code
  • Throwing ServiceSuspendException and Suspend API checkbox checked is enough for making service suspended
  • This ServiceSuspendException good only in few scenarios
    • External System Integration Failures (WCS / payment Processing)
    • SMTP email server failure

Any question please email to support@activekite.com
Happy Learning. Come lets learn together.

Leave a Reply

Your email address will not be published. Required fields are marked *