What is a transaction type calculation?

A calculation is an optional component of a transaction type that triggers additional functionality for all transactions belonging to that type. 

A calculation:

• Must have a type that triggers a particular LUSID function.

• Can have a side to pass extra information to the function.

• Can have a formula that drives the function.

• Must have a transactionFeeId and transactionFeeCapitalisation to drive Fee calculations.

Only one instance of any calculation is allowed per transaction type except for Fee.

Note: The result of a calculation can be examined on an output transaction.

Fee calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: YES

Calculates a particular transaction fee according to a formula, for example an exchange fee or a broker fee.

You can add as many Fee calculations to a transaction type as there are transaction fees to calculate. Each must identify a transaction fee definition determining the formula, and decide whether the result is capitalised or not:

• The transactionFeeId must reference the scope and code of a transaction fee definition.

• transactionFeeCapitalisation.capitalisation must be either Capitalised, NonCapitalised or Conditional.

• If the above is Conditional, you must specify a transactionFeeCapitalisation.capitalisedCondition. If the expression evaluates to true, the fee is capitalised; otherwise it is uncapitalised.

The result is stored in the custom output property nominated by the transaction fee definition, and automatically added to the output transaction.

"calculations": [
  {
    "type": "Fee",
    "transactionFeeId": {
      "scope": "TradeFees",
      "code": "Broker"
    },
    "transactionFeeCapitalisation": {
      "capitalisation": "Capitalised"
    }
  },
  {
    "type": "Fee",
    "transactionFeeId": {
      "scope": "TradeFees",
      "code": "Exchange"
    },
    "transactionFeeCapitalisation": {
      "capitalisation": "Conditional",
      "capitalisedCondition": "Transaction.units gt 200"
    }
  }
]

TaxAmounts calculation

• Requires side: YES

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Calculates tax amounts due. More information.

Note the following:

• The result is stored in the custom output property nominated by the tax rule set, and automatically added to the output transction.

• The side is required to pass information about the underlying instrument to the tax calculation engine. See an example.

• This calculation is ignored for a particular transaction if no tax rule set can be found to apply.

"calculations": [
  {
    "type": "TaxAmounts",
    "side": "Side1"
  }
]

TransactionSequence calculation

• Requires side: NO

• Requires formula: YES

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Determines the order in which transactions are processed relative to transactions belonging to other transaction types if all are loaded into LUSID with identical effective at datetimes. More information.

The formula field must contain, or resolve to, an integer. The lower the number, the higher the priority in the processing queue. A formula can contain the following components:

• A constant value, for example "1" or "98765".

• A transaction field, for example "units", or property or derived property, for example "Properties[Transaction/default/GrossConsideration]".

• An instrument field, for example "Instrument.InstrumentDefinition.InstrumentType".

For example, you could specify a TransactionSequence formula of "2" for a Buy transaction type:

"calculations": [
  {
    "type": "TransactionSequence",
    "formula": "2"
  }
]

…and a TransactionSequence formula of "1" for a Sell transaction type:

"calculations": [
  {
    "type": "TransactionSequence",
    "formula": "1"
  }
]

This means that if a Buy transaction and a Sell transaction are loaded into LUSID with identical effective at datetimes then the Sell transaction is processed first, even if it is loaded second in the same request (and therefore has a slightly later as at entry datetime).

Note you can use LUSID derived property formula syntax to create conditional statements, so for example:

"calculations": [
  {
    "type": "TransactionSequence",
    "formula": "If(Instrument.InstrumentDefinition.InstrumentType eq 'Equity') Then 2 Else 3"
  }
]

Txn:TradeToPortfolioRate calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Looks up an exchange rate from the transaction to the portfolio currency in the LUSID Quote Store. More information.

Note the following:

• The lookup is performed for the transaction date, not the settlement date (if they are different).

• The result is stored in the Transaction/default/TradeToPortfolioRate system property.

• This calculation is ignored if Transaction/default/TradeToPortfolioRate is explicitly added to a particular transaction.

