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.

• The platform evaluates multiple sources in alphabetical order.
• A valid mapping in one source does not guarantee successful resolution.
• Resolution can fail if another source in the evaluated list is not mapped for that value.
• Maintain mappings for all applicable values across all configured sources to ensure consistent lookup resolution.

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

Response

[
   {
       "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 together with its dependent child lookup values in a single request, so that child values are resolved as part of the parent-child hierarchy rather than on their own.

A child value in a lookup hierarchy is meaningful only under its parent and cannot be resolved on its own. In a Country and City hierarchy, for example, the city value PR maps to Paris under the country France, but to Praia under the country Cape Verde. A request that includes the city value PR without a parent country is therefore ambiguous, because RDM has no way to choose between Paris and Praia. Hierarchy Transcode resolves the parent value and the child value together and preserves the parent-child relationship in the response.

A hierarchy transcode request places the parent lookup value in the values map and nests each dependent child lookup value inside a dependentValues array. RDM resolves the child values as part of the hierarchy and returns canonical values that reflect the parent-child relationship. To learn how to structure the request and read the response, including field descriptions and error handling, see Transcode Hierarchical Lookups.

Parent-child validation across multiple sources

Parent-child validation is specific to hierarchical lookups and differs from the per-source resolution described in How source mappings affect lookup resolution. The same entity can receive a parent value from more than one source system, and those sources do not always supply the same value. For parent-child validation, RDM validates a child value against all of the resolved parent values together, rather than against the parent value from the child's own source. The following rules describe how RDM applies this logic:

• The source system does not affect validation. RDM validates a child value against the canonical codes of the resolved parent values, regardless of which source provided each value. A child value from one source can resolve against a parent value from a different source.
• Parent and child values are validated as a combined set, not as matched pairs. RDM gathers the canonical codes of all resolved parent values of the same lookup type into one set, then checks whether the child value is a valid child of any code in that set.
• A child value resolves whenever any one parent is valid for it. As long as at least one resolved parent value is a valid parent for the child value, RDM resolves the child value and returns no error.

The following example shows how the combined-set behavior works. Suppose the same entity receives country and city values from two sources:

• Source A provides the country France and the city Paris.
• Source B provides the country Japan and the city Paris.

When RDM resolves this request, it places both resolved countries, France and Japan, into one set and checks the city Paris against that set as a whole. Paris is a valid city under France, so it resolves successfully. RDM does not check each source on its own, so it does not detect that Source B paired Paris with Japan, which is not a valid combination. Because at least one valid parent exists in the set, RDM resolves the city value and returns no lookup error. As a result, the invalid Japan and Paris pairing is treated as resolved, and the response gives no indication that one source supplied an invalid combination.

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.