SPIKE: ENG-545 - Eclipse E4 Pricing Data Extraction

2026-07-20 update: this spike only evaluated the SOAP API surface. dbo.MaterialUnitCost — a real quantity-break price table, readable via the same direct-SQL path used for every other Eclipse E4 entity — was missed. Confirmed readable with a personal Kerberos identity; production ordermatic_svc service-account access remains blocked pending the required SELECT grant (ENG-548). (dbo.CustomerPricing was the first guess and turned out to be a dead end — a per-customer markup/discount override table, not a price list.) See the “Update 2026-07-20” section in debt/backlog/eclipse-e4-pricing-api-plan.md before acting on the SOAP-based conclusion below.

Overview

Currently, VMS ERP (Eclipse E4 / EPMS Connect) is the only ERP integration with priceLevels: 0. This completely disables ERP-side price validation for VMS quotes, forcing a fallback to whatever was extracted from the document. The goal of this spike is to evaluate options for extracting pricing data from Eclipse E4 to enable proper price validation.

Findings from EPMS Connect API Documentation

A review of the EPMS Connect.docx API documentation reveals a few potential vectors for retrieving pricing data via the SOAP web service.

1. The GetTemplateList Endpoint (Recommended)

This endpoint is designed to return a list of “Templates” (which correspond to items/catalogs in EPMS terminology) for a given Customer Account.

Request:

• CustAccount (Customer ID)
• SendBlanks (Boolean)

Response (GetTemplateListResult): Returns a list of Template nodes containing:

• TemplateCode (The MaterialCode/SKU)
• Description
• Quantity
• ManualPrice

Pros:

• Returns data contextually tied to a CustAccount, which is ideal for customer-specific price tiers/catalogs.
• Requires no new API development on the VMS side.
• Fits naturally into the Ordermatic synchronization pipeline (syncing price tiers per customer).

Cons:

• Only returns items set up as templates. If a customer orders an ad-hoc material not mapped as a template, it will not appear here.

2. The GetComponentInfo Endpoint

This endpoint provides information about components on an existing Job/Estimate.

Request:

• JobType
• KeyNumber (Job or Estimate Number)

Response: Returns ComponentInfo including ComponentQuantity nodes that have Quantity and Price elements.

Pros:

• Shows the actual unit prices returned by the ERP’s internal estimator/pricing engine.

Cons:

• Requires creating an Estimate first. This makes it useless for pre-submission catalog price validation.

3. Inventory Query Endpoint (GetInventoryStatus)

Currently used in searchItem().

Pros:

• Already implemented to validate item existence.

Cons:

• Only returns inventory numbers (QuantityOnHand, QuantityOnOrder, etc.). It does not return any price data whatsoever.

Proposed Architecture / Solution

To give Eclipse E4 parity with other connection types regarding ERP-side price validation, we should implement a Customer-Tier Price List Sync utilizing the GetTemplateList endpoint.

Implementation Steps

1. Service Capability Update Update EclipseE4Service.getCapabilities() to return priceLevels: 1 (or whatever the standard is for enabling customer-specific tiers) once the synchronization is implemented.

2. Customer Catalog Synchronization Create a cron/sync job or hook into the existing price list sync pipeline to call GetTemplateList(CustAccount) for all active E4 customers.

   • Extract the TemplateCode as the erpItemId
   • Extract ManualPrice as the unitPrice
   • Upsert these records into the Ordermatic pricing database associated with that customer.

3. Fallback Considerations Because GetTemplateList might not return a comprehensive list of all possible database materials (only active templates for the customer), the auto-validate fallback (recently implemented in b8d8f3e) will remain critical. If an item price is not found in the synced Template list, it should fall back to the PO price while flagging an info/warning that the item lacks a defined price in the VMS customer catalog.

4. Future-proofing: Real-time Pricing If VMS needs realtime pricing validation without syncing, a heavier lift would be creating a “Dummy Estimate” using ConvertEstimateToOrder (or an equivalent Estimate creation method if exposed) and then calling GetComponentInfo to read the prices back. This is generally an anti-pattern due to API latency and side-effects, so the offline sync via GetTemplateList is highly preferred.

Conclusion

The quickest and most architecturally sound path to resolving ENG-545 is to utilize the GetTemplateList SOAP action as a customer-specific price catalog export. This aligns with Ordermatic’s existing price validation models and provides a reliable baseline for VMS quotes.