"calculations": [
  {
    "type": "Txn:TradeToPortfolioRate"
  }
]

Txn:ExchangeRate calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Looks up an exchange rate from the transaction to the settlement currency in the LUSID Quote Store. More information.

Note the following:

• The lookup is performed for the transaction date, not the settlement date (if they are different).

• The result is stored in the exchangeRate field.

• This calculation is ignored if exchangeRate is explicitly set on a particular transaction.

"calculations": [
  {
    "type": "Txn:ExchangeRate"
  }
]

Txn:Netback calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Calculates the cost of the unfounded amount for transactions in instruments of type LoanFacility. The result is stored in the Transaction/default/Netback system property.

Please contact Technical Support for more information.

"calculations": [
  {
    "type": "Txn:Netback"
  }
]

Txn:NotionalAmount calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Calculates notional amount for transactions in instruments of type Future and ContractForDifference. More information.

Note the following:

• For most contracts the calculation is txn price * txn units * (contract size / scale factor).

• The calculated amount is in transaction currency, not settlement currency (if they are different).

• The result is stored in the Transaction/default/NotionalAmount system property. See an example.

• This calculation is ignored if Transaction/default/NotionalAmount is explicitly added to a particular transaction.

"calculations": [
  {
    "type": "Txn:NotionalAmount"
  }
]

Txn:BondInterest calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Calculates accrued interest for transactions in instruments of type Bond, ComplexBond, InflationLinkedBond, CdsIndex and CreditDefaultSwap. More information.

Note the following:

• The calculated amount is in transaction currency, not settlement currency (if they are different).

• Accrual is calculated up to settlement date, not transaction date (if they are different).

• The result is stored in the Transaction/default/BondInterest system property. See an example.

• This calculation is ignored if Transaction/default/BondInterest is explicitly added to a particular transaction.

"calculations": [
  {
    "type": "Txn:BondInterest"
  }
]

Txn:GrossConsideration calculation

• Requires side: NO

• Requires formula: NO

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Calculates gross consideration as an amount including accrued interest but before fees. More information.

Note the following:

• The calculated amount is in settlement currency, not transaction currency (if they are different).

• The result is stored in the Transaction/default/GrossConsideration system property.

• This calculation is ignored if Transaction/default/GrossConsideration is explicitly added to a particular transaction.

"calculations": [
  {
    "type": "Txn:GrossConsideration"
  }
]

The calculation depends on the instrument type:

DeriveTotalConsideration calculation

• Requires side: NO

• Requires formula: YES

• Requires transactionFeeId or transactionFeeCapitalisation: NO

Calculates total consideration according to a user-specified formula. Note that LUSID typically expects this to be after fees, in contrast with gross consideration which is before fees. More information.

Note: The totalConsideration.amount field must be set to 0 on an input transaction for this calculation to occur. It cannot be omitted. The totalConsideration.currency field can be set as normal.

Note the following:

• The calculated amount is in settlement currency, not transaction currency (if they are different).

• The result is stored in the totalConsideration.amount field on an output transaction. See an example.

• This calculation is ignored if totalConsideration.amount is set to an amount other than 0 on a particular input transaction.

For example, for transactions that increase a position you might want to calculate total consideration as gross consideration plus fees. Note that if you include any other calculations in the formula (such as Txn:GrossConsideration) then you must also include them in the transaction type:

"calculations": [
  {
    "type": "DeriveTotalConsideration",
    "formula": "Txn:GrossConsideration + Properties[Transaction/Fees/TotalCapitalisedFees]"
  },
  {
    "type": "Txn:GrossConsideration"
  }
]

For transactions that reduce a position you might want to calculate total consideration as gross consideration minus fees.

"calculations": [
  {
    "type": "DeriveTotalConsideration",
    "formula": "Txn:GrossConsideration - Properties[Transaction/Fees/TotalCapitalisedFees]"
  },
  {
    "type": "Txn:GrossConsideration"
  }
]