The Entity Type

Entities are the building blocks of the Commercial Graph.

Different types of entities are supported and can be configured or defined in the Business Model. Typical examples of entities are People, Organizations, Products, Locations, and so on. An entityType is a class of entity, whereas an entity is a specific instance of an entity type. Example: Individual is a Reltio Connected Cloud entity type, whereas Jim is an entity (or instance) of type Individual.

Some objects in the Reltio-controlled layers are abstract and cannot be materialized as an instance. For example, the Reltio Connected Cloud L1 layer defines the abstract Party entity type with a small collection of attributes in it. The L1 then goes on to define the Individual entity type and the Organization entity type, both of which inherit from Party, both of which are non-abstract and both of which add additional attributes specific to their type and business function. Continuing with the concept of inheritance, in the L2 Life Sciences container, the HCP entity is defined (to represent physicians) which inherits from the Individual type but also defines a small collection of attributes unique to the HCP concept. Thus we have the entity taxonomy Party/Individual/HCP and the resulting HCP entity type provides the developer and user with the aggregate attribution of Party, Individual and HCP.

Entities are typically linked together into what Reltio calls the Commercial Graph which can be arbitrarily large and complex. Entity-to-entity links are provided by the Relationship type, described in a later section. In a relationship type definition, one entity type must be defined as the Start Object entity type and one must be defined as the End Object entity type. This then gives the Relationship a concept of directionality. And when a relationship is posted the post must reference the uri of each entity while mentioning which entity is considered the start object for the relationship and which is considered the end object.

Configuring the Entity type object means configuring all of the concepts and properties the object can contain which drive the behavior of the entity. In the Entity type, the following concepts are available for configuration:

  • Attributes
  • Entity Roles
  • Match Rules

The Entity type is defined by the following metadata:

Property Required Description Type
URI Yes Path that is used to reach the entity type. Format: configuration/entityTypes/{EntityTypeName} Example: configuration/entityTypes/Individual String, URI
id Yes-for response JSON Internal, system-generated id. Used internally to get the difference between two versions of configurations when configuration is updated. String
label Yes Readable name of the entity type. Example: Individual String
description   Description for the entity type. String
extendsTypeURI   URI of entity type or a role that is extended by this entity type. Example: configuration/roles/Party String, URI
typeColor   Color that will be used to visualize this entity type. For example, in Graph View, it will be the color of a node. Example: #00FF00 String, hex color
typeIcon   Icon used in UI facets when representing the entity type. String, URL
typeGraphIcon   Icon used in UI graphs when representing the entity type. String, URL
typeImage   Default profile image. String, URL
dataLabelPattern   Pattern that is used to build entity object label. Can include static text as well as patterns-attributes in curly brackets. With square brackets you can define conditional label patterns: if an attribute used inside the brackets does not exist, then all content inside the brackets will be skipped.
Note: If dataLabelPattern is not specified, label is used. Example: {FirstName} {MiddleName} {LastName}[, {Credentials}]
String
secondaryLabelPattern   Pattern that is used to build entity object secondary label. Can include static text as well as patterns-attributes in curly brackets.
Note: You can use comma-separated string built from business card attributes. In this case use {businessCardAttributes} as a string value. Examples: {businessCardAttributes}
OR {Address}.
 
dataTooltipPattern   Pattern that is used to build the entity object's tooltip. Can include static text as well as patterns-attributes in curly brackets. Note: If dataTooltipPattern is not specified, label is used. Example: Tooltip: {configuration/entityTypes/Individual/attributes/FullName} String
entitySmartLogic   Identifies if entity type has smart logic. Possible values: Person, Organization, Location. String
entityTypeRoleURIs   Array of URIs for role that can be used in combination with this entity type. For example, an Individual entity object can be client, while Location object cannot be. Example: [ "configuration/roles/Client", "configuration/roles/Advisor"] Array of role URIs(Entity Roles)
attributes   Attributes that are defined as standard for this entity type. Attributes can be of Simple, Nested and Reference type. Please find more details in Attributes Configuration.
Note: Not every entity object will have all attributes defined in its entity type. Also, entity object can have some attributes that are not defined in configuration-custom attributes.
Example: { "URI":"configuration/entityTypes/Individual/attributes/FirstName", "name": "FirstName", "id":"4", "label":"First Name", "type":"String"}
JSON object of Attributes Configuration
defaultFacetedAttributes   Array of attributes that must be faceted for that entity.

