Immutable Reference Attributes

Enable the immutability of reference attributes to avoid a change in the referenced entities and avoid generating multiple events because of non-significant differences in the source data.

The reference attribute of an entity (entity A) is a link to a part of the attributes of the referenced entity (entity B) and the relation that connects these entities. If the values of these linked attributes in the entity B or the relation changes, then the entity A with the reference attribute also changes. Often, several entities are linked with the same referenced entity via the referenced attribute.

For example, there is an entity of the type Individual with an Address reference attribute and with Location type for the referenced entity. It is possible for multiple Individual entities, such as A1, A2, A3, and A4, to have the same address. This means that their Address reference attribute points to the same Location entity. If the Location entity has changed, then all reference attributes of the entities A1, A2, A3, and A4 change as well and the Reltio Platform generates an ENTITY_CHANGED event for all these entities to propagate the changes to the Search system, History, and Matching system.

Assume that if the same address is used for four entities: A1, A2, A3, and A4, and these are defined in the source system with some non-significant differences as follows:

  • A1: New York, Main Avenue 123

  • A2: New York, Main Ave. 123

  • A3: New York, NY, Main Avenue, 123

  • A4 : New York, Main Avenue 123

Logically, since all the addresses are the same, they will match the same Location entity after cleansing and matching.
  1. Entity A1 is loaded into Reltio, the Location entity B is created with the address New York, Main Avenue 123, and an ENTITY_CREATED event is generated for entity A1 and entity B.
  2. Entity A2 is loaded into Reltio, and since the address is the same, the Location entity B is used as the referenced entity in the Address reference attribute, but the attributes of the Location entity will be changed to New York, Main Ave. 123. As a result, an ENTITY_CREATED event is generated for entity A2, and an ENTITY_CHANGED event is generated for entity A1 (because the reference attribute has changed) and for entity B.
  3. Entity A3 is loaded into Reltio, and since the address is the same, the Location entity B is used as the referenced entity in the Address reference attribute, but the attributes of the Location entity will be changed to New York, NY, Main Avenue, 123. As a result, an ENTITY_CREATED event is generated for entity A3, and an ENTITY_CHANGED event is generated for entities A1 and A2 (because the reference attribute has changed) and for entity B.
  4. Entity A4 is loaded into Reltio and Location entity B is used as the referenced entity in the Address reference attribute. The final attribute values of the Location entity depends on the order in which the entities are loaded. In this example, we have loaded entity A4 last, so the location is the same as for entity A1.
This example explains a situation where such non-significant differences in the source data may produce multiple unnecessary events, but the final results are displayed as if the Location entity were not changed at all. The immutable reference attributes feature enables us to ignore such differences and not generate unnecessary events, thus improving the performance and stability. If the feature is enabled, and we load the data as explained in the example, only one event, ENTITY_CREATED, is generated for each entity. The only difference in the result is that we will always have values for the Location entity which was loaded first, as opposed to values for the Location entity which was loaded last if the feature was not enabled. In both cases this will depend on the order of loading entities, which is random.
Note: Important points about immutable reference attributes:
  • Reltio recommends that you always enable the immutability of reference attributes if you use Location as the reference attribute.
  • The immutability of reference attributes only affects changes done through the reference attributes. If the referenced entity is updated directly, that is, not as a part of the reference attribute of another entity, then the changes will always be applied, and all events will be generated.
  • Changes are ignored only for attributes of the referenced entity, not for attributes of the relation. They are updated as expected.
  • If a new source data, that is, another crosswalk type or value, which does not exist in the referenced entity is loaded, then it is added and the referenced entity is updated as expected (with disabled immutable reference attributes).
  • If the entity with the reference attribute is updated, and the referenced entity in the new reference attribute does not match the current referenced entity, then two things can happen:
    • A new referenced entity is created.
    • The referenced attribute will point to the existing entity which matches the incoming data, that is, the reference attribute will be changed.

When you customize the immutability of the reference attributes, the reference attribute properties in the metadata configuration listed in Table 1: Properties are used.

Table 1. Properties
Property Type Description Default Value
immutable Boolean Defines the immutability of the reference attribute. The default value is set to true for all tenants created after 09/22/2021 and false for all other tenants.
Note: To change the default value for your tenant, contact Reltio Support Portal.
immutableForSources Array of URIs for sources (String) Defines the immutability of the selected sources. If the immutable property is set to false, then the immutableForSources property enables the immutability for the selected sources, so that changes are always ignored. The default value is an empty array.
immutableExceptForSources Array of URIs for sources (String) Defines the immutability of the selected sources. If the immutable property is set to true, then the immutableExceptForSources property disables the immutability for the selected sources, so that changes are always applied. The default value is an empty array.

The immutable property defines the immutability of the reference attributes. When this property is enabled, it is not possible to change the value of the sub-attributes that came from the referenced entity, although you still can change the values from the relation.

Using the immutableForSources property, it is possible to define an array of source systems (with URIs and IDs) for which the sub-attributes become immutable. This can be done inside the business configuration as shown in the example:
{
          "uri": "configuration/entityTypes/HCP/attributes/Address",
          "relationshipLabelPattern": "rank - {AddressRank}",
          "referencedAttributeURIs": [
            "configuration/relationTypes/HasAddress/attributes/AddressType",
	    ...
            "configuration/entityTypes/Location/attributes/AddressLine1",
            "configuration/entityTypes/Location/attributes/AddressLine2",
            "configuration/entityTypes/Location/attributes/City",
            "configuration/entityTypes/Location/attributes/Zip",
	    ...
          ],
          "immutableForSources": [
            "SOURCE_SYS_001", "SOURCE_SYS_002"
          ]
        }

