Accelerate the Value of Data

Add an Entity type

Learn more about the available entity types and how the metadata for an entity type defines that entity.

Entity type metadata

This table lists the metadata properties you can configure using the Add an Entity type API.

PropertyRequiredDescriptionType
URIYesPath that the software uses to reach the entity type. Format: configuration/entityTypes/{EntityTypeName} Example: configuration/entityTypes/IndividualString, URI
idYes-for response JSONInternal, system-generated ID. Used internally to get the difference between two versions of configurations when configuration is updated.String
labelYesReadable name of the entity type. Example: IndividualString
descriptionNoDescription for the entity type.String
extendsTypeURINoURI of an entity type that is extended by this entity type. Example: configuration/roles/PartyString, URI
typeColorNoColor that the software useswill be used to visualize this entity type. For example, in Graph View, it’s the color of a node. Example: #00FF00String, hex color
typeIconNoIcon used in UI facets when representing the entity type.String, URL
typeGraphIconNoIcon used in UI graphs when representing the entity type.String, URL
typeImageNoDefault profile image.String, URL
dataLabelPatternNo Pattern that the software uses to build an entity object label. Can include static text, as well as patterns-attributes in curly brackets. You can use square brackets to define conditional label patterns. If an attribute used inside the set of brackets doesn’t exist, then all content inside the brackets are skipped.
Note: If dataLabelPattern is not specified, label is used. Example: {FirstName} {MiddleName} {LastName}[, {Credentials}]
]
String
secondaryLabelPatternNoPattern that the software uses to build an 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}.
dataTooltipPatternNoPattern that the software uses to build the tooltip for an entity object. Can include static text, as well as patterns-attributes in curly brackets.
Note: If dataTooltipPattern is not specified, a label is used.

Example: Tooltip: {configuration/entityTypes/Individual/attributes/FullName}

String
entitySmartLogicNoIdentifies when the entity type has smart logic. Possible values: Person, Organization, Location.String
entityTypeRoleURIsNo

Array of URIs for a role that can be used in combination with this entity type. For example, an Individual entity object can be a client, while a Location object cannot be. For more details, see Entity Roles.

Example: ["configuration/roles/Client", "configuration/roles/Advisor"]
Array of role URIs
attributesNoAttributes that are defined as standard for this entity type. Attributes can be of Simple, Nested and Reference type. For more details, see Attributes Configuration.

Example: { "URI":"configuration/entityTypes/Individual/attributes/FirstName", "name": "FirstName", "id":"4", "label":"First Name", "type":"String"}

JSON object of Attributes Configuration
defaultFacetedAttributesNoArray of attributes that must be faceted for that entity.

Example:

"defaultFacetedAttributes": [ "configuration/entityTypes/Plan/attributes/Type", "configuration/entityTypes/Plan/attributes/PaymentType" ]

Array of attributes
businessCardAttributeURIsNoAttributes that are returned as search result items and displayed in the Profile band; that is, the top item on the Profile page with profile icon and label. There are three groups of attributes:
  • Label: Attributes from labelPattern.
  • Secondary label: Attributes from secondaryLabelPattern.
  • Business card: Attribute from businessCardAttiributeURIs. Can be used in place of secondary labels.

The business card attributes are an array of URIs for attributes that must be used in a business card. These attributes follow in the order of priority and the order is preserved.

Example:

"businessCardAttributeURIs":[
 "configuration/entityTypes/Individual/attributes/FirstName",
 "configuration/entityTypes/Individual/attributes/Gender"
 ],

For details, see Attributes Configuration

Array of attributes URIs)
imageAttributeURIsNoArray of URIs for attributes that might contain entity object images. The system considers the first array element as the default bucket for profiles.

Example: [ "configuration/entityTypes/Individual/attributes/ImageLinks"]

For details, see Attributes Configuration.

Array of attributes URIs
matchGroupsNoArray of match groups specification. For details, see Match Rule Configuration - Step by Step.Array
cleanseNoEnables you to define a set of data cleanse rules based on an entity type by specifying:
  • Cleanse service
  • inputMapping: Defines which attributes must be cleansed to provide attributes URI
  • outputMapping: Service output mappings - mapping of cleanse output to entity type attributes
