RetailConfig

The API /OpenApi/RetailConfig provides semi static information about the retailer and options they have set.

The API /OpenApi/RetailConfig/Dynamic provides more dynamic information, such as when data was last changed.

Both of these APIs return caching headers so that highly frequent polling is done from cache or CDN. The cache timers may change to be longer overnight when the retailer is known not to be trading

Retail Config Dynamic

The response to /OpenApi/RetailConfig/Dynamic includes, among other things, two arrays of equal size, RVE and RowCount. Tables are allocated fixed indexes in these arrays.

The RVE array contains the last date/time UTC this table was changed. (more on RVE values).

The RowCount array contains a realistic estimate of the total number of rows. It should be correct but may sometimes suffer from minor drift. Detecting changes using RowCount alone is not reliable as rows may be added and deleted, and still have the same RowCount. We recommend not using RowCount as the truth, but an indicative value.

An RVE value of zero typically means "I don't know at this time'". This API call is highly optimised to be frequently called, and as such does not pause to load or check anything on the server, it simply displays the current state.

The term "table" is used loosely, a table in the RVE array may be a combination of tables. The RVE for a table may be changed if a subtable was editted as well. For example, changes to the physical table products1 will change the RVE for products in /RetailConfig/Dynamic rather than sending a seperate table entry. What this practically means is that RVE values may change but you might not see what changed if you query the table - the change is there but your request doesn't always see it.

"RetailConfigDynamic": {
  "RVE": [ 20210101.233456, 20210722.141526, 20181224.190156 ],
  "RowCount": [ 645181, 19203, 17 ]
}

This packet means

• The table Products (entry 0) was last changed at 20210101.233456 or 1-jan-2021 23:34:56 UTC and currently has 645181 rows


• The table Suppliers (entry 1) was last changed at 20210722.141526 or 22-oct-2021 14:15:26 UTC and currently has 19203 rows

The arrays RVE and RowCount will not return trailing zero entries. A shorter table than you expect means the value in the index you are wanting is currently ZERO.

RVE Array Index Values

Index	Purpose	When RVE Changes
0	Products
1	Suppliers
2	Departments, including secondary department groups
3	Customers
4	Accounts
10	R_PaymentTypes
12	ProductKits
13	Pricemaps
15	Locations
23	Slow Changing Reference Data. A catchall for several tables that rarely change
24	Tracked Items
25	Product Manufacturing
28	Sales Picking	Any API Sale is received in Picking state Any Picking sale is completed or voided Any picking sale is altered, including items picked, comments added etc

How to Use Dynamic Config

The Dynamic Config result provides a simple overview of the state of large portions of the retailers system. If the RVE for an area does not change between calls, then nothing has changed server side. If the RVE has increased, then something, potentially related to that area has changed. There is no indication what has changed, and false positives may sometimes occur.

The RVE values mean that a remote app can request dynamic config within a polling loop to determine if anything has changed:

var LastCustomersRVE = 0;

PollCustomerChanges() {
    fetch('/OpenApi/RetailConfig/Dynamic', {
        method: 'get',
        headers: {
            'x-api-key': Your API Key
        }
    }).then(function (resp) {
        return resp.json();
    }).then(function (dynamic) {
        let NeedPoll = false;
        
        if (dynamic.RVE.length > 3) {
            if (dynamic.RVE[3] > LastCustomersRVE) NeedPoll = true;
            if (dynamic.RVE[3] < 1) NeedPoll = true;                // Handle "no idea" from server and poll anyway
        } else NeedPoll = true;                                     // Hmmm, no data, lets poll anyway

        if (! NeedPoll) {                                           // Recommended.  Poll periodically regardless
            if (TimeSinceLastPoll > SomeLongConstant) NeedPoll = true;
        }

        if (NeedPoll) {
            ....
        }
    }
}

As Dynamic Config result contains short term browser caching settings, you can fetch the object frequently and it will only incur network traffic sometimes.

An eCommerce website may find index 28 (SalesPicking) of particular use to check the status of its sales. This RVE will change when any change to the list of picking sales is detected. If you are checking to see when sales are completed by the store, this RVE can save you checking all sales every poll time. Check to see if the RVE has changed, if not then skip polling

Internals

Dynamic config is implemented in Fieldpine in the following way

• The server maintains a shared memory structure for the retailer with all the values
• Server Apps (Fieldpine uses a micro service style design) update the values if they potentially affect an area
• When a request for DynamicConfig is received, the HTTP agent simply grabs the shared memory and returns that result
• The resulting HTTP response may be sent with varying cache durations depending on circumstances
  • If you are polling at 2am, and the retailer is a 9 to 5 type operation, a longer cache time is sent
  • If activity has been detected outside normal hours, shorter times may be sent. eg. Your eCommerce site is recording hits at 11pm
  • Times vary by size of retailer