Lookup Specification

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.

What are Lookup Specifications?

A Lookup Specification is a configuration object that describes how Grooper should perform a lookup operation. It defines:

The type of external source to query (such as a database, CMIS repository, web service, XML file, or lexicon).
The fields or variables used as input for the lookup (called lookup fields).
The mapping of results to Grooper fields (called target fields).
The logic for handling multiple results, missing data, or conflicts.

Why use lookups?

Lookups provide several benefits in Grooper:

Data validation: Ensure extracted values match records in external systems, improving data quality.
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:

Complexity: Configuring lookups requires understanding both Grooper and the external data source.
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

The results of a lookup can be used in two primary ways:

Validation: Compare extracted field values against lookup results to ensure accuracy. For example, verifying that an invoice number exists in a database.
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.

Grooper provides options for handling multiple results, missing data, and conflicts, allowing you to control how lookups affect your Data Model.

Lookup specifications

Grooper supports several types of Lookup Specifications, each designed for a specific type of external source:

Database Lookup – Query relational databases using SQL.
CMIS Lookup – Query content management systems using CMISQL.
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.

See also: