What is a system property?

A system property is a built-in function belonging to a particular type of entity that can either be read-only or writable:

Category

Enables you to...

Example

Read-only

Retrieve system information from LUSID that may not be available through other mechanisms.

Transaction/default/SourcePortfolioId

You can retrieve this system property for transactions in a derived portfolio and LUSID reveals the original portfolio in which each transaction is booked.

Writable

Record data that LUSID can then use in valuation and other business operations.

Transaction/default/TradeToPortfolioRate

You can attach this system property to transactions with values that record exchange rates for those traded in a different currency, enabling LUSID to maintain the cost basis of the portfolio in the base currency

You can interact with system properties in much the same way as the custom properties you create to extend the LUSID data model. System properties have a 3-stage key consisting of a domain, scope and code in exactly the same way, though note the underlying system property types are opaque.

Retrieving system properties for entities

To retrieve a system property, decorate it onto entities of the appropriate type when you retrieve the latter, in the same way as a custom property. For example, to decorate Transaction/default/SourcePortfolioId onto transactions retrieved from one of the LUSID demonstration portfolios:

curl -X GET "https://<your-domain>.lusid.com/api/api/transactionportfolios/Finbourne-Examples/UK-Equities/transactions?propertyKeys=Transaction%2Fdefault%2FSourcePortfolioId"
  -H "Authorization: Bearer <your-API-access-token>"

Note: FINBOURNE reserves the right to change the underlying format and data type of system properties, so retrievals at different times may yield different results.

Attaching writable system properties to entities

To attach a writable system property, enter the property key and a value when you upsert an entity of the appropriate type, in the same way as a custom property. For example, to use Transaction/default/TradeToPortfolioRate to record the USD/GBP rate for a USD transaction in one of the GBP-denominated demonstration portfolios:

curl -X POST "https://<your-domain>.lusid.com/api/api/transactionportfolios/Finbourne-Examples/Global-Equity/transactions"
  -H "Authorization: Bearer <your-API-access-token>"
  -H "Content-Type: application/json-patch+json"
  -d '[{
       "transactionId": "01",
       "type": "Buy",
       "instrumentIdentifiers": {
           "instrument/default/Figi": "BBG000C6K6G9"
         },
       "transactionCurrency": "USD",
       "properties": {
          "Transaction/default/TradeToPortfolioRate": {
            "key": "Transaction/default/TradeToPortfolioRate",
            "value": {
              "metricValue": {
                "value": 0.73,
                "unit": ""
              }
            }
          }
      },
      ...
     }
 ]'

Transaction system properties

Note you can only use transaction system properties with transactions (not other types of entity).

System property key

Writable?

Data type

Explanation

Transaction/default/BondInterest

YES

Number

Stores the bond interest bought or sold when buying or selling fixed income instruments.

Transaction/default/TradeToPortfolioRate

YES

Number

Stores the exchange rate between the transaction currency and the portfolio base currency.

Transaction/default/GrossConsideration

YES

Number

Stores the gross consideration, which is the total consideration plus any fees.

Transaction/default/OriginalTradeDate

YES

String

Overrides the transaction date when creating a new tax lot. This is mainly used for 'transfer'-type transactions; that is, the transfer is recorded with a transaction date of ‘today’ but it's an investment you've held for ten years, and you want to preserve the 'days held'.

Transaction/default/OriginalSettlementDate

YES

String

As above, but for the settlement date.

Transaction/default/TaxLotSelectionMethod

YES

String

Overrides the default accounting method (set either on the portfolio, or the transaction type). Available values are FirstInFirstOut, LastInFirstOut, HighestCostFirst, LowestCostFirst.

Transaction/default/AllocationMethod

YES

String

Set the value to Prorated to override the default behavior (either built-in to LUSID or set on the transaction type) and prorate a transaction that itself has no sub-holding keys across all sub-holding keys defined for the portfolio. This is typically useful where a transaction represents a single coupon or dividend payment but the investment is held in multiple strategies.

Transaction/default/RequiresFundingLegHistory

YES

String

Set the value to True to override the default behavior and indicate that the instrument being transacted is a funding leg.

Transaction/default/NotionalAmount

YES

Number

Stores the notional amount of a buy or sell transaction in a future or CFD instrument.

Transaction/default/PortfolioId

NO

String

For a transaction in a portfolio group, retrieves the code of the portfolio in which it is booked.

