What is a transaction template?

A transaction template is a blueprint for LUSID to automatically generate transactions in appropriate portfolios in response to a particular type of instrument event.

For example, LUSID emits a bond coupon event every time a coupon is due on an instrument mastered as type Bond. LUSID also provides a default transaction template for bond coupon events that automatically generates an output transaction for the coupon amount in every portfolio with a holding in that bond. You can use the default transaction template as-is, or create your own custom template to override and configure the process.

Note that an instrument event can be:

LUSID provides a default transaction template for every type of event. To examine a template, call the GetTransactionTemplate API, specifying:

  • The appropriate instrumentEventType, for example BondCouponEvent.

  • An instrumentType emitting this event, for example Bond.

  • A scope of default. Note this is a protected scope and you cannot edit the default transaction templates, nor add your own in this location.

For example:

curl -X GET "https://<your-domain>.lusid.com/api/api/instrumenteventtypes/BondCouponEvent/transactiontemplates/Bond/default" 
  -H "Authorization: Bearer <your-API-access-token>"

The response to this call is currently as follows (note default transaction templates may evolve over time):

{
  "instrumentType": "Bond",
  "instrumentEventType": "BondCouponEvent",
  "description": "LUSID default template for automatically generated transactions in respect of Bond Coupon instrument events.",
  "scope": "default",
  "componentTransactions": [
    {
      "displayName": "Bond Income",
      "transactionFieldMap": {
        "transactionId": "{{instrumentEventId}}-{{holdingId}}",
        "type": "BondCoupon",
        "source": "default",
        "instrument": "{{instrument}}",
        "transactionDate": "{{BondCouponEvent.exDate}}",
        "settlementDate": "{{BondCouponEvent.paymentDate}}",
        "units": "{{eligibleBalance}}",
        "transactionPrice": {
          "price": "{{BondCouponEvent.couponPerUnit}}",
          "type": "CashFlowPerUnit"
        },
        "transactionCurrency": "{{BondCouponEvent.currency}}",
        "exchangeRate": "1",
        "totalConsideration": {
          "currency": "{{BondCouponEvent.currency}}",
          "amount": "{{BondCouponEvent.couponAmount}}"
        }
      },
      "transactionPropertyMap": []
    }
  ],
  ...
}

Note the following:

  • This template handles instrument events of type BondCouponEvent emitted by instruments of type Bond.

  • It is domiciled in the default (that is, system) transaction template scope.

  • It generates a single transaction for each portfolio with a holding in the underlying instrument. Note it is possible for a template to generate multiple transactions.

  • This transaction has no condition; that is, it is always produced when LUSID emits a bond coupon event.

  • This transaction belongs to a BondCoupon transaction type, which must exist in the default transaction type source.

  • The transactionDate is the ex-dividend date and the settlementDate is the payment date.

  • The quantity held (units) is assessed dynamically per-portfolio and per-coupon.

  • The transactionPrice.price is the coupon per unit, which is calculated as the annual coupon rate multiplied by the principal and divided by the number of coupons per year.

  • The transactionCurrency is the currency specified in the bond economic definition, and an exchangeRate of 1 means the settlement currency is the same.

  • The totalConsideration.Amount is the coupon per unit scaled by the quantity held.

Note this template does not set the Transaction/default/TradeToPortfolioRate system property to calculate the cost basis of the transaction in the portfolio currency, where this is different to the transaction/settlement currency. A mechanism for setting an exchange rate for foreign currency transactions is coming soon.