Immutable Reference Attributes

Use reference attributes in a way when numerous entities make reference to the same in another entity by marking all sub-attributes of a reference attribute as immutable for some particular sources.

For cases where you want to use reference attributes in a way when numerous entities make reference to the same in another entity, it’s possible to run into the situation when the referenced entity is constantly updated because of small, for example, Suite 1 vs. Ste 1 vs #1 in some sub-attribute of Address attribute (referenced to a Location). These unnecessary updates may produce a large number of unnecessary events and impact the performance. Enabling Immutable Reference Attributes feature helps to avoid these negative effects and decreases the time taken for a data load because less number of messages are added to queues. For these instances, we provide the ability to mark all sub-attributes of a reference attribute as immutable for some particular source or all sources. For example, for an HCP with the reference attribute Address (referenced to a Location), the address is marked as immutable for some sources. Inside Address, there are some sub-attributes (such as AddressLine1, City, Zip and so on). These sub-attributes have values loaded from source systems that are listed as immutable. Therefore, if a request is sent to insert another value with an existing crosswalk, then the Reltio platform ignores this change and will not apply it to the object. In this case, there is no change on the Location object and as a result, messages are not sent about the HCPs that are related to it.

The following table lists properties that can allow you to customize the immutability of reference attributes:

Table 1. Properties
Property Type Default
immutable Boolean The value depends on the tenant level setting. The default value is false.
immutableForSources Array of URIs for sources (String) Empty array
immutableExceptForSources Array of URIs for sources (String) Empty array

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

Note: The default value of immutable property depends on the other property defined on tenant configuration level. If you want to make all reference attributes immutable for your tenant, contact Reltio Customer Support.
With “immutableForSources”, it is possible to define an array of source systems (URIs and IDs could be used) for which the sub-attributes become immutable. This can be done inside the business configuration as shown in this 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 defined for the HCP that it is not possible to change address attributes loaded from SOURCE_SYS_001 and SOURCE_SYS_002. For example, some HCPs make a reference to the same Location, and this Location has crosswalk X, which is from SOURCE_SYS_001. If a request is sent to add/modify any HCP with the same Location (having the same crosswalk), then this change is ignored, and the Location remains unchanged.

When this option is turned on, you can specify entity attributes for which you would like changes to be considered as immutable when uploading similar entities. For example, even if a Location object is marked as immutable, but changes must be applied, then you can send a request to directly modify the Location (although, not as part of an HCP).

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

Note: Reltio suggests using this feature if you use Location as a reference attribute (because of its nature). However, there can be some rare cases when this feature cannot be used. To understand the rare cases, requires investigation.

Example Scenarios

Updating an Existing Crosswalk

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

Step 1: Post some L3 with:

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

Step 2: Post HCP like:

[
  {
    "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 HCP like (new HCP, referencing Location with the same existing crosswalk but having another value for AddressLine1):

[
  {
    "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 in Step 3 is that a new HCP is created, and the existing Location is used because it will be merged on the fly by the crosswalk. However, the value of the AddressLine1 attribute is not changed because NPI is marked as immutable, and for Location there is a crosswalk of this type that already exists with the “locXwalk” value.

Updating the Existing Surrogate Crosswalk

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

Step 1: Post some L3 with:

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

Introduction of a surrogate crosswalk for the Location entity type:

"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 HCP like:

[
  {
    "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 HCP like (new HCP referencing Location with the same existing crosswalk but having another value for AddressLine1):

[
  {
    "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 in Step 3 is that a new HCP is created, and the existing Location is used because it will be merged on the fly by the crosswalk (as the sent Location will have the same crosswalk value as the existing Location). However, the value of the AddressLine2 attribute is not added because HMS is marked as immutable, and for Location there is a crosswalk of this type that already exists with the same value.