Creating custom data models for LUSID entities

You can create custom data models for certain LUSID entity types in order to:

Ensure users enter values for particular identifiers and/or properties when they create/edit entities of these types.
Set display preferences when entities of these types are listed in LUSID web app dashboards.

Custom data models are currently available for the following entity types:

Instrument
Transaction (this and other entity types coming soon)

For example, you could create a custom data model for instruments that mandates users must enter a FIGI identifier and a value for a ‘country code’ custom property.

You could go further and create multiple, nested custom data models for particular instruments in order to create a hierarchy that helps classify your data universe. For example, you could specify the custom data model described above as the ‘parent’ applicable to all instruments and then create two ‘child’ custom data models, one applicable to:

Instruments of type Bond that further mandates users must enter an ISIN identifier.
Instruments of type Equity that further mandates users must enter a value for an ‘exchange code’ property.

Example: Creating multiple, nested custom data models for instruments

To implement this scenario we could call the CreateCustomDataModel API, but the LUSID web app offers the best experience.

Step 1: Creating a parent custom data model applicable to all instruments

Navigate to Data Management > Custom Data Models and select Instrument:
Right-click on the Instrument widget and select Add child from the context menu:
On the left-hand side of the screen, give the custom data model a Scope, a Code that is unique within the scope, a Display name and Description:

Making the custom data model applicable to all instruments

On the Conditions tab, the default behaviour is to make the custom data model applicable to all instruments.

Since this is the required behaviour for our custom data model, there is no need to add a condition.

Mandating particular identifiers

On the Identifiers tab, click the Add identifiers button to add the FIGI identifier and make it Required:

Mandating particular properties

On the Properties tab, click the Add properties button to add a suitable country code property and make it Required:

You can add multiple properties using the Add wildcard button, for example Leg/* to add all properties from the Leg domain, or Instrument/MyScope/* to add all properties from the Instrument domain in the specified scope. Note, however, that multiple properties added using wildcards cannot be made Required, so these properties appear prominently in create/edit dialogs but LUSID users are not forced to enter values.

Specifying more intuitive names for data fields, identifiers and properties

On the Aliases tab we can optionally specify more intuitive names for instrument data fields, identifiers and properties, for example:

These names are used instead of the LUSID default names on screens where instruments are listed.

Configuring the sort order when instruments are listed

On the Sort order tab we can optionally change the default way in which screens containing lists of instruments are sorted. More info coming soon.

Creating the custom data model

Click the Save button to create the model and examine the new hierarchy:

Step 2: Creating a child custom data model applicable to bonds

Right-click on the newly-created All Instruments widget and select Add child from the context menu.
On the left-hand side of the screen, give the child custom data model a Scope, a Code that is unique within the scope, a Display name and Description. Note the Entity type, Level and Parent code fields are inherited from the parent custom data model.
On the Conditions tab, click the Add condition button to restrict applicability using any combination of instrument data fields, identifiers and/or properties. For example, to restrict the model just to instruments of type Bond:
Note that to restrict the model to all LUSID types of bond (Bond, ComplexBond and InflationLinkedBond) we would need to use Advanced mode and create an expression using LUSID filter syntax, for example instrumentDefinition.instrumentType in 'Bond','ComplexBond','InflationLinkedBond'.
On the Identifiers tab, add the ISIN identifier and make it Required:
Click the Save button to create the model and examine the new hierarchy:

Step 3: Creating a child custom data model applicable to equities

Right-click on the All Instruments widget and select Add child from the context menu.
On the left-hand side of the screen, give the child custom data model a Scope, a Code that is unique within the scope, a Display name and Description. Note the Entity type, Level and Parent code fields are inherited from the parent custom data model.
On the Conditions tab, click the Add condition button to restrict applicability using any combination of instrument data fields, identifiers and/or properties. For example, to restrict the model just to instruments of type Equity:
On the Identifiers tab, add a suitable exchange code property and make it Required:
Click the Save button to create the model and examine the new hierarchy:

Creating entities as a user under custom data models

With our custom data models in place, a LUSID user can choose to create or edit instruments under (that is, in the context of) these data models. When they do, the restrictions mandated by the data models apply.

Using the LUSID web app

Navigate to the Data Management > Instruments dashboard and note the breadcrumb trail in the top left corner. The primary Instruments dashboard in the trail lists standard instruments created without reference to data models (and that therefore might not have values for particular identifiers or properties):

Navigate to a location in the dropdown menu to list instruments created under a particular custom data model, for example Instruments > All instruments > Equity instruments:

Click the Create instrument button on this dashboard; note that the mandatory identifiers and properties are displayed prominently on the input screen, prefixed with an M icon. The asterisk after the name means a LUSID user cannot create the instrument until values are provided:

Using the LUSID REST API

A LUSID user can call the UpsertInstruments API and supply the dataModelScope and dataModelCode of the custom data model to use as query parameters in the URL, for example:

curl -X POST "https://<your-domain>.lusid.com/api/api/instruments?dataModelScope=CDMs&dataModelCode=Equities"
   -H "Authorization: Bearer <your-API-access-token>"
   -H "Content-Type: application/json"
   -d '{"upsert-request-1": {
    "name": "BP $0.25 LDN",
    ...
  }
}'

The user should check the failed object in the response for instruments that did not meet the requirements of this custom data model:

{
  "values": {},
  "staged": {},
  "failed": {
    "upsert-request-1": {
      "id": "upsert-request-1",
      "type": "CustomDataModelValidationFailure",
      "detail": "Mandatory Custom Data Model Identifier 'Instrument/default/Figi' was not provided",
      "errorDetails": []
    }
  },
  ...
}