About IDs and numbers

Most entities you will find in the Retail3000 API are representations of tables in our database. Every entity backed by a table will contain an ItemId property. This is the primary key field of that entity and is unique within the entire instance. The ItemId is also used for references in other tables or so called foreign keys. Because this is an automatically populated field it is guaranteed to be unique. The ItemId is a good property to use when keeping data in sync between your application and RetailVista and can be used in various internal processes. Do keep in mind that it is bad design to rely on the actual value too much. 

To explain this, just an example: An ItemId 345 on a production system representing a certain brand does not necessarily have the same ItemId of that same brand on a test environment. Another example is when a product with barcode 12345 and ItemId 100 is deleted and recreated again it will become a different (new) ItemId. Never ‘hard code’ ItemId’s or assume they are predictable because they’re absolutely not.

Besides the ItemId there are a few other common properties that can be found on a lot of entities. Often a number or code is used to identify data, these are more user oriented record identification properties. ItemId's are never visible to users, codes and numbers are. Examples are productnumbers, customernumbers, brand codes and salegroup codes. Numbers are not related to ItemId’s in any way although they are usually auto incrementing. When communicating with end-users or NedFox about data it is important to distinguish numbers from ItemId’s. Some program flows like the authentication sequence expect numbers while others like updating or retrieving single entities expect the ItemId of the entity. The properties are pretty self describing, so a propertyname ending with 'ItemId' will expect an Id value and not a number of code.

Besides the ItemId you will see many other <Prefix>Id properties in the various entities. A rule of thumb within the Retail3000 API is that any property ending it’s name with Id is a reference to an entity named like the prefix plus 'Info'. BrandId refers to the entity BrandInfo, SaleTypeId to SaleTypeInfo. 

Some exceptions can occur due to naming conflicts or because we like to name our properties in a self-describing way. Good examples of these are two other properties of frequent occurrence, CreatedByUserId and LastModifiedByUserId. These both refer to the Users table and corresponding UserInfo entity. Because there are two references to Users a single UserId is not sufficient and a distinction must be made.