Transaction/default/PortfolioScope

NO

String

As above, but retrieves the portfolio scope.

Transaction/default/SourcePortfolioId

NO

String

For a transaction in a derived transaction portfolio, retrieves the code of the original portfolio in which it is booked.

Transaction/default/SourcePortfolioScope

NO

String

As above, but retrieves the portfolio scope.

Transaction/default/TxnInputType

NO

String

For a transaction booked with a transaction type that is aliased to a source, retrieves the original transaction type. For example, transactions from SourceA might have a BUY transaction type, those from SourceB have an ACHETER type, and both are aliased to a PURCHASE type that is set as the default source:

Type

Units

Source

Transaction/default/TxnInputType

PURCHASE

100

SourceA

BUY

PURCHASE

200

default

PURCHASE

300

SourceB

ACHETER

Transaction/default/ResultantHolding

NO

Number

For a transaction booked with a transaction type that itself has a movement with a ‘security’ side (that is, concerned with instruments and units), retrieves the current holding. For example:

Type

Units

Transaction/default/ResultantHolding

PURCHASE

100

100

PURCHASE

200

300

SELL

250

50

Transaction/default/InvestmentScalingMetadata

NO

String

Transaction/default/CounterpartyAgreementId

NO

String

Transaction/system/SourceInstrumentId

NO

String

Transaction/system/SourceInstrumentId

NO

String

Transaction/system/AppliedTaxRule

NO

String

Retrieves the tax rule in a tax rule set that LUSID applied to an activity such as a corporate action based on matching property values. More information.

Transaction type system properties

Note you can only use transaction type system properties with transaction types (not other types of entity).

System property key

Writable?

Data type

Explanation

On the transaction type itself

TransactionConfiguration/default/CashFlowType

YES

String

Override the cash flow type associated with a particular transaction type.

By default, LUSID's cashflow generation tool (the GetUpsertablePortfolioCashFlows API) generates a set of upsertable transactions with the built-in CashFlow transaction type.

If you would prefer LUSID to assign a different transaction type to a particular upsertable transaction based on the cash flow type emitted by the underlying instrument, apply this property to that transaction type and give it one of the following cash flow type values:

Cash flow type

Explanation

Premium

A premium.

Coupon

A coupon payment. Distinct from a premium in that a coupon would be paid for a bond or rates leg whereas as a premium would be paid on an insurance-related product such as a credit default swap.

Notional

A notional-related flow, such as a notional exchange.

Principal

A payment of principal, typically return of principal.

Protection

A payment as a result of a default event on a credit protection leg.

Cash

A cash payment resulting from an option or settlement of an option.

For example, an interest rate swap transaction emits a cash flow type of Coupon. You could assign a property with this value to a transaction type that specifies a more sophisticated set of movements more appropriate to an IRS than CashFlow.

For an example, see the life cycle section of this Jupyter Notebook.

TransactionConfiguration/default/AllocationMethod

YES

String

Set the value to Prorated to override the default behavior and prorate all the transactions of this transaction type that have no sub-holding keys across all sub-holding keys defined for the portfolio.

This is typically useful where transactions represent a single coupon or dividend payment but investments are held in multiple strategies. Note you can override this for an individual transaction. For an example, see this Jupyter Notebook.

TransactionConfiguration/default/InstrumentEventType

YES

String

Set the value to transitionEvent/Dividend to use this transaction type for corporate actions automatically determined by LUSID to be cash dividends.

By default, LUSID applies the built-in Dividend transaction type to corporate actions representing cash dividends, which has the effect of increasing the main cash balance by the dividend amount, minus any tax due if a tax rule set applies.

For example, you may want to override Dividend and specify your own transaction type in order to process tax differently. See an example.

On a movement within the transaction type

TransactionConfiguration/default/TaxLotSelectionMethod

YES

String

Override the default accounting method (set on the portfolio) for all transactions of a particular transaction type. Available values are FirstInFirstOut, LastInFirstOut, HighestCostFirst, LowestCostFirst. Note you can override this for an individual transaction.

Holding system properties

System property key

Writable?

Data type

Explanation

Holding/default/TaxlotPurchaseDate

NO

DateTime

Retrieves the date on which a set of assets was purchased.

Holding/default/TaxlotPurchasePrice

NO

Decimal

Retrieves the price paid in the portfolio currency for the set of assets purchased.

