Iso20022

AgentCAMovementInstructionV01

seev.019.001.01

Scope This message is sent by an issuer (or its agent) to a CSD to order:

Message Construction

Every ISO20022 message has at the highest level what we call ‘building blocks’. Because the message is constructed as immutable records, the association is by composition. Below you can see the relationship between the message and its constituent building blocks: For comparison, see the ISO20022 official specification

classDiagram
     direction LR
%% AgentCAMovementInstructionV01 recursion level 0 with max 0
AgentCAMovementInstructionV01 *-- "1..1" DocumentIdentification8 : Identification
AgentCAMovementInstructionV01 *-- "0..1" DocumentIdentification8 : AgentCAElectionAdviceIdentification
AgentCAMovementInstructionV01 *-- "1..1" CorporateActionInformation1 : CorporateActionGeneralInformation
AgentCAMovementInstructionV01 *-- "1..1" CorporateActionMovement1 : MovementGeneralInformation
AgentCAMovementInstructionV01 *-- "0..1" UnderlyingSecurityMovement1 : UnderlyingSecuritiesMovementDetails
AgentCAMovementInstructionV01 *-- "0..1" CashMovement2 : UnderlyingCashMovementDetails
AgentCAMovementInstructionV01 *-- "0..1" ProceedsMovement1 : ProceedsMovementDetails

Now, we will zero-in one-by-one on each of these building blocks.

Identification building block

Identification assigned by the Sender to unambiguously identify the instruction. Identifies the document by providing a unique identification and optionally the date/time of the creation of the document. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% DocumentIdentification8 recursion level 0 with max 1
class DocumentIdentification8{
    Identification IsoMax35Text
    CreationDateTime IsoISODateTime
}

DocumentIdentification8 members

Member name Description Data Type / Multiplicity
Identification Unique identification of the document. IsoMax35Text - Required 1..1
CreationDateTime Date/time of the creation of the document. IsoISODateTime - Optional 0..1

AgentCAElectionAdviceIdentification building block

Identification of the Agent CA ElectionAdvice when the movements are the result of an ElectionAdvice. Identifies the document by providing a unique identification and optionally the date/time of the creation of the document. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% DocumentIdentification8 recursion level 0 with max 1
class DocumentIdentification8{
    Identification IsoMax35Text
    CreationDateTime IsoISODateTime
}

DocumentIdentification8 members

Member name Description Data Type / Multiplicity
Identification Unique identification of the document. IsoMax35Text - Required 1..1
CreationDateTime Date/time of the creation of the document. IsoISODateTime - Optional 0..1

CorporateActionGeneralInformation building block

General information about the corporate action event. General information about the corporate action event. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% CorporateActionInformation1 recursion level 0 with max 1
class CorporateActionInformation1{
    IssuerCorporateActionIdentification IsoMax35Text
    CorporateActionProcessingIdentification IsoMax35Text
}
CorporateActionInformation1 *-- "1..1" IPartyIdentification2Choice : AgentIdentification
CorporateActionInformation1 *-- "1..1" ICorporateActionEventType2FormatChoice : EventType
CorporateActionInformation1 *-- "1..1" ICorporateActionMandatoryVoluntary1FormatChoice : MandatoryVoluntaryEventType
CorporateActionInformation1 *-- "0..1" ICorporateActionEventProcessingType1FormatChoice : EventProcessingType
CorporateActionInformation1 *-- "1..1" FinancialInstrumentDescription3 : UnderlyingSecurity
%% IPartyIdentification2Choice recursion level 1 with max 1
%% ICorporateActionEventType2FormatChoice recursion level 1 with max 1
%% ICorporateActionMandatoryVoluntary1FormatChoice recursion level 1 with max 1
%% ICorporateActionEventProcessingType1FormatChoice recursion level 1 with max 1
%% FinancialInstrumentDescription3 recursion level 1 with max 1
class FinancialInstrumentDescription3{
    PlaceOfListing IsoMICIdentifier
}
FinancialInstrumentDescription3 *-- "1..1" SecurityIdentification7 : SecurityIdentification
FinancialInstrumentDescription3 *-- "0..1" IPartyIdentification2Choice : SafekeepingPlace

CorporateActionInformation1 members

