Views:

When you create a transaction type in LUSID you must specify a side for each movement. Put simply, the side tells LUSID which attributes (required, optional and/or properties) to use when converting a transaction into a set of movements that are used to generate the holding for the underlying instrument in a transaction portfolio.

Using a built-in side

An example of a side is the built-in "Side1":

FieldValue for Side1Description
sideSide1The unique name for the side.
securityTxn:LusidInstrumentIdThe security to use for the side. In this example this is the security that the transaction resolves to as identified by its unique LUID.
currencyTxn:TradeCurrencyThe currency to use for the side. In this example this is the transaction currency on a transaction.
rateTxn:TradeToPortfolioRateThe exchange rate to the portfolio's base currency. This is used to maintain the cost basis in the portfolio's base currency.
unitsTxn:UnitsThe units to use for the side. In this example this is the Units on a transaction.
amountTxn:TradeAmountThe 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 fields on a transaction.

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

FieldValid side valuesDescriptionExample value
securityTxn:LusidInstrumentIdThe transaction's LUID.LUID_98ABCDJK
Txn:TradeCurrencyThe transaction's currency.CCY_USD
Txn:SettlementCurrency or Txn:SettleCcyThe transaction's settlement currency.CCY_GBP
Txn:PortfolioCurrencyThe portfolio's currency.CCY_JPY
A transaction propertyA 3-stage property key representing a custom property in the Transaction domain, for example Transaction/Demo/BuyAmountCcy. The property must either use the built-in String data type or have a custom data type with a primitive valueType of String. The property value must contain a valid instrument LUID, currency LUID, or ISO 4217 currency code.LUID_98ABCDJK or CCY_GBP or GBP
currencyTxn:TradeCurrencyThe transaction's currency.GBP
Txn:SettlementCurrency or Txn:SettleCcyThe transaction's settlement currency.USD
Txn:PortfolioCurrencyThe portfolio's currency.EUR
A transaction propertyA 3-stage property key representing a custom property in the Transaction domain, for example Transaction/Demo/BuyAmountCcy. The property must either use the built-in currency or iso4217Currency data type, or have a custom data type with a primitive valueType of String. The property value must contain a valid ISO 4217 currency code or currency LUID.JPY or CCY_JPY
rateTxn:TradeToPortfolioRateThe exchange rate between the transaction's trade currency and the portfolio base currency added to the transaction using the Transaction/default/TradeToPortfolioRate system property.1.09
SettledToPortfolioRateThe portfolio rate divided by the exchange rate, where portfolio rate is the rate from trade currency to portfolio currency and exchange rate is the rate from trade currency to settlement currency.1.78
A transaction propertyA 3-stage property key representing a custom property in the Transaction domain, for example Transaction/Demo/FxRate. The property must either use the built-in number or currencyAndAmount data type, or have a custom data type with a primitive valueType of Decimal or Int. The property value must contain a parsable numeric value.1.17
A constant valueFor example, 1.0 when using Txn:PortfolioCurrency as the currency.1.0
units, amount, notionalAmount

(note notionalAmount can only be set using the SetSideDefinition API)
Txn:UnitsThe transaction's units.100
Txn:TotalConsiderationThe transaction's value in the settlement currency. 12678
Txn:TradeAmountThe total consideration converted to the trade currency via the exchange rate.12678
Txn:BondInterestThe accrued interest in the settlement currency that is included in the purchase/sale of a bond added to a transaction using the Transaction/default/BondInterest system property.90000
BasedOnSeparateBondInterestThe transaction's total consideration with the bond interest subtracted where the bond interest is the value of the Transaction/default/BondInterest system property.82000
Txn:BondInterestPortfolioThe bond interested recorded using the Transaction/default/BondInterest system property converted to the portfolio currency.75000
A transaction propertyA 3-stage property key representing a custom property in the Transaction domain, for example Transaction/Demo/Commission. The property must either use the built-in number or currencyAndAmount data type, or have a custom data type with a primitive valueType of Decimal or Int. The property value must contain a parsable numeric value.302345
A constant valueFor example, 0 when the units are not updated ie. a cost adjustment.0

Sides are returned as part of the response to List transaction types.

Creating a custom side

You can create custom sides using LUSID's System Configuration APIs (note these are being progressively replaced by the Transaction Configuration APIs) . 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:

FieldValueDescription
sideTradeCommissionsThe unique name for the side.
securityTxn:LusidInstrumentIdThe security to use for the side. In this example this is the security that the transaction resolves to as identified by its unique LUID.
currencyTxn:SettlementCurrencyThe currency to use for the side. In our example this is the settlement currency on a transaction.
rateTransaction/custodian/exchange_rateThe rate to use for the side. In this example this is the custom property Transaction/custodian/exchange_rate.
unitsTransaction/custodian/broker_commissionThe units to use for the side. In this example this is the custom property Transaction/custodian/broker_commission.
amountTransaction/custodian/broker_commissionThe 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 3-stage property key instead of just the default transaction attributes.

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

Missing fieldBehaviour
securityThe instrument will resolve to the unknown instrument with "LUID_ZZZZZZZ"
currencyThe currency will resolve to the unknown currency "ZZZ"
rateThe rate will default to zero (0)
unitsThe units will default to zero (0)
amountThe amount will default to zero (0)