Chapter 4   Integrating Exchange with an External System


The iPlanet Market Maker Exchange module can be customized to integrate with an external module, such as a third-party application or another iPlanet Market Maker module. As an example, this chapter explains how to integrate the iPlanet Market Maker order management system (OMS) with the Exchange module.

This chapter contains the following sections:

• Overview

• Implementing the Integration

• Error Recovery

Overview

---

Rather than presenting general instructions for integrating the Exchange module with external applications, the instructions in this chapter will address a specific example: integrating the Exchange module with the order management system (OMS) of iPlanet Market Maker. By using the example instructions as a guideline, you will be able to implement the integration of the Exchange module with any downstream application such as trade settlement, portfolio management, or any legacy order management systems within the buyer and seller companies.

A trade consists of a single active order, matched with one or more (buy/sell) orders. This pairing of a buy order and a matching sell order is called a trade pair. A trade can contain one or more trade pairs. For each trade pair, a requisition (or multiple requisitions) is created in OMS that contains a single line item representing the trade, or purchase. The requisition is submitted to an approval process within the buyer company. If the requisition is approved by the buyer company, the order is submitted to the seller company for further processing. All the buy-side information is collected from the buy order in the trade pair; all the sell-side information is collected from the sell order in the trade pair.

The order processes that occur after these trades happen are external to the Exchange module. These OMS processes will need to be integrated with the Exchange module. In the out-of-box iPlanet Market Maker software, two reference exchanges for directing the buy orders in a trade to the OMS have been implemented:

• Basic reference exchange

• Transport reference exchange

With the help of the iPlanet Messaging Queue, exchange events are published by MOMPublisherService for each exchange service. These events are defined as SERVICE_PROPERTYs. A MOM_LISTENER picks up these published messages under the topic trades and calls the API of the BasicExchangeAsyncManager. This API in turn invokes the corresponding service (in this case, the OMS service) and the service performs the business function.

Implementing the Integration

---

To implement the Exchange module integration with OMS, the following tasks are required:

1. Creating a service (java class) that will invoke the appropriate OMS module API to create requisitions

2. Defining the new service as a service in the XML schema for the exchange you are implementing

3. Writing a MOM listener that will listen to the topic trades

4. Defining the listener as a MOM_LISTENER in the XML schema for the exchange you are implementing

5. Adding a method to the public class BasicExchangeAsyncManager and the remotable framework to which the listener would make calls
   

   ---

   Note	The above Listener/AsyncManager/Service pattern can be used in a generic manner to integrate the Exchange module with any external or third party application.

   ---

   
   

Basic Reference Exchange

The Basic reference exchange implements a listener for the trades topic in the Exchange module. Each time a trade takes place, the listener picks up the message corresponding to the trades topic and calls a method (business logic) that invokes the OMS module APIs to create a requisition.

For this purpose, a message oriented middleware (MOM) listener, OMSMOMListener, has been created and defined in the XML schema of the Basic reference exchange. The listener invokes the API of the BasicExchangeAsyncManager, which then delegates the call to the OMSService (OMSServiceImpl) where the required business functions are performed.

If the OMS module was implemented correctly, the requisition is submitted for approval according to the OMS module logic.

The following figure illustrates the integration of a Basic reference exchange with OMS.

Sample Code
Table 4-1 shows sample code for the OMS service. This service contains the business logic and calls the OMS module APIs to create a new requisition for each trade pair when the trade takes place. This service is defined in the XML schema descriptor file, BasicSchema.xml, as a SERVICE with quantity and price axes as the SERVICE_PROPERTYs.

.. requisition.setSourceGuid(buyOrder.getGuid()); requisition.setSourceType(OrderSource.EXCHANGE); requisition.setSourceDisplayableId(buyOrder.getTrackingNumber(); LineItem item = omsManager.newRequisitionLineItem(); item.setVendorGuid(sellOrderRequest.getCompany()); item.setSourceGuid(symbolGuid); item.setDescription(symbol.getDescription()); item.setQuantity((new Long(tradeUnitQuantity)).intValue()); item.setPrice(new Price(tradeUnitPrice)); item.setNegotiatedPrice(new Price(tradeUnitPrice)); item.setUnitOfMeasure("EA"); item.setDisplayableId(symbol.getName()); requisition.setOwningCompany(buyOrderRequest.getCompany()); requisition.setOwner(buyOrderRequest.getUser()); requisition.setCreator(buyOrderRequest.getUser());

requisition.setDescription("This requisition is for Trade ID="+tradeID +" ,Buy Order Tracking Number="+buyOrder.getTrackingNumber() +" ,Sell Order Tracking Number="+sellOrder.getTrackingNumber()); requisition.addLineItem(item); requisition.store(); boolean isOMSRegistered = ModuleList.isModuleRegistered(OMSModule.getModuleCode()) ;              if(isOMSRegistered){ requisition.submitForApproval(); ......

Table 4-2 shows sample code is for the OMS MOM listener. This listener is defined in the XML schema descriptor BasicSchema.xml as a MOM_LISTENER which would pick up all the messages in the trades topic of the Basic reference exchange.

public class OMSMOMListener extends ExchangeMOMListener { /** * Processes a TradeMOMMessage message to create an OMS Requisition. * <P> * It calls the BasicExchangeAsyncManager.createOMSRequisition(String tradeID) * method. * <P> * * @param msg the TradeMOMMessage to process. * @throws JMSException if message retrieval fails * @throws VortexException thrown if the processing of the message fails. */ public void processMessage(Message message) throws JMSException, VortexException { ObjectMessage objMessage = (ObjectMessage) message; TradeMOMMessage tradeMsg = (TradeMOMMessage) MOMUtils.unwrapObject((byte[])objMessage.getObject()); Context ctx = TLContext.getImmContext(); BasicExchangeAsyncManager asyncMgr = BasicExchangeAsyncManager.getBasicExchangeAsyncManager(ctx);

asyncMgr.createOMSRequisition(tradeMsg.getTradeId()); } }

Table 4-3 shows the sections of the XML schema descriptor file where the OMS service and the OMS MOM listener are defined.

<SERVICE name="OMSService" impl_class="com.reference.basic.service.OMSServiceImpl"> <SERVICE_PROPERTIES> <SERVICE_PROPERTY name="PriceAxisName" value="PriceAxis" /> <SERVICE_PROPERTY name="QuantityAxisName" value="QuantityAxis" /> </SERVICE_PROPERTIES> </SERVICE>

<MOM_LISTENER name="OMSMOMListener" impl_class="com.reference.basic.mom.OMSMOMListener"> <MOM_LISTENER_PROPERTIES> <MOM_LISTENER_PROPERTY name="active" value="false"/> <MOM_LISTENER_PROPERTY name="debug" value="error"/> <MOM_LISTENER_PROPERTY name="message.topic" value="trades" /> </MOM_LISTENER_PROPERTIES> </MOM_LISTENER>

Error Recovery

---

If errors, such as lack of privileges, are encountered while creating the requisitions in the OMS module, the MOM message designated for the OMS listener is stored by the Exchange Module Recovery Mechanism, and a notification of the error is sent to the iPlanet Market Maker administrator as well as to all the account holders of the buy order. The iPlanet Market Maker administrator would then replay the message once the problem is resolved.

---

Note

By default, the OMS listener is set to Off in the exchange XML schema. To view the requisitions that have been created in the OMS module, the company that owns the buy order needs to be assigned as a buyer company (or both, buyer and seller company) in the iPlanet Market Maker community, with appropriate OMS privileges.

---