Relationship Between Assets and Instruments
As outlined in the article "Introduction to the XML file" there is a close relationship between Assets and Instruments, and this relationship is key to understanding the XML file structure.
Asset -> Instrument
Instrument properties are properties that are the same for assets held across multiple portfolios. These properties can be provided once and then referenced each time a specific instrument is identified in the file.
Below is a simple sample file, which contains two portfolios, each holding an asset referencing the same "Nokia Equity" instrument. In this case, we want to apply the same instrument properties to both "Nokia Equity" positions. This is done with a reference to the Instrument, as shown in the picture below.
As seen both of the two "Nokia Equity" Assets reference the InstrumentId of the corresponding Instrument, as defined in the Instrument section of the XML file. During the execution of the FundApps rules, the rules engine will pull all the instrument properties onto these assets.
This example was simple, where the asset could directly reference all the properties needed. Holding more complex instruments, such as derivatives, convertible bonds, ADRs, etc. requires an additional step in this structure, which is discussed below.
Asset -> Instrument -> Instrument
Shareholding disclosure regimes are usually interested in calculating ownership in issuers of shares. Exposure to shares can either be held by holding the shares directly, or by holding derivatives and other products which have an equity as their underlying instrument. The example below illustrates how to model a position in an ADR with the "Nokia Equity" as its underlying instrument.
The ADR asset has the InstrumentName "Nokia ADR NYSE" and is held in portfolio 15. As in the previous example, the asset is referencing an instrument, in this case with InstrumentId "ADR_Nokia".
This reference instrument is the ADR instrument, where only instrument properties specific to the ADR are specified. As previously mentioned, shareholding disclosure is concerned with the ownership of equity shares. The ADR instrument itself does not provide any information on the underlying equity shares, so it is necessary to provide the ADR instrument with a link to the underlying equity. This is done by specifying a Component InstrumentID.
Here the ADR Instrument Component references the "Nokia Equity" instrument. The ADR component specifies the InstrumentId of the underlying equity, as shown in the figure above. Again, when the rules engine executes the rules, it will pull through the Equity properties to the ADR level and subsequently add the joint set of Instrument properties to the "Nokia ADR NYSE" asset to check whether the ADR Asset gives rise to a disclosure requirement.