Attributes configuration
Learn how to configure the attributes in the Reltio business model.
Attributes configuration overview
In the Reltio business model configuration, you can configure the attributes in Entity Types, Relation Types, and Interaction Types.
An attribute in the Reltio platform can hold multiple values, each associated with a contributing crosswalk. Use the Attribute APIs to manipulate individual values associated with an attribute.
Reltio supports these attribute types:
- Enumerated
- Simple attributes with a predefined set of values.
- Lookup
- Simple attributes with a predefined set of values loaded from a JSON file and thus can be easily changed.
- Nested
- Non-atomic attributes that can have simple or nested attributes. An example is the Education attribute that consists of atomic simple attributes such as University, Year of Graduation, and Degree.Note: If you want to merge nested attributes, contact Support to enable the collapseNonOvNestedsWhenMatchOvOnlyEnabled parameter in your tenant configuration. By default, the flag is disabled, that is, it’s set to false.
- Reference
-
Non-atomic attributes that reference properties of another entity object. An example is the Address attribute references the Location entity. Multiple objects can reference the same object. Typically used to model a M:M relationship
Attribute configuration can specify all types of attributes, in any order (order is preserved). If you change an attribute type, create a new index for your tenant to obtain correct results in future searches. You can initiate a Reindex job and create a separate index using the enableSeparateIndexing flag. For more information, see Reindex Data Task.
- keyAttributeURIs
- matchFieldURIs
- doNotOverrideForSourceURIs
- immutableExceptForSources
- immutableForSources
- referencedAttributeURIs
- dependentLookupAttributes
In the following examples, the parameter values in the child configuration aren’t defined, so they inherit their values from the parent configuration.
Parent Configuration
..."entityTypes": [
{
"uri": "configuration/entityTypes/HCO",
"attributes": [
{
"label": "Name",
"name": "Name",
"description": "Name",
"type": "String",
"hidden": false,
"important": false,
"system": false,
"required": false,
"searchable": true,
"attributeOrdering": {
"orderType": "ASC",
"orderingStrategy": "LUD"
},
"uri": "configuration/entityTypes/HCO/attributes/Name",
"skipInDataAccess": false
}
]
}
]...
Child Configuration
..."entityTypes": [
{
"uri": "configuration/entityTypes/HCO",
"attributes": [
{
"description": "New Simple attribute",
"name": "A1",
"label": "A1_label",
"type": "String",
"hidden": true,
"uri": "configuration/entityTypes/HCO/attributes/A1"
},
{
"label": "Changed label for Name",
"type": "String",
"uri": "configuration/entityTypes/HCO/attributes/Name"
}
]
}
]...
Configuration With Inheritance
..."entityTypes": [
{
"uri": "configuration/entityTypes/HCO",
"attributes": [
{
"label": "Al_label",
"name": "A1",
"description": "New Simple attribute",
"type": "String",
"hidden": true,
"important": false,
"system": false,
"attributeOrdering": {
"orderingStrategy": "LUD"
},
"uri": "configuration/entityTypes/HCO/attributes/A1",
"skipInDataAccess": false
},
{
"label": "Changed label for Name",
"name": "Name",
"description": "Name",
"type": "String",
"hidden": false,
"important": false,
"system": false,
"required": false,
"searchable": true,
"attributeOrdering": {
"orderType": "ASC",
"orderingStrategy": "LUD"
},
"uri": "configuration/entityTypes/HCO/attributes/Name",
"skipInDataAccess": false
}
]
}
]...
Attributes structure
Attributes of an object are stored in the attributes property. It’s a JSON object, where all attributes are grouped by attribute names and that has URI: {entity URI}/attributes. Each attribute name represents a collection of attribute instances with the structure provided in the table below. All requests to the data API must be signed with an access token. For more information, see topic Authentication API.
Property | Description | Type |
---|---|---|
URI |
The path used to reach an attribute configuration. Format: configuration/{objectType}/attributes/{AttributeName} |
String, URI |
type | Type of attribute from the configuration. | String, URI |
value |
For simple attributes: value of attribute. Can be String, Integer, Number, or URL based on the type of attribute. For nested and reference attributes: stores subattributes. | String OR JSON object |
required | Specifies whether the attribute is required (that is, during create/update, the API validates that this attribute is defined). Default value is false. | String |
entityURI | Applicable only for reference attributes (see Reference attribute configuration). | Entities API URI |
refEntity | Only for reference attributes. Contains "crosswalks" of referenced entity attributes and "objectURI" pointing to the referenced entity. | JSON object |
refRelation | Only for reference attributes, contains "crosswalks" of referenced relation and "objectURI" pointing to the referenced relation. | JSON object |
startEntityCrosswalks | Crosswalks of start entity with which this relation was created in the case when a relation was created as part of the reference attribute, or specifying start entity by crosswalk. | JSON object |
endEntityCrosswalks | Crosswalks of end entity with which this relation was created in the case when a relation was created as part of reference attribute, or specifying end entity by crosswalk. | JSON object |
Example:
{
"URI": "entities/e1/attributes",
"FirstName":[
{
"URI": "entities/e1/attributes/FirstName/1",
"type": "configuration/entityTypes/Individual/attributes/FirstName",
"value":"Ivan"
},
{
"URI": "entities/e1/attributes/FirstName/2",
"type": "configuration/entityTypes/Individual/attributes/FirstName",
"value":"John"
}
],
"Education":[
{
"URI": "entities/e1/attributes/Education/3",
"type": "configuration/entityTypes/Individual/attributes/Education",
"value":{
"University":[
{
"URI": "entities/e1/attributes/Education/3/University/4",
"type": "configuration/entityTypes/Individual/attributes/Education/University",
"value":"UCSF"
},
{
"URI": "entities/e1/attributes/Education/3/University/5",
"type": "configuration/entityTypes/Individual/attributes/Education/University",
"value":"SPbGU"
}
]
}
}
],
"Address":[
{
"URI": "entities/e1/attributes/Address/6",
"entityURI": "entities/e2",
"type": "configuration/entityTypes/Individual/attributes/Address",
"value":{
"City":[
{
"uri": "entities/e1/attributes/Address/6/City/7",
"type": "configuration/entityTypes/Location/attributes/City",
"value":"New York"
}
],
"AddressType":[
{
"URI": "entities/e1/attributes/Address/6/AddressType/8",
"type": "configuration/relationshipTypes/HasAddress/attributes/AddressType",
"value":"Home"
}
]
}
}
]
}
Simple and enumerated attribute configuration
The Simple and Enumerated attribute configurations have the following properties:
Property | Required | Description | Type |
---|---|---|---|
URI | Yes |
Path that is used to reach the attribute configuration. Format: configuration/{objectType}/attributes/{AttributeName} | String, URI |
ID | Yes, for response JSON | System-generated id used internally to get the difference between two versions of the configurations when the configuration is updated. | String |
label | Yes | Readable name of the attribute. This is the text that is shown in the UI for the attribute. | String |
name | Yes |
The Name of an attribute. The name that is used for the attribute internally in the system.
Important: It’s a best practice that the name property for an attribute must be unique across entities. For example, if you have entities for person, employee, and individual, you must have an attribute with the name property set to firstname for only one of the entities; not all three. Non-unique attribute names can cause sorting and other search-related issues. | String |
hidden | No | This property is optional. It allows marking an attribute as hidden. The hidden attributes will be present in the response only when the sendHidden option is used in the request. This flag can be used by applications to determine when to display characteristics of attributes. For example, the Hub doesn’t display attributes marked as hidden. Default: false. | Boolean |
Description | No | Detailed description for the attribute. | String |
faceted | No | If true, this attribute will be displayed in the +More list on the Search page when the entity is selected. | Boolean |
defaultFacetedAttributes | No | If true, the array of attributes will be displayed in the default attributes list or as facets in the Quick Filters panel on the Search page when the entity is selected. | Array of attributes |
searchable | No | If true, this attribute will be displayed in the Advanced Search page when the entity is selected. | Boolean |
defaultSearchAttributes | No | If true, this attribute is displayed in the default attribute list on the Advanced Search page when the entity is selected. | Boolean |
important | No | Deprecated - don’t use. Marks the attributes that are important in the UI with a bold font or asterisks. | Boolean |
type | Yes | Data type of the attribute, Simple, Nested, or Reference. Possible values for Simple are:
| String, Enum |
cardinality | No |
Cardinality of the attribute type. It has two sub-elements:
During the application of a configuration, Reltio Cloud verifies that if minValue is specified, then it must be greater than or equal to zero; if maxValue is specified, then it must be greater than or equal to 1; and if both attributes are specified, then maxValue must be greater than or equal to minValue. Here’s an example:
Note: The values must be Integers; that is, values such as 1.793 aren’t acceptable.
| Integer |
searchable | |||
values | Yes, for enumeration attributes | Array of possible values for an attribute. | Array of values (String) |
defaultValue | No | This property is optional. It allows configuring default values for attributes. When you create a new profile in the UI, these attributes are added in the profile with the configured default values. You can also override the default value. | String |
The StringNotTokenized type for a simple attribute signals that two fields must be created in the index when storing attribute values of this type in the ES index:
- normal ("name": "San Francisco")
- "nameNotTokenized" : "San_Francisco" - one with post-fix "NotTokenized" with all value white spaces and punctuation replaced with some sign like "_" to avoid ES tokenization.
{
"URI":"configuration/entityTypes/Individual/attributes/FirstName",
"Name": "FirstName",
"ID":"4",
"label":"First Name",
"type":"String"
}
Example 2: {
"URI":"configuration/entityTypes/Individual/attributes/Gender",
"Name":"Gender",
"ID":"5",
"label":"Gender",
"type":"String",
"values":["Male","Female","Unknown"]
}
Nested attribute configuration
The following table summarizes the nested attribute configuration properties:
Property | Required | Description | Type |
---|---|---|---|
URI | Yes |
Path that is used to reach the attribute configuration. Format: configuration/{objectType}/attributes/{AttributeName}/../{AttributeName} | String, URI |
ID | Yes, for response JSON | Internal, system-generated ID used internally to get the difference between two versions of the configurations when the configuration is updated. | String |
label | Yes | The readable name of the attribute. | String |
hidden | No | This property is optional. It allows marking an attribute as hidden. The hidden attributes will be present in the response only when the sendHidden option is used in the request. This flag can be used by applications to determine when to display characteristics of attributes. For example, the Hub doesn’t display attributes marked as hidden. Default: false. | Boolean |
dataLabelPattern | Yes | Pattern that is used to build the attribute value label. This can include static text as well as patterns-attributes in curly brackets. Example: {FirstName} {MiddleName} {LastName}. With square brackets you can define conditional label patterns. If an attribute used inside the brackets doesn’t exist, then all content inside the brackets will be skipped. Example: {FirstName} {MiddleName} {LastName}[, {Credentials}] Note:
| String |
Name | Yes | Name of an attribute. Will be used in Data API (/*link*/). | String |
Description | No | Detailed description for the attribute. | String |
type | Yes | For Nested attribute, the value must always be Nested. | Static String 'Nested' |
cardinality | No |
Cardinality of the attribute type. It has two sub-elements:
During the application of a configuration, Reltio Cloud verifies that if minValue is specified, then it must be greater than or equal to zero; if maxValue is specified, then it must be greater than or equal to 1; and if both attributes are specified, then maxValue must be greater than or equal to minValue. Here’s an example:
Note: The values must be Integers; that is, values such as 1.793 aren’t acceptable.
| Integer |
attributes | Yes | Array of possible nested attributes. CAUTION: It’s bad practice to use the same name for a nested attribute and its sub-attribute. | Array of Attributes Configuration |
enableNestedPartialOverride | No | Set true/false to control whether nested attributes can be partially overridden. Value configured at attribute level overrides the value defined at physical configuration. If not defined at attribute level, then the value defined in the physical configuration will be applied to the nested attribute. | Boolean |
singleValue | No | If true, then only one value can appear in the attribute in the entity. If you specify several different values (possibly from different sources), then all these values will be combined into one nested value (with different values for subattributes). Default: false. | Boolean |
singleValueByCrosswalk | No | If true, then only one value for a particular source can appear in the attribute in the entity. If you specify several different values (from the same source), then all these values will be combined into one nested attribute value (with different values for subattributes). If there is partial override, such nested attribute from the request body won’t substitute whole value for the data provider crosswalk, but it will override (partially) subattributes inside the value. Default: false. | Boolean |
singleValueByCrosswalkSources | No | If the singleValueByCrosswalk property is true, you can additionally specify for which sources to use or ignore the singleValueByCrosswalk rule. Attributes:
| Nested, Array of Sources (String) |
matchFieldURIs, matchFieldURIsExactOrAllNull, matchFieldURIsExactOrNull matchFieldURIsIgnoreCase | No |
Optional sections that can be defined only for nested attributes. They’re used to define match rules for merging nested attributes. These rules specify which subattributes' similarity would define whether different values of nested attributes would merge or not. They have the following format:
In the example above, the following portion
specifies matching "Education" with the same "University" and "Degree" subattributes, the same or both missing YearOfGraduation and YearsInProgram subattributes, and the same or any missing "GPA" and Graduated subattributes. The match rules sections are connected by AND. However, each section is optional and can be used in any combination with other sections or separately. Note: matchFieldURIs, matchFieldURIsExactOrAllNull, matchFieldURIsExactOrNull rules are connected by AND. Each section is optional and can be used in any combination with the others or separately. If the match rule section isn’t defined, then nested attributes will merge if all of their subattributes have the same value.
If the matchFieldURIs section is defined (as described above for the Education nested attribute), then the following apply:
If the "matchFieldURIsExactOrAllNull" section is defined, (as described above for the "Education" nested attribute), then the following apply:
If the matchFieldURIsExactOrNull section is defined (as described above for the Education nested attribute), then the following applies:
By default, the matchFieldURIs nested attribute property is case sensitivity for attribute values, when performing matching for matchField configuration. Set matchFieldURIsIgnoreCase to true for matchFieldURIs, matchFieldURIsExactOrAllNull, and matchFieldURIsExactOrNull configuration to get case insensitive matching. Example 1: Merge if all fields from matchFieldURIs are the same and all fields from matchFieldURIsExactOrAllNull and matchFieldURIsExactOrNull are missing, but there are some other different subattributes.
must merge with this inserted attribute:
in one "Education" attribute in the entity because:
Example 2: Don’t merge attributes having all the same fields if not all of the fields from matchFieldURIs are defined.
must not merge with the inserted attribute
in one Education attribute in the entity because there’s no field ("Degree") defined in these attributes. Example 3: Don’t merge attributes having all the same fields if some fields from matchFieldURIsExactOrAllNull are defined in only one attribute.
must not merge with the inserted attribute.
in one "Education" attribute because there’s no field ( "YearOfGraduation") defined in the Edu2 attribute, although all other attributes are the same. Example 4: Merge attributes if all fields from matchFieldURIs are the same, all fields from matchFieldURIsExactOrAllNull are missing, and some of the fields from matchFieldURIsExactOrNull are defined only in one attribute.
must merge with the inserted attribute.
in one "Education" attribute because:
Note: Nested attributes merge when a new attribute is inserted or a nested attribute is updated.
| |
matchOvOnly | No |
Optional property that specifies whether non-OV values of subattributes would be considered when merging different values of the nested attribute. Default value is false. If the value is set to true, that is, if matchOvOnly is enabled, then match rules are applied only to sub-attribute values with OV=true, and sub-nested attributes that only have end-dated crosswalks are considered to be different from attributes that don't have values or have values with at least one active crosswalk. If the value is false, that is, if matchOvOnly is disabled, then all values of the subattribute are considered. For example, the following value
must merge with the inserted value
if "matchOvOnly" is true; otherwise, it mustn't be merged. Note: This property can’t be used with 'flatOvCalculation' enabled, and neither with 'OtherAttributeWinnerCrosswalk' survivorship strategy with outer 'primaryAttributeUri' used for subattributes of a nested .
|
{
"URI":"configuration/entityTypes/Individual/attributes/Education",
"Name":"Education",
"type":"Nested",
"dataLabelPattern":"{University} {Degree}, {YearOfGraduation}",
"singleValueByCrosswalk": true,
"singleValueByCrosswalkSources": {
"exclude": [
"configuration/sources/Reltio"
]
},
"matchFieldURIs":[
"configuration/entityTypes/Individual/attributes/Education/University",
"configuration/entityTypes/Individual/attributes/Education/Degree"
],
"matchOvOnly": true,
"attributes":[
{
"URI":"configuration/entityTypes/Individual/attributes/Education/University",
"ID":"1",
"Name":"University",
"label":"University",
"type":"String"
},
{
"URI":"configuration/entityTypes/Individual/attributes/Education/Degree",
"ID":"2",
"Name":"Degree",
"label":"Degree",
"type":"String"
},
{
"URI":"configuration/entityTypes/Individual/attributes/Education/YearOfGraduation",
"ID":"3",
"Name":"YearOfGraduation",
"label":"Year of graduation",
"type":"Int"
},
{
"URI":"configuration/entityTypes/Individual/attributes/Education/GPA",
"ID":"4",
"Name":"GPA",
"label":"GPA",
"type":"Number"
}
]
}
Reference attribute configuration
Property | Required | Description | Type |
---|---|---|---|
URI | Yes |
Path that is used to reach the attribute configuration. Format: configuration/{objectType}/attributes/{AttributeName} | String, URI |
ID | Yes, for response JSON | System-generated id used internally to get the difference between two versions of the configurations when the configuration is updated. | String |
label | Yes | Readable name of the attribute. | String |
Name | Yes | Name of the attribute. Used in the Data API (/*link*/). | String |
Description | No | Detailed description for the attribute. | String |
hidden | No | This property is optional. It allows marking an attribute as hidden. The hidden attributes will be present in the response only when the sendHidden option is used in the request. This flag can be used by applications to determine display characteristics of attributes. For example, the Hub doesn’t display attributes marked as hidden. Default: false. | Boolean |
type | Yes | For reference attributes the value must always be reference. | Static String "Reference" |
cardinality | No |
Cardinality of the attribute type. It has two sub-elements:
During the application of a configuration, Reltio Cloud verifies that if minValue is specified, then it must be greater than or equal to zero; if maxValue is specified, then it must be greater than or equal to 1; and if both attributes are specified, then maxValue must be greater than or equal to minValue. Here’s an example:
Note: The values must be Integers; that is, values such as 1.793 aren’t acceptable.
| Integer |
relationshipTypeURI | Yes | The URI of a relationship type used in the reference attribute. | String, Relationship Type URI |
relationshipLabelPattern | Yes | The pattern that is used to build the attribute relationship value label. It can include static text as well as patterns-attributes in curly brackets. Example: {FirstName} {MiddleName} {LastName}With square brackets you can define conditional label patterns: if an attribute used inside the brackets doesn’t exist, then all content inside the brackets will be skipped. Example: {FirstName} {MiddleName} {LastName}[, {Credentials}]Note: If relationshipLabelPatternisn’t specified, label is used. | String, Pattern |
referencedEntityTypeURI | Yes | The URI of entity type or role that is referenced from an entity though relationshipTypeURI. | String, Entity Type, or Role URI |
referencedAttributeURIs | Yes | A Reference attribute doesn’t have its own attributes. It’s using attributes of a relationship and referenced entity. In this property, an array of relationship and referenced entity URIs is the set that will be used as part of the reference attribute. | Array of URIs for relationship and referenced entity attributes |
doNotOverrideForSourceURIs | No | If there is profile override, if the reference attribute isn’t provided in a request, then the existing reference attributes from sources (specified in this parameter) won’t be deleted. You’ll need to delete relationships that are no longer needed. | Array of URIs for Sources |
referenceAttributeDirection | No | Specifies whether the reference attribute must appear in the entity when a relationship of type relationshipTypeURI is present. Possible values:
| Static String: "both", "parentToChild", or ""childToParent" |
immutable | No | Defines the Immutable Reference Attributes. This parameter overrides the immutableRefAttrsByDefault parameter from the tenant configuration for this particular attribute. | Boolean |
immutableForSources | No | Used to define an array of source systems (URIs and IDs) for which it isn’t possible to change the value of subattributes that come from the referenced entity. However, you can change the values from the relation. | Array of URIs for Sources (String) |
immutableExceptForSources | No | Defines a list of sources that will ignore the immutable parameter. As a result, attribute values that come from one of defined sources will anyway change the reference object. | Array of URIs for sources (String) |
{
"URI":"configuration/entityTypes/Individual/attributes/Address",
"Name":"Address",
"label":"Address",
"ID":"9",
"type":"Reference",
"referencedEntityTypeURI":"configuration/entityTypes/Location",
"relationshipTypeURI":"configuration/relationshipTypes/HasAddress",
"relationshipLabelPattern":"{configuration/relationshipTypes/HasAddress/attributes/AddressType}",
"doNotOverrideForSourceURIs" : [
"configuration/sources/DEA",
"configuration/sources/Veeva"
],
"referencedAttributeURIs":[
"configuration/relationshipTypes/HasAddress/attributes/AddressType",
"configuration/entityTypes/Location/attributes/City"
]
}
Attribute ordering and attribute survivorship
Attribute values ordering and attribute values survivorship are both complex sorting strategies, but have different usage and configuration. The survivorship results of both these strategies are transient and don’t interfere with each other. Attribute survivorship strategy results (OV values) are used by the UI to customize which attribute values to display. Attribute values order in output is determined by attribute ordering strategy.
Attribute ordering strategy is defined in the attribute configuration. All supported options are given in the table below.
Strategy Name | Description | Attribute Configuration Example |
---|---|---|
LUD |
Last Update Date strategy. The most recently updated attribute values have the highest sort priority. By default, all attribute values are ordered by this strategy, and the value with the maximum update date is first in the listing of ordered values. The maximum update date for the value is calculated as follows:
After the update is calculated, attribute values are sorted by such dates in descending order. |
|
FieldBased |
Only for complex attributes such as nested or reference. This type of ordering strategy defines that complex attribute values must be sorted in accordance with some attribute value inside this attribute. For example, for nested attribute Education, you can use ordering based on the YearOfGraduation value. Note: Optionally, you can define the order type property as "orderType" : "DESC" or "orderType": "ASC". This property applies ascending or descending order to attributes values sorting. By default, the ascending order is used.
|
|
Attribute Survivorship Rules are rules that drive the calculation of the operation values (OV) for an attribute among the values that have been contributed by various sources to the attribute. Attribute Ordering is a sorting strategy for an attribute and is used to visually sort multiple instances of a nested or reference attribute. For more information, see Attribute ordering strategy and Design survivorship rules.