Implementing Post-trade Allocation

Requirements

To implement FX Sales' Post-trade Allocation, you require:

Front end: FX Sales 2.14.0 or greater
Back end: an integration adapter with a registered implementation of the AllocateTradeListener interface (available from FX Integration API 3.52+).

Implementation checklist

Perform each of the steps below:

Implement the AllocateTradeListener interface
Add the CanAllocate and IsAllocated fields to trade confirmation messages
Grant user permissions
Configure Post-trade Allocation

Implement the AllocateTradeListener interface

In this section you will implement the AllocateTradeListener interface and register your implementation with your trading adapter’s com.caplin.motif.fx.trading.FXTradeAdapter instance.

AllocateTradeListener handles client-sent events in the Allocate trade model, the state diagram for which is reproduced below:

Allocate trade model

Follow the steps below:

Create an implementation of the AllocateTradeListener interface:

In the constructor for your implementation, store a reference to the AllocateTrade constructor parameter:

public class MyAllocateTradeListener implements AllocateTradeListener
{
  private AllocateTrade allocateTrade = null;

  public MyAllocateTradeListener(AllocateTrade allocateTrade)
  {
    this.allocateTrade = allocateTrade;
  }

  ...
}

In the onSubmit(SubmitTradeEvent) method of your implementation, handle the client’s request for trade details:
1. Using the TradeId field of the SubmitTradeEvent as a reference, request the trade’s details from your trading system.
2. Validate the returned trade details. Check the trade is identified by the trading system as allocatable, and perform any further validation required by your implementation.
  - If the trade is invalid, then send a Reject message to the client:
    
    this.allocateTrade.sendRejectTradeEvent();
  - If the trade is valid, then create and send a DetailsUpdate message to the client.
    
    Create an instance of SpotTradeDetails or ForwardTradeDetails using the class’s associated builder, accessed via the newBuilder() method. For documentation on the builders, see SpotTradeDetails.Builder and ForwardTradeDetails.Builder. For example code, see SpotTradeDetails example and ForwardTradeDetails example.
    
    // Build the DetailsUpdate message Message tradeDetails = SpotTradeDetails.newBuilder() .setCommonTradeDetailsFields( ... ) // ... example truncated
    
    Send the SpotTradeDetails or ForwardTradeDetails message to the client:
    
    // Send the DetailsUpdate message to the client this.allocateTrade.sendDetailsUpdateEvent(tradeDetails);
In the onClientClose(ClientCloseEvent) method of your implementation, handle the client’s closure of the allocation:
1. Perform any clean up and logging required by your implementation
2. Send a ClientCloseAck message to the client:
  this.allocateTrade.sendClientCloseAckTradeEvent();
In the onAllocate(AllocateTradeEvent) method of your implementation, handle the client’s allocation request:
1. Retrieve the allocation legs from the AllocateTradeEvent instance.
2. Validate the allocation legs.
  - If the allocation legs are invalid, then send a Reject message to the client:
    
    this.allocateTrade.sendRejectTradeEvent();
  - If the allocation legs are valid, then perform the tasks below:
    
    Re-allocate the trade using your trading system’s API.
    
    Update blotter records for the original trade:
    
    Field Value
    
    Status
    
    Allocated
    
    CanAllocate
    
    false
    
    IsAllocated
    
    true
In the onTradeClosed method in your implementation, handle any clean up and logging required when the trade channel is closed.
Implement and register an instance of AllocateTradeListenerFactory with the FXTradeAdapter instance in your adapter.

The code example below creates and registers an anonymous implementation of the AllocateTradeListenerFactory interface:
```
fxTradeAdapter.registerAllocateTradeListenerFactory(new AllocateTradeListenerFactory() {
  @Override
  public AllocateTradeListener createTradeListener(AllocateTrade trade) throws TradeException {
    return new MyAllocateTradeListener(trade);
  }
})
```
The code above can also be expressed using a Java method reference to the MyAllocateTradeListener constructor, which shares the same method signature as the method createTradeListener in AllocateTradeListenerFactory:
```
fxTradeAdapter.registerAllocateTradeListenerFactory(MyAllocateTradeListener::new);
```

