Each corporate action event has at least one participation type, which in turn determines election types and cardinality.
The issuer of your corporate action should provide a specification that determines participation, which you can map to a LUSID participation type as follows:
Mandatory, which means there is only ever one election (that is, there is no choice). You must participate and you must choose that election.MandatoryWithChoices, which means there can be one or many elections. You must participate and choose one of the elections.Voluntary, which means there can be one or many elections. You do not have to participate, but if you do you must choose one of the elections.
To discover the participation type(s) and elective choices (if any) available for a particular event, call the GetTransactionTemplateSpecification API, for example for CashDividendEvent:
{
"instrumentEventType": "CashDividendEvent",
"supportedInstrumentTypes": [
"Equity",
"SimpleInstrument"
],
"supportedParticipationTypes": [
"Mandatory",
"MandatoryWithChoices"
],
"supportedElectionTypes": [
{
"electionType": "CashElection",
"cardinality": {
"WhenMandatory": "One",
"WhenMandatoryWithChoices": "Many"
},
"referencedAs": [
"CashDividendEvent.declaredElection",
"CashDividendEvent.chosenElection"
]
}
],
...
}We can see that for CashDividendEvent:
Two participation types are available:
MandatoryandMandatoryWithChoices.One election type is available,
CashElection. If the corporate action issuer requires you to specify:Mandatory, you must specify one cash election and then choose it.MandatoryWithChoices, you can specify multiple different cash elections and then choose one of them.
Most corporate action events have a single participation type. The following have more than one:
Corporate action event | Available participation types | Available election types (and cardinality) | Specify this participation type if… |
|---|---|---|---|
|
|
| There is one security election and you must choose it. |
|
| There is one security election and/or one cash election and/or one lapse election, and you must choose one. | |
|
|
| There is one currency election and you must choose it. |
|
| There are multiple currency elections and you must choose one. | |
|
|
| There is one currency election and you must choose it. |
|
| There are multiple curency elections and you must choose one. | |
|
|
| There is either one security election or one cash & security election, and you must choose the one on offer. |
|
| There is one security election and/or one security & cash election and/or one cash election, and you must choose one. | |
|
|
| There is either one security election or one cash & security election or one cash election, and you must choose the one on offer. |
|
| There is either one security election or one cash & security election or one cash election, and you can take one or leave the lot. |
Specifying multiple cash elections
At the time of writing, CashDividendEvent and CapitalDistributionEvent allow you to select a participation type of MandatoryWithChoices and then specify multiple cash elections.
Issuers of corporate actions might provide specifications in different ways. Consider the example specifications below for the same CashDividendEvent:
Specification 1 | Specification 2 | ||
|---|---|---|---|
Elections | Declared | GBP at a dividend rate of 0.5 | GBP at a dividend rate of 0.5 |
Offer 1 | USD at an exchange rate to GBP of 1.35 | USD at a dividend rate of 0.675 | |
Offer 2 | JPY at an exchange rate to GBP of 200 | JPY at a dividend rate of 100 | |
| | ||
Notes | For GBP, the | The | |
In both example specifications above, GBP is the declared, chosen and default election; these flags are set to True for GBP and False for both offer elections:
"cashElections": [
{
"electionKey": "GreatBritishPounds",
"dividendCurrency": "GBP",
"dividendRate": "0.5",
"isDeclared": "True",
"isChosen": "True",
"isDefault": "True",
},
...
]This means that, by default, every portfolio registered with the corporate action source and with a holding on the ex-date is paid the dividend in GBP.
You can change this on a per-portfolio basis by loading an event instruction.
To change this for every portfolio so that the dividend is paid in USD instead, set the isChosen flag to False for GBP and True for USD, for example:
"cashElections": [
{
"electionKey": "GreatBritishPounds",
"dividendCurrency": "GBP",
"dividendRate": "0.5",
"isDeclared": "True",
"isChosen": "False",
"isDefault": "True",
},
{
"electionKey": "USDollar",
"dividendCurrency": "USD",
"exchangeRate": "1.35",
"isDeclared": "False",
"isChosen": "True",
"isDefault": "False",
},
...
]