Apama Capital Markets Foundation 10.7 | Capital Markets Foundation | Legacy Finance Interfaces | The actors in com.apama.oms | Value constraint rules
 
Value constraint rules
This topic describes com.apama.oms.NewOrder event fields. The constraints on the fields in the events are best explained by detailing each field of each event individually.
*NewOrder
the new order event submits an order from a publisher to a receiver. Its fields specify details of the order, such as where it is to be sent, how big it is and whether it is a buy or sell order.
*orderId
The order identifier specified in the new order links all events for a particular order together. All order updates, amends and cancels pertaining to this order must have the same value for orderId. The interface does not impose any restrictions on the orderId value, other than that it must be a unique value within a correlator instance. Third-party systems to which adapters connect, may have arbitrary restrictions on the length, format and uniqueness of order IDs so adapter implementations may need to map the order ID supplied by an order publisher to a value that will work with a specific third-party system. The publisher should ensure that the identifier is globally unique, preferably across correlator runs. One common technique is to use integer.getUnique() combined with currentTime, to generate a unique ID at runtime. Receivers should be selective. When they receive a new order event, they should only listen for amend and cancel events where both the order identifier and service identifier match. This will avoid the complications that can arise if a badly-behaved publisher only ensures identifiers are unique per receiver.
*symbol
This is the symbol for the instrument that the publisher wishes to trade. The type of identifier used will differ from receiver to receiver and no normalization is performed. The publisher must ensure they use the right identifier. Some a adapters use RIC codes, some CUSIPs, some ISINs and others use their own symbology. Publishers should publish symbols with the correct case (upper/lower). Receivers can optionally choose to ignore case if it is safe to do so. The documentation for each receiver implementation should detail whether it is case sensitive or not.
*price
This is a floating point field containing the price for an order. Interpretation of this field is adapter specific and will vary with order type. Commonly MARKET type orders will ignore this field and LIMIT orders are submitted using this price. Stop orders, where supported, may either use this field for the stop trigger price, or for the limit price of stop limit orders. The exact behavior for stop orders is receiver specific, if supported at all.
*side
The side of the market the order is being submitted against. Publishers must send BUY or SELL, in upper case. Receivers should accept sides in a case insensitive way, but do not have to. Some adapter’s order receivers will accept additional sides, such as SHORT SELL. Please note these are not really sides (an order book only has two of those), they are really modifiers for accounting and compliance purposes and should be conveyed as extra parameters. There is no guarantee that any given publisher, monitor or receiver will understand any type other than BUY and SELL. CMF components such as the position service may not handle such sides correctly.
*type
The type of the order can be any string, but order receivers will only understand a small set of values. These are adapter specific. Almost all receivers support MARKET and LIMIT order types. Publishers should send these types in upper case and receivers should a accept them in a case insensitive manner. The documentation of a receiver implementation must document all order types supported and any requirements in terms of extra parameters. Common types used include STOP, STOP MARKET, and STOP LIMIT.
*quantity
This integer field indicates how much of an instrument should be executed. The exact meaning differs from receiver to receiver, especially in foreign exchange where some receivers use this field to represent a number of contracts, others use it to represent a cash figure. For example, trading 1M EUR/USD might require a quantity of 1000000, or if in lots of 100,000 it might require 10, or it might simply be 1. Please see the receiver-specific documentation in the adapter readme file for details.
*serviceId
This field specifies which order receiver is to process the new order. It is used to construct a composite destination key that determines where an order gets sent. Publishers can publish to any service identifier they like. Receivers must only listen on one identifier and that must never be an empty, , identifier. The publisher has no guarantees that it will receive a response to a new order event. No receiver may be listening on that identifier.
*brokerId
This field is seldom used. Some receivers are not direct connections to exchanges, but are a way of sending orders to a network of brokers. In that situation, the broker identifier can be used to instruct the adapter which broker should handle the order. Receivers that support this field should give further details in their documentation. When an adapter supports the broker id field, it can sometimes be considered part of the composite destination key, for example, in CMF firewall rules. A few older adapters use the brokerId to specify the user id to use when connecting to the OMS system. This is an incorrect use of this field. The correct way for adapters to determine the user id for the OMS system is to use the ownerId field. This ownerId corresponds to the Apama user ID, the dashboard user ID. As it is often impossible for the user IDs in Apama and the OMS to match and because they are not always in a one-to-one mapping, the adapter should provide a means to configure Apama user IDs to OMS system user IDs. See the ownerId description for more details.
*bookId
This field is also seldom used. It is a field used for accounting purposes when sending orders through order management systems that support the concept of a book. Adapters that support this field should document details of its use.
*marketId
The market identifier is the part of the composite destination key that determines where an order gets sent. Its original purpose was to allow the user to send orders to different kinds of market, for example, spot, forward and futures markets. Many receivers still use it for this purpose. In other receivers, which allow more than one instance to be run at once, such as the QFIX adapter, the market identifier is used to specify which instance the order is for. The instances themselves are normally configured using a SessionConfig event. Details of such events are to be found in the documentation for the relevant receivers.
*exchange
The exchange is part of the composite destination key that determines where an order gets sent. It is used with receivers that connect to technologies that give a uniform interface to many exchanges. For example, it would be used to send orders to the LSE, NYSE, eCBOT or Xetra. Details on how this field is used can be found in the documentation for each receiver.
*ownerId
The owner identifier field contains the user ID that an order should be associated with. Typically this will match a dashboard user name. Order receivers must not expect the user identifiers used by external systems to be in this field. As these two ids will seldom match, the receiver must implement a lookup service to map dashboard user to the downstream user id. This mapping will be configured with receiver specific events. The receiver must document the technique it uses.
*extraParams
The new order event contains this dictionary parameter to allow receivers to be provided with additional details about an order, such as their duration (IOC, FOK, GTD) or parameters for complex order types, such as stop limit orders. Details about supported parameters should be given in the documentation of each receiver, mentioning which are optional and which mandatory.