Skip to content

Product Inquiry Implementation in JMC

Overview

Product Inquiry is a sophisticated search and browsing feature in Jumpmind Commerce (JMC) that allows users to discover products through a hierarchical category system combined with dynamic filtering capabilities. Unlike item inquiry which focuses on specific item lookups, product inquiry provides a conversational discovery experience for exploring the product catalog.

Migration Note: For guidance on transitioning from Item Inquiry to Product Inquiry, see the Product Inquiry Migration Guide.

Architecture

Core Components

Backend Services: - IProductInquiryService - Main service interface exposing REST endpoints - ProductInquiryEndpoint - Implementation handling product search logic - ProductInquiryRepository - Data access layer for inquiry-related operations - ProductInquiryState - Flow state managing UI interactions

Frontend Components: - ProductInquiryComponent - Main Angular component rendering the inquiry screen - ProductCategoryComponent - Displays hierarchical category navigation - ProductFiltersComponent - Renders dynamic filter options - ProductSearchResultComponent - Shows search results

Data Model

Primary Tables

ITM_PRODUCT - Core product information: - PRODUCT_ID - Unique product identifier - DESCRIPTION - Product description - PRODUCT_COPY_ID - Reference to rich content sections - Supports augmented fields via product_classifiers - Products group related items together (e.g., a shirt in different sizes/colors)

ITM_ITEM - Individual sellable items: - ITEM_ID - Unique item identifier - ITEM_NAME - Display name for the item - DESCRIPTION - Short item description used in search results, receipts, and product listings. Supports internationalization via ITM_ITEM_I18N - LONG_DESCRIPTION - Detailed item description used in product detail views and rich content displays. Supports markdown formatting and internationalization - PRODUCT_ID - Reference to parent product - TAX_GROUP_ID - Tax classification - TYPE_CODE - Item type (MERCHANDISE, SERVICE, etc.) - FAMILY_CODE - Product family classification - ITEM_COPY_ID - Reference to item-specific content - Supports augmented fields via item_options

ITM_PRODUCT_I18N - Localized product information: - PRODUCT_ID - Reference to product - LOCALE - Language/region code - DESCRIPTION - Localized product description

ITM_ITEM_I18N - Localized item information: - ITEM_ID - Reference to item - LOCALE - Language/region code (e.g., 'en_US', 'es_ES', 'fr_CA') - ITEM_NAME - Localized item name - DESCRIPTION - Localized short item description (overrides ITM_ITEM.DESCRIPTION) - LONG_DESCRIPTION - Localized detailed description (overrides ITM_ITEM.LONG_DESCRIPTION)

ITM_PRODUCT_OPTION - Product option types: - PRODUCT_ID - Reference to product - OPTION_TYPE_ID - Type of option (color, size, etc.) - Links products to their configurable attributes

ITM_INQ_CATEGORY - Defines the hierarchical category structure: - CATEGORY_ID - Unique category identifier - PARENT_ID - Parent category for hierarchy - DISPLAY_NAME - User-friendly category name - DISPLAY_ORDER - Sort order within siblings - IMAGE_URL - Category image - EXPOSES_MATCHES_FLAG - Whether selecting this category shows products

ITM_INQ_CATEGORY_MEMBER - Maps products to categories: - CATEGORY_ID - Reference to inquiry category - PRODUCT_ID - Reference to product

ITM_INQ_ATTRIBUTE - Defines filterable attributes: - ATTRIBUTE_ID - Unique identifier for this searchable item or product attribute - ATTRIBUTE_TYPE - Technical descriptor (e.g. bean name) for the mechanism by which values for this attribute are determined - DISPLAY_NAME - User-friendly label for this attribute - DISPLAY_ORDER - Order in which this attribute should be displayed relative to other searchable attributes. Lower values get more prominent representation - FILTER_SCOPE - Dictates the context(s) in which this attribute should be made available for filtering (INQUIRY, ALL, etc.)

ITM_INQ_ATTRIBUTE_ITEM_VAL - Item level attributes: - ITEM_ID - The ID of the item to which this searchable attribute value is assigned - ATTRIBUTE_ID - The ID of the searchable attribute assigned a value (references ITM_INQ_ATTRIBUTE) - ATTRIBUTE_VALUE - The value assigned to the searchable attribute - Primary key: ITEM_ID, ATTRIBUTE_ID - Example: if Brand and Color were defined as searchable/filterable attributes, then this table would have values for each item for those attributes (Brand=Nike, Color=Blue) - Note: attributes can be defined at the product or item level or both. If no attributes are defined at the item level, product level attributes will be used for search as each item is tied to a product