Member name Description Data Type / Multiplicity
AgentIdentification Identification of the issuer agent. IPartyIdentification2Choice - Required 1..1
IssuerCorporateActionIdentification Reference given to the event by the CA event issuer (agent). IsoMax35Text - Optional 0..1
CorporateActionProcessingIdentification Reference assigned by the account servicer to unambiguously identify a corporate action event. IsoMax35Text - Optional 0..1
EventType Type of corporate action event. ICorporateActionEventType2FormatChoice - Required 1..1
MandatoryVoluntaryEventType Specifies whether the event is mandatory, mandatory with options or voluntary. ICorporateActionMandatoryVoluntary1FormatChoice - Required 1..1
EventProcessingType Type of processing involved by a Corporate Action. ICorporateActionEventProcessingType1FormatChoice - Optional 0..1
UnderlyingSecurity Identification of the underlying financial instrument, ie, the financial instrument affected by the corporate action event. FinancialInstrumentDescription3 - Required 1..1

MovementGeneralInformation building block

Provides general information about the movement. Provides information about the movement instruction. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% CorporateActionMovement1 recursion level 0 with max 1
class CorporateActionMovement1{
    OrderType DistributionInstructionType1Code
    HighPriorityIndicator IsoYesNoIndicator
    OptionNumber IsoExact3NumericText
    RequestedExecutionDate IsoISODate
    AccountIdentification IsoMax35Text
}
CorporateActionMovement1 *-- "0..1" ICorporateActionOption1FormatChoice : OptionType
CorporateActionMovement1 *-- "0..1" IPartyIdentification2Choice : AccountOwnerIdentification
CorporateActionMovement1 *-- "0..1" IUnitOrFaceAmount1Choice : ConfirmedBalanceSecuritiesQuantity
%% ICorporateActionOption1FormatChoice recursion level 1 with max 1
%% IPartyIdentification2Choice recursion level 1 with max 1
%% IUnitOrFaceAmount1Choice recursion level 1 with max 1

CorporateActionMovement1 members

Member name Description Data Type / Multiplicity
OrderType Type of movement instruction. DistributionInstructionType1Code - Required 1..1
HighPriorityIndicator Indicates whether the movement is a high priority or not. Meaning when true: High priority
OptionNumber Number identifying the available corporate action options. IsoExact3NumericText - Optional 0..1
OptionType Specifies the corporate action options available to the account owner. ICorporateActionOption1FormatChoice - Optional 0..1
RequestedExecutionDate Date at which the distribution movement must be executed. IsoISODate - Required 1..1
AccountOwnerIdentification Identification of the party that owns the account. IPartyIdentification2Choice - Optional 0..1
AccountIdentification Identification of the account. IsoMax35Text - Optional 0..1
ConfirmedBalanceSecuritiesQuantity Quantity of securities in the confirmed balance, ie, the balance to which the credit of the outturned resources applies. IUnitOrFaceAmount1Choice - Optional 0..1

UnderlyingSecuritiesMovementDetails building block

Information related to the movement of the underlying securities. Provides information about the underlying securities movement. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% UnderlyingSecurityMovement1 recursion level 0 with max 1
UnderlyingSecurityMovement1 *-- "1..1" SecurityIdentification7 : SecurityIdentification
UnderlyingSecurityMovement1 *-- "1..1" IUnitOrFaceAmount1Choice : SecuritiesQuantity
UnderlyingSecurityMovement1 *-- "1..2" SecuritiesAccount8 : AccountDetails
%% SecurityIdentification7 recursion level 1 with max 1
class SecurityIdentification7{
    ISIN IsoISINIdentifier
    Description IsoMax140Text
}
SecurityIdentification7 *-- "1..1" AlternateSecurityIdentification3 : OtherIdentification
%% IUnitOrFaceAmount1Choice recursion level 1 with max 1
%% SecuritiesAccount8 recursion level 1 with max 1
class SecuritiesAccount8{
    CreditDebitIndicator CreditDebitCode
    AccountIdentification IsoMax35Text
    OptionNumber IsoExact3NumericText
    SecurityHoldingForm FormOfSecurity1Code
}
SecuritiesAccount8 *-- "0..1" IPartyIdentification2Choice : AccountOwnerIdentification
SecuritiesAccount8 *-- "0..1" ISecuritiesBalanceType10FormatChoice : BalanceType
SecuritiesAccount8 *-- "0..1" ICorporateActionOption1FormatChoice : OptionType
SecuritiesAccount8 *-- "0..1" IStampDutyType1FormatChoice : StampDuty

UnderlyingSecurityMovement1 members