Example:

"defaultFacetedAttributes": [ "configuration/entityTypes/Plan/attributes/Type", "configuration/entityTypes/Plan/attributes/PaymentType" ]
Array of attributes
businessCardAttributeURIs   Attributes that are returned as search result items and displayed in the Profile band (that is, the top item on profile screen with profile icon and label). There are three groups of attributes:
  • Label: Attributes from labelPattern
  • Secondary label: Attributes from secondaryLabelPattern
  • Business card attributes: Can be used in place of secondary labels.
The business card attributes is an array of URIs for attributes that must be used in a business card. They come in priorities order and order is preserved.
Example:
"businessCardAttributeURIs":[
    "configuration/entityTypes/Individual/attributes/FirstName",
    "configuration/entityTypes/Individual/attributes/Gender"
    ],
Array of attributes URIs(see details in Attributes Configuration)
imageAttributeURIs   Array of URIs for attributes that might contain entity object images. First array element will be considered as default "bucket" for profiles. Example: [ "configuration/entityTypes/Individual/attributes/ImageLinks"] Array of attributes URIs(see details in Attributes Configuration)
matchGroups   Array of match groups specification. For details see Match Rule Configuration - Step by Step. Array
cleanse   Allows to define a set of data cleanse rules based on the for an entity type by specifying:
  • Cleanse service
  • inputMapping: define which attributes must be cleansed provide attributes URI
  • outputMapping: Service output mappings - mapping of cleanse output to entity type attributes
JSONArray
dependentAttributes No Allows to define set of attributes that depend on an entity attribute value(s). Each JSON in the Array describes one attribute called control attribute. The control attribute URI must be specified by attributeUri parameter. All possible values of the control attribute and appropriate dependent attributes must be specified in values Array. Each JSON in the values Array may contain valuesList Array of strings (possible values of the control attribute) and list of dependent attribute URIs invisibleAttributes assigned to these values. If the valuesList is not specified, then this item belongs to undefined value of the control attribute. If the control attribute has a value which is not specified in the values Array, then dependent attributes from the default section are used. If the dependentAttributes section is configured for an Entity Type, then User will see attributes assigned to current values of control attributes or any other attributes that are not mentioned in the section. JSONArray
lifecycleActions No Life Cycle Actions that must be executed for this entity lifecycle hooks. Example: "lifecycleActions": { "beforeSave": [ "BeforeSaveAction" ] } JSON object (see details in Life Cycle Actions (LCA) Service API)
overrideIgnorePin No Determines if the "pin"/"ignore" flags must be overridden after updating attribute by the same value. By default, true. Example: "overrideIgnorePin": "false" Boolean
matchBeforeCreate No Enables/disables on-the-fly optimization to match entities before create. In case optimization is enabled and match was found by auto rule the new entity will be merged on-the-fly with existing one instead of created separately. By default, true. Example: "matchBeforeCreate": "false" Boolean
useOnlyOvValuesInReferencedEntities No

Use this option to determine if you must use non-OV values of all attributes of the current entity type when the entity is used as a reference attribute. The default value is false, and if specified, then the system works without changes. If you set the value to true, then the inside reference attributes which refer to this entity will use only OV values from the particular entity. In this case, if a non-OV value is changed, then it is changed only in the referenced entity; therefore, there is no need to send an event to all entities which have a relation with this one. There is no issue with searching by non-OV values because the reference attribute will not have it.

