Lookup Specification: Difference between revisions

Latest revision as of 11:15, 15 October 2025

This article is about the current version of Grooper.

Note that some content may still need to be updated.

2025

A Lookup Specification defines a "lookup operation", where existing Grooper fields (called "lookup fields") are used to query an external data source, such as a database. The results of the lookup can be used to validate or populate field values (called "target fields") in Grooper. Lookup Specifications are created on "container elements" (data_table Data Models, insert_page_break Data Sections and table Data Tables) using their Lookups property. Lookups may query using all single-instance fields relative to the container element (including those defined on parent elements up to the root Data Model), but cannot be used to populate a field value on a parent of the container element.

Introduction

A Lookup Specification in Grooper defines how information is retrieved from external sources to validate or populate fields within a Data Model. Lookups are essential for connecting your extracted data to authoritative sources, such as databases, web services, or reference lists, ensuring data accuracy and completeness.

Lookups are used to:

Validate extracted values against trusted sources.
Populate additional fields based on related information.
Enforce business rules by cross-referencing data.

Benefits:

Ensures data consistency and accuracy.
Automates population of related fields, reducing manual entry.
Supports complex validation scenarios.

Drawbacks:

May introduce dependencies on external systems.
Can increase processing time if sources are slow or unavailable.
Requires careful configuration to avoid mismatches or errors.

How they work

Lookup Specifications operate by defining a set of "lookup fields" and "target fields" within container elements such as Data Models, Data Sections, and Data Tables. When a lookup is triggered, Grooper queries the external source using the values from the lookup fields. The results can then be used to validate the original data or to populate the target fields with new information.

For example, a Data Field for "Customer ID" might use a lookup to validate the ID against a database and automatically fill in the "Customer Name" and "Address" fields.

Lookup Specifications

Grooper supports several types of Lookup Specifications, each designed for different integration scenarios:

Database Lookup: Connects to a database using a Data Connection and executes a SQL query. Commonly used for validating or enriching data from enterprise databases.

CMIS Lookup: Queries a CMIS Repository using CMISQL to retrieve metadata or content information. Useful for integrating with document management systems.

Lexicon Lookup: Uses a Lexicon (reference list or dictionary) to match and validate field values. This type is less common but valuable for standardized lists or fuzzy matching.

Web Service Lookup: Sends requests to a web service endpoint (REST or SOAP) and parses the response to populate fields. Enables integration with cloud services and APIs.

XML Lookup: Extracts data from an XML file or resource using selectors and mappings. Ideal for scenarios where reference data is stored in XML format.

Each Lookup Specification is configured within a Data Model, Data Section, Data Table, or Data Field, allowing flexible integration with a wide range of external sources.

Where are Lookup Specifications

Lookup Specifications can be found on container elements like Data Models, Data Sections, and Data Tables.
The Lookups property is found within the Behavior section of the property grid of the selected Node.
Click the ellipsis button to open the "List of Lookup Specifications" collection editor.
Click the add button to see a list of selectable Lookup Specifications.
Select a Lookup Specification from the drop-down menu.
Once a specification is selected it will be added to the collection.
Once selected, you can edit the properties of the Lookup Specification in its property grid.

