Lookups

Overview

Lookups provide powerful search functionality that allows users to find and select existing records from the database. They create searchable interfaces with customizable filters, display columns, and result ordering. Lookups are essential for data selection workflows and can be integrated into flows, pages, and user interfaces.

Lookup configuration interface showing definition, parameters, display, and ordering options

What is a Lookup?

A Lookup is a search interface that:

• Searches Data: Queries database records based on user-defined criteria
• Filters Results: Applies customizable filters to narrow down search results
• Displays Results: Shows search results in configurable columns and formats
• Enables Selection: Allows users to select records for further processing
• Integrates Workflows: Can be called from flows and UI components

Lookup Definition

Lookup Name

• Purpose: Unique identifier for the lookup
• Requirement: Must be unique across all lookups in the system
• Usage: Referenced when calling lookup from flows or UI components
• Best Practice: Use descriptive names that indicate the search purpose

Result Limit

• Purpose: Define maximum number of results the lookup can return
• Performance: Prevents excessive database load and improves response time
• Configuration: Set to 0 for unlimited results (use with caution)
• Recommendation: Set reasonable limits based on expected data volume

Data Set

• Purpose: DataSet definition that defines the search scope and structure
• Search Basis: The lookup search is based on this DataSet definition
• Integration: Links lookup results to your data model structure
• Requirement: Must reference an existing DataSet definition
• Usage: Determines how selected data is structured for further processing

First Alias (Optional)

• Purpose: Define from which level of the DataSet the lookup result will be loaded
• Default: Uses top-level alias of the DataSet if not specified
• Use Case: When you want to load data from a specific entity level
• Flexibility: Allows fine-grained control over data loading scope

Filter

• Purpose: SQL-like filter to search for records in database
• Syntax: Similar to SQL but uses DataSet alias names instead of table names
• Parameters: Reference lookup parameters using %parameter name% syntax
• Example: (Customer.Name LIKE '%CustomerName%' OR %CustomerName% = '')

Lookup Parameters

Parameters define the search criteria that users can input to filter lookup results.

Parameter Name

• Purpose: Unique identifier for the parameter
• Requirement: Must be unique within the lookup
• Usage: Referenced in filter using %parameter name% syntax
• Best Practice: Use descriptive names that match the search field

Type From

• Purpose: Select field that defines the data type for this parameter
• Data Type: Inherits data type from the selected field
• Value Lists: Value Lists are also inherited - if selected field has a Value List, parameter displays as dropdown
• Validation: Ensures parameter values match expected data type

Populate From (Optional)

• Manual Search: Leave blank for user-entered search criteria
• Automatic Population: Specify how parameters are populated from existing records
• Context-Aware: Use current record values to pre-populate search parameters
• Use Case: Search for related records based on current data context

Lookup Display

Defines how search results are presented to users, including which fields are displayed and how they are formatted.

Hierarchical Display

• Multiple Aliases: When columns come from entities with 1-many relationships
• Tree Structure: Results displayed in hierarchical manner
• Parent-Child: Shows related data in expandable tree format
• Navigation: Users can drill down through related information

Title

• Purpose: Define column header in lookup results
• Grouping: Multiple fields can share one title
• Example: "Customer Name" title for both firstname and lastname fields
• Implementation: First field gets the title, subsequent fields leave title blank

Entity Alias, Attribute

• Field Selection: Choose which fields to display in results
• Data Source: Select from available DataSet entities and their attributes
• Multiple Sources: Can display fields from different entities
• Customization: Control exactly what information users see

Lookup Order

Defines how search results are sorted, with support for multiple sorting criteria.

Entity Alias, Attribute

• Sort Field: Define which field controls the ordering
• Multiple Criteria: Can order by multiple fields with priority
• First Priority: First defined field takes sorting priority
• Data Types: Works with all attribute data types

Ascending

• Sort Direction: Define ascending or descending order
• True: Ascending order (A-Z, 1-9, oldest to newest)
• False: Descending order (Z-A, 9-1, newest to oldest)
• Per Field: Each sort field can have different direction

Practical Examples

Customer Search Lookup

• Lookup Name: CustomerSearch
• Data Set: CustomerManagement
• Parameters:
  • CustomerName (Type from: Customer.Name)
  • City (Type from: Customer.City)
• Filter: (Customer.Name LIKE '%CustomerName%' OR %CustomerName% = '') AND (Customer.City = %City% OR %City% = '')
• Display: Customer Name, Company, City, Status
• Order: Customer.Name (Ascending)

Project Lookup with Hierarchy

• Lookup Name: ProjectLookup
• Data Set: ProjectManagement
• Display: Shows Projects with nested ProjectTasks
• Hierarchical: Users can expand projects to see tasks
• Order: Project.StartDate (Descending), ProjectTask.Priority (Ascending)

Status-Filtered Lookup

• Lookup Name: ActiveCustomers
• Parameters: Status (Type from: Customer.Status, Populate from: "Active")
• Filter: Customer.Status = %Status%
• Use Case: Pre-filtered lookup showing only active customers

Integration with Flows

Lookup Action

• Flow Integration: Use "lookup" standard action in flows
• Action Name: References the lookup name
• Parameters: jsp parameter specifies display page
• Result Handling: Selected record loads into specified DataSet

Button Integration

• UI Buttons: Attach lookup actions to interface buttons
• User Experience: Provides search functionality within forms
• Data Selection: Users can search and select related records
• Context Preservation: Maintains current data context during search

Best Practices

Performance Optimization

• Result Limits: Set appropriate limits to prevent performance issues
• Indexed Fields: Use database-indexed fields in filters when possible
• Parameter Validation: Ensure parameters have appropriate data types
• Filter Efficiency: Write efficient filter conditions

User Experience

• Intuitive Parameters: Use parameters that match user mental models
• Relevant Display: Show fields that help users identify correct records
• Logical Ordering: Sort results in meaningful ways
• Optional Parameters: Make parameters optional with OR conditions

Filter Design

• Flexible Search: Use LIKE operators for text searches
• Optional Conditions: Include OR %parameter% = '' for optional parameters
• Multiple Criteria: Combine parameters with AND/OR logic
• Data Validation: Ensure filter syntax matches DataSet structure

Common Patterns

Simple Search Pattern

• Single Parameter: One search field (e.g., name)
• LIKE Filter: Partial matching with wildcards
• Optional: Include empty parameter condition
• Use Case: Quick record finding

Multi-Criteria Pattern

• Multiple Parameters: Several search fields
• Combined Logic: AND/OR combinations
• Flexible Matching: Users can search by any combination
• Use Case: Advanced search scenarios

Hierarchical Display Pattern

• Related Entities: Parent-child relationships
• Tree Structure: Expandable result display
• Multiple Levels: Deep hierarchy navigation
• Use Case: Complex data relationships

Getting Started

Ready to create lookups? Follow these resources:

• Data Set Definition: Understand DataSet structure for lookups
• Standard Actions: Learn how to use lookup actions in flows
• Your First Application - Part 4: See lookups in practice

Related Topics

• Flows: Integrating lookups into business workflows
• Entities & Attributes: Understanding data structure for lookup filters
• Value Lists: Using value lists in lookup parameters