What is a transaction template specification?

A transaction template specification is a set of rules that a transaction template must adhere to in order to handle a particular type of LUSID instrument event.

Note that an instrument event can either be:

LUSID provides a transaction template specification for every type of event, for example BondCouponEvent. To examine this template specification, call the GetTransactionTemplateSpecification API as follows:

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

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

{
  "instrumentEventType": "BondCouponEvent",
  "supportedInstrumentTypes": [
    "Bond",
    "ComplexBond",
    "InflationLinkedBond"
  ],
  "supportedParticipationTypes": [
    "Mandatory"
  ],
  "supportedElectionTypes": [],
  "supportedTemplateFields": [
    {
      "fieldName": "holdingId",
      "specificity": "AllEventsAndHoldings",
      "description": "The id of the holding to which the instrument event is being applied",
      "type": "String",
      "usage": [
        "holdingId"
      ]
    },
    {
      "fieldName": "holdingCurrency",
      "specificity": "AllEventsAndHoldings",
      "description": "The currency of the holding to which the instrument event is being applied",
      "type": "Currency",
      "usage": [
        "holdingCurrency"
      ]
    },
    {
      "fieldName": "instrumentEventId",
      "specificity": "AllEventsAndHoldings",
      "description": "The id of the instrument event that is being applied to the holding",
      "type": "String",
      "usage": [
        "instrumentEventId"
      ]
    },
    {
      "fieldName": "instrument",
      "specificity": "AllEventsAndHoldings",
      "description": "The instrument of the holding and instrument event",
      "type": "InstrumentId",
      "usage": [
        "instrument"
      ]
    },
    {
      "fieldName": "eligibleBalance",
      "specificity": "AllEventsAndHoldings",
      "description": "The number of units of the instrument held on the instrument event's entitlement date (typically the exDate)",
      "type": "Decimal",
      "usage": [
        "eligibleBalance"
      ]
    },
    {
      "fieldName": "exDate",
      "specificity": "InstrumentEventType",
      "description": "The ex date (entitlement date) of the coupon",
      "type": "DateTime",
      "usage": [
        "BondCouponEvent.exDate"
      ]
    },
    {
      "fieldName": "paymentDate",
      "specificity": "InstrumentEventType",
      "description": "The payment date of the coupon",
      "type": "DateTime",
      "usage": [
        "BondCouponEvent.paymentDate"
      ]
    },
    {
      "fieldName": "currency",
      "specificity": "InstrumentEventType",
      "description": "The currency in which the coupon is paid",
      "type": "Currency",
      "usage": [
        "BondCouponEvent.currency"
      ]
    },
    {
      "fieldName": "couponPerUnit",
      "specificity": "InstrumentEventType",
      "description": "The coupon amount received for each unit of the instrument held on the ex date",
      "type": "Decimal",
      "usage": [
        "BondCouponEvent.couponPerUnit"
      ]
    },
    {
      "fieldName": "couponAmount",
      "specificity": "InstrumentEventType",
      "description": "The total coupon amount received for the holding, calculated as couponPerUnit x eligibleBalance",
      "type": "Decimal",
      "usage": [
        "BondCouponEvent.couponAmount"
      ]
    }
  ],
  "eligibilityCalculation": {
    "entitlementDate": "exDate",
    "eligibleUnits": "SettledUnits"
  }
}

Note the following:

  • This transaction template specification defines rules for a transaction template designed to handle instrument events of type BondCouponEvent.

  • The supportedInstrumentTypes array lists the types of instrument that emit this event.

  • The supportedParticipationTypes array lists only Mandatory because instrument lifecycle events have no user input and are always mandatory. A corporate action event, on the other hand, can be optional or have elective choices defined in the supportedElectionTypes array. 

  • The supportedTemplateFields array lists the variables available to include in a transaction template. In each, the usage array defines the syntax for use with the Mustache template system, so for example you can insert a variable representing a bond coupon amount as {{BondCouponEvent.CouponAmount}}.

  • The eligibilityCalculation object defines how the eligible balance is calculated. For a bond coupon, this is the number of settled units held in a portfolio on the ex-dividend date; note this might be different to the number of traded units.