If you enable this option, then your system performs as if the option ignoreNonOVChangesWhenUpdateThroughReferencedEntity is enabled for this entity type. This means that you cannot specify useOnlyOvValuesInReferencedEntities as true and directly specify ignoreNonOVChangesWhenUpdateThroughReferencedEntity as false (only true or no value are permitted in this case).

Boolean
ignoreNonOVChangesWhenUpdateThroughReferencedEntity No

Use this option to determine if you must send an event indicating that the referenced entity was changed in the case when a non-OV value was updated on a current entity. The default value is false, and if specified, then the system works without changes. If you set the value to true for some entity type, then during the update of an entity of another type (which uses the first entity as a reference attribute) the system will not send events indicating that all entities with references to the first entity were changed. If you enable this option, and an OV value was changed, a message is sent, indicating that the related entity was changed. However, the message will not contain information about non-OV values. The message for the entity itself will contain all values (OV and non-OV).

If you change a Location, then ENTITY_CHANGED events for reference entities (for example, HCP/HCAs) will be sent only in the case of a change to an OV slice of the Location. This behavior is true in the case when the Location is updated as a reference attribute.

Note: If the Location is updated directly (that is, the body of a request contains the Location entity type as an object for update), then the system will work as it had previously, and all related entities are notified that the Location was changed.
Note: Reference attributes will be a part of an OV slice of Location + Attributes of relationship HAS_ADDRESS.
Boolean
skipValidationForAbstractType No Sometimes validation errors can occur for abstract entity types that are not part of the implementation. To exclude such entity types from being checked during validation, you can use this parameter. When this parameter is set to true for an entity type, the validation rules are not applied if the entity type is abstract. This parameter takes one of the following values:
  • from the highest level configuration if it is set there.
  • from the same entity type at the previous level if it's not set at the highest level.
If the current entity type is without this parameter but extends another entity type that has this parameter, the current entity type does not inherit from the parent entity type.

Example

skipValidationForAbstractType is taken from the same entity type from the lower level configuration.

In L2, the GPO entity type contains skipValidationForAbstractType and therefore, there are no validation errors at this level:
{
      "uri": "configuration/entityTypes/GPO",
      "label": "GPO",
      "abstract": true,
      "skipValidationForAbstractType": true,
      "dataTooltipPattern": "",
      "typeColor": "#AB8800",
      "typeIcon": "images/base_type/house.png",
      "typeImage": "images/defaultImage/no-loc.png",
      "typeGraphIcon": "images/graphIcon/location-icon.png",
      "extendsTypeURI": "configuration/entityTypes/Organization",
      "attributes": [...],
      "geoLocationAttributes": [...],
      "dataLabelPattern": "{Name}",
      "secondaryLabelPattern": "{businessCardAttributes}",
      "survivorshipGroups": [...],
      "imageAttributeURIs": [...],
      "analyticsAttributes": [...]
      }
In L3, the same GPO does not contain skipValidationForAbstractType:
{
      "uri": "configuration/entityTypes/GPO",
      "label": "GPO",
      "abstract": true,
      "dataTooltipPattern": "",
      "typeColor": "#AB8800",
      "typeIcon": "images/base_type/house.png",
      "typeImage": "images/defaultImage/no-loc.png",
      "typeGraphIcon": "images/graphIcon/location-icon.png",
      "extendsTypeURI": "configuration/entityTypes/Organization",
      "attributes": [...],
      "geoLocationAttributes": [...],
      "dataLabelPattern": "{Name}",
      "secondaryLabelPattern": "{businessCardAttributes}",
      "survivorshipGroups": [...],
      "imageAttributeURIs": [...],
      "analyticsAttributes": [...]
}
Result
{
            "uri": "configuration/entityTypes/GPO",
            "label": "GPO",
            "dataTooltipPattern": "",
            "typeColor": "#AB8800",
            "typeIcon": "images/base_type/house.png",
            "typeImage": "images/defaultImage/no-loc.png",
            "typeGraphIcon": "images/graphIcon/location-icon.png",
            "skipValidationForAbstractType": true,
            "extendsTypeURI": "configuration/entityTypes/Organization",
            "attributes": [...],
            "geoLocationAttributes": [...],
            "dataLabelPattern": "{Name}",
            "secondaryLabelPattern": "{businessCardAttributes}",
            "survivorshipGroups": [...],
            "imageAttributeURIs": [...],
            "analyticsAttributes": [...]
}

