Implementing Post-trade Allocation


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 instance.

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

InitialDetailsRequestedDetailsProvidedRejectedClientCloseSentAllocateSentAllocatedErrorClientClosedSubmitDetailsUpdateRejectClientCloseAllocateClientCloseAllocateAckRejectErrorHoldWithdrawClientCloseAckLegendTransitions initiated by the client are inyellow.Transitions initiated by the server are inblue.
Allocate trade model

Follow the steps below:

  1. Create an implementation of the AllocateTradeListener interface:, Throwable)onSubmit(SubmitTradeEvent)onTradeClosed()onError(TradeEvent, Throwable)onUnhandledTradeEvent(AllocateTrade, TradeEvent)receiveInvalidFieldsEvent(InvalidFieldsEvent)receiveInvalidTransitionEvent(InvalidTransitionEvent)MyAllocateTradeListenerAllocateTrade allocateTradeMyAllocateTradeListener(AllocateTrade)onAllocate(AllocateTradeListener)onClientClose(ClientCloseTradeEvent)onSubmit(SubmitTradeEvent)onTradeClosed()Default methodsonError,onUnhandledTradeEvent,receiveInvalidFieldsEvent, andreceiveInvalidTransitionEventare not overriddenin this example.
  2. 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;
  3. 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:

      • If the trade is valid, then create and send a DetailsUpdate message to the client.

        1. 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
        2. Send the SpotTradeDetails or ForwardTradeDetails message to the client:

          // Send the DetailsUpdate message to the client
  4. 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:

  5. 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:

      • If the allocation legs are valid, then perform the tasks below:

        1. Re-allocate the trade using your trading system’s API.

        2. Update blotter records for the original trade:

          Field Value







  6. In the onTradeClosed method in your implementation, handle any clean up and logging required when the trade channel is closed.

  7. 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() {
      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:


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

When you set this field to true, it indicates to front-end applications that the back-end trading system supports allocation of this trade.


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?









Grant user permissions

Make the following configuration changes to your permissioning adapter:

  1. Define the following action rule:

    Field Description

    Subject match


    Field match criteria

    TradingProtocol = "Allocate"

    Product reference field






  2. Grant users and groups the following permission:

    Field Description









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:


Set to true to enable the Post-trade Allocation feature. For more information, see CAPLIN.PTA.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.


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


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: