Sterling oms taskq based agent server

By | 11/12/2017

Sterling oms taskq based agent server

Sterling OMS TaskQ Based agent

In Sterling OMS we have 2 type of servers

  • Agent Server
    • TaskQ based
    • Non TaskQ based
  • Integration Server

Please read this post to get different between agent and integration servers

In this post we are going to see how to create simple TaskQ based agent.

Sterling OMS TaskQ based Agent Server

Requirement: When order stays in Draft order Status for 30 days, automatically delete order after 30 days.

Note: Deleting draft order using order purge agent available as OOB (Out-of-Box) functionality. this blog created to explain how to create TaskQ agent in Sterling OMS.

Task Q Records can be created in 2 ways

  • Systematic way : Pipeline Configuration: Enabling Transaction as task basedPipeline Configuration Sales order

Sterling oms taskq based agent server

if Draft Order Confirm transaction enabled with “This transaction is task based”, during draft order creation system automatically generates record into YFS_TASK_Q table. This record will be picked-up by agent server for processing.

  • Manual way : Calling manageTaskQueue API

In this post we are going to see how to use manageTaskQueue API and deleteOrder API.

Configuration Steps

  • Create new transaction with name DELETE_DRAFT_ORDER_AUTOIBM OMS Transaction Creation
  • Under time triggered tab give the Java class name as “com.oms94.agent.TaskQDemoAgent” (Code given below)IBM_OMS_TIME_TRIGGERED_TRANS
  • Create New Agent Server (DraftOrderDelete) by clicking green color + symbolIBM_OMS_AGENT_CREATE
  • Configure Run Time Properties as shown belowIBM_OMS_AGENT_RUN_TIME_CONFIG
  • Configure Criteria Parameter as shown belowIBM_OMS_Criteria_Parameter_Definition
  • Create New Sync Service with name DraftOrderTaskQRecordInsertDraftOrderTaskQRecordInsert Service
  1. API : Extended API
  2. API Name : createTaskQRecord
  3. Class Name : com.oms94.agent.CreateTaskQRecord
  4. Method Name : createTaskQRecord
  • Create New Action and configure DraftOrderTaskQRecordInsert service into actionDraft Order Action
  • Configure newly created action part of Draft Order Creation transactions ON_SUCCESS eventDraft Order Create Transaction

Java code Changes

Add below given code in eclipse and generate jar file.

package com.oms94.agent;

import java.rmi.RemoteException;
import java.text.SimpleDateFormat;
import java.util.Calendar;
import java.util.GregorianCalendar;

import org.w3c.dom.Document;

import com.oms94.util.XMLUtil;
import com.yantra.interop.japi.YIFApi;
import com.yantra.interop.japi.YIFClientFactory;
import com.yantra.yfc.dom.YFCDocument;
import com.yantra.yfs.japi.YFSEnvironment;
import com.yantra.yfs.japi.YFSException;

 * Demo class for creating yfs_task_q record manually
public class CreateTaskQRecord {

	protected static YIFApi api = null;
	public Document createTaskQRecord(YFSEnvironment env, Document doc) throws YFSException, RemoteException, Exception {
		if(doc == null) {
			return doc;
		System.out.println("Input createTaskRecord: " + XMLUtil.getStringFromDocument(doc));
		YFCDocument document = createManageTaskQueueInputXML(doc);
		System.out.println("Input manageTaskQueue: " + XMLUtil.getStringFromDocument(document.getDocument()));
		doc = getApi().manageTaskQueue(env, document.getDocument());
		return doc;

	private YFCDocument createManageTaskQueueInputXML(Document doc) {
		String orderHeaderKey = doc.getDocumentElement().getAttribute("OrderHeaderKey");
		YFCDocument  document = YFCDocument.createDocument("TaskQueue");
		document.getDocumentElement().setAttribute("DataKey", orderHeaderKey);
		document.getDocumentElement().setAttribute("DataType", "OrderHeaderKey");
		document.getDocumentElement().setAttribute("HoldFlag", "N");
		document.getDocumentElement().setAttribute("Operation", "Manage");
		document.getDocumentElement().setAttribute("TransactionId", "DELETE_DRAFT_ORDER_AUTO.0001.ex");
		document.getDocumentElement().setAttribute("AvailableDate", getNextAvilDate());
		return document;

	private String getNextAvilDate() {
		SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss");
		Calendar currentCal = new GregorianCalendar();
		currentCal.add(Calendar.DATE, 30); // this value should be read from configuration
		String sNextAvailableTime = sdf.format(currentCal.getTime());
		System.out.println("sNextAvailableTime:" + sNextAvailableTime);
		return sNextAvailableTime;
	protected YIFApi getApi() throws Exception {
		if(api == null) {
			api = YIFClientFactory.getInstance().getApi();
    	return api;
package com.oms94.agent;

import java.rmi.RemoteException;

import org.w3c.dom.Document;

import com.oms94.util.XMLUtil;
import com.yantra.interop.japi.YIFApi;
import com.yantra.interop.japi.YIFClientFactory;
import com.yantra.ycp.japi.util.YCPBaseTaskAgent;
import com.yantra.yfc.dom.YFCDocument;
import com.yantra.yfs.japi.YFSEnvironment;
import com.yantra.yfs.japi.YFSException;

public class TaskQDemoAgent extends YCPBaseTaskAgent  {

	protected static YIFApi api = null;
	 * <?xml version="1.0" encoding="UTF-8"?>
		DataKey="2017111300523176633" DataType="OrderHeaderKey" HoldFlag="N"
		TaskQKey="2017111300523476638" TransactionKey="2017111223535276390">
   			<TransactionFilters Action="Get" DAYS_TO_WAIT="30" DocumentParamsKey="0001" 
   			DocumentType="0001" NumRecordsToBuffer="5000" ProcessType="ORDER_FULFILLMENT" 
   			ProcessTypeKey="ORDER_FULFILLMENT" TransactionId="DELETE_DRAFT_ORDER_AUTO.0001.ex" TransactionKey="2017111223535276390" />
	public Document executeTask(YFSEnvironment env, Document doc)
			throws Exception {
		System.out.println("Input executeTask: " + XMLUtil.getStringFromDocument(doc));
		Document deleteOrderResult = getApi().deleteOrder(env, createDeleteOrderInput(doc).getDocument());
		System.out.println("deleteOrderResult:" + XMLUtil.getStringFromDocument(deleteOrderResult));
		return doc;
	private YFCDocument createDeleteOrderInput(Document doc) {
		String orderHeaderKey = doc.getDocumentElement().getAttribute("DataKey");
		YFCDocument  document = YFCDocument.createDocument("Order");
		document.getDocumentElement().setAttribute("OrderHeaderKey", orderHeaderKey);
		document.getDocumentElement().setAttribute("Action", "DELETE");
		return document;
	protected YIFApi getApi() throws Exception {
		if(api == null) {
			api = YIFClientFactory.getInstance().getLocalApi();
    	return api;

Build and Deployment

Build the jar file and replace it in <OMS_INSTALL_DIR>\jar\customjar\1\SterlingCustom94.jar. Read here how to create custom jar and add part of install.

Build the application using below command

buildear.cmd -Dappserver=weblogic -Dwarfiles=smcfs,sbc -Dearfile=smcfs.ear -Dnowebservice=true -Ddevmode=true -Dnodocear=true -Dwls-10=true create-ear


Deploy the newly created EAR.

How to test this change ?

  • Go to Sterling Order Create Console and create Order in Draft order
  • Run query and find Task_Q record got created with AvailableDate as current date + 30 days
select * from yfs_task_q 
where data_type='OrderHeaderKey' 
and transaction_key in (select transaction_key 
from yfs_transaction where tranid='DELETE_DRAFT_ORDER_AUTO.0001.ex')
order by 1 desc
  • For testing purpose modify the AvailableDate with below query (your agent will not pickup this record for next 30 days)
update yfs_task_q set AVAILABLE_DATE=sysdate where task_q_key='?'
  • run the agent <OMS_INSTALL_DIR>/bin/agentserver.cmd DraftOrderDelete
  • Draft Order got deleted and yfs_task_q record got deleted successfully.

Points to remember ?

  • While extending YCPBaseTaskAgent we need to override executeTask(YFSEnvironment env, Document doc) method
  • If transaction executed successfully yfs_task_q record gets removed
  • if transaction fails  yfs_task_q tables lock_id column value will be incremented by 1 and AvailableDate = sysdate + 4 hours (try after 4 hours; configurable)
  • If some one confirms the draft order (By calling API or from screen), from ON_SUCCESS event need to invoke manageTaskQueue API to clear the YFS_Task_Q table record
  • In the above example deleteOrder API cleans the records from YFS_TASK_Q table automatically. if not we should implement registerProcessCompletion or manageTaskQueue API to clear the record.
private Document registerProcessCompletion(YFSEnvironment env, String taskQKey) throws YFSException, RemoteException, Exception   {
	return getApi().registerProcessCompletion(env, createRegisterProcessCompletionInput(taskQKey));

private Document createRegisterProcessCompletionInput(String taskQKey) {
	YFCDocument  document = YFCDocument.getDocumentFor("<RegisterProcessCompletionInput KeepTaskOpen='N'>"
		+ "<CurrentTask TaskQKey='" 
	+ taskQKey + "'/></RegisterProcessCompletionInput>");
	return document.getDocument();

33 thoughts on “Sterling oms taskq based agent server

    1. admin Post author

      Thanks Ravi. We love to update every week. But due to many reason not able to do. Will try our best to update more.

  1. Suneetha

    Dear Team,

    I was looking for the interview questions from couple of years. Now I found very good website which has cleaned ,detailed and nice explanation. It’s very easily understandable for who does not about sterling OMS basics.

    Thank you so much for the interview questions.

    Could you please provide some details about Sourcing and Scheduling rules.

    Thank you in advance.

    1. admin Post author

      Thanks lot for your feedback. yes for sure will add more details on sourcing and scheduling. First we are trying to over the basic before going to advanced
      topics. if any specific question please write to

  2. ravi

    can you Please provide import com.oms94.util.XMLUtil i.e also. Please?

    1. admin Post author

      Thanks Ravi for the update. You are one person who try to do all my blogs. Thanks lot for that. Just email us if any place need more clarity we will help you. Thanks again for all your support.

  3. Praveen

    I have another doubt related to Hang Off Table.
    Suppose we have created a Hang Off table (EG: ABC_HANG_ORDER_HDR) having parent YFS_ORDER_HEADER table.
    Is it possible to get HangOff table data using standard API call like getOrderDetails? If so how to do that?

    1. ravi

      Lets approach this by considering the hang-off table EXTN_ITEM_ACTIVATION which has the parent YFS_ORDER_HEADER. Assuming that AUDITREQUIRED is ‘N’ in the extensions.xml for this hang-off table. If we want to insert records in the hang-off table while the order is created i.e while createOrder API is invoked then we can pass the below XML to the createOrder API: In the above XML please note that the hang-off table attributes are present under EXTN element. After the XML is passed to the createOrder API, we can see that corresponding records are inserted in the Order related tables as well as the EXTN_ITEM_ACTIVATION table. Similarly, if we want to make any changes to the values in EXTN_ITEM_ACTIVATION table, we can do it by passing relevant XML to changeOrder API : At the Order level, we pass the Order Header Key for reference. At the EXTN level, we pass the value that we want to modify. Here we are trying to modify the earlier Serial_Number to a new value i.e 1111.

      1. ravi

        with Services :-
        To insert/modify/getDetails/getList/delete data to/from the hang-off table, we can use services as extended Database APIs cannot be called directly. If we insert data to EXTN_ITEM_ACTIVATION table by invoking service configured for createEXTNItemActivation API from HTTP API Tester, we can pass the sample xml generated from the command below: -Dtable=EXTN_ITEM_ACTIVATION -f templateXmlGen.xml This will insert the corresponding record in EXTN_ITEM_ACTIVATION table. Now to modify this record we can call a service which in turn invokes modifyEXTNItemActivation API. This will audit no records in yfs_order_audit and yfs_order_audit_detail table. If the Auditrequired is ‘Y’ in the Extensions.xml, then the audits will be recorded in the yfs_audit table else not.

        1. Praveen

          Thanks for the information Ravi.
          But if possible please let me know the sample template format in case we need to make getOrderDetails/getOrderList call to retrieve records from hang off table.
          As per the above mentioned details it should be in the format like

          Kindly correct me if I miss understood.


  4. shekar

    can you give me more examples of Non task Q agents other than RTAM?

    1. admin Post author

      Example 1: Assume any custom table needs purge process (No connection with pipeline), we need to implement as non-task-q based.
      Example 2: Purges – After inventory Sync clear out data that may be discarded after having been processed. Example SUPPLYTEMPPRG

      1. Varun Goel

        Can we purge a custom standalone table in sterling. How we will set up the purge agent for this?

        1. admin Post author


          Yes we can create purge for custom table. In this case we need to implement non task-q based agent. Need to implement getJob() and executeJobs() method to achieve the same. Soon we will try to come with example for this. Hope helps. Happy learning.

  5. ravi

    Actually i was posted template here but not populating Please sent provide email is , i will sent you on it.

  6. ravi

    Genarte the template -Dtable=EXTN_ITEM_ACTIVATION -f templateXmlGen.xml

    1. Mohammed Irfan Mansuri

      Hi ravi,
      I tried this but getting below error, please suggest what I should do…

      [sterling@ip-10-156-0-211 bin]$ ./ -Dtable=MS_INVENTORY_AVAILABLE_CHANGE -f templateXmlGen.xml
      Buildfile: /opt/IBM/bin/templateXmlGen.xml

      [mkdir] Created dir: /opt/IBM/extn/sampleXML




      /opt/IBM/bin/templateXmlGen.xml:17: The following error occurred while executing this line:
      /opt/IBM/bin/templateXmlGen.xml:37: java.lang.NullPointerException
      at java.util.Hashtable.hash(
      at java.util.Hashtable.get(
      at java.util.PropertyResourceBundle.handleGetObject(
      at java.util.ResourceBundle.getObject(
      at java.util.ResourceBundle.getObject(
      at java.util.ResourceBundle.getString(

      1. admin Post author


        We are also getting same error. We are looking for solution for this problem. Does any found solution for this issue ? Please let us know

        Active Kite Admin

  7. kaviarasu

    I can understand that this topic is about task q based where it will put an entry in task q table, either through oob transaction or manually created task q based custom agents.

    What about non task q based agent –> i just know it will not put in task q table so that next transaction in the pipeline is not dependent on the parent transaction. So can you please tell me about this.

    1. admin Post author

      In java class you need to extend YCPBaseAgent which ask you to override getJobs() and executeJob(Document doc)
      As part of getJob() method we write logic to fetch records to be processed and executeJob will process the records. Let say if you want to perform purge for custom table

      getJob() — based on the number of days records to keep fetch record and return List
      executeJob() — will be called with single Document object, here user has to call api to purge

      Hope this help. Soon will try to get post with example. Thanks. Keep learning

  8. test

    How to implement synchronization on a particular table in Sterling.
    Ex: I have 5 different intergration servers, which insert record in a particular table. How can I make sure at a time, only integration server, can insert record in the table. Without using NO_WAIT on table.

  9. srishti

    I wanted to clear my following concept :
    1. What happens in the background while buiding EAR? I.e what gets build and re-included in EAR? why is there a need to build the same? The changes in which folder makes it necessary to build EAR
    Does it re-build jar folder,resources,entity or what?
    Please help 🙂


    1. admin Post author


      We use following comments

      To build EAR file : creates properties.jar file and uses resources.jar and entities.jar part of EAR (Created by other commands)
      buildear.cmd -Dappserver=weblogic -Dwarfiles=smcfs -Dearfile=smcfs.ear -Dnowebservice=true -Ddevmode=true -Dnodocear=true -Dwls-10=true create-ear
      here create-ear is ant target name

      To build resource jar : Resource jar build required when change happened in template or resource folder. By default resource jar build happens when entity build requested.
      deployer.cmd -t resourcejar

      To build entity jar : Entity build required only when you make change related to database.
      deployer.cmd -t entitydeployer

      To update sandbox.cfg change config

      Hope this helps !!! Keep Learning.

  10. Ankit

    Please help me understand architecture in case of multi threaded agent. How does a thread pick up a message from Q. How do we avoid 2 threads to pick same message from Q. How do we avoid such a conflict.


    1. admin Post author


      This is very good question. Question you asked need real good discussion. But will try to explain here

      1. In OMS we have agent server / Integration server (both supports multi thread and multi instance)
      2. Integration server : when started with multi thread (Thread count = 5), 5 listeners will be attached to the queue.listeners will read one message at time parallel. So there no way same message can be picked.
      3. In case agent server we have 2 types TaskQ and NonTaskQ
      4. In TaskQ we will have executeJob() method
      5. In NonTaskQ we will have getJobs() and executeJob()
      6. Here getJobs() is single thread because DB lock on yfs_object_lock table
      7. executeJob() is multi threaded

      This is very high level. If you need more details, please let us know. we can connect and discuss. Thanks

      1. Vishal

        I also had a similar question. Could you please send me the details ?

  11. sushma shukla

    I am working on getting sales order purging, which get purged when there is are no child orders related to it. However we have returns and transfers orders usually associated with them. Now i see that in order for SO to get purged I will have to get the TO and RO’s purged as well.

    While i look at the pipeline, the PURGE.0003 and PURGE.0006 are configured and agents too. However in the YFS_TASK_Q there is no entry for these agents to be picked up. I see the OOB transactions CLOSE_RECEIPT.0003 is added before PURGE.0003, and pickup status of PURGE.0003= dropstatus of CLOSE_RECEIPT.0003 which is 3950. However in the pipeline(on the connector) we have updated the drop status to 3950.001 which is extended status of 3950. Similar is the case for PURGE.0006 as well(I have tried changing this to 3950)

    I assume configurations are somehow incorrect and so no entry for PURGE.0003/0006 but cannot figure out what is wrong.

    Is there someone here who could help out with this?


Leave a Reply

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

Iconic One Theme | Powered by Wordpress
Skip to toolbar