Apama 10.3 | Apama Capital Markets Foundation Documentation | Capital Markets Foundation | Finance Smart Blocks for Developing Scenarios | CMF legacy finance support smart blocks | Multi-Leg Order Manager v2.0
 
Multi-Leg Order Manager v2.0
The Multi-Leg Order Manager block lets you submit a single order that is actually a container for multiple orders. Each of the contained orders is referred to as a leg.
Note
The Multi-Leg Order Manager block has not been updated to use the new block interface. That is, it uses routed events to communicate with its scenario. Also, you cannot use the Multi-Leg Order Manager block in a parallel scenario.
Description
The Multi-Leg Order Manager block is based on the Order Manager block. When you use the Order Manager block, you use its parameters to specify, among other things, one instrument, one price, and one quantity. With the Multi-Leg Order Manager block, you can specify a different set of values for, for example, the instrument, price, and quantity for each leg contained in an order. This can result in better performance because the correlator sends one large event instead of several smaller events.
The Multi-Leg Order Manager block allows a scenario to
*Submit one or more orders to market service provider monitors that are loaded in the correlator. Each order can contain any number of legs.
*Receive reports about the orders and/or the legs
*Amend or cancel the orders and/or the legs
The market service provider monitors are outside the scenario. The Multi-leg Order Manager block communicates with EPL from the legacy finance support block by using the events defined in the com.apama.mlom package. For information about these events, see the ApamaDoc. All events are in the com.apama.mlom package.
To make this block available to your scenario, you must add the Legacy Finance Support bundle to your project.
The topics below provide information for using the Multi-Leg Order Manager.
When to use the multi-leg order manager
To use the Multi-Leg Order Manager block, you must use the QFIX adapter or write your own adapter. In addition, each order must be one of the specified CME iLink order types. Contact Software AG Global Support to learn the supported types.
It is expected that subsequent Apama releases will provide support for the use of the Multi-Leg Order Manager block with additional adapters and order types. If you are not using the QFIX adapter with the supported order types, or you do not want to write your own adapter, use Order Manager v5.0.
When you have an order with only one leg, using the Multi-Leg Order Manager block might be more cumbersome than using the Order Manager block. This is because the Multi-Leg Order Manager block requires more events, and therefore more time, to update the single leg. For example, to amend an order, the Multi-Leg Order Manager block generates three events, while the Order Manager block generates one event.
When you want to place multiple multi-leg orders that use different adapters, use a different Multi-Leg Order Manager block for each adapter.
The Multi-Leg Order Manager block is an alternative to the Order Manager block. The advantage of the Multi-Leg Order Manager block is that it makes it easier to manage complex orders. In addition, the Multi-Leg Order Manager block distinguishes between final orders that can still be updated and final orders that can no longer be updated. These are referred to as "settled". See Updating final orders.
Submitting multi-leg orders
In a multi-leg order, there is data that is common to all legs in the order and there is data that is relevant to each of the legs. To submit an order, you must define the legs of the order.
To submit an order:
1. Optionally set the order’s ID by specifying a value for the orderId parameter. Alternatively, you can let the Multi-Leg Order Manager block generate the order ID. by setting the auto-generate order identifier parameter to true. This ensures that the order ID is unique within the scope of the Multi-Leg Order Manager block. When auto-generate order identifier is true, the Multi-Leg Order Manager block also generates unique leg IDs.
2. Invoke the start multi-leg order operation.
3. For one leg, assign values to the Multi-Leg Order Manager block parameters.
4. Invoke the submit leg operation.
5. Repeat Step 3 and Step 4 for each leg.
6. Invoke the submit multi-leg order operation.
After you invoke the submit multi-leg order operation, the block sends data to its order status feed, leg status feed and then its order book status feed.
Modifying multi-leg orders
To add a new leg, modify an existing leg, or remove a leg:
1. Set the orderId parameter to the ID of the order you want to modify.
2. Invoke the start modify multi-leg order operation.
3. Follow the appropriate steps for modifying, adding or removing a leg:
To modify a leg:
a. Set the legId parameter to the ID of the leg you want to modify.
b. Assign updated values to the Multi-Leg Order Manager block parameters.
c. Invoke the amend leg operation.
To add a leg:
a. Specify a unique value for the legId parameter unless the auto-generate order identifier parameter is set to true.
b. Specify the appropriate values for the other parameters.
c. Invoke the submit leg operation.
To remove a leg:
a. Set the legId parameter to the ID of the leg you want to remove.
b. Invoke the remove leg operation.
4. Repeat all substeps in Step 3 for each leg you want to modify, add, or remove.
5. Invoke the amend multi-leg order operation.
After you invoke the amend multi-leg order operation, the block sends data to its order status feed, leg status feed and then its order book status feed.
Working with multi-leg orders
Order IDs and leg IDs must be unique in the scope of the Multi-Leg Order Manager block. Once an ID is used in the block, it cannot be used again for a different order or leg. This is true even if the order or leg is cancelled or completed.
At any one point in time, each order has one status and one state. Likewise, each leg has one status and one state. The status is a text description of where the order or leg is in the order process. The state is a number, from 0 through 9, that indicates more precisely the location of the order or leg in the order process. See Order states and statuses for further information. All information in that topic applies to legs, as well as orders.
When the legs in an order are in different states, the state of the order is unknown (9). When the legs in an order are all in the same state, the state of the order is the same as the state of the legs.
The Multi-Leg Order Manager block maintains an order book that contains information about each of the orders it has submitted. The order book indicates the state and status of each order placed from that block. In the order book, an order identifier distinguishes each order from every other order placed from that block. You always specify the order identifier as a parameter when you amend, cancel, retrieve, or clear an order.
The Multi-Leg Order Manager block also maintains a leg book for each order. The leg book contains information about each of the legs submitted as part of the order. In the leg book, a leg identifier distinguishes each leg from every other leg in that order. You always specify the leg identifier as a parameter when you amend, cancel, retrieve, or clear a leg.
Updating final orders
When a leg is final, it has either been completed, cancelled, or rejected. Sometimes, it is necessary to update a leg that is final. The Multi-Leg Order Manager block continues to listen for update events for final legs. If an update event occurs, the Multi-Leg Order Manager block performs the update.
If you do not want to allow updates to a final leg, you must specify that the leg is settled. To do this, your client must send a LegUpdate event to the Multi-Leg Order Manager block and specify true for the settled field. LegUpdate events are defined in the com.apama.mlom package. For additional information, see the ApamaDoc.
Parameters
Parameter
Description
orderId
A unique identifier in the scope of the Multi-Leg Order Manager block. The block uses this identifier to perform operations on the order.
serviceId
The name of the market service provider monitor to use, or an empty string to use any market service provider monitor.
tradeId
The name of the trader.
traderSubId
Additional identification information for the trader.
marketId
The name of the market 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.
marketSubId
Additional identification information about the market 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.
legId
A unique identifier in the scope of the Multi-Leg Order Manager block. The block uses this identifier to perform operations on the leg.
symbol
The instrument to trade for the leg identified by the current legId.
price
The price to trade at, or 0 for a market order, for the leg identified by the current legId.
quantity
The amount to trade for the leg identified by the current legId. For example, the number of shares to buy or sell.
side
BUY or SELL. Applies to the leg identified by the current legId. 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). This parameter applies to each leg in the order.
extra parameters
Any extra parameters for the service. Applies to each leg in the order.
leave orders open on scenario exit
If true, the block does not cancel orders when the scenario enters the end state. This leaves the orders uncontrollable in the market.
auto-generate order identifier
If true, the Multi-Leg Order Manager block generates the order identifier and the leg identifiers for you when you submit a multi-leg order. The generated identifiers have the following format:
Order_n
Leg_n
Obtain the generated order identifier from the order identifier field of the order status output feed. Obtain the generated leg identifiers from the leg identifier field of the leg status output feed. The Multi-Leg Order Manager block sends data to these feeds immediately after you place an order. The default is that this parameter is set to false, which means that you must explicitly specify a unique order identifier and unique leg identifiers when you submit a multi-leg order.
Operations
Operation
Description
start multi-leg order
Start submission of a new order. See Submitting multi-leg orders.
submit leg
Add a leg to the current order’s set of legs.
submit multi-leg order
Send the order to the market. The order automatically enters state 1, waiting for acknowledgment.
start modify multi-leg order
Open order for modifications. See Modifying multi-leg orders.
remove leg
Remove the leg identified by the current legId from the order identified by the current orderId.
amend leg
For the leg identified by the current legId, modify the price, quantity, side, type, or extraParams parameter.
amend multi-leg order
Send modified order to the market. The order automatically enters state 5, pending change, unless the order is not modifiable at this time. See Modifying multi-leg orders.
cancel order
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.
cancel leg
Cancel the leg in the market. The leg automatically enters state 6, pending cancel, unless the leg is not modifiable at this time. The market can reject a cancellation. Consequently, after a leg is in the pending cancel state, it can become cancelled, completed, or, if the cancellation is rejected, working.
retrieve order
Retrieve information about the order specified by the orderId parameter. You can obtain the state of a previously placed order even if other orders have been processed since the specified order. Obtain the information from the order status output feed.
retrieve leg
Retrieve information about the leg specified by the legId parameter. Obtain the information from the leg status output feed.
clear
Clears the order status, order iteration complete, and leg iteration complete output feeds. This operation has no effect on the market state. If you have output feeds connected directly to your user interface, you might call this operation to refresh the user interface.
cancel all orders and legs
Cancel all orders and their legs. When the tradeable field of the order book status output feed has a value of 0, all orders are out of the market. Note that the market might reject some cancellations.
iterate orders
Begin iterating over all orders in the Multi-Leg Order Manger block’s order book. The iteration is complete when the order iteration complete output feed becomes true.
iterate legs
Begin iterating over legs that belong to the current order. The iteration is complete when the leg iteration complete output feed becomes true.
next order
Continue to the next order in the iteration. The order in which the next operation visits orders in the order book is undefined.
next leg
Continue to the next leg in the iteration of the current order’s legs. The order in which the next leg operation visits legs in the leg book is undefined.
Input feeds
This block has no input feeds. Instead, the Multi-Leg Order Manager block maintains listeners that listen to events from the market service provider monitors. Since the Multi-Leg Order Manager block does not have any input feeds, you cannot wire another block to the Multi-Leg Order Manager block.
Output feeds
The Multi-Leg Order Manager block generates output in response to events from the market service provider monitors, and Multi-Leg Order Manager block operations. You can wire a Multi-Leg Order Manager block output feed to another block, such as the Position Calculator block. The Multi-Leg Order Manager block provides the following output feeds:
*order status — The Multi-Leg Order Manager block generates the order status output feed upon placement, modification, or cancellation of an order. This feed reports all information about each order, including averages or totals for all legs in a particular order. Each time there is a change in the order, such as a state or status change for any leg, the order status feed provides output. The order status feed also provides output after invocation of an operation on the order, such as retrieving, submitting, or iterating.
*order book status —This feed provides summaries about all legs in all orders in the order book. For example, it indicates how many legs are in each state. The Multi-Leg Order Manager sends information to the order status feed first, and then to this feed.
*leg status — The Multi-Leg Order Manager block generates the leg status output feed upon placement, modification, or cancellation of a leg. Each time there is a change in a leg, such as a state or status change, the leg status feed provides output. The leg status feed also provides output after invocation of an operation on the leg, such as retrieving, submitting, or iterating.
*consistency — This feed indicates whether order status is consistent with the order book status, and whether order status is consistent with the status of each leg. The Multi-Leg Order Manager block sends output to this feed whenever there is a change to the order book.
*order iteration complete — This feed indicates when an iteration through the order book is complete.
*leg iteration complete — This feed indicates when an iteration through the leg book for the current order is complete.
Feed
Fields
Description
order status
order identifier
The Multi-Leg Order Manager block’s unique identifier for the order for which the order status output feed is providing information. This identifier was specified or generated when this order was placed. This identifier distinguishes this order from every other order placed by this block. An order identifier must be unique within the scope of the block that placed the order.
market order identifier
An identifier supplied by the market, typically unique across all orders in that market.
symbol
If all legs in the order are trading the same instrument, this field contains the identifier for the instrument being traded. If all legs are not trading the same instrument, this field is empty.
price
The volume weighted average price of all legs in the order. Takes into account any changes to any legs.
quantity
The total number of units, such as shares, to trade for all legs in the order. Includes any changes to any legs.
state
The order’s state indicated by an integer from 0-9. See Order states and statuses for a description of what each integer signifies.
money executed
The sum of price * quantity for all fills of all legs in this order, or 0.0 if no fills have occurred.
average price executed
The volume-weighted average price over all fills for all legs, or 0.0 if no fills have occurred.
last price executed
The price obtained per item for the last fill, or 0.0 if no fills of any legs in this order have occurred.
quantity executed
The number of items traded so far, or 0.0 if no fills of any legs in this order have occurred.
quantity remaining
The number of items left to trade in the market for all legs in this order, or 0.0 if all items have been traded.
in market
Number of legs in the order that are known to the market.
visible
Number of legs in the order that are 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
Number of legs in the order that can be modified immediately. The Multi-Leg Order Manager block 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
Number of legs in the order that have been rejected or cancelled, possibly before being entered into the market. A cancelled leg might have had some quantity traded.
change rejected
Number of legs in the order for which the most recent modification or cancellation was rejected by the market. An explanation might be available in the status message field.
externally modified
Number of legs in the order that have been modified by anything other than the scenario, for example, the market or a third party.
final
Number of legs in the order that have entered the final state. This means the leg was completed, cancelled, or rejected. Note that a leg in the final state can still be updated. A leg that is settled can no longer be updated.
status message
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.
extra parameters
String that specifies additional parameters in a name=value format.
numLegs
Number of legs in the order.
numSettled
Number of settled legs in the order. A settled leg cannot be updated.
last quantity executed
The number of items traded in the last fill, or 0.0 if no fills of any legs in this order have occurred.
type
The type of the order — MARKET, LIMIT, or some other type supported by the market.
side
The side of the order — BUY, SELL, or some other side supported by the market.
order book status
Provides information about all legs in all orders.
number of orders
The number of orders that are in the block’s order book. This is the number of orders that have been placed from this instance of the Multi-Leg Order Manager block, including those that are final or settled.
total placed
The number of shares that have been ordered from all legs that belong to all orders that were submitted by this instance of the Multi-Leg Order Manager block, and that have reached the market. This includes legs that have been cancelled, rejected, and completed, as well as legs that are in the market. While modifications can cause this number to decrease, cancellations do not.
total executed
The sum of the quantities executed for all legs.
total working
The sum of the quantities remaining to be traded for legs that are in the market. For example, if you submit a leg to buy 100 shares and so far 75 shares have been bought, this adds 25 to the value of total working.
waiting for acknowledgement
The number of legs that are in state 1 — waiting for acknowledgment from the market service provider monitor.
working
The number of legs that are in the market and modifiable. These are the legs that are in state 2 (in the market) and they are not in state 5 (pending change) or state 6 (pending cancel).
complete
The number of legs that are in state 3 (completely filled).
rejected
The number of legs that are in state 4 (rejected). That is, the market rejected the leg.
pending change
The number of legs that are in state 5 (pending change). That is, the leg has been modified but the modified order is not yet in the market.
pending cancel
The number of legs that are in state 6 (pending cancel). That is, the leg has been cancelled but the cancellation has not reached the market.
cancelled
The number of legs that are in state 7 (cancelled).
suspended
The number of legs that are in state 8 (suspended in the market).
in market
The number of legs that are in the market but not necessarily modifiable. These are the legs that are in state 2 (in the market) or state 5 (pending change) or state 6 (pending cancel).
visible
The number of legs that are visible in the market. For example, legs that specify stop orders are invisible until they have been triggered by a particular price.
modifiable
The number of legs that are modifiable.
tradeable
The number of legs that might trade. This count includes every leg that is not completed, cancelled, or rejected. If a scenario waits until it has no outstanding legs in the market, it should wait for the tradeable field to become 0.
final
The number of legs that are in state 3 (completed), state 4 (rejected) or state 7 (cancelled). A final leg can still be updated. For example, if something about a final leg needs to be corrected, the leg might be updated.
settled
The number of legs that are final and cannot be updated.
leg status
leg identifier
The Multi-Leg Order Manager block’s unique identifier for leg for which it is generating information. This identifier distinguishes this leg from every other leg placed by this block.
market order identifier
An identifier supplied by the market, typically unique across all orders in that market.
symbol
Identifier for the instrument this leg is trading.
price
The price requested either when the leg was submitted or the latest modification to the leg. A price of 0.0 signifies a market order.
quantity
The total number of units, such as shares, to trade, or the number the leg has been amended to.
side
The side of the leg — BUY, SELL, or some other side supported by the market.
type
The type of the leg — MARKET, LIMIT, or some other type supported by the market.
state
The order’s state indicated by 0-9. See Order states and statuses.
money executed
The sum of price * quantity for all fills of this leg, or 0.0 if no fills have occurred.
average price executed
The volume-weighted average price over all fills of this leg, or 0.0 if no fills have occurred. For example, suppose you submit a leg 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.
last price executed
The price obtained per item for the last fill for this leg, or 0.0 if no fills have occurred.
last quantity executed
The number of items traded in the last fill for this leg, or 0.0 if no fills of this leg have occurred.
quantity executed
The number of items traded so far, or 0.0 if no fills of this leg have occurred.
quantity remaining
The number of items left to trade in the market as part of this leg.
in market
true if the leg is known to the market.
visible
true if the leg is visible in the market. Some markets consider legs 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 leg can be modified immediately. The Multi-Leg Order Manager block 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 leg has been rejected or cancelled, possibly before being entered into the market. A cancelled leg might have had some quantity traded.
change rejected
true if the most recent modification or cancellation of the leg was rejected by the market. An explanation might be available in the status message field.
externally modified
true if the leg has been modified by anything other than the scenario, such as the market or a third party.
final
true if the quantity specified for the leg has been traded, or if the leg was cancelled or rejected. A final leg can still be updated.
status message
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.
extra parameters
String that specifies additional parameters, which contain more information about the instrument being traded. The string is in a name=value format.
settled
true if this leg is final and can no longer be updated.
consistency
orderStatusBookConsistent
true if order status and order book status are the same. When this field is false, it might indicate a problem.
legOrderConsistent
true if leg status and order status are the same. If every leg has the same status, then the order also has that status, and the legOrderConsistent field would be true. If every leg does not have the same status, then the order would be in the unknown state, and the legOrderConsistent field would be false.
order iteration complete
complete
true if the iteration over the orders placed by this block has completed.
leg iteration complete
complete
true if the iteration over the legs that belong to the current order has completed.
Copyright © 2013-2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.