JSONArray
cleanseInputObjectBeforeOverwriteNo Enables (value is set to true) or disables (value is set to false) the cleanse function for a specific entity before the overwrite process. By default, the property is set to true and cleanse is performed. If the property is set to false, cleanse is skipped.
Sample entity request
[
        ...
    {
    "type": "configuration/entityTypes/Location",
    "tags": [
      "sport",
      "movies"
    ],
    "attributes": {
      "AddressLine1": [
        {
          "value": "00836 W Wewlington Ave F1 5"
        }
      ],
      "AddressLine2": [
        {
          "value": "Chicago EYE"
        }
      ],
      "StateProvince": [
        {
          "value": "IL"
        }
      ],
      "City": [
        {
          "value": "Chicago"
        }
      ],
      "Country": [
        {
          "value": "USA"
        }
      ],
      "Zip": [
        {
          "value": {
            "Zip5": {
              "value": "60657"
            }
          }
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/FB",
        "value": "e1"
      }
    ]
  }
]
Entity after it is updated
[
    ...
  {
    "type": "configuration/entityTypes/Location",
    "tags": [
      "sport",
      "movies"
    ],
    "attributes": {
      "AddressLine1": [
        {
          "value": "00836 W Wewlington Ave F1 5 NEW"
        }
      ],
      "AddressLine2": [
        {
          "value": "Chicago EYE NEW"
        }
      ],
      "StateProvince": [
        {
          "value": "IL NEW"
        }
      ],
      "City": [
        {
          "value": "Chicago NEW"
        }
      ],
      "Country": [
        {
          "value": "USA NEW"
        }
      ],
      "Zip": [
        {
          "value": {
            "Zip5": {
              "value": "60657"
            }
          }
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/FB",
        "value": "e2"
      },
      {
        "type": "configuration/sources/FB",
        "value": "e1",
        "dataProvider": false
      }
    ]
  }
]
Boolean
dependentAttributesNoEnables you to define set of attributes that depend on an entity attribute value(s).
  • Each JSON in the Array describes a single attribute called a 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 the values Array.
  • Each JSON in the values Array may contain valuesList Array of strings (possible values of the control attribute) and a list of dependent attribute URIs invisibleAttributes assigned to these values. If the valuesList is not specified, then this item belongs to the undefined value of the control attribute.
  • If the control attribute has a value that is not specified in the values Array, then the software uses dependent attributes from the default section are used.
  • If the dependentAttributes section is configured for an Entity Type, then you, as a user, see the attributes assigned to current values of control attributes or any other attributes that are not mentioned in the section.
JSONArray
lifecycleActionsNoLife Cycle Actions that must be executed for the lifecycle hooks for this entity lifecycle hooks.

Example: "lifecycleActions": { "beforeSave": [ "BeforeSaveAction" ] }

For details, see Life Cycle Actions (LCA) Service API

JSON object
overrideIgnorePinNoDetermines if the "pin"/"ignore" flags must be overridden after updating an attribute by the same value. By default, true.

Example: "overrideIgnorePin": "false"

Boolean
matchBeforeCreateNoEnables/disables on-the-fly optimization to match entities before the create operation. If optimization is enabled and a match was found by auto rule, the software merges the new entity on-the-fly with the existing one, instead of being created separately. By default, true.

Example: "matchBeforeCreate": "false"

Boolean
useOnlyOvValuesInReferencedEntitiesNo
Use this option to determine whether 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; however:
  • If you set the value to true, then the inside reference attributes that refer to this entity use only OV values from the particular entity. In this case, if a non-OV value changes, then it is changed only in the referenced entity. So there is no need to send an event to all entities that have a relation with this one. If you search by non-OV values, it won't be found because the reference attribute won’t 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. The system permits only true or no value in this case.
Boolean
ignoreNonOVChangesWhenUpdateThroughReferencedEntityNoUse this option to determine whether 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; however:
  • 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 wheren 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 works as it had previously, and all related entities are notified that the Location was changed.
  • Reference attributes are a part of an OV slice of Location + Attributes of relationship HAS_ADDRESS.
Boolean
skipValidationForAbstractTypeNoSpecifies when to exclude entity types from a validation. 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 doesn’t have this parameter but extends another entity type that has this parameter, the current entity type does not inherit from the parent entity type.

Example: The software takes skipValidationForAbstractType from the same entity type from the lower-level configuration.

In L2, the GPO entity type contains skipValidationForAbstractType, so 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 extendsconfiguration/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