How does LUSID resolve transaction templates and types for corporate action events?

  • Updated on Apr 2, 2025
  • Published on Mar 10, 2025

LUSID provides a default transaction template for every type of corporate action event, domiciled in the default (that is, system) template scope.

A default transaction template mandates a transaction type with a particular name (alias) and source for each transaction it generates in response to that event, and in addition expects to locate the transaction type in a particular scope. Note a transaction type scope is not the same as a transaction template scope. More on transaction type scope and source resolution.

You have the option to override a default transaction template for an event by creating one in a custom template scope, and specify a transaction type with a different name and source. If you do, you must register this custom template scope with each portfolio you wish the event to impact.

The following troubleshooting diagram summarises how LUSID resolves transaction templates and transaction types each time it emits an event, using CashDividendEvent as an example:

One or more transactions should be automatically generated in a portfolio in response to an instrument event. If they are not, the first step is to call the QueryApplicableInstrumentEvents API for that portfolio.

You should see a record of each emitted event. Note the following:

  • An event has a completeness status, which can either be Complete or Incomplete. Some events require market data in order to calculate amounts, for example fixings for inflation-linked bonds.

  • If the status is Incomplete, there should be a generatedEventDiagnostics object in the response that helps diagnose the problem, for example:

  • The transactions array should preview transaction(s) generated by the event. If this array is empty, it may mean LUSID cannot resolve the transaction type:

    • There may be a problem with the transaction type source. Are you using the default transaction template?

      • YES: The transaction type must be domiciled in the default source. Is there a transaction type with the expected name in this source?

      • NO: Have you specified a different source in your custom transaction template? Is there a transaction type with this name in this source?

    • There may be a problem with the transaction type scope. Does your portfolio have a transaction type scope set? (again, note this is not the same as a transaction template scope):

      • NO: The transaction type must be stored in the default scope. Is there a transaction type with the expected name and source in that scope?

      • YES: The transaction type must be stored in your custom scope. Is there a transaction type with the expected name and source in that scope?

Note a successfully-previewed transaction has a resolvedTransactionTypeDetails object that identifies the resolved transaction type, in this case DividendIncome in the default source and default scope:

{
  "values": [
    {
      "portfolioId": {
        "scope": "Equities",
        "code": "UKGrowth"
      },
      "holdingId": 75513281,
      "lusidInstrumentId": "LUID_00003EBB",
      "instrumentScope": "default",
      "instrumentType": "Equity",
      "instrumentEventType": "CashDividendEvent",
      "instrumentEventId": "BBG000BPH459-2024-02-06",
      "loadedEvent": {
        "instrumentEventId": "BBG000BPH459-2024-02-06",
        "corporateActionSourceId": {
          "scope": "CAS",
          "code": "UKPortfolios"
        },
        "instrumentIdentifiers": {
          "Instrument/default/Figi": "BBG000BPH459"
        },
        "lusidInstrumentId": "LUID_00003EBB",
        "instrumentScope": "default",
        "description": "BBG000BPH459-2024-02-06",
        "eventDateRange": {
          "start": "2024-02-06T00:00:00.0000000+00:00",
          "end": "2024-02-10T00:00:00.0000000+00:00"
        },
        "completeness": "Complete",
        "instrumentEvent": {
          "paymentDate": "2024-02-10T00:00:00.0000000+00:00",
          "exDate": "2024-02-06T00:00:00.0000000+00:00",
          "cashElections": [
            {
              "electionKey": "USD",
              "exchangeRate": 1,
              "dividendRate": 0.2,
              "isChosen": false,
              "isDeclared": true,
              "isDefault": true,
              "dividendCurrency": "USD"
            },
            {
              "electionKey": "GBP",
              "exchangeRate": 0.8,
              "dividendRate": 0.16,
              "isChosen": true,
              "isDeclared": false,
              "isDefault": false,
              "dividendCurrency": "GBP"
            }
          ],
          "announcementDate": "2024-02-06T00:00:00.0000000+00:00",
          "recordDate": "2024-02-06T00:00:00.0000000+00:00",
          "instrumentEventType": "CashDividendEvent"
        },
        "properties": [],
        "sequenceNumber": 0,
        "participationType": "MandatoryWithChoices"
      },
      "transactions": [
        {
          "transactionId": "BBG000BPH459-2024-02-06-75513281",
          "type": "DividendIncome",
          "instrumentIdentifiers": {
            "Instrument/default/LusidInstrumentId": "LUID_00003EBB"
          },
          "instrumentScope": "default",
          "instrumentUid": "LUID_00003EBB",
          "transactionDate": "2024-02-06T00:00:00.0000000+00:00",
          "settlementDate": "2024-02-10T00:00:00.0000000+00:00",
          "units": 1000,
          "transactionPrice": {
            "price": 0.2,
            "type": "CashFlowPerUnit"
          },
          "totalConsideration": {
            "amount": 160,
            "currency": "GBP"
          },
          "exchangeRate": 0.8,
          "transactionCurrency": "USD",
          "properties": {
            "Transaction/Ccy/OriginalDivCcy": {
              "key": "Transaction/Ccy/OriginalDivCcy",
              "value": {
                "labelValue": "USD"
              }
            },
            "Transaction/SHKs/CashDividends": {
              "key": "Transaction/SHKs/CashDividends",
              "value": {
                "labelValue": "<Not Classified>"
              }
            }
          },
          "source": "default",
          "entryDateTime": "0001-01-01T00:00:00.0000000+00:00",
          "transactionStatus": "Active",
          "transactionGroupId": "BBG000BPH459-2024-02-06",
          "resolvedTransactionTypeDetails": {
            "scope": "default",
            "source": "default",
            "type": "DividendIncome"
          }
        }
      ]
    }
  ],
  ...
}
JSON