Using a Custom Name Dictionary

You can create a Custom Name Dictionary Cleanser and use it during matching instead of the Reltio provided name cleanser.

If you have developed your own list of base names and their synonyms, and wish the match engine to leverage your list instead of the in-built dictionary, there are three key steps to perform, summarized here and detailed afterward.

Note: Using a custom Name Dictionary is not supported at this time in the Rule Builder within the console.
  1. Add two sources and a lookup type to your RDM tenant.
  2. Load base and synonym values to the new lookup type.
  3. Add a cleanse adapter to your match rule that redirects the match engine to your custom dictionary.

Detailed steps for using a custom name dicstionary

Let’s assume the following example values which makes the steps and code snippets easy to follow. Let’s say you work for the Acme Corp, and you have the following pieces of information:

  • MDM Tenant ID where match is being configured - mdm1234567890 (example)
  • RDM tenant ID that your your MDM tenant subscribes to - rdm1234567890 (example)
  • New Lookup Type code for your name dictionary - ACME_NAME_DICTIONARY (your choice)
  • New source for base names you will add - DICT_BASE_NAME (required name)
  • New source for synonyms you will add - DICT_SYNONYM (required name)

Add two sources and a lookup type to your RDM Tenant

Using the RDM UI, add two new sources to your RDM tenant. The two source names must be:

  • DICT_BASE_NAME
  • DICT_SYNONYM

Add a Lookup Type with name of your choice, for example, Acme Name Dictionary, to your RDM tenant. Once entered, notice the format of the actual Lookup Type code that is generated with underscores: ACME_NAME_DICTIONARY. This is the code you will need to specify in your L3 configuration.

Click into the new Lookup Type you added and add the two sources (DICT_BASE_NAME and DICT_SYNONYM) as source columns, as shown below (order does not matter).

Load Base and Synonym Values to the Lookup Type

POST values into your new lookup type using the following example JSON that establishes the synonyms of bennie, ben, and benji for the base name of benjamin. Note, we recommend you use the python program Synonym Loader that you can download from the Reltio ROCS Page.

[
  {
    "tenantId": "RBcvGv0Dcmcjhgy",
    "type": "ACME_NAME_DICTIONARY",
    "enabled": true,
    "code": "bennie",
    "sourceMappings": [
      {
        "source": "DICT_BASE_NAME",
        "values": [
          {
            "code": "benjamin",
            "value": "benjamin",
            "description": "Predefined Name Dictionary value",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      },
      {
        "source": "DICT_SYNONYM",
        "values": [
          {
            "code": "bennie",
            "value": "bennie",
            "description": "Predefined Name Dictionary value",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      }
    ]
  },
  {
    "tenantId": "RBcvGv0Dcmcjhgy",
    "type": "ACME_NAME_DICTIONARY",
    "enabled": true,
    "code": "ben",
    "sourceMappings": [
      {
        "source": "DICT_BASE_NAME",
        "values": [
          {
            "code": "benjamin",
            "value": "benjamin",
            "description": "Predefined Name Dictionary value",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      },
      {
        "source": "DICT_SYNONYM",
        "values": [
          {
            "code": "ben",
            "value": "ben",
            "description": "Predefined Name Dictionary value",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      }
    ]
  },
{
    "tenantId": "RBcvGv0Dcmcjhgy",
    "type": "ACME_NAME_DICTIONARY",
    "enabled": true,
    "code": "benji",
    "sourceMappings": [
      {
        "source": "DICT_BASE_NAME",
        "values": [
          {
            "code": "benjamin",
            "value": "benjamin",
            "description": "Predefined Name Dictionary value",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      },
      {
        "source": "DICT_SYNONYM",
        "values": [
          {
            "code": "benji",
            "value": "benji",
            "description": "Predefined Name Dictionary value",
            "enabled": true,
            "canonicalValue": false,
            "downStreamDefaultValue": false
          }
        ]
      }
    ]
  }
]

Once loaded, you can view the entries in your RDM UI.

Notes on the above: The python program assumes you have used the two sources mentioned, DICT_BASE_NAME, DICT_SYNONYM All name strings must be loaded in lower-case. Notice in the above that every instance of benjamin, bennie, ben, and benji are in lowercase. We strongly suggest you maintain lowercase in your Excel and in-turn, your CSV file.

Add a cleanseAdapter to your match rule that redirects to your custom dictionary in RDM

Include the following cleanse adapter JSON within the cleanse element of your match rule configuration.

{
  "cleanse": [
    {
      "cleanseAdapter": "com.reltio.cleanse.impl.NameDictionaryCleanser",
      "cleanseAdapterParams": {
        "rdmServiceUri": "https://rdm.reltio.com",
        "oauthInstance": "https://auth.reltio.com/oauth/token",
        "rdmTenantId": "rdm1234567890",
        "dictionary": "rdm/lookupTypes/ACME_NAME_DICTIONARY"
      },
      "mappings": [
        {
          "attribute": "configuration/entityTypes/Individual/attributes/FirstName",
          "cleanseAttribute": "configuration/entityTypes/Individual/attributes/FirstName"
        }
      ]
    }
  ]
}

Notes on code sample above

  1. The example assumes use of the First Name attribute within the Individual entity type. Adjust accordingly to suit your use case.
  2. For the parameter rdmTenantID, provide the actual RDM tenant ID you wish to use, from the RDM tenants provisioned for you; The RDM tenant you choose should be configured with your new lookup type that contains the two required sources, DICT_BASE_NAME, and DICT_SYNONYM. In the example above, the lookup type was named, AcmeDictionaryLookup but you should choose a dictionary name of your liking.