Setting Up Menu Sync for a Store

Before an invoice can reference a product, that product must exist in the Chrilan catalog. The middleware automates this: it pulls menu items and tax definitions from Oracle Simphony and pushes them to Chrilan. This guide shows how to enable it for a store.

What menu sync does (in brief)

Every 60 seconds, the scheduler loads all active stores with menu sync enabled.
For each store, it fetches the full menu from the Oracle STS API (with automatic pagination).
It also fetches tax classes and tax rates so each item gets the correct ZRA VAT category.
Items are converted to Chrilan products (PLU, name, price, VAT category, department) and pushed in bulk via POST /product/createBulk.
Everything is logged: totals, converted, skipped.

For the full technical detail see Platform: Menu Synchronization.

Prerequisites

Requirement	Notes
Store registered and active	See Managing stores
Chrilan API key saved on the store	Products are pushed under this key
Correct Oracle menu path	See below — this is where most setups go wrong
Menu sync enabled globally	`menu-sync.enabled=true` on the server (default)

The Oracle menu path

The menu path tells Oracle which location's menu to fetch. It has three parts:

{OrgShortName}:{LocationRef}:{RevenueCenterRef}

Example: PCK:PCK_3103:101

Component	Example	Notes
OrgShortName	`PCK`	Organization short name in Oracle Simphony
LocationRef	`PCK_3103`	Must be the exact Oracle Simphony location reference — not an internal store code
RevenueCenterRef	`101`	Revenue center within the location

Common failure Using an internal store code such as PED001 instead of the real Oracle LocRef (PCK_3103) causes Oracle to return HTTP 403. Always confirm the LocRef with the Oracle Simphony administrator.

Enabling sync for a store

Open the store in the portal (Stores → Edit).
Set the Oracle menu path (e.g. PCK:PCK_3103:101).
Set the default department if it differs from the standard 50203301.
Tick Menu sync enabled and save.
Within a minute, the scheduler will pick the store up. Check Reports for the outbound /product/createBulk call to confirm.

What gets synced for each item

Chrilan field	Source
`plu`	Oracle `menuItemId`
`name`	Oracle item name
`sellingIncl`	Price at `priceSequence == 1` (the dine-in / standard price level)
`vatCat`	Resolved from the item's Oracle tax class: `STANDARD_RATED`, `ZERO_RATED_BY_NATURE` or `EXEMPT`
`department`	The store's default department (default `50203301`)
`countryOfOrigin`	`ZM`
`type`	`singleItem`

Which price is used?

Oracle menu items can have several price levels (e.g. “St Down”, “Takeaway”, “Yango”). The middleware uses priceSequence == 1 — the dine-in/standard price — as the fiscal reference price. Items with no sequence-1 price sync with price 0 (they are not skipped).

Which VAT category?

Tax definitions are fetched live from Oracle. In short: an active rate above 0% → STANDARD_RATED; a 0% rate → ZERO_RATED_BY_NATURE; a disabled/absent rate → EXEMPT. If the tax fetch fails, items fall back to STANDARD_RATED (safe default for PCK, whose entire menu is 16% VAT).

Verifying it works

In Reports, find the periodic /product/createBulk transactions for the store and confirm success.
Add a new item in Oracle Simphony, wait ~1 minute, then confirm it can be sold (invoices referencing its PLU succeed).
Skipped items (no PLU or no name) are counted in the sync summary logs.