The HDPH to Monday.com synchronization engine (often referred to as the "Consolidated Brain") is the core system responsible for keeping your order data perfectly aligned. It fetches the latest order details from HDPH, compares them against your existing Monday.com subitems, and automatically applies the necessary updates, classifications, and status changes.
This guide explains how the synchronization engine works, the required inputs, and how it classifies your order data.
Performance Upgrade: The service classification step was recently upgraded from an AI-based model to a deterministic matching engine. This makes the sync significantly faster and 100% predictable based on line-item names.
How the Sync Engine Works
The synchronization process runs in a single, consolidated step that performs five distinct stages to ensure Monday.com perfectly reflects the HDPH order.
flowchart TD
A["Start Sync Engine"] --> B["1. Fetch Monday Subitems"]
B --> C["2. Fetch HDPH Order Data"]
C --> D["3. Classify Services"]
D --> E["4. Update Monday Flags"]
E --> F["5. Compute Diffs & Title Codes"]
F --> G["Output Sync Results"]- 1
Fetch Current Monday.com Subitems
The engine first queries Monday.com using GraphQL to retrieve all existing subitems for the target order. It collects their Pulse IDs and Product IDs to establish a baseline of what is currently on the board.
- 2
Fetch Latest HDPH Order Data
Next, it securely connects to the HDPH API to pull the most recent line items, product names, and pricing associated with the order.
- 3
Classify Services
The engine scans the names of the products ordered and automatically categorizes them into specific service buckets (like Rush, Appraisal, or Matterport) based on keyword matching.
- 4
Update Monday.com Flags
Before processing individual line items, the engine updates the main Monday.com item. It sets the status to Synced and updates the specific service columns (e.g., marking the "Rush" or "Measurement" columns).
- 5
Compute Diffs and Title Codes
Finally, the engine compares the HDPH source data against the Monday.com baseline. It calculates exactly which subitems need to be added, removed, or updated. It also generates shorthand "Title Codes" and detects if any Stock Neighborhood Amenities were ordered.
Required Inputs
To run successfully, the sync engine requires specific data points to be mapped from your previous steps.
| Input Variable | Description |
|---|---|
mondayApiToken | Your Monday.com API token (usually mapped to a system variable). |
hdphApiKey | Your HDPH Read-Only API key. |
itemId | The Monday.com Pulse ID for the main order item. |
orderName | The unique HDPH Order Name/ID used to fetch order details. |
currentNAStatus | The current status of the Neighborhood Amenities column in Monday.com. |
Ensure your API keys have the correct permissions. The Monday.com token requires both read and write access to update column values and subitems.
Service Classification Rules
During Stage 3, the engine scans the combined text of all ordered product names. It uses the following keyword rules to classify services and update Monday.com columns:
| Service Category | Trigger Keywords (case-insensitive) | Resulting Status |
|---|---|---|
| Travel | travel fees | "Travel" |
| Appraisal | appraisal | "Appraisal" |
| Matterport | matterport | "Matterport" |
| Rush | same day rush, cp-rush | "Rush" |
| Rush (Morning) | morning rush | "AMRush" |
| Amenities | amenit | "Yes" |
| Measurement | measurement, inspection | "Yes" |
(If no Rush keywords are found, the Rush status defaults to "Standard". If no Amenities or Measurement keywords are found, they default to "No".)
Advanced Processing Features
The Title Code Engine & Swallow Rules
To keep order titles clean and scannable, the engine translates long product names into short codes (e.g., "Detailed Measurement & Photography" becomes M/P).
To prevent redundant codes from cluttering the title, the engine applies Swallow Rules. For example, if an "Essentials" package (ES) is ordered, it automatically "swallows" the individual codes for Measurement (M), Photography (P), and Marketing Kit (MK), outputting only ES.
The Diff Engine (Add / Remove / Update)
Because HDPH is the source of truth, the engine counts the exact number of each product type in the HDPH order and compares it to Monday.com.
Excess items in Monday.com are flagged for removal.
Missing items are flagged to be added.
Matching items are flagged for an update to ensure pricing and names are perfectly synced.
Stock Amenity Detection
The engine specifically looks for "Stock Neighborhood Amenities". It checks against known Product IDs (like 245474 and 314325) and exact name matches. If detected, it prepares a flag to change the Monday.com Amenities status specifically to "Stock".
Next Steps: Once the Consolidated Brain finishes running, it outputs a comprehensive JSON payload. You must map this payload to your subsequent write steps (like Step 11) to actually execute the subitem creations, deletions, and Title Code updates in Monday.com.