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.

How source mappings affect lookup resolution

When multiple sources are defined for the same lookup value, lookup resolution follows the additional source mapping rules listed below.

• RDM uses the source that comes first in alphabetical order.
• If that source has a mapping, resolution succeeds.
• If that source has no mapping, resolution fails even if another source has a mapping.
• A mapping in another source does not change the result.
• Keep a mapping for the value in every source that can appear on the record.

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

The following example shows a complete transcoding request.

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

Response

The following example shows a successful response with the transcoded canonical value for the GENDER1 lookup type.

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

Hierarchy Transcode

Hierarchy Transcode resolves a parent lookup value and its dependent child lookup values in a single request. RDM resolves each child value within its parent-child hierarchy instead of resolving the child independently.

For example, in a Country and City hierarchy, the source lookup value PR resolves to Paris when the parent country is France and to Praia when the parent country is Cape Verde. Without the parent country, RDM cannot determine which canonical city value PR represents.

In a hierarchy transcode request, specify parent lookup values in values and their dependent child lookup values in dependentValues. For the request structure, response fields, and errors, see Transcode Hierarchical Lookups.

The transcodeHierarchyOnSource property determines how RDM validates child values against parent values from multiple sources. You can set this top-level property when creating an RDM tenant or update the configuration of an existing tenant. If the property is not set, RDM treats it as false.

When transcodeHierarchyOnSource is false or not set

RDM combines the canonical codes of all successfully resolved parent values of the same lookup type. It validates each child against this combined set, regardless of which source provided the parent or child value. A child resolves if it has a valid parent-child relationship with any parent code in the set.

For example, Source A provides France and Paris, while Source B provides Japan and Paris. RDM resolves France and Japan, then checks both city values against the combined set of countries. As Paris is a valid child of France, both city values resolve.

When transcodeHierarchyOnSource is true

RDM checks each child against parents resolved from the same source. In the example above, Paris from Source A resolves under France. Paris from Source B fails validation under Japan.

For example, if Source B provides Paris without requesting a country from Source B, RDM checks Paris against the successfully resolved countries, including France from Source A. If Source B requests a country but that request fails to resolve, Paris from Source B fails validation instead.

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.