By default, Luminesce providers for built-in entities such as portfolios, instruments and transactions do not know anything about your custom properties, so columns (fields) representing these properties cannot be displayed in the catalog for entity providers out-of-the-box.
Note: You can read/write properties independently of entities using a small set of dedicated property providers. See a list.
The same is true for entities that support user-specified identifiers, for example custom entities, persons and legal entities. Note that under-the-hood, an identifier is defined as a property type with a 3-stage key.
You can configure a read/write entity provider pair to 'inline' properties and/or identifiers in order to interact with them in the same way as standard entity data fields. Consider the following example of the
Lusid.Person.Writer provider pair (the catalog is the same for both):
- Out-of-the-box on the left, the catalog lists the standard data fields for person entities: Description, DisplayName and LusidEntityId.
- Once configured on the right, the catalog additionally lists the Address property and the PortManId and TraderId identifiers (you may need to click the refresh button, highlighted in red):
Lusid.Person.Writer at the same time, and vice versa. The change affects your entire domain, so every user who wants to use those providers.
You can now use:
Lusid.Personto retrieve property and identifier values.
Lusid.Person.Writerto create, update and delete property and identifier values. For more information on nuances of writing different kinds of property to LUSID entities, see this article.
Understanding which entity providers you can configure
You can configure most read/write entity provider pairs, including (though not limited to):
- Portfolios and portfolio groups
- Transactions and holdings
- Instruments of any asset class
- Legal entities and persons.
To see a full list, run the following query:
select distinct Name, Description from Sys.Registration where Name like 'Lusid.%.Factory';
An entry in the table of results means you can pass the name of that provider (for example,
Lusid.Instrument.FxOption) to the
Sys.Admin.Lusid.Provider.Configure provider (see below).
Sys.Admin.Lusid.Provider.Configure provider enables you to configure a read/write entity provider pair. It has the following syntax:
select * from Sys.Admin.Lusid.Provider.Configure where Provider = '<configurable-entity-provider>' and Configuration = <table-of-configuration-data> and WriteAction = '<action>';
<configurable-entity-provider>is the catalog name of a provider that supports configuration (you can supply either the reader or the writer).
<table-of-configuration-data>is, at a minimum, a table with one column containing 3-stage property keys, one row per property/identifier.
Setto add the table of properties/identifiers to the provider, removing any existing. This is the default if
Modifyto add the table of properties/identifiers to the provider, retaining any existing.
Removeto remove the table of properties/identifiers, retaining any ones not specified.
Resetto factory-reset the provider, removing all properties/identifiers.
The table of configuration data can optionally have the following additional columns to enrich the catalog. If omitted,
Sys.Admin.Lusid.Provider.Configure automatically extracts information from the underlying property type. Consider the following example table for the
|Mandatory column||Optional columns|
Note the following:
- If you do not specify a Name then the display name of the underlying property type is used. Note names must be unique in the catalog, so the ability to alias is useful.
- If you specify a Description it appears in a tooltip next to the field in the catalog to help provider users understand the expected data.
- If you specify
Truefor IsMain then a reader provider returns the field in queries that begin
select ^ from Some.Provider. This has no impact on a writer provider. The default is
- If you specify an AsAt datetime then information is extracted from an old underlying property type. The default is to use the latest property type.
- If the underlying property type has a complex data type with a unit schema (for example,
iso4217CurrencyAndAmount), then you can specify a separate Key for each part using dot notation, to create two fields in the provider. For example, to represent a
Person/Salary/Amountproperty that has this two-part data type:
Key Name DataType Description
The amount of the salary
The currency of the salary
Configuring an entity provider for the first time
The following example query adds an Address property and PortManId and TraderId identifiers to the catalog for the
Lusid.Person provider (and
Lusid.Person.Writer), and also confers friendly column names, 'main' status, and tooltips. Since the
WriteAction parameter is omitted,
Set is assumed:
@keysToCatalog = values ('Person/Manager/Address', 'Address', False, 'A property representing the address of the person'), ('Person/PortfolioManagers/ManagerId', 'PortManId', True, 'An identifier for this person as a portfolio manager'), ('Person/Traders/TraderId', 'TraderId', True, 'An identifier for this person as a trader'); @config = select column1 as [Key], column2 as Name, column3 as IsMain, column4 as Description from @keysToCatalog; select * from Sys.Admin.Lusid.Provider.Configure where Provider = 'Lusid.Person' and Configuration = @config;
Updating an entity provider
The following query uses
WriteAction = 'Modify' to add a new property to the catalog for
Lusid.Person, retaining the three added above. Only the property key is specified, so the column name inherits the display name of the underlying property type, the field is not considered 'main', and no tooltip is provided. Since the table of data resolves to exactly one column and one row, a scalar variable can be passed in:
@@keysToCatalog = select 'Person/Manager/PhoneNumber' as [Key]; select * from Sys.Admin.Lusid.Provider.Configure where Provider = 'Lusid.Person' and Configuration = @@keysToCatalog and WriteAction = 'Modify';
The following query uses
WriteAction = 'Remove' to remove one of the identifiers from
Lusid.Person. Only the property key is required:
@@keysToCatalog = select 'Person/Traders/TraderId' as [Key]; select * from Sys.Admin.Lusid.Provider.Configure where Provider = 'Lusid.Person' and Configuration = @@keysToCatalog and WriteAction = 'Remove';
The following query uses
WriteAction = 'Reset' to remove all properties and identifiers from
Lusid.Person. No property keys are required:
select * from Sys.Admin.Lusid.Provider.Configure where Provider = 'Lusid.Person' and WriteAction = 'Reset';
You can see a list of all currently-configured entity provider pairs by running the following query:
select distinct Name, Client from Sys.Registration where Name like 'Lusid.%' and Name not like '%CustomEntity%' and Client is not null;