ITM_INQ_ATTRIBUTE_PRODUCT_VAL - Product level attributes: - PRODUCT_ID - The ID of the product to which this searchable attribute value is assigned - ATTRIBUTE_ID - The ID of the searchable attribute assigned a value (references ITM_INQ_ATTRIBUTE) - ATTRIBUTE_VALUE - The value assigned to the searchable attribute - Primary key: PRODUCT_ID, ATTRIBUTE_ID - Example: if Brand and Color were defined as searchable/filterable attributes, then this table would have values for each product for those attributes (Brand=Nike, Color=Blue)

ITM_PRODUCT_COPY_SECTION - Product content sections: - PRODUCT_COPY_ID - Unique identifier for product content - SECTION_ID - Identifier for content section within product - SECTION_TITLE - Display title for the content section - MARKDOWN_TEXT - Rich content in markdown format - DISPLAY_ORDER - Controls section presentation order

ITM_PRODUCT_COPY_SECTION_I18N - Internationalized product content: - LOCALE - Language/region code for localized content - PRODUCT_COPY_ID - Reference to product content - SECTION_ID - Reference to content section - SECTION_TITLE - Localized section title - MARKDOWN_TEXT - Localized content in markdown format

ITM_SELLING_PRICE - Item pricing information: - SELLING_PRICE_ID - Unique price identifier - ITEM_ID - Reference to item - PRODUCT_ID - Reference to product group - PRICE_TYPE - Type of price (regular, sale, etc.) - LIST_PRICE - Manufacturer suggested retail price - PRICE - Actual selling price - QUANTITY - Quantity for the price (bulk pricing) - COST - Retailer cost - Supports effective dating and tagging

ITM_SELLING_RULE - Item selling restrictions and rules: - ITEM_ID - Reference to item - SELLING_STATUS_CODE - Availability status (AVAIL, NA, RECALLED) - Various boolean flags for selling restrictions: - COUPON_ALLOWED - Whether coupons can be applied - RETURN_PROHIBITED - Whether returns are allowed - DISCOUNT_ELIGIBLE - Whether discounts can be applied - ORDER_ELIGIBLE - Whether item can be ordered - LOYALTY_POINTS_ELIGIBLE - Whether loyalty points apply - Age restrictions (MINIMUM_SELLER_AGE, MINIMUM_BUYER_AGE) - Quantity limits (MINIMUM_SALE_UNIT_COUNT, MAXIMUM_SALE_UNIT_COUNT) - Special requirements (serial number, warranty signup) - Supports effective dating and tagging

Key Features

1. Hierarchical Category Navigation

The system supports unlimited depth category hierarchies. Categories are organized in a single-parent tree structure where: - Root categories have no parent - Each category can have multiple children - Products inherit membership from ancestor categories - Only categories with exposesMatches=true display product results

Example hierarchy: 

APPAREL
├── WOMEN
├── MEN  
├── SWIM
│   └── WATER_SHOES
└── KIDS

2. Dynamic Filtering System

The filtering system is highly extensible through several interfaces:

IProductInquiryFilterGenerator - Generates available filters based on search results IProductInquiryFilterConverter - Converts UI filters to search expressions IProductInquiryFilterProvider - Provides filter definitions

Filters are automatically generated from: - Product attributes present in search results - Item-level attributes across matching products - Custom filter providers

3. Rich Product Content Display

Product details are enhanced with structured content sections: - Tabbed Interface - Content sections appear as tabs in product details - Markdown Support - Rich formatting for product descriptions and specifications - Internationalization - Localized content for multi-language deployments - Flexible Structure - Configurable sections for different product types - Fallback Logic - Default content when localized versions unavailable

4. Conversational Search Experience

The inquiry process follows a conversational pattern: 1. User starts at root categories or searches by text 2. Selects a category to narrow results 3. Applies filters to further refine 4. Views matching products with rich content tabs 5. Can navigate back through breadcrumbs to adjust search

API Endpoints

Based on the JMC API Documentation, the Product Inquiry Service exposes the following endpoints:

Core Endpoints

PUT /rest/item/inquiry/categories - Retrieve category hierarchy - Summary: Retrieves all product inquiry categories having a specified parent or other ancestor category - Operation ID: getProductInquiryCategories - Request Body: GetProductInquiryCategoriesRequest - Response: GetProductInquiryCategoriesResponse

PUT /rest/item/inquiry - Execute product search - Summary: Reports all products belonging to a given category or to one of its sub-categories also satisfying all specified filter criteria. Additionally reports new product inquiry categories and filters which may be selected to further refine the result set in a subsequent product inquiry operation. - Operation ID: inquireAboutProducts - Request Body: ProductInquiryRequest - Response: ProductInquiryResponse

