A movement is a component of a transaction type. It defines the economic impact of all transactions belonging to that type on holdings.
A transaction type must have at least one movement, and can have two or more. For example, the built-in
Buy transaction type provided with LUSID—intended to signal a purchase of an instrument such as an equity or bond—has two movements. For each transaction upserted to a portfolio with a transaction type of
Buy, LUSID automatically:
- Increases the quantity of your holding in the underlying instrument (ie. BP or MSFT) by the number of units purchased.
- Decreases the core cash balance in the transaction currency (ie. GBP or USD) by the total consideration.
Understand how LUSID uses transaction types to generate holdings.
A movement has the following data fields:
|Optional||Specifies a name for the movement.|
|Mandatory||One of the built-in movement types controlling how and when holdings are updated.|
Controls whether the change is an increase or decrease. Allowed values are
If transactions have unsigned units and amounts then
1 signals an increase and
-1 signals a decrease. However, the opposite is true if units and amounts are signed. So for example if a sell transaction is for -30 units, then
1 signals a decrease.
A side is a plug-and-play component that determines which holdings are impacted and what attributes of transactions contribute to the change.
Allowed values are either the built-in sides provided with LUSID (currently
Side2WithoutBondInterest), or you can create your own custom sides.
This can be any number of:
- Custom properties to extend the data model and store extra information about movements. These properties must be from the
- System properties that are valid for movements.
Allocates one or more sub-holding keys (SHKs) to override or supplement strategy tags applied directly to transactions.
Specify a 3-stage
propertyKey representing a SHK registered with the parent portfolio, and either
mapFrom the value of another transaction property, or
setTo a static value (including an empty string to de-allocate an SHK).
For an example, see this tutorial on breaking out broker commission as a separate cash holding.
A comma-separated list of options to configure the movement. The following are available:
Specify this option to override LUSID's standard logic and:
- Adjust the number of holding units by the number of units specified by the side.
- Adjust the holding cost by the amount specified by the side.
This is different to LUSID's default closing behavior, which is to scale the cost and calculate realised gain/loss.
This option can be used when
movementTypes is set to
StockMovement to adjust the units of holdings without impacting the cost, perhaps to model a 1-for-2 reverse stock split by loading a transaction that halves the number of units but with a total consideration of zero:
- The units are reduced by the transaction units, as normal.
- The cost is not affected (that is, adjustment is zero).