How do I configure Luminesce entity providers to read/write properties?

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 and 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):

Note: Configuring Lusid.Person configures 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.Person to retrieve property and identifier values.
• Lusid.Person.Writer to 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).

Using the Sys.Admin.Lusid.Provider.Configure provider

The 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>';

where:

• <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.
• <action> is either:
  • Set to add the table of properties/identifiers to the provider, removing any existing. This is the default if WriteAction is omitted.
  • Modify to add the table of properties/identifiers to the provider, retaining any existing.
  • Remove to remove the table of properties/identifiers, retaining any ones not specified.
  • Reset to 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 Lusid.Person provider:

Mandatory column	Optional columns
Key	Name	Description	IsMain	AsAt
Person/Manager/Address	Address	A property representing the address of the person	False	Latest
Person/PortfolioManager/ManagerId	PortManId	An identifier for this person as a portfolio manager	True	#2022-01-01 09:00:00#
Person/Trader/TraderId	TraderId	An identifier for this person as a trader	True	Latest

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 True for 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 False.
• 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/Amount property that has this two-part data type:

  Key	Name	DataType	Description
  Person/Salary/Amount.Value	SalaryAmount	Decimal	The amount of the salary
  Person/Salary/Amount.Unit	SalaryCurrency	Text	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';

Factory-resetting an entity provider

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;