Member name Description Data Type / Multiplicity
SecurityIdentification Identification of the financial instrument. SecurityIdentification7 - Required 1..1
SecuritiesQuantity Quantity of financial instrument. IUnitOrFaceAmount1Choice - Required 1..1
AccountDetails Provides information about the debited/credited securities account. SecuritiesAccount8 - Collection 1..2

UnderlyingCashMovementDetails building block

Information related to the movement of the underlying cash. Provides information about the cash movement. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% CashMovement2 recursion level 0 with max 1
class CashMovement2{
    Amount IsoActiveCurrencyAndAmount
}
CashMovement2 *-- "1..2" CashAccount19 : AccountDetails
%% CashAccount19 recursion level 1 with max 1
class CashAccount19{
    CreditDebitIndicator CreditDebitCode
}
CashAccount19 *-- "0..1" IPartyIdentification2Choice : AccountOwnerIdentification
CashAccount19 *-- "1..1" IAccountIdentification2Choice : AccountIdentification

CashMovement2 members

Member name Description Data Type / Multiplicity
Amount Cash amount. IsoActiveCurrencyAndAmount - Required 1..1
AccountDetails Provides information about the account which is debited/credited. CashAccount19 - Collection 1..2

ProceedsMovementDetails building block

Information related to the movement of the CA proceeds. Details of the proceeds movements. For comparison, see the ISO20022 official specification

classDiagram
   direction tb
%% ProceedsMovement1 recursion level 0 with max 1
ProceedsMovement1 *-- "0..0" CashProceeds1 : CashProceedsMovementDetails
ProceedsMovement1 *-- "0..0" SecuritiesProceeds1 : SecuritiesProceedsMovementDetails
ProceedsMovement1 *-- "0..1" TaxVoucher1 : TaxDetails
%% CashProceeds1 recursion level 1 with max 1
class CashProceeds1{
    PostingAmount IsoActiveCurrencyAndAmount
    ReconciliationDetails IsoMax350Text
}
CashProceeds1 *-- "1..2" CashAccount19 : AccountDetails
%% SecuritiesProceeds1 recursion level 1 with max 1
class SecuritiesProceeds1{
    ReconciliationDetails IsoMax350Text
}
SecuritiesProceeds1 *-- "1..1" SecurityIdentification7 : SecurityIdentification
SecuritiesProceeds1 *-- "1..1" IUnitOrFaceAmount1Choice : PostingQuantity
SecuritiesProceeds1 *-- "1..2" SecuritiesAccount10 : AccountDetails
%% TaxVoucher1 recursion level 1 with max 1
class TaxVoucher1{
    TaxVoucherRate IsoBaseOneRate
    TaxCredit IsoActiveCurrencyAndAmount
    TaxDeduction IsoActiveCurrencyAndAmount
    GrossAmount IsoActiveCurrencyAndAmount
    NetAmount IsoActiveCurrencyAndAmount
    TaxCreditRate IsoPercentageRate
    WithholdingTaxAmount IsoActiveCurrencyAndAmount
    WithholdingTaxRate IsoPercentageRate
    CashAmountBroughtForward IsoActiveCurrencyAndAmount
    CashAmountCarriedForward IsoActiveCurrencyAndAmount
    NotionalTax IsoActiveCurrencyAndAmount
    NotionalDividendPayable IsoActiveCurrencyAndAmount
    BargainDate IsoISODate
    BargainSettlementDate IsoISODate
    StampDutyAmount IsoActiveCurrencyAndAmount
    ChargeAmount IsoActiveCurrencyAndAmount
    CommissionAmount IsoActiveCurrencyAndAmount
}
TaxVoucher1 *-- "1..1" IUnitOrFaceAmount1Choice : RecordDateHolding
TaxVoucher1 *-- "0..1" PriceValue1 : ScripDividendReinvestmentPricePerShare
TaxVoucher1 *-- "0..1" PriceValue1 : AllotedSharesCost
TaxVoucher1 *-- "0..1" ForeignExchangeTerms9 : ForeignExchangeDetails

ProceedsMovement1 members

Member name Description Data Type / Multiplicity
CashProceedsMovementDetails Provides information about the movement of the cash proceeds. CashProceeds1 - Unknown 0..0
SecuritiesProceedsMovementDetails Provides information about the movement of the securities proceeds. SecuritiesProceeds1 - Unknown 0..0
TaxDetails Provides information about the tax voucher. TaxVoucher1 - Optional 0..1