skipValidationForAbstractType cannot be inherited from the parent entity type

In L2, the GPO entity type contains skipValidationForAbstractType and therefore, there are no validation errors at this level:
{
      "uri": "configuration/entityTypes/GPO",
      "label": "GPO",
      "abstract": true,
      "skipValidationForAbstractType": true,
      "dataTooltipPattern": "",
      "typeColor": "#AB8800",
      "typeIcon": "images/base_type/house.png",
      "typeImage": "images/defaultImage/no-loc.png",
      "typeGraphIcon": "images/graphIcon/location-icon.png",
      "extendsTypeURI": "configuration/entityTypes/Organization",
      "attributes": [...],
      "geoLocationAttributes": [...],
      "dataLabelPattern": "{Name}",
      "secondaryLabelPattern": "{businessCardAttributes}",
      "survivorshipGroups": [...],
      "imageAttributeURIs": [...],
      "analyticsAttributes": [...]
}
In L3, the GPOExtended extends configuration/entityTypes/GPO and does not contain skipValidationForAbstractType:
entityTypes": [
    {
      "uri": "configuration/entityTypes/GPOExtended",
      "label": "GPOExtended",
      "dataTooltipPattern": "",
      "typeColor": "#AB8800",
      "typeIcon": "images/base_type/house.png",
      "typeImage": "images/defaultImage/no-loc.png",
      "typeGraphIcon": "images/graphIcon/location-icon.png",
      "extendsTypeURI": "configuration/entityTypes/GPO",
      "abstract": true,
      "survivorshipGroups": [
        {
          "uri": "configuration/entityTypes/GPOExtended/survivorshipGroups/default",
          "default": false,
          "roles": [
            "TEST_ROLE"
          ],
          "mapping": [
            {
              "attribute": "configuration/entityTypes/GPOExtended/attributes/Address",
              "survivorshipStrategy": "Aggregation"
            },
            {
              "attribute": "configuration/entityTypes/GPOExtended/attributes/Identifiers",
              "survivorshipStrategy": "Aggregation"
            },
            {
              "attribute": "configuration/entityTypes/GPOGPOExtended/attributes/Specialities",
              "survivorshipStrategy": "Aggregation"
            }
          ]
        }
      ]
    }  
]

Result of Applying L3

Error Message: Attribute with URI configuration/entityTypes/GPOExtended/attributes/Address mentioned in survivorship rules configuration is not found.
Boolean

Entity Type Example

Defining an entity type for Individual.

