How do I create a custom transaction template?

Updated
  • Updated on May 13, 2025
  • Published on Aug 20, 2024
Prev Next

You can create a custom transaction template in a dedicated template scope to configure the process of handling a particular type of LUSID instrument event.

You might want to do this to:

  • Change some aspect of the default transaction template, for example the description or the name or source of the transaction type. Note you should exercise care in changing calculated fields (those using Mustache template syntax, for example {{BondCouponEvent.couponPerUnit}}), and also the transactionId which has been calibrated to prevent clashes with transactions generated by other instrument events.

  • Add properties to transactions generated by an instrument event. More information.

  • Delay the impact of an instrument event by up to 24 hours. More information.

Note: A custom transaction template overrides a LUSID default transaction template providing the dedicated template scope in which it resides has been registered with a portfolio. Note if it cannot be located, LUSID falls back to using the default transaction template.

  1. Call the CreateTransactionTemplate API, specifying in the URL:

    • The instrumentEventType to handle.

    • The instrumentType emitting these events.

    • The dedicated template scope (storage location). This is created if it does not exist. Note you cannot add a template to the protected default scope.

  2. In the body of the API request, specify:

    • A friendly description.

    • In the componentTransactions array, a definition for at least one transaction. You can can specify more than one definition if you want to generate different kinds of transaction each time an event is emitted. Each transaction definition:

      • Must have a displayName.

      • Can have a condition. If omitted, a transaction is always generated when an event is emitted. Note a condition uses LUSID's filter syntax, and expressions can be chained using the and and or operators.

      • Must have a transactionFieldMap object that provides instructions for populating (at a minimum) the mandatory fields for a transaction in LUSID. You can specify a static value (of an appropriate data type) for each field, or use Mustache template syntax to insert variables, for example {{eligibleBalance}}. Valid variables are determined by the transaction template specification for the type of event.

      • Can have a transactionPropertyMap to extend the data model of generated transactions.

Note: Once created, you can edit a custom template using the UpdateTransactionTemplate API.

Consider the following example, of a custom template designed to handle events of type BondCouponEvent emitted by instruments of type Bond. The template resides in a MyTransactionTemplates scope, and differs from the default template provided by LUSID as follows:

  • A condition is inserted to specify that a transaction is only generated if the eligibleBalance (number of units held in a portfolio) is greater than a certain number at the time the event is emitted.

  • The transactionId has been customised. Note this ID must be unique within a portfolio, else an existing transaction is updated.

  • The transaction type source has changed to reference a different transaction type (with the same BondCoupon alias, but residing in a different location).

curl -X POST 'https://<your-domain>.lusid.com/api/api/instrumenteventtypes/BondCouponEvent/transactiontemplates/Bond/MyTransactionTemplates' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "description": "My template for overriding the LUSID-provided default bond coupon template.",
  "componentTransactions": [
    {
      "displayName": "Bond Income Override",
      "condition": "{{eligibleBalance}} gt 200",
      "transactionFieldMap": {
        "transactionId": "Automatically-generated txn: {{instrumentEventId}}-{{holdingId}}",
        "type": "BondCoupon",
        "source": "MyTransactionTypeSource",
        "instrument": "{{instrument}}",
        "transactionDate": "{{BondCouponEvent.exDate}}",
        "settlementDate": "{{BondCouponEvent.paymentDate}}",
        "units": "{{eligibleBalance}}",
        "transactionPrice": {
          "price": "{{BondCouponEvent.couponPerUnit}}",
          "type": "CashFlowPerUnit"
        },
        "transactionCurrency": "{{BondCouponEvent.currency}}",
        "exchangeRate": "1",
        "totalConsideration": {
          "amount": "{{BondCouponEvent.couponAmount}}",
          "currency": "{{BondCouponEvent.currency}}"
        }
      },
      "transactionPropertyMap": []
    }
  ]
}'
JSON

Coming soon

Coming soon

You can extend the data model of generated transactions by populating the transactionPropertyMap object on a custom transaction template.

You can add any number of properties from the Transaction domain to generated transactions; values for these properties can be:

  • Static values. You might to use this to specify additional sub-holding keys (SHK). Note that generated transactions automatically inherit the SHKs of the holding they are updating.

  • Mapped from an instrument event field using Mustache template syntax.

  • Mapped from a Portfolio property added to the parent portfolio.

  • Mapped from an InstrumentEvent property added to an instrument event that was manually loaded into a corporate action source.

Consider the following example:

"transactionPropertyMap": [
  {
    "propertyKey": "Transaction/SHKs/Strategy",
    "value": "Growth"
  },
  {
    "propertyKey": "Transaction/Region/Currency",
    "value": "{{BondCouponEvent.currency}}"
  },
  {
    "propertyKey": "Transaction/Accounting/Expense",
    "value": "Portfolio/default/ExpenseTreatment"
  },
  {
    "propertyKey": "Transaction/People/Trader",
    "value": "InstrumentEvent/People/Trader"
  },
]
JSON