Request of data is about the way to get data from Retail3000 in an efficient and high-performance way. This is a very important chapter, lots of API integrations are initially built incorrect, resulting into a waste of server resources and disruption of the Retail3000 systems. Such integrations reqest the same data over and over again, sometimes even on a high frequency.

In general, data should be requested based on changes since a certain date & time. For small tables it's not a big issue requesting them once a day for example. Larger tables (let's say 1000 records or more) should be requested based on a timestamp. This chapter is split into requesting data with and without timestamp support. NedFox is extending more and more 'Get' requests with timestamp support. If a large table needs to be requested while it's not having timestamp support, please contact us so we can prioritize the extension of that table.

Tables with timestamp request support

The tables with timestamp support can be recognized by a filter property 'ModifiedSinceDateTime'. In most circumstances this is part of a filter object, but there are situation where it's just a parameter in the 'Get' method. We are working to make this more consistent.

1. There should be a local saved last synchronization date/time. If this is the first synchronization, use 1/1/1900 as last synchronization date/time.

2. First request the server date & time, by using GetServerDateTime() from GeneralComponents.asmx. Save that time in memory for later use.

3. Now request the data by using some 'Get' request since the previous local saved date&time.

4. When the data retrieval was succesfull, save the received server date & time from 2 as last succesfull synchonization date/time.

In general, large tables will have 'offset' support. This kind of functionality makes it possible to iterate through the data in smaller batches. In that case you have to iterate untill no data or less data is being retrieved as requested. This implementation can be recognized by a 'MaxRecords' and an 'Offset' property. The 'Offset' property is 'zero based' and can be used to request a starting point of the data to be received. Because it's zero-based, the first request should have an offset of 0. For MaxRecords we advice to use a value between 5.000 and 10.000. Don't set it lower, it will result into more requests to be processed and thus higher use of our valuable resources. In most circumstances the 'Offset' and 'Maxrecords' properties are separate properties of the 'Get' method but there are situations where these properties are part of a filter object. Again, we are working to make this more consistent. The steps above are adjusted below to demonstrate that implementation.

1. There should be a local saved last synchronization date/time. If this is the first synchronization, use 1/1/1900 as last synchronization date/time.

2. First request the server date & time, by using GetServerDateTime() from GeneralComponents.asmx. Save that time in memory for later use.

3. Now request the data from offset 0 by 10.000 records by using some 'Get' request since the previous local saved date&time.

4. When the number of retrieved rows is less as the requested number of records (maxRecords, 10.000) there is no more data available. In that case go to step 6.

5. Process the received data and increment the offset by the number of maxRecords, 10.000 in this example. Now go to step 3 again.

6. When the data retrieval was succesfull, save the received server date & time from 2 as last succesfull synchonization date/time.

Tables without timestamp request support

As mentioned earlier, please only use this for small tables. In case of large tables without a ModifiedSinceDateTime get property, please contact us so we can extend that table! Don't start using it because it will result into large amounts of traffic and customer costs.

If the table is small, just use a 'Get' statement to retrieve all records. Small tables won't have many changes, so it's not useufll to synchronize very often. Our advice is to sync once a day or even a longer interval.

Retail3000 primary keys

To be able to update the changed Retail3000 records in a satellite system, it's advised to save the Retail3000 primary key in the local system record. This key is always named 'ItemId'. A local field like 'Tag' is normally used to save such information, but off course the name is free to choose. This property is needed to find a local record in case of changes in Retail3000. Also when a record is deleted in Retail3000, this property can be used to find the local record and delete is also.