Adjusting times and delaying the impact of instrument events

By default, LUSID emits instrument events at UTC midnight, and so transactions generated by those events impact portfolios at the same time.

Note: The information in this article applies to both instrument lifecycle and corporate action events unless otherwise stated.

You can configure the definition of an instrument to add some or all of the following:

A primary timezone so that events are emitted at local midnight rather than UTC midnight.
A start of day time in that timezone so events are emitted at that time rather than local midnight, perhaps to account for daylight saving.
A market open time in that timezone so that generated transactions impact portfolios when the market is open, and market data is available, rather than when the events are emitted.

Example: Configuring the timing of a Microsoft cash dividend

Consider a variation on this example of a CashDividendEvent, with date stamps instead of the exDate and paymentDate datetime fields:

{
  "instrumentEventId": "MSCashDividend-2024-02-06",
  "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},
  "description": "Cash dividend of 20 cents per share",
  "participationType": "MandatoryWithChoices",
  "eventDateStamps": {
    "exDate": {
      "day": 6,
      "month": 2,
      "year": 2024
    },
    "paymentDate": {
      "day": 10,
      "month": 2,
      "year": 2024
    },
  },
  "instrumentEvent": {
    "instrumentEventType": "CashDividendEvent",
    ...

Since no explicit time or timezone information is available for date stamps, and the datetime fields themselves are omitted, LUSID:

Emits the CashDividendEvent on 6 February 2024 at UTC midnight.
Generates a transaction representing the dividend payment amount with a:
- Transaction date of the exDate: 6 February 2024 at UTC midnight.
- Settlement date of the paymentDate: 10 February at UTC midnight.

Note: If you specify both date stamps and corresponding datetime fields, the latter are preferred.

Let’s imagine we want to change this to:

Emit the event in the New York timezone rather than UTC.
Set the start of day in New York to be 1am local time instead of midnight.
Set the market open time to be 9:30am local time.

Step 1: Specifying temporal information in the instrument definition

We can call the UpsertInstruments API to add a timeZoneConventions object to an existing Equity instrument representing Microsoft:

curl -X POST 'https://<your-domain>.lusid.com/api/api/instruments'
   -H 'Authorization: Bearer <your-API-access-token>'
   -H 'Content-Type: application/json-patch+json'
   -d '{"upsert-request-1": {
    "name": "MSFT",
    "identifiers": {"Figi": {"value": "BBG000BPH459"}},
    "definition": {
      "instrumentType": "Equity",
      "domCcy": "GBP",
      "timeZoneConventions": {
        "primaryTimeZone": "America/New_York",
        "startOfDay": "NY_SOD",
        "primaryMarketOpen": "NY_Open"
      }
    }
  }
}'

Note the following:

The primaryTimeZone field is mandatory. It accepts any IANA timezone identifier.
The startOfDay field is optional and accepts the code of a cut label definition in the same timezone.
The primaryMarketOpen field is optional and accepts the code of a cut label definition in the same timezone. Note further configuration is required to actually generate transactions at this time.

Step 2: Examining resolved datetimes for the corporate action

We can call the GetInstrumentEvents API to examine the time and timezone information resolved for this CashDividendEvent from the Microsoft instrument definition:

