Migration Guide: Item Inquiry to Product Inquiry¶

Overview¶

This guide provides step-by-step instructions for migrating from Item Inquiry to Product Inquiry in JMC. Product Inquiry offers enhanced search capabilities with hierarchical category navigation and dynamic filtering, providing a more intuitive product discovery experience.

Related Documentation: For comprehensive technical details about Product Inquiry implementation, see Product Inquiry Implementation.

Key Differences¶

Item Inquiry (Current)¶

Simple text-based search
Direct item lookup by ID/name
Hand key or scan barcode
Basic search results display
Limited categorization
Single-step search process

Product Inquiry (Target)¶

Hierarchical category navigation
Hand key or scan barcode
Dynamic attribute-based filtering
Conversational search experience
Rich product browsing

Migration Steps¶

1. Data Model Overview¶

Product Inquiry introduces several new data models that extend the existing product/item structure:

Core Data Models¶

ITM_INQ_CATEGORY - Hierarchical category structure - Supports unlimited depth category trees - Each category can have a single parent - EXPOSES_MATCHES_FLAG controls whether selecting the category shows products - Includes display ordering and image URLs for UI presentation

ITM_INQ_CATEGORY_MEMBER - Product-to-category relationships - Many-to-many mapping between products and categories - Products can belong to multiple categories - Enables flexible product categorization

ITM_INQ_ATTRIBUTE - Filterable attribute definitions - Defines the dictionary of searchable/filterable attributes - FILTER_SCOPE determines where attributes are available (INQUIRY, ALL, etc.) - ATTRIBUTE_TYPE specifies how values are determined (product, item, derived)

ITM_INQ_ATTRIBUTE_PRODUCT_VAL - Product-level attribute values - Stores explicit attribute values assigned to products - Used for product-wide attributes like brand, material, etc.

ITM_INQ_ATTRIBUTE_ITEM_VAL - Item-level attribute values - Stores attribute values specific to individual items - Used for item-specific attributes like size, color variations

Product Content Models¶

ITM_PRODUCT_COPY_SECTION - Product content sections - Stores structured content for products (descriptions, specifications, care instructions, etc.) - Each section has a unique sectionId within a productCopyId - Contains markdownText for rich content formatting - displayOrder controls section presentation sequence - Used to populate product detail tabs in the UI

ITM_PRODUCT_COPY_SECTION_I18N - Internationalized product content - Provides localized versions of product copy sections - Supports multiple locales for the same content section - Enables multilingual product information display - Falls back to default content when locale-specific content is unavailable

Relationship to Existing Models¶

Product Inquiry leverages existing JMC data models: - ITM_PRODUCT - Core product information (unchanged) - ITM_ITEM - Individual item details (unchanged) - ITM_PRODUCT_COPY_SECTION - Rich product content displayed in detail tabs - ITM_PRODUCT_COPY_SECTION_I18N - Localized product content - Product Search Engine - Existing search infrastructure is reused - Tagging System - Categories support standard JMC tagging for multi-tenancy

2. Data Migration Strategy¶

Category Hierarchy Design¶

Analyze your existing product structure to design an appropriate category hierarchy:

Considerations: - Start with broad categories at the root level - Create logical subcategories based on how users browse - Set EXPOSES_MATCHES_FLAG=false for high-level categories to avoid performance issues - Use DISPLAY_ORDER to control category presentation order

Example Approach:

APPAREL (exposes_matches=false)
├── WOMEN (exposes_matches=true)
├── MEN (exposes_matches=true)
└── SHOES (exposes_matches=true)
    ├── ATHLETIC (exposes_matches=true)
    └── DRESS (exposes_matches=true)

Product-Category Assignment¶

Map products to categories based on existing classification: - Products can belong to multiple categories - Consider both direct assignment and inheritance through hierarchy - Use existing product attributes/classifications as mapping criteria - Validate that all products have at least one category assignment

Attribute Strategy¶

Identify filterable attributes from existing data:

Product-Level Attributes (stored in ITM_INQ_ATTRIBUTE_PRODUCT_VAL): - Brand, Material, Style, Collection - Attributes that apply to all items of a product

