Description Mappers in Intent-Based Navigation

In user-written queries, references are typically made using descriptions rather than Primary Keys (PKs). For example, users are more likely to say "provider ACME" instead of "provider 28". AI models can infer the description of the entity from user input, but they cannot directly identify the corresponding PK, which is often what programs require.This creates the need to map a description to its corresponding PK. K2BTools addresses this need with a feature called Description Mappers.

Parameters in intent resolvers

Intent resolvers can receive several types of parameters, such as:

• Filters
• Entity keys (PKs) in object actions like Update, Delete, or Display

Some examples of how parameters are used:

• Entity manager actions (like Update, Delete, Display): require the PK as a parameter.

• Filters with control types (e.g., dynamic combo boxes): typically use the item value (PK) rather than the item description.

• Filters based on enumerated domains: receive the domain value instead of the label or description.

Realms and Description Mappers

In K2BTools’ Intent Based Navigation Metadata, each parameter can be associated with a realm. A realm can be:

• Based on a known set of values (e.g., an enumerated domain)
• Mapped using a Description Mapper

A Description Mapper is a program automatically generated in the Knowledge Base by K2BTools when running the “Generate Intent-Based Navigation Objects” command. This program converts a user-entered description into the corresponding PK value.

When the AI infers that a user input corresponds to a parameter value, and that parameter has a description mapper, K2BTools automatically calls the mapper to retrieve the correct ID.

Description Mapper Structure

The generated program has the following parameters:

• In: IntentResolverName – The intent resolver being processed.
• In: ParameterName – The name of the parameter being resolved.
• InOut: ParameterValues – This parameter initially contains the extracted descriptions inferred by the LLM from the user's input. The DescriptionMapper procedure is responsible for updating this structure by updating the parameters
  • Parameters: These parameters represent the inputs provided to the intent resolver. Since some parameters (e.g., filters with IsCollection = true) can contain multiple values, the data is structured as a collection. Each element in the collection includes:
    • Extracted:The raw value inferred from the user's query by the LLM. This value may be partial, approximate, or contain misspellings.
    • Mapped: The corresponding primary key value resolved from the extracted description. This is the actual value used by K2BTools to invoke the program associated with the intent.
    • MappedDescription: The corrected or validated description that corresponds to the mapped primary key. This provides a reliable representation of the parameter, even if the original input was ambiguous or incorrect.
• Out: Success – Indicates whether the mapping was successful.
• Out: Messages – Contains any error messages.

Mapping Strategy

Inferring a PK from a description can be difficult due to:

• Descriptions not being candidate keys
• Multiple possible matches
• Misspellings or vague references from user input

K2BTools follows a three-step strategy to map descriptions:

1. Exact Match: It first attempts to find a record where the description attribute exactly matches the input.
2. LIKE Match: If no exact match is found, it uses a LIKE clause to find a partial match.
3. Manual Mapping Subroutine: If still no match is found, K2BTools calls a U_ManualMapping subroutine, which can be customized by the developer.

Customizing the Manual Mapping Subroutine

The U_ManualMapping subroutine provides a place for developers to implement custom logic, such as:

• Raising an error (by setting &Success = False and adding a message)
• Implementing additional mapping logic
• Iterating over parameters to handle complex cases

This ensures flexibility and allows developers to tailor the behavior to their application needs.

Example: Mapping a Student by Description

Consider a transaction called Student, where the description attribute is StudentLastName. A user may refer to the student by last name, first name, or full name. K2BTools automatically includes the following logic in the description mapper:

• Exact match on StudentLastName
• Partial match (Like) on StudentLastName
• Fallback to extracted value: If no matches are found, the extracted input value is used as the mapped value..
• Manual mapping:
  • The mapper calls the U_ManualMapping subroutine, where the developer can add custom logic for cases such as::
    • matching by first name,
    • matching by full name (first and last name together),
    • handling misspellings or alternative formats.

Description mapper implementation

Description Mapper U_ ManualMapping subroutine implementation

To implement custom mapping logic, the developer should iterate through all parameter values that have not been automatically matched. The code below demonstrates this process:

For &ParameterValue in &Parameter.Values
    // Only process values that are still unmapped
    If &ParameterValue.Mapped =  &Value_StudentId.ToString() 
        //Try matching by first name only
        &extracted = &ParameterValue.Extracted.ToLower()
        For Each
            Where StudentFirstName.ToString().ToLower() like '%' + &extracted + '%'
            &ParameterValue.Mapped = StudentId.ToString()
            &ParameterValue.MappedDescription = StudentLastName.ToString()
            Exit
        EndFor
    EndIf
    
    If &ParameterValue.Mapped =  &Value_StudentId.ToString()
        // If still unmapped, try splitting the input into parts
        &parts = &ParameterValue.Extracted.SplitRegEx("\s")
    If &parts.Count > 1
        &firstName = &parts.Item(1).Trim()
        &lastName =&parts.Item(2).Trim()
        // Try matching by first name and last name together
        For Each
            Where StudentLastName.ToString().ToLower().Trim() like '%' + &LastName + '%'
            Where StudentFirstName.ToString().ToLower().Trim() like '%' + &FirstName + '%'
            &ParameterValue.Mapped = StudentId.ToString()
            &ParameterValue.MappedDescription = StudentLastName.ToString()
            Exit
        EndFor
    EndIf
    // If still unmapped, try matching by last name only 
    If &ParameterValue.Mapped =  &Value_StudentId.ToString()
        For Each
            Where StudentLastName.ToString().ToLower().Trim() like '%' + &LastName + '%'
            &ParameterValue.Mapped = StudentId.ToString()
            &ParameterValue.MappedDescription = StudentLastName.ToString()
            Exit
        EndFor
    EndIf
     // If still unmapped, try matching by first name only
    If &ParameterValue.Mapped =  &Value_StudentId.ToString()
        For Each
            Where StudentFirstName.ToString().ToLower().Trim() like '%' + &FirstName + '%'
            &ParameterValue.Mapped = StudentId.ToString()
            &ParameterValue.MappedDescription = StudentLastName.ToString()
            Exit
        EndFor
    EndIF
EndFor