Loading an event instruction into a portfolio to configure event behaviour

An event instruction is a mechanism for configuring the behaviour of a particular instrument event in a particular portfolio. Note this can be either an instrument lifecycle event or a corporate action event.

Depending on the type of instrument event, you can:

Ignore it.
Configure it for all holdings in an impacted instrument. Note you may have more than one holding in the same instrument if you are using sub-holding keys (SHKs).
Configure it for a particular holding.
Trigger certain events that are not automatically emitted by LUSID, such as option exercise events.

Example: Configuring the behaviour of a CashDividendEvent corporate action

Consider a scenario where we have:

Three portfolios subscribed to a corporate action source. Each portfolio has a holding of 1000 Microsoft shares.
A CashDividendEvent corporate action like this one loaded into the corporate action source that declares a dividend of USD 0.2 per share but elects to take it in GBP at an exchange rate of 0.8:

By default on the ex-dividend date, LUSID generates output transactions in all three portfolios that result in the following GBP cash holdings:

We can change this just for Portfolio C by loading an event instruction to take the dividend in the original USD currency instead. To do this:

Call the QueryApplicableInstrumentEvents API for portfolio C to determine the ID of the instrument event to configure. The response might reveal an instrumentEventId of LUID_00003DV6-2024-02-06:

{
  "values": [
    {
      "portfolioId": {"scope": "UKEquities", "code": "PortfolioC"},
      "holdingId": 68123148,
      "lusidInstrumentId": "LUID_00003DV6",
      "instrumentScope": "default",
      "instrumentType": "Equity",
      "instrumentEventType": "CashDividendEvent",
      "instrumentEventId": "LUID_00003DV6-2024-02-06"
      ...

Call the UpsertInstrumentEventInstructions API to load a suitable event instruction into Portfolio C, for example:
```
curl -X POST 'https://<your-domain>.lusid.com/api/api/portfolios/UKEquities/PortfolioC/instrumenteventinstructions?successMode=Partial'
  -H 'Content-Type: application/json-patch+json'
  -H 'Authorization: Bearer <your-API-access-token>'
  -d '{
  "request": {
    "instrumentEventInstructionId": "MsftCashDividendOverrideFeb2024",
    "instrumentEventId": "LUID_00003DV6-2024-02-06",
    "instructionType": "ElectForPortfolio",
    "electionKey": "USD"
  }
}'
```
JSON
Note the following:
- The InstrumentEventInstructionID must be unique among all the event instructions loaded into this portfolio.
- The instrumentEventId is the ID of the instrument event to configure, in this case LUID_00003DV6-2024-02-06.
- The instructionType is ElectForPortfolio to impact every Microsoft holding in portfolio C (in circumstances where there is more than one). Alternative values are Ignore and ElectForHolding; note the latter requires a holdingId to identify which Microsoft holding to override.
- For ElectForPortfolio and ElectForHolding, the electionKey must be the key of a cash election in the original instrument event to use instead.

Now on the ex-dividend date, LUSID generates output transactions that result in GBP holdings in Portfolios A and B but a USD holding in Portfolio C: