Technical Glossary: NX to QSR Automations Property Mapping
This document outlines the technical specifications, architecture, and property mapping for the integration between NX Restaurant and QSR Automations kitchen video systems.
1. Architecture and Communication
HTTP Connection (Retrofit)
NX communicates with QSR Automations via a local network HTTP connection using the Retrofit library. The integration is managed by the ThirdPartyKitchenManagerImplementation.
DualCall Functionality
Every API request is dispatched simultaneously to a primaryServerHost and an optional secondaryServerHost. The system runs these concurrently and awaits both results to ensure redundancy.
Tiers of Communication
Check Tier: Creates the check container via
POST /Site/{siteUID}/Pos/Checks.Course Tier: Delivers specific items within a check via
POST /Site/{siteUID}/Pos/Checks/{checkNumber}/Courses.
2. Interface Methods (KdsConfigInterfaceMethod)
The kdsInterfaceMethod setting determines the timing and lifecycle of data flow from NX to QSR.
| Method | Trigger | NX Technical Event |
|---|---|---|
| ON_THE_FLY | Items sent individually as they are rung. | ItemAction.POST_ITEM → itemPost / itemsAdd |
| ON_TOTAL | Items sent in a batch when the check is totaled (Default). | CheckAction.TOTAL_CHECK → coursePost → courseNew |
| ON_TENDER | Items sent only after payment is processed. | ItemAction.ON_TENDER → itemPost → itemsAdd |
3. Object Property Mapping
QSRCheck (Check Object)
CheckNumber: Maps to
NxCheck.checkNumber(Integer).PickupTime / ScheduledDeliveryTime: Maps to
NxCheck.dueAt. Formatted asyyyy-MM-dd HH:mm:ss.Guest: Derived from
seats[0].customerTenant. Falls back toseats[0].deliveryAddress(Contact) ornxCheck.name.Vehicle: Only the
Vehicle.Modelfield is populated, pulling from theVEHICLE_TYPEorder prompt.DeliveryPartnerInfo / OnlinePartnerInfo: Both fields receive identical payloads from
NxCheck.onlineOrderData.brandandsourceOrderId.
Course Object
In QSR, a "Course" represents an NX "Ring Session" (items sent to the kitchen at the same time).
CourseNumber: Derived from the maximum
ringSessionIdwithin the item batch.DestinationID: Maps to
OrderType.numericId. Defaults to9999if unresolved.Server ID/Name: Maps to
EmployeeEntity.numericIdandgetName(). Defaults to9999and "ONLINE ORDER" for anonymous orders.Terminal: Maps to
PosDevice.stationNumber. Defaults to9999.
Item Object
ItemNumber: The unique
NxCheckItem.numericIdwithin the check.ParentItemNumber: Set to
0for top-level items; reflects the parent’snumericIdfor modifiers.ItemType: Evaluates to
FoodItem(standard) orSideItem(modifier).ItemTrait: Maps NX
PrepModifier.typeto QSR traits:NormalItem,AddItem,CutItem, orSubstituteItem.IdealCookTimes: Maps to
itemPreparationMinuteCountconverted to seconds.Description: Maps to
MenuItem.remoteName. If a keyboard prompt was used, it uses the guest-enteredNxCheckItem.name.
Record Mapping
| NX Record | QSR Kitchen Record |
| Order Type ID | Destination |
| Routing Category ID | Department |
| Item ID | Menu Item ID |
| Item Number | Check Item ID |
| Parent Item Number | Parent Check Item ID (when applicable) |
| Employee ID | Server ID |
| POS Device Station # | Terminal ID |
4. Payment and State Management
PaymentState Object
Dispatched during TOTAL_CHECK and TENDER_CHECK events.
PaymentState: Returns "Totaled" if a balance remains, or "Tendered" if the check is fully paid.
Totals:
SubTotal,Tax,Total, andTenderare all sent as dollar-formatted strings.Change: Calculated as
paymentsAppliedTotal - total(sent only if > 0).
Table and Check Status
Table Status: Uses
PUTto updateTableState(Opened, Dirtied, Cleared).Table Check Status: Uses
PUTto updateCheckState(Printed, Paid, ItemsOrdered).
5. Integration Configuration Fields
Stored in IntegrationEntity.configuration, keyed by QSR_AUTOMATIONS_ID.
| Field | Type | Default | Purpose |
|---|---|---|---|
primaryServerHost | String? | null | Primary QSR server IP/Hostname. |
secondaryServerHost | String? | null | Redundant QSR server IP/Hostname. |
serverPort | String? | "32768" | TCP port for server communication. |
kdsInterfaceMethod | String? | "ON_TOTAL" | Controls timing of item firing. |
6. Technical Limitations and Hardcoded Values
Sentinel Value (9999): Used for any missing numeric identifiers (Server, Terminal, Routing Group, etc.).
Unmapped Guest Fields:
FoodAllergies,LoyaltyCardID, andCustomValuesare not supported and remain null.Vehicle Data:
MakeandColorare not supported; onlyModelis mapped.Course Metadata:
CourseNameandCommentare not currently mapped.