Help Center
Select Category

Categories

Kurtosys App
System Admin
DXM
Documents
Studio
Data
Communities
Studio for Office

Links

Contact Support
Kurtosys website

API Method Standards and Best Practices – Properties

Easily load client data into the Kurtosys App using Kurtosys APIs.

Once loaded, data can be used in client documents, portals, or websites.

Create Properties
Go
Load Properties
Go
Update Properties
Go
Retrieve Properties
Go

What are properties and why do I need them?

Properties are commonly used to make any page element data-driven. They enable us to load short, distinct data points. Any number of them can be created. 

Functions:

  • Can be retrieved and used as single data-driven page elements in master templates
  • Can be used to automate processes or steps of a process.
  • Can carry any type of data. Mostly, they carry short values. 
 

For financial products like funds, properties are used to load fund codes, names, registered countries, inception date, etc. Characteristics of a product that change infrequently.

Documents, websites or portals require real time data to be accurate. This requires new data in the platform. Loading properties ensures that data-driven page elements are updated in real time.

Data-Driven Templates
Automate Distribution
Previous
Next

When and where do I use them?

Properties data is created in the Data Module of the Kurtosys App using one or more entity types: Fund, Class, Account or Benchmark.

They are created in the Data Dictionary. Data is loaded once they exist in the Data Dictionary.

Properties provide descriptive information relating to a specific product entity.

For example, a class would have a Class Code, a related Fund Code, a Fund Name, a Class Launch Date, and more.

Once created and loaded, they can be used in documents, websites or portals to make page elements data-driven or automate the creation and distribution of any solution. 

What do I need to use them?

  1. Identify your data-driven elements:
    Identify data-driven page elements, across the entire solution. To allow an element to be data-driven, it has to exist in the Data Dictionary and the data must be loaded in the Kurtosys App.

  2. Have the data:
    Ensure you have data, in the right format.

  3. Create properties one-by-one:
    Creating properties require each property to be created using an individual API request.

  4. Load all properties’ data at once:
    Populating properties, unlike property creation, is loaded one product or entity at one time. If you have multiple properties, your request should contain a key/value pair for each property.

  5. Use the required API parameters:
    Make sure you have the correct end point, header, content type and HTTP method. Further details on this will be provided with every step listed below.

Step 1: Create Properties

Properties must be created in the Data Dictionary before any data can be loaded.

Properties need to be created for each entity level used.

For example, if data will be loaded at class and fund level. Properties specific to each product should be created on each level respectively.

