How to use Lookup Types and Canonical Values

In a typical application landscape, various systems will each have their own set of values they use for common semantic ideas. For example, Gender is a common attribute across many systems, but the value representing females in system A might be 01; in system B it can be F, and in system C, it can be CD_Female. If your MDM tenant receives data from these three systems, without the aid of RDM, three different values might accumulate within the gender attribute of a merged record. Of these three values, any one of them may appear for the Gender field in Hub. And in this unconformed state, queries become challenging because all three values must be queried to find records representing females. Also, a search facet based on Gender will display all three values, which again is challenging and undesirable.

Instead, RDM allows you to define a Lookup Type called Gender that can be used to transcode the source values into a single Canonical value. Once you create a Lookup Type, within it, you then define Canonical Rows, each one specifying a Canonical value you wish to standardize. This value is then associated with each of the values from various source systems. In this example, you might create a Canonical Row that represents the female Gender and has a canonical value of Female. You can then and associate this value with the values of 01, F and CD_Female being provided by the three source systems A, B, and C respectively. The following image explains the usage of lookup types and canonical values.

The value you see versus the value that is stored

It is important to note that transcoding occurs on-the-fly. When the value of 01 is posted to the gender attribute of an MDM tenant record from a source system, it is the raw value 01 that is stored in the record. If you have set up a canonical row in RDM for Gender and set the canonical value to Female, then in every screen of the Hub and in every return of an API call for the record, 01 will never appear. The value will always be transcoded on-the-fly to the canonical code of Female. This is also applicable for indexing. Therefore, a search facet based on Gender will display the value of female. If the gender attribute in the MDM configuration is linked to the Gender Lookup Type, then the canonical values appear as part of a drop-down list for the attribute in Hub.

Creating New Lookups and Canonical Rows

You can create new Lookups and Canonical rows via the RDM UI or via the RDM API.

The following video explains the relationship between an RDM Lookup Type and a drop-down list for an attribute in the MDM UI, and how the items in the list are influenced by the value and code of the Lookup items:

Video - Explaining the Parenthetical Display

Using the RDM API to Request Transcoding

Each time an MDM tenant needs to display for example a specific Gender on the screen or provide it within the return of a record, it will make a transcoding request to RDM. You can do the same using a REST client such as Postman. Here is a sample request and response.

Transcoding Request

POST: {{rdmURL}}/transcode/{{rdmTenant}}

[
 {
   "values": {
     "rdm/lookupTypes/GENDER1": [
       {
         "value": "female",
         "source": "AMS"
       }
     ]
   }
 }
]

Reponse

[
   {
       "values": {
           "rdm/lookupTypes/GENDER1": [
               {
                   "type": "rdm/lookupTypes/GENDER1",
                   "code": "FEMALE",
                   "value": "F",
                   "source": "rdm/sources/AMS",
                   "attributes": [],
                   "success": true
               }
           ]
       }
   }
]

Hierarchy Transcode

See the following example of Hierarchy Transcode:

POST: {{rdmURL}}/transcode/{{rdmTenant}}

[
  {
    "values": {
      "rdm/lookupTypes/COUNTRY_TYPE": [
        {
          "value": "FR",
          "source": "AMS"
        }        
      ]
    },
    "dependentValues": [
      {
        "values": {
          "rdm/lookupTypes/CITY_TYPE": [
            {
              "value": "PR",
              "source": "AMS"
            }
          ]
        }
      }
    ]
  }
]

[
    {
        "values": {
            "rdm/lookupTypes/COUNTRY_TYPE": [
                {
                    "type": "rdm/lookupTypes/COUNTRY_TYPE",
                    "code": "FRA",
                    "value": "France",
                    "source": "rdm/sources/AMS",
                    "attributes": [],
                    "success": true
                }
            ]
        },
        "dependentValues": [
            {
                "values": {
                    "rdm/lookupTypes/CITY_TYPE": [
                        {
                            "type": "rdm/lookupTypes/CITY_TYPE",
                            "code": "PARIS",
                            "value": "Paris",
                            "source": "rdm/sources/AMS",
                            "attributes": [],
                            "success": true
                        }
                    ]
                }
            }
        ]
    }
]

The MDM Cache

When an MDM tenant makes transcoding requests to RDM, they are made against a low-latency, high throughput cache and not against the RDM tenant itself. The cache is updated every 10 minutes automatically from the RDM tenant. Therefore, when you make changes in RDM and save your work, it may take up to 10 minutes to see the results of those changes in the Hub. However, API calls made to the RDM API Endpoint fetch data directly from the RDM tenant and do not involve the cache.

New Roles and Permissions

The following roles and permissions are visible in the User Management application:

Roles

• ROLE_RDM Access permissions
• ROLE_RDM_EDIT Access permissions
• ROLE_RDM_REVIEW Access permissions
• ROLE_RDM_SUGGEST Access permissions
• ROLE_ADMIN_TENANT Access permissions - Assign this role to give a user permissions to create or add a new lookup type.

Permissions

• rdm:data.changerequests.personal
• rdm:data.changerequests

For more information on roles and access permissions, see topic System roles.