{
  "values": [
    {
      "instrumentEventId": "MSCashDividend-2024-02-06",
      "instrumentIdentifiers": {"Instrument/default/Figi": "BBG000BPH459"},
      "description": "Cash dividend of 20 cents per share",
      "participationType": "MandatoryWithChoices",
      "completeness": "Complete",
      "instrumentEvent": {
        "exDate": "2024-02-06T06:00:00+00:00",
        "paymentDate": "2024-02-10T06:00:00+00:00",
        ...

Since LUSID stores all datetimes in UTC (and does not persist date stamps):

The resolved exDate is stored as 6 February 2024 at 6am in the UTC timezone.
The resolved paymentDate is stored as 10 February 2024 at 6am in the UTC timezone.

New York is five hours behind UTC but note the UTC time has been adjusted by one hour to reflect the startOfDay in the instrument definition.

Step 3: Delaying transaction generation until market open time

To delay the timestamp of the transaction generated by CashDividendEvent until the market is open, further configuration is required. We must

Create a custom transaction template for CashDividendEvent in a particular template scope to override the default template provided by FINBOURNE, keeping all the original settings.
Add a marketOpenTimeAdjustments object with a list of datetime fields to delay until the primaryMarketOpen time in the instrument definition. Note that if the exDate timestamp is already later than the market open time, no action is taken.
Register the custom transaction template scope with the parent portfolio. Note you can patch an existing portfolio.

For example, we can call the CreateTransactionTemplate API as follows to delay both the exDate and paymentDate fields (we could choose to delay just one of these):

curl -X POST 'https://<your-domain>.lusid.com/api/api/instrumenteventtypes/CashDividendEvent/transactiontemplates/Equity/MyTransactionTemplates' 
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "description": "My template for overriding the FBN-provided default cash dividend transaction template",
  "componentTransactions": [
    {
      "displayName": "Dividend Income",
      "transactionFieldMap": {
        "transactionId": "{{instrumentEventId}}-{{holdingId}}",
        "type": "DividendIncome",
        "source": "default",
        "instrument": "{{instrument}}",
        "transactionDate": "{{CashDividendEvent.exDate}}",
        "settlementDate": "{{CashDividendEvent.paymentDate}}",
        "units": "{{eligibleBalance}}",
        "transactionPrice": {
          "price": "{{CashDividendEvent.DeclaredElection.dividendRate}}",
          "type": "CashFlowPerUnit"
        },
        "transactionCurrency": "{{CashDividendEvent.DeclaredElection.dividendCurrency}}",
        "exchangeRate": "{{CashDividendEvent.ChosenElection.exchangeRate}}",
        "totalConsideration": {
          "currency": "{{CashDividendEvent.ChosenElection.dividendCurrency}}",
          "amount": "{{CashDividendEvent.ChosenElection.dividendAmount}}"
        }
      },
      "transactionPropertyMap": [],
      "marketOpenTimeAdjustments": [
        "CashDividendEvent.exDate",
        "CashDividendEvent.paymentDate"
      ]
    }
  ]
}'

Step 4: Examining datetimes for events and generated transactions

We can call the QueryApplicableInstrumentEvents API for the parent portfolio to examine the CashDividendEvent and its impact:

{
  "values": [
    {
      "instrumentType": "Equity",
      "instrumentEventType": "CashDividendEvent",
      "instrumentEventId": "BBG000BPH459-2024-02-06",
      "loadedEvent": {
        "description": "BBG000BPH459-2024-02-06",
        "completeness": "Complete",
        "instrumentEvent": {
          "exDate": "2024-02-06T06:00:00+00:00",
          "paymentDate": "2024-02-10T06:00:00+00:00",
        },
        "participationType": "MandatoryWithChoices",
        ...
      },
      "transactions": [
        {
          "transactionDate": "2024-02-06T14:30:00.0000000+00:00",
          "settlementDate": "2024-02-10T14:30:00.0000000+00:00",
          "units": 1000,
          "transactionPrice": {
            "price": 0.2,
            "type": "CashFlowPerUnit"
          },
          "totalConsideration": {
            "amount": 160,
            "currency": "GBP"
          },
          "exchangeRate": 0.8,
          "transactionCurrency": "USD",
          "resolvedTransactionTypeDetails": {
            "scope": "default",
            "source": "default",
            "type": "DividendIncome"
          },
          ...
        }
      ]
    }
  ],
  ...
}

Note the following:

In the loadedEvent.InstrumentEvent object, the exDate and paymentDate fields reveal that LUSID emits the event at 6am in the UTC timezone (1am in New York):
In the transactions object, the transactionDate and settlementDate fields reveal that LUSID delays generating the transaction until 2:30pm in the UTC timezone (9:30am in New York).