Required fields
Field
Criteria
Description
Requirements
Example
code
Required
A unique identifier for the property.
Lowercase without spaces. Maximum of 32 characters. Words separated by an underscore. No special characters except an underscore (_).
fund_code
entityType
Required
Indicates the entity level used. Four available options: Class, Fund, Benchmark or Account
Must be one of four options: ‘CLSS’, ‘FUND’, ‘BMRK’, ‘ACCT’
FUND
dataType
Required
Indicates the type of data the field will contain.
Must be one of six options: ‘STRG’, ‘DCML’, ‘DTIM’, ‘BOOL’, ‘ITGR’ or ‘DATE’
STRG
label
Required
A label for the property. Shows as the grey text above the value of a property within the Data module.
Descriptive name using title case. Avoid special characters.
Fund Code
description
Required
A description of the data the property will carry.
Less than 100 characters. Use sentence case. Avoid special characters.
The code of the fund
validationRule
Optional
Turns on the ability to define a complete list of possible data values that can be loaded. If a data value doesn’t exactly match an item in the list – it cannot be loaded.
If included in the API request body: it must be one of two options. ‘VALUES’ or ‘NONE’.
VALUES
allowedValues
Optional (Must be added if validationRule is used with a value of ‘VALUES’
An exhaustive list of possible data values which the property can accept as valid data.
Case sensitive. Performs exact matches. A data value must be in the list to be loaded against the property.
Allowed values: ‘code1’, ‘code2’, ‘code3’, etc
formatCode
Optional
Enables the use of an existing format code in the system. A format code will apply a number, date or currency formatting to the data value loaded.
Format codes must be added via the API before they can be applied to a property.
dd.MM.yyyy
group
Required
A label that can be used to group similar properties together.
Must be a string value. Must be consistent across different properties of the same group.
core
subGroup
Optional
A label of group items within a group ie a subgroup.
Must be a string value. Must be consistent across different properties of the same sub group.
documents
includeIn
Optional
Enables the translations of data loaded against the property by automatically pulling in data values to the Translations module.
If included in the API request body: must be one of two options. ‘true’ or ‘false’
true
cardinality
Required
Option to define whether the property will carry a single value or multiple values (ie an array)
Must be one of two options: ‘1’ or ‘N’ (N indicates many)
1
An example of property creation

In the following example, we’re adding a new property to store the inception date of each product. No value validation is being performed. The property will only hold one date.

For more details on the API endpoint to be used and the minimum required parameters, see the API Documentation page. 

{
    "code": "inception_date",
    "entityType": "CLSS",
    "dataType": "DATE",
    "validationRule": "NONE",
    "label": "Inception Date",
    "description": "Shareclass Inception Date",
    "group": "core",
    "cardinality": "1"
}

The endpoint to be used can be one of the following depending on the method:

HTTPS

  1. For US clients: https://api-us.kurtosys.app/config/addProperty
  2. For UK clients: https://api-uk.kurtosys.app/config/addProperty
  3. For EU clients: https://api-eu.kurtosys.app/config/addProperty


Websocket (for bulk uploads)

  1. For US clients: wss://api-us.kurtosys.app/config/addProperty
  2. For UK clients: wss://api-uk.kurtosys.app/config/addProperty
  3. For EU clients: wss://api-eu.kurtosys.app/config/addProperty

The API will respond with the below code to indicate successful creation, along with a 200 OK response code.

{
    "propertyId": 1,
    "code": "inception_date",
    "entityType": "CLSS",
    "dataType": "DATE",
    "validationRule": "NONE",
    "label": "Inception Date",
    "formatCode": "date",
    "description": "Shareclass Inception Date",
    "group": "core",
    "cardinality": "1"
}

Create the property using the API

Log in to Kurtosys App to check it has been created successfully


Things to keep in mind
Correcting an error:

If an error was made during the initial creation, it can be corrected by resending the body with the necessary corrections. This should only be done if the property does not already have data associated with it. If data has been loaded, it should be deleted first.

Creation on different levels:

If data needs to be loaded on both class and fund levels, the property should be created separately on each level as it cannot be globally used across different levels.

Deleting properties:

Properties cannot be deleted from the Data Dictionary. Properties data can however be deleted. 

How to delete property data

Step 2: Update Properties Data

2.1 Load data

The following items should be completed before loading data:

  1. Create all the required properties in the Data Dictionary
  2. Ensure the data meets the data type requirements. For example, if a property has been created as an integer (ITRG) the data values must be rounded numbers. Decimals will be lost when loading.


Rules when loading data:

  • When loading data into properties, all the data values for all properties must be loaded at once, one product or entity at a time.
  • Each product or entity must have an identifier that allows targeting of the product to make visualisations data-driven. This could be anything but will always be referred to as a client code in the request body
An example of loading property data ​

In the following example, we have created five properties:

  1. an ISIN (used as the identifier or client code)
  2. an Inception Date
  3. an AUM figure
  4. an Asset Class
  5. a Country Registration for Institutional Clients field

Now we can load data for these five properties using the below body:

{
"clientCode": "GB00B4NVSH01",
"type": "CLSS",
"propertiesPub": {
"inception_date": {
"value": "1994-09-30"
},
"isin": {
"value": "GB00B4NVSH01"
},
"aum": {
"value": 123000000
},
"asset_class": {
"value": "Equity"
},
"country_reg_inst": {
"value": [
"LU",
"CH"
]
}
}
}

The required API parameters remain the same as for the creation of the property. Only the end point is different.

The endpoint to be used can be one of the following depending on the method:

HTTPS

  1. For US clients: https://api-us.kurtosys.app>/dataloader/upsertentity
  2. For UK clients: https://api-uk.kurtosys.app>/dataloader/upsertentity
  3. For EU clients: https://api-eu.kurtosys.app>/dataloader/upsertentity


Websocket (for bulk uploads)

  1. For US clients: wss://api-us.kurtosys.app>/dataloader/upsertentity
  2. For UK clients: wss://api-uk.kurtosys.app>/dataloader/upsertentity
  3. For EU clients: wss://api-eu.kurtosys.app>/dataloader/upsertentity

The API will respond with the below code to indicate successful creation, along with a 200 OK response code.

{
"data": {
"entityId": 1104542,
"parentEntityId": null,
"type": "CLSS",
"clientId": 1180,
"clientCode": "GB00B4NVSH01",
"lastModified": "2024-05-27T14:06:38.000Z",
"lastModifiedBy": 3544,
"created": "2024-05-27T09:56:30.000Z",
"createdBy": 3544,
"propertiesPub": {
"inception_date": {
"value": "1994-09-30"
},
"isin": {
"value": "GB00B4NVSH01"
},
"aum": {
"value": 123000000
},
"asset_class": {
"value": "Equity"
},
"country_reg_inst": {
"value": [
"LU",
"CH"
]
}
}
"properties_draft": null,
"userProperties_pub": null,
"userProperties_draft": null,
"jobReference": "1932901b-8c5d-4a6f-90c0-5743b89a2711",
"rowHash": "beb338c4b9e567f80a0c1a43dd921e4d5b75f90f8ec46e6bc5c346fedff94b86"
}
}

Load the properties data via the API

Log in to the Kurtosys App to check that the entity has been created and carries the loaded properties data

Things to keep in mind
Correcting a specific property’s data value:

If an error occurred during the initial loading, you can fix it by sending the entire request body again, including all properties. Only update the data value for the specific property that needs correction. Do not send a request body with only the specific property, as this will remove the previously loaded properties and replace them with the single property value you’ve sent.

Deleting a specific property’s data value:

If a property should no longer carry any data, you can resend the request including all required properties excluding the property that should be removed.

How to delete property data

Creation on different levels:

If data has to be loaded at both class and fund levels, the property’s data should be loaded separately at each level. This can be done by changing the ‘type’ field to the correct level. For example, ‘CLSS’ for class level, or ‘FUND’ for fund level.

Changing the client code for each product entity:

If multiple products or entities need to be loaded, make sure to change the client code field for each API request; otherwise, you will simply overwrite the same product/entity. By extension, each product or entity code must be unique.

Ensuring data loaded matches the data format:

When loading data, it is crucial to ensure that the data matches the data format of the property. 

The following rules apply to each data format:

  1. String (STRG): The field can receive any data value but is most commonly used for text, or combinations of numbers and text.
  2. Decimal (DCML): The field can receive numeric values with any number of decimals. A full stop (.) must be used to indicate decimals (eg 20.50)
  3. Integer (ITGR): The field can also carry numeric values but cannot carry decimal numbers. (eg 40)
  4. Boolean (BOOL): This field is used to store true or false data values. Data values must be provided as ‘0’ or ‘1’. Zero indicates false and one indicates true. 
  5. Date (DATE): The field can only receive and carry dates. Dates need to be formatted using the following convention: YYYY-MM-DD
  6. Date and Time (DTIM): The field is used to store combinations of dates and times. The following convention should be used: “YYYY-DD-MM HH:MM:SS”

2.2 Update data

The following items should be completed before updating data:

  1. Products and entities must already be created in the system. Each with a unique client code.
  2. Ensure you have identified the product/entity or list of entities that need to be updated.
  3. Ensure the data meets the data type requirements. For example, if a property has been created as an integer (ITRG) the data values must be rounded numbers. Decimals will be lost when loading.


Rules when updating data:

  • When updating properties all the data values for all properties must be loaded at once, one product or entity at a time.
  • Each product or entity must have an identifier that allows targeting of the product to make visualisations data-driven. This could be anything but will always be referred to as a client code in the request body.
An example of updating property data ​

In the previous step we loaded and created an entity with five properties. In the following example, we will update the same entity including two additional properties:

  1. an ISIN (used as the identifier or client code)
  2. an Inception Date
  3. an AUM figure
  4. an Asset Class
  5. a Country Registration for Institutional Clients field
  6. Benchmark Name 
  7. Share Class Code

Now we can load data for these seven properties using the below body:

{
"clientCode": "GB00B4NVSH01",
"type": "CLSS",
"propertiesPub": {
"inception_date": {
"value": "1994-09-30"
},
"isin": {
"value": "GB00B4NVSH01"
},
"aum": {
"value": 123000000
},
"asset_class": {
"value": "Equity"
},
"benchmark_name": {
"value": "MSCI World Index"
},
"share_class": {
"value": "C"
},
"country_reg_inst": {
"value": [
"LU",
"CH"
]
}
}
}

The required API parameters remain the same as for the creation of the property. Only the end point is different.

The endpoint to be used can be one of the following depending on the method:

HTTPS

  1. For US clients: https://api-us.kurtosys.app>/dataloader/upsertentity
  2. For UK clients: https://api-uk.kurtosys.app>/dataloader/upsertentity
  3. For EU clients: https://api-eu.kurtosys.app>/dataloader/upsertentity


Websocket (for bulk uploads)

  1. For US clients: wss://api-us.kurtosys.app>/dataloader/upsertentity
  2. For UK clients: wss://api-uk.kurtosys.app>/dataloader/upsertentity
  3. For EU clients: wss://api-eu.kurtosys.app>/dataloader/upsertentity

The API will respond with the below code to indicate successful creation, along with a 200 OK response code.

{
"message": "Entity updated successfully"
}

Load the updated properties data via the API

Log in to the Kurtosys App to check that the entity has been updated and carries the loaded properties data


Things to keep in mind
Correcting a specific property’s data value:

If an error occurred during the initial loading, you can fix it by sending the entire request body again, including all properties. Only update the data value for the specific property that needs correction. Do not send a request body with only the specific property, as this will remove the previously loaded properties and replace them with the single property value you’ve sent.

Deleting a specific property’s data value:

If a property should no longer carry any data, you can resend the request including all required properties excluding the property that should be removed.

How to delete property data

Creation on different levels:

If data has to be loaded at both class and fund levels, the property’s data should be loaded separately at each level. This can be done by changing the ‘type’ field to the correct level. For example, ‘CLSS’ for class level, or ‘FUND’ for fund level.

Changing the client code for each product entity:

If multiple products or entities need to be loaded, make sure to change the client code field for each API request; otherwise, you will simply overwrite the same product/entity. By extension, each product or entity code must be unique.

Ensuring data loaded matches the data format:

When loading data, it is crucial to ensure that the data matches the data format of the property. 

The following rules apply to each data format:

  1. String (STRG): The field can receive any data value but is most commonly used for text, or combinations of numbers and text.
  2. Decimal (DCML): The field can receive numeric values with any number of decimals. A full stop (.) must be used to indicate decimals (eg 20.50)
  3. Integer (ITGR): The field can also carry numeric values but cannot carry decimal numbers. (eg 40)
  4. Boolean (BOOL): This field is used to store true or false data values. Data values must be provided as ‘0’ or ‘1’. Zero indicates false and one indicates true. 
  5. Date (DATE): The field can only receive and carry dates. Dates need to be formatted using the following convention: YYYY-MM-DD
  6. Date and Time (DTIM): The field is used to store combinations of dates and times. The following convention should be used: “YYYY-DD-MM HH:MM:SS”

Step 3: Retrieve Properties Data

After loading properties data, and consequently the product or entity itself, you can now search and retrieve various products and entities from the Kurtosys App. This can be done individually or in bulk based on search criteria.

Option 1: Retrieving Properties for an Individual Product or Entity

Retrieve a specific product or entity using a specific client code.

Required fields
Field
Required
Description
Requirements
Example
type
Required
Indicates the entity level used. Four available options: Class, Fund, Benchmark or Account
Must be one of four options: ‘CLSS’, ‘FUND’, ‘BMRK’, ‘ACCT’
FUND
clientCode
Required
The identifier used for the product or entity. Could be any data value that identifies the product or entity.
A unique code that is used to identify and retrieve a specific product or entity.
FUND01
search
Required
Indicates which parameters should be included in the search. If everything should be returned, it can be included but left blank.
Must be included in the request body. Empty square brackets can be used to retrieve all data.
“search”: [ ]
An example of retrieving specific entities with property data

In the following example, we have already created a couple products/entities in the system. We would now like to retrieve the properties data for a specific product on class level: ‘GB00B4NVSH01’

{
"type":"CLSS",
"clientCode":["GB00B4NVSH01"],
"search":[]
}
  1. For US clients: https://api-us.kurtosys.app/fund/searchEntity
  2. For UK clients: https://api-uk.kurtosys.app/fund/searchEntity
  3. For EU clients: https://api-eu.kurtosys.app/fund/searchEntity

The API will respond with the below code to indicate successful creation, along with a 200 OK response code.

{
"values": [
{
"entityId": 1104611,
"parentEntityId": null,
"type": "CLSS",
"clientId": 1180,
"clientCode": "GB00B4NVSH01",
"lastModified": "2024-06-20T11:15:01.000Z",
"lastModifiedBy": 3544,
"created": "2024-06-20T10:41:40.000Z",
"createdBy": 3544,
"properties_pub": {
"asset_class": {
"value": "Equity"
},
"aum": {
"value": 123000000
},
"benchmark_name": {
"value": "MSCI World Index"
},
"country_reg_inst": {
"value": [
"LU",
"CH"
]
},
"inception_date": {
"value": "1994-09-30"
},
"isin": {
"value": "GB00B4NVSH01"
},
"share_class": {
"value": "C"
}
},
"properties_draft": null,
"userProperties_pub": null,
"userProperties_draft": null,
"jobReference": "daccba65-863d-4286-839a-76a662c85046",
"rowHash": "847a63484d8bc93a832bb9ccf0fb93c02b1ed5c010c9ef5fa137da2a89227ad0"
}
],
"total": 1
}

Log in to the Kurtosys App and review the property data within the Data module.

Option 2: Retrieve all products/entities that carry a property with a certain value

Retrieve products or entities using a search for a property carrying a specific data value.

Required fields
Field
Required
Description
Requirements
Example
type
Required
Indicates the entity level used. Four available options: Class, Fund, Benchmark or Account
Must be one of four options: ‘CLSS’, ‘FUND’, ‘BMRK’, ‘ACCT’
CLSS
search
Required
Allows the user to specify search criteria.
Contains the parameters required for the search. This includes the property, the required values, and a match type. Any number of required values can be used in the search. Two match types can be used: ‘MATCH’ for an exact match, and ‘LIKE’ for a fuzzy match.
“search”: [{ “property”: “asset_class”, “values”: [“Equity”], “matchtype”: “MATCH” }],
limit
Not Required
Allows the user to specify a limit to the number of products or entities returned. This is useful when you have a large number of results.
Must be a numeric value.
1000
start
Not Required
Returns a specified subset of results. Especially useful when you have more results than the limit specified.
Must be a numeric value. ‘0’ is the first product or entity in the list.
0
sort
Not Required
Allows for the sorting of search results. Can be based on the same property used for the search or another property.
Must contain two elements: ‘key’ which specifies the property used to sort. ‘direction’ which can either ascending (ASC) or descending (DESC).
ASC
An example of retrieving entities using search rules

In the following example, we have already created a couple products/entities in the system. We would now like to retrieve the products or entities that carry the property of Asset Class with the value of ‘Equity’.

{
"type": "CLSS",
"search": [
{
"property": "asset_class",
"values": [
"Equity"
],
"matchtype": "MATCH"
}
],
"sort": {
"key": "asset_class",
"direction": "ASC"
},
"limit": 1000,
"start": 0
}
  1. For US clients: https://api-us.kurtosys.app/fund/searchEntity
  2. For UK clients: https://api-uk.kurtosys.app/fund/searchEntity
  3. For EU clients: https://api-eu.kurtosys.app/fund/searchEntity

The API will respond with the below code to indicate successful creation, along with a 200 OK response code.

{
"values": [
{
"entityId": 1104542,
"parentEntityId": null,
"type": "CLSS",
"clientId": 1180,
"clientCode": "ABCD",
"lastModified": "2024-05-27T14:06:38.000Z",
"lastModifiedBy": 3544,
"created": "2024-05-27T09:56:30.000Z",
"createdBy": 3544,
"properties_pub": {
"asset_class": {
"value": "Equity"
},
"benchmark_name": {
"value": "S&P 500"
},
"effective_date": {
"value": "2024-05-27"
},
"fund_base_currency": {
"value": "EUR"
},
"fund_name": {
"value": "Kapital Equity Fund"
},
"isin": {
"value": "ABCD"
}
},
"properties_draft": null,
"userProperties_pub": null,
"userProperties_draft": null,
"jobReference": "1932901b-8c5d-4a6f-90c0-5743b89a2711",
"rowHash": "beb338c4b9e567f80a0c1a43dd921e4d5b75f90f8ec46e6bc5c346fedff94b86"
}
],
"total": 1,
"limit": 1000
}

Use the returned API response to confirm the entities returned

©2023 Kurtosys Systems

Youtube Linkedin Github