Apama Capital Markets Foundation 10.15 | Capital Markets Foundation | Samples | Adapter Support Bundle samples | Order Manager sample
 
Order Manager sample
This sample demonstrates the use of order management functionality. It allows the user or application to do the following:
*Submit one or more orders to market service provider monitors that are loaded in the correlator.
*Receive acknowledgment of the orders.
*Amend or cancel the orders.
Description
The user must submit an order before it is possible to amend or cancel that order. The user cannot amend or cancel a completed order. Once an order has been submitted, modified, or canceled, the market service provider monitor must acknowledge or reject that operation before it allows another operation on that same order. However, a user or application can perform consecutive operations on an order without waiting for replies from the market service provider monitor. The Order Manager sample makes this possible by automatically queueing consecutive requests, and sending them when the market service provider monitor allows modifications to the order.
About Order Manager market service provider monitors
Market service provider monitors are outside this sample. The Order Manager sample communicates with these monitors by means of well-known events. These events are defined in the com.apama.oms package, which is included in the Legacy Finance Support bundle. For more information, see the ApamaDoc.
During development, a market service provider monitor is a pure EPL simulation market. In a deployed application, a market service provider monitor is part of an adapter that communicates with an IAF process, which communicates with some market.
Order states and status fields
An order is always in one of the following states:
Illustration showing the states of an order
An order can enter the Unknown state from any other state, and can leave the Unknown state and enter any other state. An order is in the Unknown state when the adapter cannot guarantee what state the order is in. This can happen, for example, if the network between the correlator and the market is down.
In the figure, the text in italics shows the status of the order while the order is in that state:
*in market — The order is known to the market. Modifications to the order might or might not be allowed.
*modifiable — The order is known to the market and modifications to the order are allowed.
*cancelled — The trader or the market stopped processing the order before it was fully filled. The order is known to the market.
*final — The order is no longer known to the market. Modifications are not allowed.
Each status is a Boolean field in the order status output feed.
An order in the Unknown state can have a status of in market, cancelled, or modifiable.
The order status output feed also supplies Boolean fields for indicating the following for an order:
*change rejected — The most recent attempt to modify or cancel the order was rejected by the market. The change might have become impossible because a trade took over the new requested quantity, or it might have been rejected by the market for any other reason.
*externally modified — The status message typically gives details for this.
*is visible — Some markets consider orders to be known to the market but invisible until a certain condition has been met, for example, stop orders are invisible until the trigger price is reached.
Upon modification or cancellation, the market might modify some fields of an order, including changing fields to values other than those requested. The actual price and quantity that are present in the market are reported in the order status output feed.
Event structures
This sample provides the events listed below in the com.apama.oms.user package.
OrderParams
This contains the input values for placement, modification, or cancellation of an order.
Field
Description
orderIdentifier
A unique identifier to perform operations on the order.
serviceIdentifier
The name of the market service provider monitor to use, or an empty string to use any market service provider monitor.
brokerIdentifier
The name of the broker to send the order to. To determine whether you need to specify this field, and obtain more information about the meaning of this field, see the documentation (this is often a README file) for the adapter you are using. If the documentation does not mention this field, you do not need to specify it.
bookIdentifier
The name of the book the order should be accounted against. To determine whether you need to specify this field, and obtain more information about the meaning of this field, see the documentation for the adapter you are using. If the documentation does not mention this field, you do not need to specify it.
marketIdentifier
The name of the market to send the order to. To determine whether you need to specify this field, and obtain more information about the meaning of this field, see the documentation for the adapter you are using. If the documentation does not mention this field, you do not need to specify it.
exchange
The name of the exchange to send the order to. To determine whether you need to specify this parameter, and obtain more information about the meaning of this parameter, see the documentation for the adapter you are using. If the documentation does not mention this parameter, you do not need to specify it.
symbol
The instrument to trade.
price
The price to trade at, or 0 for a market order.
quantity
The amount to trade. For example, the number of shares to buy or sell.
side
BUY or SELL. Some services also support other values such as BUY MINUS or SELLSHORT.
type
MARKET or LIMIT. Some services also support other values such as STOPMARKET or STOPLIMIT. If left blank, the order is placed as a LIMIT if a price is specified or a MARKET order if no price is specified (or is 0).
extraParameters
Any extra parameters for the service.
OrderStatus
The Order Manager sample generates the order status as an acknowledgment upon placement, modification, or cancellation of an order. This reports all information about each order. Each time there is a change in the order (such as a state or status change), the order status feed provides as a callback.
Field
Description
orderIdentifier
A unique identifier to perform operations on the order.
marketOrderIdentifier
An identifier supplied by the market, typically unique across all orders in that market.
symbol
Identifier for the instrument being traded.
price
The price requested either when the order was submitted or the latest modification. A price of 0.0 signifies a market order.
quantity
The total number of units, such as shares, to trade, or the number the order has been amended to.
side
The side of the order — BUY, SELL, or some other side supported by the market.
type
The type of the order — MARKET, LIMIT, or some other type supported by the market.
state
The order's state indicated by 0-9. See Order states and status fields.
moneyExecuted
The sum of price * quantity for all fills of this order, or 0.0 if no fills have occurred.
averagePriceExecuted
The volume-weighted average price over all fills, or 0.0 if no fills have occurred. For example, suppose you place an order to buy 100 shares of IBM at up to $10.00 per share. You bought 20 shares at $9.95 and 20 shares at $9.97. The average price executed is $9.96.
lastPriceExecuted
The price obtained per item for the last fill, or 0.0 if no fills have occurred.
lastQuantityExecuted
The number of items traded in the last fill, or 0 if no fills of this order have occurred.
quantityExecuted
The number of items traded so far, or 0 if no fills of this order have occurred.
quantityRemaining
The number of items left to trade in the market as part of this order.
inMarket
true if the order is known to the market.
isVisible
true if the order is visible in the market. Some markets consider orders to be invisible until a certain condition has been met, for example, stop orders are invisible until the trigger price is hit.
modifiable
true if the order can be modified immediately. The Order Manager sample queues any attempts to modify an order when it is not modifiable. The queued modification cannot occur if the order enters a final state before becoming modifiable.
cancelled
true if the order has been rejected or cancelled, possibly before being entered into the market. A cancelled order might have had some quantity traded.
changeRejected
true if the most recent modification or cancellation was rejected by the market. An explanation might be available in the status message field.
externallyModified
true if the order has been modified, for example, by the market or a third party.
final
true if the quantity specified for the order has been traded, or if the order was cancelled.
statusMessage
A message from either the market service provider monitor or the market explaining what has happened. The format and meaning of the message varies from service to service and market to market.
extraParameters
Dictionary that specifies additional parameters, which contain more information about the instrument being traded.
OrderManagerInterface
This is an interface which is used to do different order operations. It is created by the OrderManagerHelperFactory factory interface.
Operation
Description
SubmitOrder
Send the order to the market. The order automatically enters state 1, waiting for acknowledgment.
ModifyOrder
Change the order in the market. The order automatically enters state 5, pending change, unless the order is not modifiable at this time.
CancelOrder
Cancel the order in the market. The order automatically enters state 6, pending cancel, unless the order is not modifiable at this time. The market can reject a cancellation. Consequently, after an order is in the pending cancel state, it can become cancelled, completed, or, if the cancellation is rejected, working.
CancelAllOrders
Cancel all orders. Note that the market might reject some cancellations.
onOrderStatusAcknowledgement
This is a callback on order state updates.
Sample code for a factory-to-order operation
using com.apama.oms.user.OrderManagerHelperFactory;
using com.apama.oms.user.OrderManagerInterface;
using com.apama.oms.user.OrderStatus;
 
monitor OMHelperExample {
 
context mainContext := context.current();
 
action onload() {
OrderManagerInterface omiFace :=
(new OrderManagerHelperFactory).create(mainContext,OrderStatusCb);
com.apama.oms.user.OrderParams param :=
com.apama.oms.user.OrderParams("1","EUR/USD",10.1,1000,"BUY","LIMIT",
"OrderSample","","","OrderManager","","", new dictionary<string,string>);
omiFace.SubmitOrder(param);
}
 
action OrderStatusCb(OrderStatus orderStatus) {
log "Received order status for order ID = "+ orderStatus.orderIdentifier +
" status = " + orderStatus.statusMessage at INFO;
}
 
}