{  
   "URI":"configuration/entityTypes/Individual",
   "label":"Individual",
   "id":"3",
   "description":"Entity for representing a person",
   "typeColor":"#00FF00",
   "typeIcon":"entityType/Individual.png",
   "typeGraphIcon":"entityType/IndividualSmall.png",
   "typeImage":"defaultImage/no-photo.png",
   "dataLabelPattern":"{configuration/entityTypes/Individual/attributes/FirstName}",
   "entitySmartLogic":"Person",
   "entityTypeRoleURIs":[  
      "configuration/roles/Client",
      "configuration/roles/Advisor"
   ],
   "overrideIgnorePin":"false",
   "dependentAttributes":[  
      {  
         "attributeUri":"configuration/entityTypes/Party/attributes/Name",
         "default":[  
            "configuration/entityTypes/Party/attributes/DocumentLinks",
            "configuration/entityTypes/Individual/attributes/Prefix"
         ],
         "values":[  
            {  
               "valuesList":[  
                  "CCC",
                  "AAA"
               ],
               "visibleAttributes"               [  
                  "configuration/entityTypes/Party/attributes/ImageLinks",
                  "configuration/entityTypes/Party/attributes/DocumentLinks",
                  "configuration/entityTypes/Individual/attributes/Prefix"
               ]
            },
            {  
               "visibleAttributes":[  
                  "configuration/entityTypes/Individual/attributes/Prefix"
               ]
            }
         ]
      }
   ],
   "attributes":[  
      {  
         "URI":"configuration/entityTypes/Individual/attributes/FirstName",
         "name":"FirstName",
         "id":"4",
         "label":"First Name",
         "type":"String"
      },
      {  
         "URI":"configuration/entityTypes/Individual/attributes/Gender",
         "name":"Gender",
         "id":"5",
         "label":"Gender",
         "type":"String",
         "values":[  
            "Male",
            "Female",
            "Unknown"
         ]
      },
      {  
         ";URI":"configuration/entityTypes/Individual/attributes/ImageLinks",
         "name":"ImageLinks",
         "id":"5",
         "label":"Image Links",
         "type":"Image URL"
      },
      {  
         "URI":"configuration/entityTypes/Individual/attributes/Education",
         "name":"Education",
         "type":"Nested",
         "dataLabelPattern":"{configuration/entityTypes/Individual/attributes/Education/University} { 
                configuration / entityTypes / Individual / attributes / Education / Degree 
                }, 
                { 
                configuration / entityTypes / Individual / attributes / Education / YearOfGraduation 
                } 
                ",
         "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":"Float"
            }
         ]
      },
      {  
         "URI":"configuration/entityTypes/Individual/attributes/Address",
         "name":"Address",
         "label":"Address",
         "id":"9",
         "type":"Reference",
         "referencedEntityUR":"configuration/entityTypes/Location",
         "relationshipTypeURI":"configuration/relationshipTypes/HasAddress",
         "relationshipLabelPattern":"{configuration/relationshipTypes/HasAddress/attributes/AddressType",
         "referecedAttributeURIs":[  
            "configuration/relationshipTypes/HasAddress/attributes/AddressType",
            "configuration/entityTypes/Location/attributes/City"
         ]
      }
   ],
   "businessCardAttributeURIs":[  
      "configuration/entityTypes/Individual/attributes/FirstName",
      "configuration/entityTypes/Individual/attributes/Gender"
   ],
   "imageAttributeURIs":[  
      "configuration/entityTypes/Individual/attributes/ImageLinks"
   ],
   "matchGroups":[  
      {  
         "URI":"configuration/entityTypes/Individual/matchGroups/AutoMatch",
         "label":"Auto",
         "type":"automatic",
         "rule":{  
            "URI":"configuration/entityTypes/Individual/matchGroups/AutoMatch/matchRule",
            "or":{  
               "URI":"configuration/entityTypes/Individual/matchGroups/AutoMatch/matchRule/matchRule",
               "and":{  
                  "URI":"configuration/entityTypes/Individual/matchGroups/AutoMatch/matchRule/matchRule/matchRule",
                  "exact":[  
                     "configuration/entityTypes/Individual/attributes/FirstName",
                     "configuration/entityTypes/Individual/attributes/LastName",
                     "configuration/entityTypes/Individual/attributes/MiddleName"
                  ]
               },
               "exact":[  
                  "configuration/entityTypes/Individual/attributes/SSN"
               ]
            }
         }
      },
      {  
         "URI":"configuration/entityTypes/Individual/matchGroups/SuspectMatch",
         "label":"SuspectName",
         "type":"suspect",
         "rule":{  
            "URI":"configuration/entityTypes/Individual/matchGroups/SuspectMatch/matchRule",
            "exact":[  
               "configuration/entityTypes/Individual/attributes/FirstName"               ;,
               "configuration/entityTypes/Individual/attributes/LastName"
            ]
         }
      }
   ]
}
Note: Currently, "id" parameters are not supported by Configuration API.