GET /rest/item/inquiry/{productId} - Get specific product details - Summary: Retrieves a specific product, its copy details, and the details of all items associated with it - Operation ID: inquireAboutProduct - Path Parameter: productId (string, required) - Response: ProductInquirySelectionResponse

PUT /rest/item/inquiry/getItemByAttributes - Get item by attributes - Summary: Retrieves the ItemModel for the requested productId that matches the requested attribute values map - Operation ID: getItemByAttributes - Request Body: GetItemByAttributesRequest - Response: GetItemByAttributesResponse

Response Structure

Product inquiry responses include: - matches - Products satisfying search criteria - availableCategories - Child categories for further navigation - filters - Available filters with current selections - matchCount - Total matches found - responseMatchCount - Matches returned (may be limited)

Error Handling

All endpoints return standard HTTP status codes: - 200: OK - Successful operation - 400: Bad Request - Invalid request parameters - 500: Internal Server Error - Server-side error

Error responses follow the ErrorResult schema format.

Flow Integration

State Flow Configuration

Product inquiry integrates with JMC's flow engine through ProductInquiryFlow:

ProductInquiryFlow:
    - ProductInquiryState:
          Back: CompleteState
          Select:
              ProductDetailsState:
                  AddItem: CompleteState
                  Back: ProductInquiryState

State Management

The ProductInquiryState manages: - Screen rendering with category and filter data - User interactions (category selection, filtering, search) - Navigation through breadcrumbs - Integration with product selection flows

UI Implementation

Screen Structure

The product inquiry screen consists of:

  1. Header - Navigation and branding
  2. Search Bar - Text-based product search
  3. Breadcrumbs - Category navigation history
  4. Categories - Available child categories
  5. Filters - Dynamic filter options
  6. Results - Matching products with pagination

Responsive Design

The UI adapts to different screen sizes: - Mobile: Stacked layout with collapsible sections - Tablet: Two-column layout - Desktop: Three-column layout with sidebar filters

Data Providers

The ProductInquiryResultsUIMessageDataProvider manages: - Search state and results - Applied categories and filters - Pagination and data loading - Integration with backend services

Usage Patterns

Typical User Journey

  1. Entry - User accesses product inquiry from main menu
  2. Browse - Explores category hierarchy by selecting categories
  3. Filter - Applies attribute filters to narrow results
  4. Select - Chooses a product to view details or add to transaction
  5. Navigate - Uses breadcrumbs to adjust search scope

Integration Points

Product inquiry integrates with: - Sales Flow - Adding products to transactions - Return Flow - Finding items for returns/exchanges - Order Management - Product selection for orders - Inventory - Real-time availability checking

Configuration

Category Setup

Categories are configured through CSV data loading: 

CATEGORY_ID,PARENT_ID,DISPLAY_NAME,DISPLAY_ORDER,EXPOSES_MATCHES_FLAG
APPAREL,,Apparel,0,1
WOMEN,APPAREL,Women's,0,1

Filter Configuration

Filters are defined through: - Product attribute definitions - Custom filter providers - Scope-based availability rules

Product Content Configuration

Product copy sections are configured through: - Content Structure - Define section types (description, specifications, care instructions) - Localization - Configure supported locales and fallback behavior - Display Order - Control tab sequence in product details - Content Sources - Import from PIM, CMS, or manual entry systems

# Example product copy sections
PRODUCT_COPY_ID,SECTION_ID,SECTION_TITLE,DISPLAY_ORDER,MARKDOWN_TEXT
PROD_001,description,Description,1,"## Premium Cotton Shirt\nSoft and comfortable..."
PROD_001,care,Care Instructions,2,"- Machine wash cold\n- Tumble dry low"
PROD_001,sizing,Size Guide,3,"| Size | Chest | Length |\n|------|-------|--------|"

Performance Considerations

  • Categories with exposesMatches=false prevent expensive product searches
  • Search results are limited by openpos.item.maxSearchResults configuration
  • Caching is applied to category hierarchies and attribute definitions
  • Virtual scrolling handles large result sets in the UI

Extension Points

Custom Filters

Implement IProductInquiryFilterProvider to add custom filtering logic: 

@Component
public class CustomFilterProvider implements IProductInquiryFilterProvider {
    public Collection<ProductInquiryFilter> generateFilters(ProductSearchContext context) {
        // Custom filter generation logic
    }
}

Search Integration

The system integrates with the broader product search engine through IProductSearchEngine, allowing for: - Custom search algorithms - External search providers - Advanced ranking and sorting

This implementation provides a flexible, scalable foundation for product discovery that can be adapted to various retail scenarios while maintaining consistent performance and user experience.