How do I create a custom transaction template?

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

Note: A custom transaction template overrides a LUSID default transaction template providing the dedicated 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 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/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": []
    }
  ]
}'

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 a Transaction property with a static value, perhaps to specify an additional sub-holding key (SHK). Note that generated transactions automatically inherit the SHKs of the holding they are updating.

• Map an instrument event field to a Transaction property using Mustache templating syntax, for example bond coupon currency.

• Map an InstrumentEvent property to a Transaction property. You have the option to add properties from the InstrumentEvent domain to an event when you manually load it into a corporate action source. For example, you may manually load a BondCouponEvent in order to override an automatically-emitted BondCouponEvent with a different amount.

Consider the following example:

"transactionPropertyMap": [
  {
    "propertyKey": "Transaction/SHKs/Strategy",
    "value": "Growth"
  },
  {
    "propertyKey": "Transaction/Region/Currency",
    "value": "{{BondCouponEvent.currency}}"
  },
  {
    "propertyKey": "Transaction/People/Trader",
    "value": "InstrumentEvent/People/Trader"
  },
]