Lexicon Lookup

---

The Lexicon should contain keys which match potential values for the Lookup Field. If the value of the Lookup Field is not present in the Lexicon, then the lookup operation will fail, and the Miss Disposition will be triggered.

Validation Only

To validate a field value without populating other fields, simply provide a list of valid values. For example, the entries shown below might be used to validate a 'Country Name' field:

Afghanistan
Albania
Algeria
Andorra
Angola
...

Populating Fields

If field values are to be populated as a result of the lookup, the lexicon should be configured as a 'Lookup' Lexicon, where each entry is a key-value pair separated by the "=" character. For example, the following entries could be used to populate 'State Name' based on the value of the 'State Abbreviation' field:

AK=Alaska
AL=Alabama
AR=Arkansas
AZ=Arizona
CA=California
...

Multi-Column Data

Lexicons may also be configured with multi-column values, where each value has multiple components separated by a delimiter. For example, the entries below provide the city, state, and county associated with a set of ZIP codes.

...
76049=Granbury,TX,Hood
76050=Grandview,TX,Johnson
76051=Grapevine,TX,Tarrant
76052=Haslet,TX,Tarrant
76053=Hurst,TX,Tarrant
...

---

Specifies the Data Field whose value will be used as the key for the lookup operation.

• The value of this field is searched in the Lexicon to determine if a match exists.
• For validation, the lookup succeeds if the value is present in the Lexicon.
• For field population, the value is used to retrieve associated data (such as a mapped value or columns).

Best Practices:

• Choose a field that uniquely identifies the data to be validated or populated.
• The 'Lookup Field' should not also be a target in 'Field Mappings'.

Example:
Use a 'State Abbreviation' field as the lookup key to retrieve the full state name from a Lexicon.

---

Specifies how values from the Lexicon are mapped to Data Fields when a lookup is successful.

• Each mapping links a target field to a value or column from the Lexicon entry.
• For single-value lookups, map the value directly to a field.
• For multi-column lookups, use the 'Column Number' property in each mapping to specify which column to use.
• If no mappings are defined, the lookup is used for validation only.

Example:

• Map column 1 to 'City', column 2 to 'State', and column 3 to 'County' for a ZIP code lookup.

Best Practices:

• Ensure that each mapping references a valid target field and the correct column number.
• Do not map the 'Lookup Field' as a target.

---

Defines the character used to separate multiple values within a single Lexicon entry.

• Required when the Lexicon contains entries with more than one value per key (e.g., 12345=City,State,County).
• Each value is split using this delimiter, and mapped to fields via 'Field Mappings'.

Example:

• For entries like 76049=Granbury,TX,Hood, set the delimiter to a comma (",").

Tip:
Use a character that does not appear in the data values themselves.

---

Controls the similarity threshold for fuzzy matching during lookups.

• A value of 1.0 (100%) requires an exact match.
• Lower values (e.g., 0.9 or 0.8) allow approximate matches, useful for handling typos or OCR errors.
• Fuzzy matching is especially helpful when user-entered data may not exactly match the Lexicon entries.

Example:

• Set to 0.95 to allow a 95% similarity match for city names.

Best Practices:

• Use fuzzy matching only when necessary, as it may increase the chance of incorrect matches.

---

When enabled, reverses the direction of fuzzy lookups:

• Instead of matching the 'Lookup Field' value against the Lexicon keys, it matches against the values.
• Returns the corresponding key for the closest matching value.

Use Case:

• Useful when you need to look up a code based on a descriptive value, rather than the other way around.

Note:
This option is only available when 'Similarity' is less than 1.0 (fuzzy matching enabled).

---

Use this property to provide a human-readable explanation of the lookup's purpose, configuration, or any special instructions. This description is displayed in the property grid and can help other users understand the intent and behavior of the lookup.

---

Can be one of the following values:

Name	Value	Description
Auto	0	Trigger automatically when the value of a lookup field changes. Use this mode for fully automated lookups. The lookup will execute any time a referenced field value changes, ensuring data is always validated or populated in real time.	►
Conditional	1	Trigger automatically when the value of a lookup field changes, only if the target fields are currently empty. Use this mode to avoid overwriting existing data. The lookup will only execute if the target fields are blank, making it ideal for initial population scenarios.	►
Manual	2	Must be triggered manually by a user. Use this mode when lookups should only occur on explicit user action, such as clicking a button. This is useful for scenarios where automatic lookups are not desired.	►
Custom	3	The trigger condition will be defined by the Trigger expression. Use this mode for advanced scenarios where a custom code expression determines when the lookup should execute. The expression must evaluate to true for the lookup to run.	►

Determines the conditions under which a lookup operation is triggered. Use this to control automation, user interaction, or custom logic for lookup execution.

---

Enter a code expression that evaluates to true or false. The lookup will only execute if the expression returns true. This allows for advanced, data-driven control over when the lookup fires. Example:@FieldA != null && @FieldB == "Active"

---

Can be one of the following values:

Name	Value	Description
Normal	0	Flag the lookup fields and clear the target fields. Sets an error status on the lookup fields and clears any values in the target fields. Use this to alert users and remove potentially invalid data.	►
Flag	1	Flag the lookup fields. Sets an error status on the lookup fields but leaves target field values unchanged. Use this to notify users of a problem without removing existing data.	►
Clear	2	Clear the target field values. Clears the values of the target fields without flagging an error. Use this to silently remove data when no match is found.	►
Ignore	3	Do nothing. Behave as though no lookup is defined. No action is taken if no results are found. Use this to ignore missing data and leave the current values and status unchanged.	►

Determines the behavior of the lookup operation when no matching records are found in the external data source. Configure this to control user feedback and data clearing.

---

Can be one of the following values:

Name	Value	Description
Normal	0	Flag the lookup fields and clear the target fields. Sets an error status on the lookup fields and clears the target fields. Use this to prevent ambiguous or conflicting data from being used.	►
Flag	1	Flag the lookup fields. Sets an error status on the lookup fields but leaves the target fields unchanged. Use this to alert users to a conflict while preserving existing data.	►
Accept	2	Use the first row in the result set. Accepts the first result returned by the lookup and populates the target fields with its values. Use this when it is acceptable to use the first match, but be aware of potential data ambiguity.	►
Ignore	3	Do nothing. Behave as though no lookup is defined. No action is taken if multiple results are found. Use this to ignore conflicts and leave the current values and status unchanged.	►

Controls the behavior when the lookup query returns more than one matching record. Choose the option that best fits your data integrity and workflow needs.

---

Can be one of the following values:

Name	Value	Description
Overwrite	0	Populate the target fields. Overwrites the values of the target fields with the results from the lookup, regardless of whether they are currently empty or already populated.	►
Supplement	1	Populate the target fields if they are empty. Only sets the value of a target field if it is currently blank. Existing values are preserved. Use this to avoid overwriting user-entered or previously populated data.	►
None	2	Do not populate any fields. The lookup will not update any target fields. Use this mode for validation-only scenarios, where you want to check values but not change them.	►

Controls whether and how the results of a lookup operation are written to the target fields. Choose the method that matches your data entry and validation requirements.

This property displays a comma-separated list of all Data Fields and Variable Definitions that are used as input for the lookup query. These are the values that will be sent to the external data source to perform the lookup.

This property displays a comma-separated list of all Data Fields that will be set or validated by the results of the lookup. These are the target fields that will receive values from the external data source.