Resolve attribute or tenant lookups

Learn more about the attribute level property resolveLookupCode.

Set lookup values at the tenant or attribute level

You can resolve lookup codes at the attribute or tenant level using the resolveLookupCode parameter. When set to true, the system resolves the code to the canonical lookup value. When set to false, the system uses the raw input value.

At the attribute level, you can apply resolveLookupCode to attributes linked to Reference Data Management (RDM) lookups. The attribute-level setting takes precedence whenever it is explicitly defined, including when the attribute is set to false while the tenant-level value is true. The tenant-level value applies only as the default for attributes that don't declare their own resolveLookupCode setting.

If resolveLookupCode is set to false, the system uses lookupRawValue by default.

Update configured lookup values

Lookup data is stored in the tenant primary database, and these values don't automatically update. After you change a configured lookup value using resolveLookupCode, run the Reload Lookup Data Task to update existing records with the new lookup resolution. Alternatively, update individual entities directly. For more information, see Load entities into a tenant.

Survivorship and lookup filtering

Survivorship rules that filter on lookup attributes compare against the stored attribute value. When resolveLookupCode is true, the filter uses the lookup code. When it is false, the filter must match the stored value exactly.

If a survivorship rule filters by a specific value (for example,"equals": [{"value": "PHN"}]), the attribute's value becomes the operational value only when the compared field matches. With resolveLookupCode set to false, the stored raw value must match the filter exactly. A raw value of TEL.1 does not match a filter for PHN, even if both resolve to the same lookup entry. Reindexing does not resolve the mismatch. To resolve it, run the Reload Lookup Data Task, or update the filter literals in the survivorship rule.

Address re-cleansing after enablement

Enabling resolveLookupCode after an address attribute was already loaded using a lookup value causes the platform to re-cleanse each affected entity one time. This happens because the cleanse function must switch its input from lookupRawValue to lookupCode. The one-time re-cleanse can be triggered by any subsequent attribute update on the entity, including updates to attributes that are not address-related. The platform evaluates cleanse-input staleness for the entity as a whole rather than per attribute. After this one-time re-cleanse completes for an entity, further updates to non-address attributes do not trigger additional cleansing.

To avoid the resulting re-cleanse volume, proactively re-cleanse the tenant once immediately after enabling resolveLookupCode, instead of letting re-cleansing occur organically as entities are updated. Run the Re-cleanse Data Task on the tenant to complete this in a single pass.

Enable the resolveLookupCode parameter

To enable resolveLookupCode, set it to true. The following is an example for configuring the resolveLookupCode parameter.

{
    "uri": "configuration/entityTypes/HCO/attributes/Country",
    "name": "Country",
    "label": "Country",
    "description": "Country",
    "type": "String",
    "hidden": false,
    "important": false,
    "system": false,
    "searchable": true,
    "skipInDataAccess": false,
    "lookupCode": "rdm/lookupTypes/Country",
    "dependentLookupAttributes":
    [
        "configuration/entityTypes/HCO/attributes/State"
    ],
    "resolveLookupCode": true
}

Important: After enabling resolveLookupCode, run a lookup reload task to apply the change. Otherwise, values used in match rules (such as MatchFieldURI) may not resolve correctly.

resolveLookupCode example

If resolveLookupCode property is enabled (true), then API responses won't include lookupRawValue for attribute values.

Note:

Lookup data is stored in the tenant primary database and these values will not automatically update. You must reload the data or update the entity to get the updated values.

"Country":
[
    {
        "type": "configuration/entityTypes/HCO/attributes/Country",
        "ov": true,
        "value": "United Kingdom",
        "lookupCode": "GB",
        "uri": "entities/16TUbnyv/attributes/Country/25Y7U40yl"
    }
]

lookupRawValue

For attributes where the resolveLookupCode parameter is disabled (false), you will see the lookupRawValue parameter. For more information about how lookupRawValue is used when a lookup attribute is referenced in a survivorship filter, see Survivorship Rules.

"Country":
[
    {
        "type": "configuration/entityTypes/HCO/attributes/Country",
        "ov": true,
        "value": "United Kingdom",
        "lookupCode": "GB",
        "lookupRawValue": "GB",
        "uri": "entities/16TUbnyv/attributes/Country/25Y7U40yl"
    }
]

Unify and manage your data