Field	Value
Status	`Allocated`
CanAllocate	`false`
IsAllocated	`true`

Add the CanAllocate and IsAllocated fields to trade confirmation messages

Wherever your back end code creates a trade confirmation message, populate the CanAllocate and IsAllocated fields in the CommonTradeConfirmationFields field set.

The CanAllocate and IsAllocated fields are not included in the CommonTradeDetailsFields field set.

The CommonTradeConfirmationFields field set is used in the following trade models:

ESP (TradeConfirmation message)
RFS (TradeConfirmation message)
Amend (TradeConfirmation message)
SalesIntervention (TradeConfirmation message)

The CommonTradeConfirmationFields field set is used in the following blotter records:

Field definitions

CanAllocate: When you set this field to true, it indicates to front-end applications that the back-end trading system supports allocation of this trade.
IsAllocated: When you set this field to true, it indicates to front-end applications that the trade has been allocated and can no longer be allocated (regardless of the value of CanAllocate).

Front-end applications should refer to the values of both CanAllocate and IsAllocated to determine if a trade is allocatable.

Determining if a trade is allocatable
CanAllocate	IsAllocated	Trade is allocatable?
`false`	`false`
`true`	`false`
`false`	`true`
`true`	`true`

Grant user permissions

Make the following configuration changes to your permissioning adapter:

Define the following action rule:

Field Description

Field	Description
Subject match	`^/PRIVATE/%U/TRADE/FX$`
Field match criteria	`TradingProtocol = "Allocate"`
Product reference field	ALL_PRODUCTS
Action	ALLOCATE
Namespace	POST_TRADE_ALLOCATION

Subject match

^/PRIVATE/%U/TRADE/FX$

Field match criteria

TradingProtocol = "Allocate"

Product reference field

ALL_PRODUCTS

Action

ALLOCATE

Namespace

POST_TRADE_ALLOCATION

Grant users and groups the following permission:

Field Description

Action

ALLOCATE

Product

.*

Namespace

POST_TRADE_ALLOCATION

Authorisation

ALLOW

Field	Description
Action	ALLOCATE
Product	.*
Namespace	POST_TRADE_ALLOCATION
Authorisation	ALLOW

For more information on permissioning, see Permissioning.

For a tutorial on creating a permissioning adapter, see Writing a permissioning adapter.

Configure Post-trade Allocation

The following FX Sales configuration items apply to Post-trade Allocation:

CAPLIN.PTA.ENABLED: Set to true to enable the Post-trade Allocation feature. For more information, see CAPLIN.PTA.ENABLED.
CAPLIN.PTA.ENTITY_SEARCH.ENABLED: Set to true to display the client column in the allocation table on Post-trade Allocation tickets. The client column allows the trader to allocate to a different client than that of the original trade. For more information, see CAPLIN.PTA.ENTITY_SEARCH.ENABLED.
CAPLIN.MOTF.TICKET.ACCOUNT.ALLOW_NULL_SELECTION: Set to true to allow traders to allocate to null trading accounts. Also allows traders to trade against null trading accounts in MOTF tickets. For more information, see CAPLIN.MOTF.TICKET.ACCOUNT.ALLOW_NULL_SELECTION
CAPLIN.MOTF.TICKET.ACCOUNT.AUTO_SELECT_FIRST: Set to true to automatically select the first valid trading account after changing the value in a Client cell in the allocation table on Post-trade Allocation tickets (see CAPLIN.PTA.ENTITY_SEARCH.ENABLED). Also automatically selects the first valid trading account in MOTF tickets. For more information, see CAPLIN.MOTF.TICKET.ACCOUNT.AUTO_SELECT_FIRST

See also: