How do I create a custom transaction template?

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 LUSID default transaction template, for example the description or the type (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.

• Prevent an instrument event impacting a portfolio before a certain date (see condition statement in example below).

• Delay transaction generation 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.

Using the LUSID REST API

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 ex-date of the coupon is after a particular date registered with the portfolio.

• 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": "{{BondCouponEvent.exDate}} gt {{Portfolio/My_date_property_scope/My_date_property_code}}",
      "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": []
    }
  ]
}'

Using Luminesce

Coming soon

Using the LUSID web app

Coming soon

Adding properties to generated transactions

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"
  },
]