Holding/default/TaxlotId

NO

String

Retrieves a unique identifier for the set of assets purchased.

Holding/default/SourcePortfolioId

NO

String

For a holding in a portfolio group, retrieves the code of the portfolio to which it belongs.

Holding/default/SourcePortfolioScope

NO

String

As above, but retrieves the portfolio scope.

Holding/default/Instrument

DEPRECATED

Holding/default/Units

DEPRECATED

Holding/default/Cost

DEPRECATED

Holding/default/PortfolioCost

DEPRECATED

Holding/default/Type

DEPRECATED

Holding/default/Currency

DEPRECATED

Holding/default/Weight

DEPRECATED

Holding/default/Date

DEPRECATED

Holding/default/SubHoldingKey

DEPRECATED

Holding/default/FundLineage

DEPRECATED

Holding/default/PV

DEPRECATED

Holding/default/PvCcy

DEPRECATED

Holding/default/Price

DEPRECATED

Holding/default/ExchangeRate

DEPRECATED

Holding/default/Accrual

DEPRECATED

Holding/default/Nominal

DEPRECATED

Holding/default/ForwardFx

DEPRECATED

Holding/default/DfDomCcy

DEPRECATED

Holding/default/DfFgnCcy

DEPRECATED

Holding/default/Delta

DEPRECATED

Holding/default/ParallelDelta

DEPRECATED

Holding/default/ForwardTransactionId

DEPRECATED

Portfolio system properties

Note you can only use portfolio system properties with portfolios (not other types of entity).

System property key

Writable?

Data type

Explanation

Portfolio/default/ModelFees

YES

Number

Store fees for LUSID to use when calculating aggregated returns.

Portfolio/default/AnnualReturnAdjustment

YES

Number

Store adjustments for LUSID to use when calculating aggregated returns.

Portfolio/default/FundFamily

Portfolio/default/ConstituentAnnualReturnAdjustment

YES

Number

Store adjustments for constituents in a benchmark for LUSID to use when calculating aggregated returns.

Portfolio/default/Scope

DEPRECATED?

Portfolio/default/Name

DEPRECATED

Portfolio/default/Id

DEPRECATED

Instrument system properties

Note you can use instrument system properties with transactions and holdings as well as instruments.

System property key

Writable?

Data type

Explanation

Instrument/default/Name

NO

String

Retrieves the display name of the instrument.

Instrument/default/Scope

NO

String

Retrieves the scope in which the instrument is mastered.

Instrument/default/BloombergExchangeCode

NO

String

Retrieves the Bloomberg exchange code.

Instrument/default/LusidInstrumentId

NO

String

Retrieves the automatically-generated LUID identifier.

Instrument/default/ClientInternal

NO

String

Retrieves the ClientInternal market identifier.

Instrument/default/MicCode

NO

String

Retrieves the market identifier code for the exchange.

Instrument/default/Currency

NO

String

Retrieves the ISO 4217 currency code.

Instrument/default/Isin

NO

String

Retrieves the Isin market identifier.

Instrument/default/Cusip

NO

String

Retrieves the Cusip market identifier.

Instrument/default/Sedol

NO

String

Retrieves the Sedol market identifier.

Instrument/default/RIC

NO

String

Retrieves the RIC market identifier.

Instrument/default/Ticker

NO

String

Retrieves the Ticker market identifier.

Instrument/default/CompositeFigi

NO

String

Retrieves the CompositeFigi market identifier.

Instrument/default/ShareClassFigi

NO

String

Retrieves the ShareClassFigi market identifier.

Instrument/default/Figi

NO

String

Retrieves the Figi market identifier.

Instrument/default/WertPapier

NO

String

Retrieves the Wertpapier market identifier.

Instrument/default/QuotePermId

NO

String

Retrieves the QuotePermId market identifier.

Instrument/default/EdiKey

NO

String

Retrieves the EdiKey market identifier.

Instrument/default/LookThroughPortfolioId

NO

String

Instrument/default/LookThroughPortfolioScope

NO

String

Legal entity system properties

Note you can only use legal entity system properties with legal entities (not other types of entity).

System property key

Writable?

Data type

Explanation

LegalEntity/default/LEI

YES

String

Store the Legal Entity Identifier, a 20-character alpha-numeric code based on the ISO 17442 standard. See gleif.org for further information.