What is a Side in LUSID?

When I am configuring transaction types I need to specify a "Side", what is this and how does it work?

When you configure a Transaction Type in LUSID you will need to specify a Side for each Movement. Put simply the Side tells LUSID which attributes (required, optional and/or properties) to use from the transaction to specify values for the units, security, currency, exchange rate and total amount used in generating the holdings for a portfolio.

 

An Example using LUSID's predefined side values

An example of this is the default Side named "Side1". You can see its definition below.

Field Value Description
side Side1 The unique name for the side. In this example "Side1". 
security Txn:LusidInstrumentId The security to use for the side. In this example this is the security that the Transaction resolves to as identified by its unique LUSID Instrument Id.
currency Txn:TradeCurrency The currency to use for the side. In this example this is the TransactionCurrency on a Transaction.
rate Txn:TradeToPortfolioRate The exchange rate to the portfolio's base currency. This is used to maintain the cost basis in the portfolio's base currency.
units Txn:Units The units to use for the side. In this example this is the Units on a Transaction.
amount Txn:TradeAmount The amount to use for the side. In this example this is a calculated field which uses other attributes on the Transaction.

 


Here you can see that each of the attributes are all prefixed with "Txn:" as they are either required, optional or calculated attributes on a Transaction.

The full list of predefined "Txn:" values for each Field in the side configuration is contained in the table below:

 

Field Valid side values Description Example value
security Txn:LusidInstrumentId The transaction's LUID. LUID_98ABCDJK
security Txn:SettlementCurrency The transaction's settlement currency. CCY_USD
currency Txn:TradeCurrency The transaction's currency. GBP
currency Txn:SettlementCurrency The transaction's settlement currency. USD
rate Txn:TradeToPortfolioRate The exchange rate between the transaction's trade currency and the portfolio base currency added to the transaction using the property Transaction/default/TradeToPortfolioRate 1.09
rate Txn:SettledToPortfolioRate The exchange rate between the transaction's settle currency and the portfolio base currency. 1.78
units Txn:Units The transaction's units.  
units Txn:BondInterest The accrued interest in the settlement currency that is included in the purchase/sale of a bond added to a transaction using the property Transaction/default/BondInterest 12678
units Txn:TotalConsideration The transaction's value in the settlement currency. 102000
units Txn:BasedOnSeparateBondInterest The transaction's total consideration with the bond interest subtracted. 122000
units Txn:TradeAmount The transaction's value in the transaction currency. 8000

 

Custom Sides

You can create custom sides via LUSID's SystemConfiguration API. This allows you to pick the values for the units, currency, security etc. from custom defined properties rather than the default transaction fields. You can find a great example of creating a side in the sample Jupyter notebook Tracking Your Trading Commissions. In the notebook the Side configuration is as follows:

Field Value Description
side TradeCommissions The unique name for the side. In this example "TradeCommissions". 
security Txn:LusidInstrumentId The security to use for the side. In this example this is the security that the Transaction resolves to as identified by its unique LUSID Instrument Id.
currency Txn:SettlementCurrency The currency to use for the side. In our example this is the Settlement Currency on a Transaction.
rate Transaction/custodian/exchange_rate The rate to use for the side. In this example this is the custom property Transaction/custodian/exchange_rate.
units Transaction/custodian/broker_commission The units to use for the side. In this example this is the custom property Transaction/custodian/broker_commission.
amount Transaction/custodian/broker_commission The amount to use for the side. In this example this is the custom property Transaction/custodian/broker_commission.


In this instance you can see the use of custom properties defined by their three part property key instead of just the default transaction attributes.

 

Missing Values

Note that if you upsert a transaction with missing values for properties used by a custom Side the behaviour is as follows:

Missing Field Behaviour
security The instrument will resolve to the LUSID unknown instrument with "LUID_ZZZZZZZ"
currency The currency will resolve to the unknown currency "ZZZ"
rate The rate will default to zero (0)
units The units will default to zero (0)
amount The amount will default to zero (0)