How do I create a custom transaction template?

Providing you have suitable access control permissions, 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. See how to do this.

The following methods are available:

• Using the LUSID REST API
• Using the LUSID web app (coming soon)
• Using Luminesce (coming soon)
   

Using the LUSID REST API

1. Obtain an API access token.
2. Call the CreateTransactionTemplate API, passing in your API token and 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.
3. 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 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.
   • Optionally in the transactionPropertyMap array, one or more properties, each consisting of a propertyKey (3-stage property type) and a value.

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 (highlighted in red below) 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 (in green). Note this ID must be unique within a portfolio, else an existing transaction is updated.
• The transaction type source has changed (in yellow) 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 the LUSID web app