Item-Level Attributes (stored in ITM_INQ_ATTRIBUTE_ITEM_VAL): - Size, Color, Finish - Attributes that vary between items of the same product

Derived Attributes (calculated dynamically): - Price ranges, availability status - Computed from existing data during search

Product Content Strategy¶

Plan how to populate product copy sections for rich product details:

Content Section Types: - Product descriptions and specifications - Care and maintenance instructions - Size guides and fit information - Material composition and features - Warranty and return policies

Content Population Sources: 1. Existing product descriptions - Migrate from current product data 2. External content systems - Import from PIM, DAM, or CMS 3. Structured data entry - Create standardized content templates 4. Localization services - Translate content for multiple markets

Data Population Approach¶

There can be many approaches to populating these new product inquiry tables
Extract from existing augmented fields on products/items
New integration from original datasource for populating these new product inquiry tables.
Parse from product names/descriptions using pattern matching
Import from external systems (PLM, PIM, etc.)
Manual data entry for critical missing attributes
Default values for incomplete data
Migrate product content to copy sections for enhanced detail display

3. Configuration Changes¶

Flow Configuration¶

Update your flow configuration to use Product Inquiry. The flow is already defined in product-inquiry-flow.yml:

ProductInquiryFlow:
  - ProductInquiryState:
      Back: CompleteState
      Select:
        ProductDetailsState:
           AddFetchItem: { subflow: AddItemFlow, ReturnAction: ReturnFromAddFetchItem }
           AddItem: CompleteState
           AddItemToDeliveryOrder: CompleteState
           AddItemToPickupOrder: CompleteState
           AddItemToShipToStoreOrder: CompleteState
           AddItemToReturn: CompleteState
           PrintTicket: { subflow: MicroCapFlow, ReturnAction: ReturnPrintTicket, ConfigScope: { microCapId: 'ticketPrinting' } }
           Back: ProductInquiryState
           Scan: ProductInquiryState
           Exit: CompleteState

Button Configuration¶

By default, Product Inquiry is enabled from the SaleState by adding a button to the CTX_BUTTON table with action ProductInquiry. And by default, it is accessible from the HomeScreenState via the action ProductSearch.

# Example button configuration
"BUTTON_GROUP_ID","BUTTON_ID","EFFECTIVE_START_TIME","PARENT_BUTTON_ID","DISPLAY_ORDER","BUTTON_NAME","BUTTON_TYPE","BUTTON_VALUE",BUTTON_VARIANT,"DEFAULT_PAYLOAD","ENABLED","ICON_TYPE","PERMISSION_ID","ADDITIONAL_STYLE","EFFECTIVE_VERSION","EFFECTIVE_END_VERSION","ENABLE_IN_TRAINING_MODE","EFFECTIVE_END_TIME","TAG_COUNTRY","TAG_STATE","TAG_BUSINESS_UNIT_ID","TAG_STORE_TYPE","TAG_DEVICE_TYPE","TAG_BRAND","TAG_APP_ID"
"home","ProductSearch","2018-12-27 13:43:12.000000000",,"50","key:home:home.productSearch","action","ProductSearch",,,"1","search",,,,,"1",,"*","*","*","*","*","*",*
"sale.transaction.active","ProductInquiry","2018-12-27 13:43:09.000000000",,"10","key:sale:sale.transaction.active.productInquiry","action","ProductInquiry",,,"1","Search",,,,,"1",,"*","*","*","*","*","*","pos"
"sale.transaction.inactive","ProductInquiry","2018-12-27 13:43:09.000000000",,"10","key:sale:sale.transaction.inactive.productInquiry","action","ProductInquiry",,,"1","Search",,,,,"1",,"*","*","*","*","*","*","pos"

Application Properties¶

The following configurations are used by Product Inquiry:

# Search bar maximum length (used in ProductInquiryState)
openpos.itemSearch.searchBarMaxLength=22

# Maximum search results (used in ProductInquiryRepository)
openpos.item.maxSearchResults=10000

