Views:

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:

Data fieldStatusExplanation
nameOptionalSpecifies a name for the movement.
movementTypesMandatoryOne of the built-in movement types controlling how and when holdings are updated.
directionMandatory

Controls whether the change is an increase or decrease. Allowed values are 1 and -1.
 

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.

sideMandatory

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 Side1, Side2, BondInt and Side2WithoutBondInterest), or you can create your own custom sides.

propertiesOptional

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 TransactionConfiguration domain.
  • System properties that are valid for movements.
mappingsOptional

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.

movementOptionsOptional

A comma-separated list of options to configure the movement. The following are available:

OptionNotes
DirectAdjustment

Specify this option to override LUSID's standard logic and:
 

  1. Adjust the number of holding units by the number of units specified by the side.
  2. 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).
Keywords: movement