Extensibility and generalization considerations

To facilitate generalized design patterns in the system, the AgentCAMovementInstructionV01 implementation follows a specific implementaiton pattern. First of all, AgentCAMovementInstructionV01 impleemnts IOuterRecord indicating it is the outermost logical part of the message definition. Like all message wrappers, AgentCAMovementInstructionV01Document implements IOuterDocument. Because AgentCAMovementInstructionV01 implements IOuterDocument, it is a suitable template parameter for IOuterDocument, and causes the internal ‘Message’ to be of type AgentCAMovementInstructionV01.

classDiagram
    class IOuterRecord
    AgentCAMovementInstructionV01 --|> IOuterRecord : Implements
    AgentCAMovementInstructionV01Document --|> IOuterDocument~AgentCAMovementInstructionV01~ : Implements
    class IOuterDocument~AgentCAMovementInstructionV01~ {
        AgentCAMovementInstructionV01 Message
     }

Document wrapper for serialization

The only real purpose AgentCAMovementInstructionV01Document serves is to cause the document to be serialized into the ‘urn:iso:std:iso:20022:tech:xsd:seev.019.001.01’ namespace. Therefore, it will probably be the usual practice to build the message and construct this wrapper at the last minute using AgentCAMovementInstructionV01.ToDocument() method. The returned AgentCAMovementInstructionV01Document value will serialize correctly according to ISO 20022 standards.

classDiagram
    AgentCAMovementInstructionV01Document *-- AgentCAMovementInstructionV01 : Document

Sample of message format

This is an abbreviated version of what the message should look like.

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:seev.019.001.01">
    <AgtCAMvmntInstr>
        <Id>
            <!-- Identification inner content -->
        </Id>
        <AgtCAElctnAdvcId>
            <!-- AgentCAElectionAdviceIdentification inner content -->
        </AgtCAElctnAdvcId>
        <CorpActnGnlInf>
            <!-- CorporateActionGeneralInformation inner content -->
        </CorpActnGnlInf>
        <MvmntGnlInf>
            <!-- MovementGeneralInformation inner content -->
        </MvmntGnlInf>
        <UndrlygSctiesMvmntDtls>
            <!-- UnderlyingSecuritiesMovementDetails inner content -->
        </UndrlygSctiesMvmntDtls>
        <UndrlygCshMvmntDtls>
            <!-- UnderlyingCashMovementDetails inner content -->
        </UndrlygCshMvmntDtls>
        <PrcdsMvmntDtls>
            <!-- ProceedsMovementDetails inner content -->
        </PrcdsMvmntDtls>
    </AgtCAMvmntInstr>
</Document>

Data from ISO specification

This is the technical data from the specification document.