# Item option to UI component builder mapping (used in ProductDetailsState)
openpos.item.itemOptionToUIComponentBuilderName.color=productOptionSwatchPartBuilder
openpos.item.itemOptionToUIComponentBuilderName.size=basicProductOptionPartBuilder

# Orders configuration (used in ProductDetailsState)
openpos.orders.createOrders.enabled=true
openpos.orders.bispis.enabled=true
openpos.orders.shipToStore.enabled=true
openpos.orders.universalCart.enabled=false
openpos.orders.allowMultipleOrderTypesInTransaction=true

# Inventory display configuration
openpos.itemSearch.itemDetails.displayBuddyStoreInventoryInfo=false
openpos.itemSearch.itemDetails.displayBusinessUnitInventoryInfo=true

# Promotion types to display
openpos.itemSearch.itemDetails.promotionTypesDisplayed=ITEM_DISCOUNT,PRODUCT_DISCOUNT

# Returns configuration
openpos.returns.addItemUponFetchRequest=true

4. Flow Integration¶

Product Inquiry integrates with the sale flow as shown in sale-flow.yml:

SaleFlow:
  - SaleState:
      # Existing item inquiry
      ItemInquiry: { subflow: ItemInquiryFlow, ReturnAction: ItemInquiryFinished, ConfigScope: { itemActionGroupId: itemInquiry.sale } }
      # New product inquiry
      ProductInquiry: { subflow: ProductInquiryFlow, ReturnAction: ItemInquiryFinished, ConfigScope: { itemActionGroupId: itemInquiry.sale } }
      # Return to product inquiry from details
      ReturnToProductInquiryItem: { subflow: ProductInquiryFlow, ReturnAction: ItemInquiryFinished, ConfigScope: { itemActionGroupId: itemInquiry.sale } }

And from the home screen:

HomeScreenState:
  # Existing item search
  ItemSearch: { subflow: ItemInquiryFlow, ReturnAction: ItemInquiryFinished, ConfigScope: { itemActionGroupId: itemInquiry.sale } }
  # New product search
  ProductSearch: { subflow: ProductInquiryFlow, ReturnAction: ItemInquiryFinished, ConfigScope: { itemActionGroupId: itemInquiry.sale } }

5. Data Validation and Testing¶

Test Scenario Examples¶

Category Navigation: Verify hierarchical browsing works
Filter Application: Test attribute-based filtering
Search Integration: Ensure text search still functions
Product Selection: Confirm product selection flows work
Performance: Test with realistic data volumes

6. Rollback Plan Example¶

Preserve Item Inquiry¶

Keep Item Inquiry available during transition:

# Dual flow support during migration
ItemInquiryFlow:
  - ItemInquiryResultsState:
      # ... existing configuration

ProductInquiryFlow:
  - ProductInquiryState:
      # ... new configuration

Gradual Migration¶

Both flows can coexist during migration. Users can access both:¶

Item Inquiry via ItemInquiry or ItemSearch actions
Product Inquiry via ProductInquiry or ProductSearch actions

Migration Checklist (Actual implementation may find this redundant or may need more considerations)¶

Data Migration¶

[ ] Populate category hierarchy in ITM_INQ_CATEGORY
[ ] Map products to categories in ITM_INQ_CATEGORY_MEMBER
[ ] Define filterable attributes in ITM_INQ_ATTRIBUTE
[ ] Populate product attribute values in ITM_INQ_ATTRIBUTE_PRODUCT_VAL
[ ] Populate item attribute values in ITM_INQ_ATTRIBUTE_ITEM_VAL
[ ] Create product content sections in PRODUCT_COPY_SECTION
[ ] Add localized content in PRODUCT_COPY_SECTION_I18N for internationalization
[ ] Validate data integrity

Application Updates¶

[ ] Add ProductInquiry (for sale screen) and ProductSearch (for home screen) buttons to CTX_BUTTON table
[ ] Remove old ItemInquiry and ItemSearch buttons from this table
[ ] Configure application properties for search and display (can leave default until modifications are desired)
[ ] Add entries in i18n table for internationalizing product copy and attribute values