In this example, it is not possible for the HCP to change the address attributes loaded from the SOURCE_SYS_001 and SOURCE_SYS_002 source systems. For example, some HCPs may reference the same Location entity, and the Location entity has a crosswalk X, which is from the SOURCE_SYS_001source. Now, if a request is sent to add or modify any HCP with the same Location entity, that is, with the same crosswalk, then this change is ignored and the Location entity remains unchanged.

When you set the immutable property to true, you can specify which entity attributes to consider as immutable when uploading similar entities. For example, even if a Location entity is marked as immutable but changes are made, then you must send a request to modify the Location entity.

The immutableExceptForSources property is the opposite of the immutableForSources property. You can use it with the immutable property when you must have a white list of sources. The attribute values that come from provided sources will change the address attributes.

Example 1: Updating an Existing Crosswalk

In this scenario, the sub-attributes of the HCP are not changed.

Step 1: Post an L3.

"immutableForSources":[
            "HMS", "configuration/sources/NPI"
          ]

Step 2: Post the HCP code.

[
  {
    "type": "configuration/entityTypes/HCP",
    "attributes": {
      "FirstName": [{"value": "FirstName01"}],
      "LastName": [{"value": "LastName01"}],
      "Address": [
        {
          "value": {
            "AddressLine1": [{"value": "AddressLine 1"}],
            "Country": [{"value": "Country 1"}],
            "City": [{"value": "City 1"}],
            "StateProvince": [{"value": "State 1"}]
          },
          "refEntity": {
            "crosswalks": [
              {
                "type": "configuration/sources/NPI",
                "value": "locXwalk"
              }
            ]
          }
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/NPI",
        "value": "hcpXwalk01"
      }
    ]
  }
]

Step 3: Post the HCP attributes such as a new HCP name, reference attributes with the Location entity and with the same existing crosswalk, but with another value for the AddressLine1 attribute.

[
  {
    "type": "configuration/entityTypes/HCP",
    "attributes": {
      "FirstName": [{"value": "FirstName02"}],
      "LastName": [{"value": "LastName02"}],
      "Address": [
        {
          "value": {
            "AddressLine1": [{"value": "AddressLine 2"}],
            "Country": [{"value": "Country 1"}],
            "City": [{"value": "City 1"}],
            "StateProvince": [{"value": "State 1"}]
          },
          "refEntity": {
            "crosswalks": [
              {
                "type": "configuration/sources/NPI",
                "value": "locXwalk"
              }
            ]
          }
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/NPI",

        "value": "hcpXwalk02"
      }
    ]
  }
]

The result is that a new HCP is created and the existing Location entity is used, because it will be merged with the crosswalk. However, the value of the AddressLine1 attribute is not changed because NPI is marked as immutable. Also, a crosswalk of this type that already exists with the locXwalk value for the Location entity.

Example 2: Updating the Existing Surrogate Crosswalk

In this scenario, the sub-attributes of the HCP are changed.

Step 1: Post an L3.

"immutableForSources":[
            "HMS", "configuration/sources/NPI"
          ]

Introduce a surrogate crosswalk for the Location entity:

"surrogateCrosswalks":[
   {
      "source":"configuration/sources/HMS",
      "enforce":true,
      "attributes":[
         "configuration/entityTypes/Location/attributes/AddressLine1",
         "configuration/entityTypes/Location/attributes/City",
         "configuration/entityTypes/Location/attributes/StateProvince",
         "configuration/entityTypes/Location/attributes/Zip/attributes/Zip5",
         "configuration/entityTypes/Location/attributes/Country"
      ]
   }
]

Step 2: Post the HCP attributes.

[
  {
    "type": "configuration/entityTypes/HCP",
    "attributes": {
      "FirstName": [{"value": "FirstName01"}],
      "LastName": [{"value": "LastName01"}],
      "Address": [
        {
          "value": {
            "AddressLine1": [{"value": "AddressLine 1"}],
            "Country": [{"value": "Country 1"}],
            "City": [{"value": "City 1"}],
            "StateProvince": [{"value": "State 1"}]
          },
          "refEntity": {
            "crosswalks": [
              {
                "type": "configuration/sources/HMS",
                "value": "Surrogate"
              }
            ]
          }
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/HMS",
        "value": "hcpXwalk01"
      }
    ]
  }
]

Step 3: Post the HCP attributes such as a new HCP name, reference attributes with the Location entity and with the same existing crosswalk, but with another value for the AddressLine1 attribute.

[
  {
    "type": "configuration/entityTypes/HCP",
    "attributes": {
      "FirstName": [{"value": "FirstName02"}],
      "LastName": [{"value": "LastName02"}],
      "Address": [
        {
          "value": {
            "AddressLine1": [{"value": "AddressLine 1"}],
            "AddressLine2": [{"value": "AddressLine 2"}],
            "Country": [{"value": "Country 1"}],
            "City": [{"value": "City 1"}],
            "StateProvince": [{"value": "State 1"}]
          },
          "refEntity": {
            "crosswalks": [
              {
                "type": "configuration/sources/HMS",
                "value": "Surrogate"
              }
            ]
          }
        }
      ]
    },
    "crosswalks": [
      {
        "type": "configuration/sources/HMS",

        "value": "hcpXwalk02"
      }
    ]
  }
]

The result is that a new HCP is created and the existing Location entity is used, because it will be merged with the crosswalk as the posted Location entity will have the same crosswalk value as the existing Location entity. However, the value of the AddressLine2 attribute is not added because HMS is marked as immutable. Also, there is a crosswalk of this type that already exists with the same value for the Location entity .