<messageDefinition
  xmi:id="_TQbwbNEwEd-BzquC8wXy7w_89976784"
  name="AgentCAMovementInstructionV01"
  definition="Scope&#xD;&#xA;This message is sent by an issuer (or its agent) to a CSD to order:&#xD;&#xA;- the global or individual debit of exercised resources (cash and/or securities), per event and optionally per option and per resource for all or individual CSD client's accounts;&#xD;&#xA;- and/or the individual credits of the outturn resources per event and optionally per option and per resource for a given CSD client's account.&#xD;&#xA;Usage&#xD;&#xA;This message is used to instruct:&#xD;&#xA;- the global debit of the exercised resources from the CSD client's available or sequestered balance, in which case, the order type must be 'global debit order';&#xD;&#xA;- the individual debits and credits:&#xD;&#xA;- the individual debit of the exercised resources from the CSD client's available or sequestered balance and/or&#xD;&#xA;- the individual credit of the outturn resources to the CSD client's account.&#xD;&#xA;The order type must be 'individual order';&#xD;&#xA;- a return order, in the case of a scaleback, i.e. the return of the exercised resources to the CSD client's account. The order type must be either 'global return order' or 'individual return order'; and&#xD;&#xA;change of option, e.g. in the case of the closure of an option, by moving the exercised resources from one option to another option within the sequestered balances in accordance to the new option conditions. The order type must be 'option change order'."
  registrationStatus="Registered"
  messageSet="_wRe70k2rEeG_I4xRYCA_7g"
  xmlTag="AgtCAMvmntInstr"
  rootElement="Document"
  xmlns:xmi="http://www.omg.org/XMI">
  <constraint
    xmi:id="_TQlhZdEwEd-BzquC8wXy7w_2051849581"
    name="OptionRule1"
    definition="IF MovementGeneralInformation/OrderType is CHAN (OptionChangeOrder) then OptionNumber and OptionType must be present in each occurrence of UnderlyingSecuritiesMovementDetails/CreditAccountDetails and UnderlyingSecuritiesMovement/DebitAccountDetails and OptionNumber and OptionType cannot be present in MovementGeneralInformation."
    registrationStatus="Provisionally Registered" />
  <constraint
    xmi:id="_TQlhaNEwEd-BzquC8wXy7w_-254774137"
    name="OptionRule2"
    definition="IF MovementGeneralInformation/OrderType is not CHAN (OptionChangeOrder), then OptionNumber and OptionType must be present in MovementGeneralInformation and cannot be present in any occurrence of UnderlyingSecuritiesMovementDetails/CreditAccountDetails neither in UnderlyingSecuritiesMovement/DebitAccountDetails."
    registrationStatus="Provisionally Registered" />
  <messageBuildingBlock
    xmi:id="_TQbwbdEwEd-BzquC8wXy7w_-1830305628"
    name="Identification"
    definition="Identification assigned by the Sender to unambiguously identify the instruction."
    registrationStatus="Provisionally Registered"
    maxOccurs="1"
    minOccurs="1"
    xmlTag="Id"
    complexType="_RXNBiNp-Ed-ak6NoX_4Aeg_-320016249" />
  <messageBuildingBlock
    xmi:id="_TQbwbtEwEd-BzquC8wXy7w_1167684393"
    name="AgentCAElectionAdviceIdentification"
    definition="Identification of the Agent CA ElectionAdvice when the movements are the result of an ElectionAdvice."
    registrationStatus="Provisionally Registered"
    maxOccurs="1"
    minOccurs="0"
    xmlTag="AgtCAElctnAdvcId"
    complexType="_RXNBiNp-Ed-ak6NoX_4Aeg_-320016249" />
  <messageBuildingBlock
    xmi:id="_TQlhYNEwEd-BzquC8wXy7w_-1064437187"
    name="CorporateActionGeneralInformation"
    definition="General information about the corporate action event."
    registrationStatus="Provisionally Registered"
    maxOccurs="1"
    minOccurs="1"
    xmlTag="CorpActnGnlInf"
    complexType="_TdxFY9p-Ed-ak6NoX_4Aeg_1155832018" />
  <messageBuildingBlock
    xmi:id="_TQlhYdEwEd-BzquC8wXy7w_1865905670"
    name="MovementGeneralInformation"
    definition="Provides general information about the movement."
    registrationStatus="Provisionally Registered"
    maxOccurs="1"
    minOccurs="1"
    xmlTag="MvmntGnlInf"
    complexType="_UIh5p9p-Ed-ak6NoX_4Aeg_378115287" />
  <messageBuildingBlock
    xmi:id="_TQlhYtEwEd-BzquC8wXy7w_-380692038"
    name="UnderlyingSecuritiesMovementDetails"
    definition="Information related to the movement of the underlying securities."
    registrationStatus="Provisionally Registered"
    minOccurs="0"
    xmlTag="UndrlygSctiesMvmntDtls"
    complexType="_UIO-sNp-Ed-ak6NoX_4Aeg_-697458395" />
  <messageBuildingBlock
    xmi:id="_TQlhY9EwEd-BzquC8wXy7w_940386448"
    name="UnderlyingCashMovementDetails"
    definition="Information related to the movement of the underlying cash."
    registrationStatus="Provisionally Registered"
    minOccurs="0"
    xmlTag="UndrlygCshMvmntDtls"
    complexType="_UJIWkNp-Ed-ak6NoX_4Aeg_908062376" />
  <messageBuildingBlock
    xmi:id="_TQlhZNEwEd-BzquC8wXy7w_1511604786"
    name="ProceedsMovementDetails"
    definition="Information related to the movement of the CA proceeds."
    registrationStatus="Provisionally Registered"
    maxOccurs="1"
    minOccurs="0"
    xmlTag="PrcdsMvmntDtls"
    complexType="_Ri1Csdp-Ed-ak6NoX_4Aeg_1504216884" />
  <messageDefinitionIdentifier
    businessArea="seev"
    messageFunctionality="019"
    flavour="001"
    version="01" />
</messageDefinition>

ISO Building Blocks

The following items are used as building blocks to construct this message.