Metadata reference attribute properties

Learn about the reference attribute properties available for your use.

Metadata reference attribute properties

When you customize the immutability of the reference attributes, you can use the reference attribute properties in the metadata configuration. Check out the following table:

Table 1. Available refrence attribute 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.

Examples of immutable reference use

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"
      }
    ]
  }
]

Result: The system creates a new HCP and uses the existing Location entity, because it will be merged with the crosswalk. However, the system doesn't change the value of the AddressLine1 attribute because NPI is marked as immutable. Also, a crosswalk of this type 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"
      }
    ]
  }
]

Result: The system creates a new HCP and uses the existing Location entity, 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 system doesn't add the value of the AddressLine2 attribute because HMS is marked as immutable. Also, a crosswalk of this type already exists with the same value for the Location entity.