@@ Line 3: / Line 3: @@
 <blockquote>{{#lst:Glossary|Lookup}}</blockquote>
-== What are Lookup Specifications? ==
+== Introduction ==
-A Lookup Specification is a configuration object that describes how Grooper should perform a lookup operation. It defines:
+A '''Lookup Specification''' in Grooper defines how information is retrieved from external sources to validate or populate fields within a Data Model. Lookups are essential for connecting your extracted data to authoritative sources, such as databases, web services, or reference lists, ensuring data accuracy and completeness.
-* The type of external source to query (such as a database, CMIS repository, web service, XML file, or lexicon).
+'''Lookups are used to:'''
-* The fields or variables used as input for the lookup (called '''lookup fields''').
+* '''Validate''' extracted values against trusted sources.
-* The mapping of results to Grooper fields (called '''target fields''').
+* '''Populate''' additional fields based on related information.
-* The logic for handling multiple results, missing data, or conflicts.
+* '''Enforce business rules''' by cross-referencing data.
-== Why use lookups? ==
+'''Benefits:'''
+* Ensures data consistency and accuracy.
+* Automates population of related fields, reducing manual entry.
+* Supports complex validation scenarios.
-Lookups provide several benefits in Grooper:
+'''Drawbacks:'''
+* May introduce dependencies on external systems.
+* Can increase processing time if sources are slow or unavailable.
+* Requires careful configuration to avoid mismatches or errors.
-# '''Data validation''': Ensure extracted values match records in external systems, improving data quality.
+== How they work ==
-# '''Data enrichment''': Populate additional fields with information retrieved from external sources, reducing manual entry.
-# '''Automation''': Streamline business processes by automatically filling in or checking data during batch processing.
-# '''Integration''': Connect Grooper to existing enterprise data sources, such as databases or document repositories.
-However, there are some drawbacks to consider:
+Lookup Specifications operate by defining a set of "lookup fields" and "target fields" within container elements such as [[Data Model|Data Models]], [[Data Section|Data Sections]], and [[Data Table|Data Tables]]. When a lookup is triggered, Grooper queries the external source using the values from the lookup fields. The results can then be used to validate the original data or to populate the target fields with new information.
-* '''Complexity''': Configuring lookups requires understanding both Grooper and the external data source.
+For example, a Data Field for "Customer ID" might use a lookup to validate the ID against a database and automatically fill in the "Customer Name" and "Address" fields.
-* '''Performance''': Each lookup may introduce latency, especially with remote or slow sources.
-* '''Maintenance''': Changes to external systems or lookup logic may require updates to Lookup Specifications.
-* '''Error handling''': Lookups must be configured to handle missing, ambiguous, or conflicting results.
-== How lookup results are used ==
+== Lookup Specifications ==
-The results of a lookup can be used in two primary ways:
+Grooper supports several types of Lookup Specifications, each designed for different integration scenarios:
-* '''Validation''': Compare extracted field values against lookup results to ensure accuracy. For example, verifying that an invoice number exists in a database.
+; [[Database Lookup]]
-* '''Population''': Automatically fill in target fields with data from the lookup result. For example, populating a customer name and address based on an account number.
+: Connects to a database using a [[Data Connection]] and executes a SQL query. Commonly used for validating or enriching data from enterprise databases.
-Grooper provides options for handling multiple results, missing data, and conflicts, allowing you to control how lookups affect your Data Model.
+; [[CMIS Lookup]]
+: Queries a [[CMIS Repository]] using CMISQL to retrieve metadata or content information. Useful for integrating with document management systems.
-== Lookup specifications ==
+; [[Lexicon Lookup]]
+: Uses a [[Lexicon]] (reference list or dictionary) to match and validate field values. This type is less common but valuable for standardized lists or fuzzy matching.
-Grooper supports several types of Lookup Specifications, each designed for a specific type of external source:
+; [[Web Service Lookup]]
+: Sends requests to a web service endpoint (REST or SOAP) and parses the response to populate fields. Enables integration with cloud services and APIs.
-* [[Database Lookup]] – Query relational databases using SQL.
+; [[XML Lookup]]
-* [[CMIS Lookup]] – Query content management systems using CMISQL.
+: Extracts data from an XML file or resource using selectors and mappings. Ideal for scenarios where reference data is stored in XML format.
-* [[Lexicon Lookup]] (uncommon) – Match values against a lexicon for validation or enrichment.
-* [[Web Service Lookup]] – Query REST or SOAP web services.
-* [[XML Lookup]] – Query XML files using XPath expressions.
-Each type of Lookup Specification has its own configuration options and use cases. For more details, see the linked articles above.
+Each Lookup Specification is configured within a Data Model, Data Section, Data Table, or Data Field, allowing flexible integration with a wide range of external sources.
-----
+== Where are Lookup Specifications ==
-'''See also:'''
+# Lookup Specifications can be found on container elements like Data Models, Data Sections, and Data Tables.
+# The Lookups property is found within the Behavior section of the property grid of the selected Node.
+# Click the ellipsis button to open the "List of Lookup Specifications" collection editor.
+# Click the add button to see a list of selectable Lookup Specifications.
+# Select a Lookup Specification from the drop-down menu.
+# Once a specification is selected it will be added to the collection.
+# Once selected, you can edit the properties of the Lookup Specification in its property grid.
+<div style="position: relative; box-sizing: content-box; max-height: 80vh; max-height: 80svh; width: 100%; aspect-ratio: 1.7777777777777777; padding: 40px 0 40px 0;"><iframe src="https://app.supademo.com/embed/cmg9hdcuh000uua0idxfav2qd?embed_v=2&utm_source=embed" loading="lazy" title="Lookup Specification" allow="clipboard-write" frameborder="0" webkitallowfullscreen="true" mozallowfullscreen="true" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe></div>
+== See also ==
 * [[Data Model]]
 * [[Data Section]]
 * [[Data Table]]
 * [[Data Field]]
+* [[Lexicon]]
+* [[Data Connection]]
+* [[CMIS Connection]]
+* [[CMIS Repository]]