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.

3. Object Property Mapping

QSRCheck (Check Object)

• CheckNumber: Maps to NxCheck.checkNumber (Integer).

• PickupTime / ScheduledDeliveryTime: Maps to NxCheck.dueAt. Formatted as yyyy-MM-dd HH:mm:ss.

• Guest: Derived from seats[0].customerTenant. Falls back to seats[0].deliveryAddress (Contact) or nxCheck.name.

• Vehicle: Only the Vehicle.Model field is populated, pulling from the VEHICLE_TYPE order prompt.

• DeliveryPartnerInfo / OnlinePartnerInfo: Both fields receive identical payloads from NxCheck.onlineOrderData.brand and sourceOrderId.

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 ringSessionId within the item batch.

• DestinationID: Maps to OrderType.numericId. Defaults to 9999 if unresolved.

• Server ID/Name: Maps to EmployeeEntity.numericId and getName(). Defaults to 9999 and "ONLINE ORDER" for anonymous orders.

• Terminal: Maps to PosDevice.stationNumber. Defaults to 9999.

Item Object

• ItemNumber: The unique NxCheckItem.numericId within the check.

• ParentItemNumber: Set to 0 for top-level items; reflects the parent’s numericId for modifiers.

• ItemType: Evaluates to FoodItem (standard) or SideItem (modifier).

• ItemTrait: Maps NX PrepModifier.type to QSR traits: NormalItem, AddItem, CutItem, or SubstituteItem.

• IdealCookTimes: Maps to itemPreparationMinuteCount converted to seconds.

• Description: Maps to MenuItem.remoteName. If a keyboard prompt was used, it uses the guest-entered NxCheckItem.name.

Record Mapping

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, and Tender are all sent as dollar-formatted strings.

• Change: Calculated as paymentsAppliedTotal - total (sent only if > 0).

Table and Check Status

• Table Status: Uses PUT to update TableState (Opened, Dirtied, Cleared).

• Table Check Status: Uses PUT to update CheckState (Printed, Paid, ItemsOrdered).

5. Integration Configuration Fields

Stored in IntegrationEntity.configuration, keyed by QSR_AUTOMATIONS_ID.

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, and CustomValues are not supported and remain null.

• Vehicle Data: Make and Color are not supported; only Model is mapped.

• Course Metadata: CourseName and Comment are not currently mapped.