What is a Movement in LUSID, and how is it used as part of the Movements Engine processing to build portfolio holdings?
For example if you had a "Buy" transaction for 100 Vodafone common shares (Ticker: VOD, FIGI: BBG000C6K6G9) for a total cost of £146.66 this would be made up of two movements:
1) An increase of 100 in the units of Vodafone common shares (Ticker: VOD, FIGI: BBG000C6K6G9) on the transaction date and the same increase in the settled units on the settlement date
2) The creation of a separate GBP cash commitment of -£146.66 on the transaction date and a reduction in your GBP cash balance of £146.66 on the settlement date
More generally, a Movement is defined as a change to the quantity and/or cost of a holding. Each Movement is composed of the following:
- Movement Type
The Movement Type is responsible for how and when the holding is updated.
Some of these Movement Types are a single Movement Type which only affect the holding on either the transaction date OR the settlement date (the ones in yellow with a dashed border in the image below).
The others are a combined type which consist of the combination two single Movement Types (the ones in red with a solid border). One Movement Type for the transaction date and one for the settlement date.
In our example above with Vodafone the first movement has a Movement Type of "StockMovement". This is a combination of the "Traded" and "Settlement" Movement Types and has the effect of updating the units of the Vodafone position on the transaction date (the "Traded" Movement Type) and updating the settled units of the position on the settlement date (the "Settlement" Movement Type).
The second movement in our example above has a Movement Type of "CashCommitment". This is a combination of the "Commitment" and "CashSettlement" Movement Types and has the effect of creating a GBP cash commitment on the transaction date (the "Commitment" Movement Type) and a reduction in the GBP cash balance on the settlement date (the "CashSettlement" Movement Type).
Where the Movement Type is responsible for how and when a holding updated, the Side is responsible for what it is updated with.
The Side notes which attribute on the transaction should be used to determine the Security and Currency of the holding to be updated, by how many Units and the Amount by which the holding's cost should be updated.
In the Vodafone example above the default side of "Side1" is used in the first movement. This picks the units, amount and security from the core required fields on the transaction.
In the second movement, the default side of "Side2" is used. This picks the units, amount and cash currency from the core required fields on the transaction.
You can create custom sides which pick other attributes such as commission.
The direction of the Movement describes whether the change in the units and the amount of the holding is in a positive or negative direction. This is indicated by either 1 or -1.
For the Vodafone example above the first movement has a direction of 1.
The second movement has a direction of -1.
It is important to think about how the direction works with the side as if your units and amount are signed (e.g. the units field is -30 for a sell transaction and 30 for a buy transaction) then a negative direction will have the effect of reversing the sign and can easily lead to unintended results.
Mappings allow you to set transaction properties on each movement separately. These properties can either be mapped from a property that is already on the transaction or set to a static value.
This allows you to separate the movements in different categories when generating holdings. For example you may want to tag cash flow types such as "Commission" vs "Dividend".