This document describes how to configure the following specific settings of the Openbravo omnichannel platform:
- Enterprise model
- Store pricing
- Cash Management
- Web POS
For generic documentation about Openbravo configuration please follow the Quick Guide.
If you are trying out Openbravo omnichannel platform for the first time, you MUST first execute all of the Business Setup configuration instructions in the Quick Guide before executing the configuration instructions below.
Installing the Openbravo for Retail module
The Openbravo for Retail module is the main module of the Openbravo Commerce Cloud. To install the module (an Openbravo Subscription to either Enterprise or Professional Edition is required since it is a commercial module, read more about Retail License):
- Login as System Administrator
- Navigate to General Setup -> Application -> Module Management
- Click the Add Modules tab
- Find the Openbravo for Retail module within the list of available modules.
- Click on Install Now and follow the guided installation flow.
Add Retail Stores to the Organization Model
In Openbravo an organization is a business unit within an entity (company). Each entity can have more than one business unit to cover different zones, areas, region, stores... Openbravo allows the definition of a hierarchical structure of organizations where a parent-child relationship between them can be determined. The result is a n-level organization tree, as follows:
This structure is flexible enough to support any further organizational change and may have unlimited levels, branches and nodes at each level as the situation may demand.
In Organization window there is new group of fields called Retail Configuration. There you can find Retail Organization Type field where you define whether an organization is a store or a group of stores:
- Represents a physical retail store
- Only leaf organizations should be configured as store type
- The POS terminals set up in Openbravo shall be restricted to stores
- Must have an Anonymous Customer (Business Partner defined as Customer, with a default payment method)
- Must have an Anonymous Customer Location
- Must have at least one on-hand warehouse defined in the "Warehouses" tab
- The currency defined is the currency that will be used in all terminals of this store. The currency used can be edited to define retail configurations like the precision used in Web POS terminals.
- Represents a grouping of stores (or other groups)
- Document type for Orders: The document type used for sales orders.
- Document type for returns: The document type for returned receipts
- Document type for reconciliations: The document type used for the reconciliations done when executing the "Cash up" process in the POS
- Document type for quotations: The document type for quotations
Store Pricing Configuration
Item pricing can be managed by store or store group. This allows the retailer to manage multiple pricing for a single item.
In Organization window there is a 'Price List' field inside Retail Configuration group. Any node of the enterprise model (either group or store) can have a sales price list assigned.
Pricing management rules:
- Prices defined at store level will always overwrite the prices defined at parent level
- If the store does not have any attached price list, the price will be inherited from the parent element (store group) in the organizational structure
In the following example all stores located on Zone 1 will use the prices defined at Zone 1 level, except the Store 11, that is going to have its own price list.
Before RMP19, only price lists which included the tax were supported. Starting RMP19, pricelists without including taxes are also supported in Retail.
In case a pricelist without taxes is used, the prices shown in the receipt lines will be net prices, and an additional line which includes the total tax will be shown. The total amount of the receipt will still be the gross amount.
Numerical Precision Configuration
The Web POS only supports one single precision, and by default uses the Price Precision of the currency it is working on both for its pricing precision, and for the general precision for all internal calculations. Sometimes, it's necessary when operating the backoffice to define a different Price Precision than the Standard precision, and sometimes this price precision would be wrong in the Web POS. For these cases, the POS Precision column in the currency window exists.
This POS precision prevails against every other precision, so if it is defined, then it is used both for price precision and other calculations. If it's not defined, then the Price Precision is used instead.
Assortment management allows the retailer to determine the product range that will be made available for sale at various stores.
A new window Assortment is created to provide a new grouping for products.
The window has two processes (buttons) for common operations dealing with assortment:
- Clone: New button is displayed in the toolbar. It will create a copy (clone) of the selected assortment. Newly created assortment is opened in form view in order to let the user modify it if required
- Include all products: The user will be able to include all products at once in the assortment by using this button. Duplicated products in the same assortment are not allowed
Organization window has a new optional field Assortment inside Retail Configuration section. Any node of the enterprise model (either group or store) can have an assortment assigned.
Assortment management rules:
- If a store has an attached assortment, it can only trade with products defined inside the assortment
- Assortment defined at store level will always overwrite assortment defined at parent level
- If the store does not have any attached assortment, the assortment will be inherited from the parent element (store group) in the organizational structure
- Only products included in the assortment and have a price defined in the price list assigned to the store will be available to sell.
- Starting with RR17Q3, products with attributes are supported in Openbravo Retail. Previous versions only supported products with attributes if they were not mandatory.
Assortment At POS Terminal Type Level Configuration
On 3.0RR18Q3 and previous releases, the only option to set the assortment of products for WebPOS was to define it at Store level (Organization window in the ERP). With this new development, the assortment of products for WebPOS could be defined also at POS Terminal Type level (POS Terminal Type window in the ERP).
WebPOS always needs an assortment of products to be loaded. To get the assorment, WebPOS terminal will look first if there is an assorment at POS Terminal Type level, and, in case it's not defined or set, it will look for the assortment set at Organization level.
Category Tree Configuration
Select menu option: Application / Master Data Management / Product setup / Product Category. Push button to show Tree Grid Visibilty.
- Create new categories as necesary
- Modify a category tree
- Add products to a new categories
Remember: For a category can have children check Summary Level
Cash Management Events
A cash management event is either a cash deposit or withdrawal in the store, but also the process of cashing up. A store can have several cash management events and they are configured differently depending on the nature of the event (in, out, close).
These events are managed in WebPOS and need to be defined in tab Cash Management Event in Organization window.
For each event you need to define the following:
- Name: Name of the event. In "in/out" event type, the name can be seen as the event reason shown in WebPOS to allow the cashier give more detail of the operation (e.g it can be different reasons for withdrawing money from the store, for instance the cash security level is reached in the store, or we need to transfer money from one store to another)
- Currency: Currency of the event
- Payment Method: Payment method associated to this event. In case of cash up, it is necessary to create as different close events as different payment methods are supported in the store
- Event Type: In, out, close depending on the nature of the event
- Financial Account: The account which will be the destination (or the origin) of the cash movement and it depends again on the nature of the event. For in case, it is the financial account from where money is going to be extracted (origin). For out case, it is the financial account from where money is injected (destination). Finally, for close it is the financial account where money is also going to be injected (destination). Be careful, do not use the same financial account in payment types (payments allowed for a POS Terminal) and for "close" Financial Accounts. Moreover, it is recommended to use a different financial account in payments allowed for a POS Terminal and for the "cash management" events.
Limit for approvals for count differences in initial cash count and cash up
Approval system enhancement for cash up and initial count processes, adding the possibility of specifying differences limits for each payment method before asking for an approval.
Global Count Difference Limit
Navigate to Organization window and select a organization to configure. On section Retail Configuration set Count Difference Limit, as shown on following figure:
Count Difference Limit for the payment methods
Navigate to POS Terminal Type window and select a item to configure, in tab Payment Method select a item to configure. On section Cash Up set Count Difference Limit and on section Cash Management set Initial Count Difference Limit, as shown on following figure:
Note: Before to 3.0RR16Q2, null value in this field is the same as the value 0: the approval always is required when there is a difference amount. From 3.0RR16Q2 the behavior has changed: if the field is null, then never the approval is required, if the value is 0 and there is a difference amount, the approval is required.
Navigate to POS Approval Reason window and edit/add the reasons, as shown on following figure:
Customers default configuration
The are some fields we must fill if we want to create new customers in Web POS. These fields will be the default value for customers created in our terminal.
- Default invoice term for BPs
- Default payment term for BPs
- Default BP Category for BPs
- Default country for BPs
- Default organization term for BPs
- Show Tax ID for BPs Edition: If checked, this option will show an extra field to insert the Tax ID.
- Show BP Category selector for BPs edition: If checked, this option will show an extra field to select the BP category.
The following preferences have been created:
- OBPOS_retail.disableNewBPButton, used in WebPOS to disable the New Customer button until a search is performed.
- OBPOS_retail.customer_advanced_filters, used in WebPOS to grant/deny access to the Advanced Filters window on the Customer Search popup.
- OBPOS_FilterAlwaysBPByAddress, used in WebPOS to enable/disable in the filter of business partner always use the location.
- OBPOS_NotAllowEditCustomer, used in WebPOS to allow or not to modify an anonymous customer or its adress(es).
By default, all of the products are grouped in Web POS. It means that when a line representing a product is already in the ticket and more units are added, the line will change the quantity without creating new lines.
If you want to create a new line for each product, "Grouped product" field should be disabled.
This field is located in the header of the product window.
Not grouped products will generate new lines when they are added to the ticket through "Browse", "Search", "Scan". When they are added to the ticket we will be able to change the quantity of each line.
Non Returnable Products
By default all of the products are returnables in Web POS. It means that it will always be possible to return them. However, in some cases this should not be the rule and in this field you can deactivate this functionality. It is also possible to fill the value of Overdue Return Days in order to set a maximum period of time to return an item.
This field is located in the header of the product window.
The following pop-up will rise when trying to return a non returnable product as a return line:
The following pop-up will rise when trying to return a non returnable product using verifying returns:
From 18Q3 is possible to configure the PLM (Product Lifecycle Management) Status of the products. This status affects to critical flows in which the products are used. Up to now, in the Web POS the only affected flow is the process of selling them. In the next link is possible to find more information and the different status of the PLM Status:
Configure the PLM Status
The products status is configured directly in the Product window. There, there's a selector to set the current status to it:
It is also possible to open the status list in a selector, to see which is the impact of each one:
Here the user can see how a status affect to the different flows. The selector is not modifiable, is read only.
PLM Status in the Assortment
The PLM Status can also be configured in the Assortment window, in the Product tab of the window. Any configuration done here overrides the configuration set in the Product window, affecting only in the organization for which the assortment is configured. This allows to have a different status for a product in each store. The products that are not configured in the assortment will use the status of the product.
The PLM Status can also be shown with the selector popup, as in the Product window.
Enable cross store for a product
Cross store is an utility which allow us to see the detailed stock by bin in our store and also the stock of the product in other warehouses of the organization.
To see the stock detail view the field Show stock screen shuold be checked in the product window.
In this example we will activate the stock screen for the product Base camp duffel 70L
It exists the possibility to define which warehouses are going to be part of “Cross Channel Warehouse”.
Definition is done in window “Organization” using “Cross Channel Warehouse” tab and adding the warehouses using button “CC Warehouse”. This warehouses are warehouses not defined as Warehouses on Hand of the Store, and defining them in this tab it will be possible to check the Stock of products in those warehouses from Web POS for the configured Stores.
Apart from that using the field “Included Warehouses” in the organization it is possible to define different logics:
-All excluding defined: Web POS will propose all the warehouses defined in the system except which ones defined as On Hand
-Only those defined: Web POS will propose you only the stock of defined warehouses
After this configuration, Web POS will open the stock window when a product is clicked in order to be added to the ticket.
By default, the product images are automatically loaded into the browser local database, so they can be used offline in a convenient way. However, the browser local database has a maximum size limitation in all environments, and in some of them this maximum size can be quite restrictive (specifically, in iOS, the maximum size is restricted to 50 MB).
If this maximum size is not enough for your needs, you can configure the Web POS so that it doesn't save the images into the local database, and instead requests them directly to the server.
The slight downside to using this method is that in when the POS goes offline, images for previously used products will be available, but the images for products not yet used will not (the generic 'box' image will be shown instead). If this downside is not relevant for you, then you can definitely use this method to make it possible to use big amounts of products with images in devices such as the iPad
How to configure the alternate way to load images
The first step to configure this alternate way to load images is to create a preference in the system, with property Web POS Product Images from server instead of cache, and with value Y.
This preference will tell the Web POS that it needs to load images from the server directly, instead of loading them from the local database.
To improve the performance of this functionality, and ensure that the server is not overloaded with the image requests, the images are read directly from files in the server, instead of the database. This means that image files need to be generated from the product images in the database. To do this, a process called Generate Product Images needs to be run.
This process receives an assortment as a parameter, and will generate files for all products in the assortment which contain an image. After this process has been run, the Web POS terminals should be able to load all product images without trouble.
This new functionality provides the functionality to allow or deny the creation of layaways for the anonymous customer of the store/terminal (the anonymous customer is defined either on the POS Terminal window or on the Organization window; the value on POS Terminal window, if it exists, will override the value on Organization window).
Navigate to the Organization window and check Allow anonymous customer layaway if you want to allow the creation of layaways for the anonymous customer.
Allow to void Layaways partially paid
This new feature provides the ability to configure the store to allow/deny the layaway voiding process if these have some associated payment.
Navigate to the Organization window and check Allow partially paid layaways to be voided if you want to allow the voiding of layaways when there are related payments.
Currency Exchange Rate at Store Level
This new feature provides the ability to configure currency exchange rates at Store level. Currently Openbravo only allows to define currency exchange rates at * level. With this feature, if any exchange rate is defined for an store, the one defined at * level will be overwritten.
Navigate to the Organization window and open Conversion Rates tab. Notice that the tab only will be displayed if the selected organization type is Retail Store.In this window it will be possible to define information:
- To Currenty
- Valid From Date
- Valid To Date
- Multiple Rate By: a Multiple rate by which is the rate by which the base amount will be multiplied for to calculate the converted amount.
- Divide Rate By: and a Divide rate by which is the rate by which the base amount will be divided by to calculate the converted amount.
Currency Rounding at Store Level
This new development allows to select rounding for different currencies.
Navigate to the Organization window and open Currency Rounding tab. It will be possible to configure:
- Rounding To
- Rounding Down Limit
In this example, if change is between 100 and 25, it will be rounded up to 100. However if it is less than 25, it will be rounded down to 0.
Maximum Allowed Quantity or Price Configuration
This configuration allows to show a popup if the quantity or price exceeds a value set in two new properties defined:
- Web POS maximum allowed price using keyboard
- Web POS maximum allowed quantity using keyboard
These preference works as other preferences from Web POS, in terms of configuration, with a small difference: the value set indicates Web POS the value to be exceeded to show a confirmation popup. Once set one or both of these preferences, the functionality starts to be check in Web POS.
How it works
Once configured, there are two possible scenarios to take into account:
- Web POS maximum allowed price using keyboard is defined. Two different cases could happen:
- The price to be changed is lower than the value configured. The price is set to the lines selected without any UX difference.
- The price to be changed is lower than the value configured. The price is set to the lines selected without any UX difference.
- The price to be changed is equal or greater than the value configured. The price is not set directly and a confirmation popup is shown:
- If the user click on Cancel button, the price is not set to any line(s)
- If the user click on OK button, the price is set to line(s)
- Web POS maximum allowed quantity using keyboard is defined. Two different cases could happen:
- The quantity to be changed is lower than the value configured
The quantity is set to the lines selected without any UX difference.
- The quantity to be changed is equal or greater than the value configured
The quantity is not set directly and a confirmation popup is shown:
- If the user click on Cancel button, the quantity is not set to any line(s)
- If the user click on OK button, the quantity is set to line(s)
Web POS module
A Channel is any interface used by the organization to interact with clients in an omnichannel retail context. Typical channels are the webstore, kiosks, POS terminals in a physical store, Self-Checkout terminals in a physical store, a Call centre or Back office sales.
A Channel - Touchpoint Type is a grouping of touchpoints with a identical -technical- configuration but different identification. This is a configuration designed to model a type of Touchpoint. Each touchpoint belongs to a single Touchpoint Type. Each touchpoint type refers to one single channel, but a channel can hold multiple Channel Touchpoint types.
Taking as an example physical stores, each POS Terminal is an example of a Channel Touchpoint, and all POS Terminals of a specific model belong to the same Channel Touchpoint Type. POS Terminals represent the different terminals on each store and need to be configured properly in order to ensure operations are well supported in the backofice (e.g stock is updated in the backoffice when a sale is registered, invoice is created if customer requires it, etc.).
The Channel configuration takes place in two windows:
- Channel - Touchpoint Type
- Channel - Touchpoint
This structure allows a very simple but flexible configuration. An example would be a multi-store company in multi-channel environment. Each store could be managed differently (e.g have different cash up processes) and could need separate configuration even for each channel. In this case, different POS Terminal types could be defined for each store as different Touchpoint Types. And terminals within same store could share the same Touchpoint Type. In case of eCommerce channel for example, each eCommerce platform can could be defined as separate Touchpoint Type but belong to the same Channel.
These two windows are designed to simplify the configuration process for the user: if the user needs to configure 100 touchpoints, but all of them are basically identical, then the amount of data he will need to insert is quite small, because all Touchpoints will refer to the same Touchpoint Type.
In this section, we will first describe how Channel - Touchpoint Type are configured, and then we will describe the Channel - Touchpoint window.
Channel - Touchpoint Type window
In this window, you basically design a Touchpoint Type, which will be used by one or many Touchpoints. Here you configure relevant information at Touchpoint level, but also some configuration for payment methods in a subtab.
In the header, you configure the following fields:
- Name: The name of the Touchpoint Type
- Channel: Identifies a method of sales generation. (For example, Brick and mortar, eCommerce, call center...)
- Application: Identifies the application behind each touchpoint. External modules can deploy new values and new configuration properties. This field is used to display/hide related configuration properties which are particular to that specific application. Default value is Openbravo POS.
- Group orders in one invoice: If checked, then all orders processed in the related touchpoints without an invoice are grouped by Business Partner and an invoice for each group of orders is created in the Cash Up process. If unchecked, one invoice per order will be created. Note see the performance section for its influence on cashup and ticket creation performance in the backend.
- Separate invoice for returns (Starting from RR18Q1): If selected, separate invoices will be generated during the cashup for sales orders and returns, respectively.
- Document type: The document type used for sales orders, note see the performance section for its influence on cashup and ticket creation performance in the backend.
- Document type for returns: The document type for returned receipts
- Document type for reconciliations: The document type used for the reconciliations done when executing the "Cash up" process in the POS
- Document type for quotations: The document type for quotations
There are as well some other fields related to Openbravo POS touchpoint types. Those are only visble when Openbravo POS application is selected:
- Allow pay on credit: If checked, all POS terminals (touchpoints) of this Touchpoint type will be able to pay sales orders as a credit.
- Default Payment Method: Selects the payment method that will be used by default when closing a receipt.
- Use external input: (Previously Use barcode scanner) If checked, the Web POS will take into account that an external input (keyboard or barcode scanner) is going to be used in this touchpoint type. Checking this option and then not connecting an external barcode will cause the virtual keyboard to be shown continuously in some devices (specifically in mobile devices (Android phones and tablets and iOS devices like iPads or iPhones).
- Hide virtual keyboard with barcode scanner: if Use external input is checked but you are using a barcode scanner in your mobile device which is not detected as en external keyboard, the virtual keyboard will appear very frecuently. Using this flag (enabled by default) it will not happen and the virtual keyboard will not be shown. (This feature does not work in iOS, so the value of this flag is ignored when web POS is running in iOS)
- Layaway Orders (Starting from RR15Q3): If selected, all new orders are created as layaways. This configuration option allows to create terminals that only creates layaways orders that are not paid in these terminals and must be paid in other terminal.
- Use RFID: (Starting from RR16Q3) Enables the use of an RFID reader. Also, in order to use the reader, the hardware url has to be set according with this guide.
- RFID Timeout: (Starting from RR16Q3) Set a timeout to Web POS after which a disconnect will be sent to the RFID reader (If this field is not set, the timeout is disabled). This timeout resets every time a product is scanned through the reader.
- Use Security Gate: (Starting from RR16Q3) This field establishes that after every POS sale, the terminal will send the order to the Hardware Manager, and the latter will try to call to its respective sendOrder method. This method has to be implemented in a new Hardware Manager plugin if one wants to use this check. Basically is intended to be used if a communication with a security gate is needed.
- Multi Change (Starting from RR19Q1): If selected, it will be possible to return change in different currencies. Note see this guide for the rest of the configuration needed.
- Allow prepayments and partial payment (starting from 19Q1): If selected, the system will calculate and display the prepayment amount for a specific order and it will be possible to partially pay a ticket.
- Always Select Printer (starting from 19Q2): If selected, the selecting printers window will be shown every time the user does a transaction that force to print a document.
- Auto Register HWM URL (starting from 19Q2): If selected, the Hardware Manager URLs that has been automatically registered in Hardware Manager window will be configured with this Terminal Type at Hardware URL level.
In addition to these, there are two more fields which define how the masterdata reloading is done:
- Time to fully refresh masterdata (in minutes): A full refresh is the process of reloading the whole masterdata set (including products, business partners, prices, taxes, ...). This operation is very expensive and time consuming, so it should be done only when really needed (typically, every day). If done with too much frequency, this may tax too much the server, greatly slowing down the operation of POS terminals.
- Time to incrementally refresh masterdata (in minutes): This process is much lighter than a full refresh, because it only loads records which were changed from the last time a refresh was done. This is much less expensive than a full refresh, but has the disadvantage that if a record was deleted, it will not detect it.
If neither of the fields is defined, then the system will fully refresh all data when the user logs in (and data will not be automatically refreshed until the next log in).
If only the first field is filled, then the system will fully refresh all data in the next login done after of minutes specified in the field.
If both fields are specified, then both incremental will be done each number of minutes as indicated in the field. The full refresh will be done in the next login done after of minutes specified in the field.
When the time Time to incrementally refresh masterdata (in minutes) expires, the web pos will start loading in background all the models.
And when the next ticket is finished, or the Time to Show Incremental Refresh Popup (in minutes) expires, it will save the model changes in db, and when doing this it will show a loading screen. As the loading already took place, the amount of time the user is blocked has been significantly reduced.
If there is no changes in any of the models, nothing will be shown to the user.
If an incremental refresh with a large volume of data happens, the UI will then be blocked as this data needs to be loaded in chunks. The background masterdata maximum size can be configured by the preference "Background Masterdata Maximum Size". If set to -1 it will disable the background masterdata refresh, and the previous way of loading the data blocking the UI will be used.
Also in 19Q4 version, the incremental refresh will not be triggered by default when logging in the application or refreshing it. Only if it is really time to refresh the data (taking into account the Time to incrementally refresh masterdata (in minutes) preference), the incremental data loading will be triggered when logging in the application.
In the Payment Method tab, you configure the following fields:
- Search key: An identifier string for the payment method.
- Name: The name of the payment method.
- Payment method: The Openbravo payment method associated with this payment method.
- Currency: The currency associated to this payment method.
- G/L Item for Writeoff: In case the amount received when paying a ticket differs from what is expected, this G/L Item reflects this difference. It is recommended to use the name of the Touchpoint and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash overpayments.
- G/L Item for Rounding(Starting from RR19Q1): In case rounding is activated it is needed to configure this GL Item in order to associate it to rounding cash differences.
- Payment Provider: Dialog that will be used to confirm the payment of a receipt using this payment method, usually the dialogs listed in this field are included by payment gateway modules.
- Refund Provider: Dialog that will be used to confirm the refund of a return order using this payment method, usually the dialogs listed in this field are included by payment gateway modules.
- Allow Open Drawer: If checked, to paid, the cash drawer will be opened
- Open drawer before closing ticket: If checked, when paying a ticket, new step will appear to open drawer before finish paying the ticket.
- Cash: When checked indicates this payment method is a cash method and will show a coins and bank notes panel when selected. To configure a new coins and bank notes panel go the document How to create a new coins and bank notes selector. It also indicates that overpayments made with a cash method will be returned to the customer and the change to return to the customer will be calculated and displayed in the payment panel.
- Default Cash Payment Method: only shown for a cash payment method, when there are multiple cash payment methods one of them can be flagged as the default cash payment method, is used for example when displaying the initial count view in the retail sessions module.
- Show coin keypad: If the payment method is cash you can configure if you want to see the coin keypad checking this field to yes. If unchecked, the basic numeric pad will appear.
- Max. Limit Amount (Starting from RR15Q1): This amount limits the quantity of money you can use to pay a ticket for that payment method. For example if the tickets is 505€ and the limit for the cash payment method is 500 the system will show a message "The maximum limit (500 €) for this payment method has been exceeded. Payment not allowed"
- Overpayment Limit (Starting from RR15Q3)(Renamed to Overpayment / Change Limit in RR15Q4.2): This field is visible only for cash payment method that allows overpayment. If it contains a value, the amount of change that can be returned to a customer cannot be greater than the amount of this field, otherwise an error message will be shown to the cashier.
- Overpayment / Change Limit (Starting from RR15Q4.2): This field is visible for every payment methods and it is used to define the behavior regarding overpayments.
- If this field is empty, overpayments (change in case of payment method has been defined as cash) are allowed.
- If the value set in this field is 0, overpayments (change in case of payment method has been defined as cash) are not allowed.
- If the value set in this field is a number greater than 0, overpayments (change in case of payment method has been defined as cash) will be allowed if the amount of the overpayment (change in case of payment method has been defined as cash) is not greater than this value.
- Payment method Category (Starting from RR15Q2): This combo allows to group different payment methods in one category. This categorization means that when being in the payment panel instead of seeing all the payment methods the user will see just one. When clicking the button it will show the payment methods that belong to it
- Image (Starting from RR15Q2): This field makes sense when the payment methods is categorized, that is, when it belongs to a Payment Method Category. When the popup gets opened it will show not only the name of the payment method but an image. Taping the image will select the payment
- Count Payment in Cash Up: (Starting from RR17Q2) This flag allows to avoid counting a payment method in Cash Up flows. The payment methods that have this flag unchecked are not taken into account when doing a Cash Up in the Web POS, not being possible even to count them. If this flag is unchecked, the other fields that belongs to the Cash Up group are ignored (are hidden).
- Automate movement to Other: If this field is selected, there will be an additional step during the cash up process for this payment method, which will allow the user to specify how much money should be kept in the main account, and how much will be moved to a secondary account (configured in the Cash Management Events tab of Organization window). Hence, if you select this, following checks need to be considered, which are the different options given to the user while cashing up for this payment method:
- Keep Fixed amount: A fixed amount will be kept in the financial account of the terminal
- Amount:: The amount for the previous option
- Allow variable amount: If checked, the user will be able to input an amount to keep in the financial account of the terminal
- Allow not to move: If checked, the user will be able to keep everything in the financial account of the terminal, so not "moving" money
- Allow move everything: If checked, the user will be able to move all money to the destination financial account configured in the Cash Management Event
- Cash differences: This G/L Item is used if there are cash differences during cash up (theoretical amount different than the counted one). The created transaction will be associated with it. We strongly recommend using the name of the Touchpoint Type and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash differences
- Cash deposit/withdrawal: This G/L Item is the one associated in the transaction added in the financial account in both terminal and backoffice after cash up processed is processed. So it is important a G/L Item is configured here. We strongly recommend using the name of the Touchpoint Type and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash G/L Item for Cash up
- Count Cash: For payment methods marked as Cash indicates whether to show or not a cash count step in the cash up process to count the cash amount in the drawer with the help of currency denominations. To activate this option you must configure first Coins and Bank notes in the Currency window for the payment method currency.
- Allow withdrawals: If checked, withdrawals can be created associated with this payment method
- GLItem for withdrawals: The G/L Item associated with the transactions created for withdrawals. We strongly recommend using the name of the Touchpoint Type and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash withdrawal
- Allow deposits: If checked, deposits can be created associated with this payment method
- GLItem for deposits: The G/L Item associated with the transactions created for deposits. We strongly recommend using the name of the Touchpoint Type and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash differences
This section applies if Multi Change is enabled
- Change less than: Amount that has to be returned in another currency
- Change Payment: Currency in which change has to be returned if amount is less than selected in "Change less than" field
If Leave as Credit field is set to 'Y' that payment method wont take part on the CashUp process since it is not going to get paid. It won't also have a Financial Account associated.
In the tab Hardware URL you can configure a list of Hardware Manager (only for printer devices) to allow the cashier to select a different printer to use in the case he wants to or the current selected printer is not working for any reason. This list of Hardware URL addresses is shared by all the touchpoints with the same Touchpoint Type and it must be configured using the Hardware Manager window.
Terminal for Seller
From RR17Q3, a new concept of terminal have been included. These terminals are Terminals for Sellers.
Terminals for Sellers are terminals distributed in different sections of a store. These terminals are only used to create layaways, so are never used to directly buy or return products. An example may be a customer who is in a supermarket, in the fruits section. This customer chooses four apples and asks to a seller to create a layaway with those four apples, which will be paid to a vendor in a normal terminal.
To consider a touchpoint to be a Terminal for Seller, the touchpoint needs to belong to a Touchpoint Type with an specific configuration:
- The Layaway Orders field must be checked.
- The Touchpoint Type may only contain payment methods that are not counted in the Cash Up process.
- The roles that are accessing to these touchpoints should have the Web POS action Receipt this Layaway property set to 'N'.
As commented before, a Terminal for Seller should never be used to pay tickets or return products. These terminals don't contain a drawer, so any operation related to a cash movement is not allowed. Due to this reason, Terminals for Sellers are not allowed to do Cash Ups or any operation available in the Cash Management window. The following functionalities are disabled here:
- Open Drawer
- Cash Up
- Cash Up Partial
- Cash Management
- Verified Returns: The verified return menu entry is disabled, but is not also possible to do any type of return, because the new created tickets will always be layaways
As the Cash Up, Cash Up Partial and Cash Management menu entries are disabled, if an user tries to navigate directly to any one of those pages directly by URL, a popup will appear telling that a Terminal for Seller cannot navigate to that URL.
Payment methods not counted in the Cash Up process:
Even if this type of touchpoint is not considered to work with payments, there are some flows that may need to get money back. Those flows are:
- Void Layaway
- Cancel Layaway
- Cancel and Replace removing products that were previously fully or partially paid
These three situations will be always managed using payment methods that are not counted in the cash up, so which won't need to have a drawer in the terminal.
If the Sessions module is used, Terminals for Sellers are also considered and their behavior particularly when the Store is closed changes a bit. You can find a bit more information here
Allow to configure the UI
A new field called "Touchpoint UI configuration" has been created in touchpoint type window. This field allows to select a certain UI configuration which is configured in a separate window called "Touchpoint UI Configuration". There, several actions (buttons) can be placed in differents areas of the screen according to the user needs.
Touchpoint types which are already configured will mantain the prior behavior (field will be blank). For new ones, a preconfigured Touchpoint UI Configuration (Default POS UI Configuration) will be used. This value can be set as blank (to use prior behavior) or changed for a Touchpoint UI Configuration specifically created.
Here you can find more information about that feature
Channel - Touchpoint window
In this window the individual Touchpoints must be created.
In the header, the following fields are configured:
- Search key: An identifier for this touchpoint, it must be unique. In case of a POS terminal touchpoint, it is the one that is going to be used in the URL to access the terminal
- Name: The name of the touchpoint
- Hardware URL: The URL of the receipt printer, it will be given by the hardware manager, followed by /printer
- Scale URL: The URL of the scale
- Order Sequence Prefix: This prefix is used for the order documents generated in Sales Order window in the backoffice for each ticket of the touchpoint
- Quotation Sequence Prefix: This prefix is used for the document number of quotations generated in this touchpoint.
- Touchpoint Type: The Touchpoint Type which describes the configuration used by this Touchpoint
- Default Tab for Web POS: Ability to define whether the tab for selecting products is Scan (when scanning products is the main action) or the browse
- Default customer: The customer can be configured at store level or at terminal level. In this case it is more restrictive so if it is filled then the system will use this customer instead
- Terminal Key Identifier: When Terminal Authentication enabled preference is 'Y', this is the code for this Touchpoint configuration. Using for first time a physical device connecting to Web POS we will be able to link the device to this configuration using this code.
- Is linked to a physical device: This field is checked when a physical device is linked to this Touchpoint configuration using Terminal Authentication security.
- Unlink device: This process button allow us to unlink the actual physical device from this configuration. We could lose data not synchronized in the ERP (terminal is offline and exists data to send to the ERP), we need to be sure of this action.
- Cache Session Id: This read only field shows the id which identifies the current cache session id. This id must match with terminal cache session id to allow login.
- Return Sequence Prefix: This prefix is used for the document number of POS returns generated in this touchpoint. It's not mandatory, and if it's not set, then return documents will share the sequence with normal sales orders.
- Order Document No Padding: This field defines the size of the document number sequence in Web POS per terminal. By default the size is 7.
- Full Invoice Sequence Prefix: Prefix used for full invoice document number generation. It must be defined in order to issue full invoices from Web POS.
- Full Return Invoice Sequence Prefix: Prefix used for full return invoice document number generation. In case it is not defined, full invoice sequence prefix will be used instead.
- Simplified Invoice Sequence Prefix: Prefix used for simplified invoice document number generation. It must be defined in order to issue simplified invoices from Web POS.
- Simplified Return Invoice Sequence Prefix: Prefix used for simplified return invoice document number generation. In case it is not defined, full invoice sequence prefix will be used instead.
In the payment type, the following information is configured:
- Search key: It is an identifier string for the payment method.
- Name: The name of the payment method
- Payment method: The payment method type defined in the Touchpoint Type, which contains the configuration information for this payment method
- Financial account: The financial account associated with this payment Very important: The financial account must be associated only with this payment. It should not be used in operations generated in backoffice, only transacctions generated in the touchpoint should be deposited. The Organization of the Financial Account, must be in the Org Access list of the User Role (Only in the Cash Up process) . POS processes will not work correctly otherwise. (Starting from RR17Q2) The payment methods are not automatically deposited in the financial account. Instead, the Automatic Deposit field that belongs to the Payment Method tab in the Financial Account window is checked to do or not the deposit automatically
- Cash management close event: The cash management close event which should be used when executing the cash up process
Very important. Payment methods are secured by Search key value in Role preferences. There are three predefined values: OBPOS_payment.cash for cash payments. OBPOS_payment.cash payment method is also used to calculate cash change in the payment panel. OBPOS_payment.card for card payments and OBPOS_payment.voucher for voucher payments. If you need to add new payments with different Search key values you need to secure them in order to allow users to use the new payments you create. To do this, as System Administrator you need to go to the window References, in this window search the record with name Property Configuration and in the tab List Reference add a new record with the same Search key as the new payment you need to add. This new record should belong to your own module which should be dependent from the Web POS module. Once it is created you will be able to assign permissions to this new payment in the Preferences window.
Note. The search key field in the tab List Reference must start with the DB prefix of the module you are creating this value, but the search key of the payment method does not need to start with any prefix, so for example if the search key in List Reference is OBPOS_payment.mypayment the search key in the payment method to secure can be OBPOS_payment.mypayment or payment.mypayment.
Note. When a ticket is created within Web POS, the information related to the payments of this order is stored in Sales Order > Payment plan > payment details
Note. Do not add payment types if this touchpoint has an open cashup. This window is to define configurations before start working in Web POS, if you change the configuration while the touchpoint is operating you could have errors in the touchpoint or data inconsistency.
In the cash up history, the following information is configured:
- Organization: It is store of the Touchpoint.
- User/Contact: The name of the user who did the cash up.
- Cashupdate: The date when the cash up was done.
- Cash Up Report: This process button, create a pdf report with all the information about the cash up.
In the reconciliation subtab, the following information is configured:
- Payment type: It is payment type which is related to the financial account of the reconciliation.
- Reconciliation: The reconciliation itself.
- Override Touchpoint Type Configuration: this flag allows to override the configuration of the cash up defined in the touchpoint type – Payment Method.
- Automate movement to Other: If this field is selected, there will be an additional step during the cash up process for this payment type, which will allow the user to specify how much money should be kept in the main account, and how much will be moved to a secondary account (configured in the Cash Management Events tab of Organization window). Hence, if you select this, following checks need to be considered, which are the different options given to the user while cashing up for this payment method:
- Keep Fixed amount: A fixed amount will be kept in the financial account of the terminal
- Amount: The amount for the previous option
- Allow variable amount: If checked, the user will be able to input an amount to keep in the financial account of the terminal
- Allow not to move: If checked, the user will be able to keep everything in the financial account of the terminal, so not "moving" money
- Allow move everything: If checked, the user will be able to move all money to the destination financial account configured in the Cash Management Event
- Cash differences: This G/L Item is used if there are cash differences during cash up (theoretical amount different than the counted one). The created transaction will be associated with it. We strongly recommend using the name of the Touchpoint and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash differences
- Cash deposit/withdrawal: This G/L Item is the one associated in the transaction added in the financial account in both terminal and backoffice after cash up processed is processed. So it is important a G/L Item is configured here. We strongly recommend using the name of the Touchpoint and the Payment method for naming the G/Item in order to avoid problems with matching transactions and bank statements. Example: VBS Cash G/L Item for Cash up
- Count Cash: For payment type marked as Cash indicates whether to show or not a cash count step in the cash up process to count the cash amount in the drawer with the help of currency denominations. To activate this option you must configure first Coins and Bank notes in the Currency window for the payment type currency.
In Channel - Touchpoint window you can define a hierarchy of touchpoints in order to allow to share any payment method you have accross touchpoints of the same organization. e.g.- There are 4 terminals in an store but you have only one pinpad.
More than two levels of hierarchy are not supported. This means that a “master” touchpoint cannot be slave of any touchpoint.
A touchpoint can use both standard payment methods and shared payment methods at the same time.
When a touchpoint is defined in the backoffice, another touchpoint can be specified as its “master”. When this is done, two important changes happen in the POS operation:
- Shared payment methods can be defined. Shared payment methods will not appear in the “slave” touchpoints when doing the cash up, and will only appear in the “master” touchpoint. Standard payment methods will appear normally in the cash up of each touchpoint.
- The cash ups for the “slave” touchpoints must be done before the cash up in the “master” touchpoint can be done. The cash ups in the “slave” touchpoints will not have any real consequence in the backend other than enabling the cash up in the master touchpoint. The invoices and reconciliations for the payments generated in all the terminals will be created only when the cash up in the “master” touchpoint is done.
- The Shared Payment Type from the same Payment methods needs to have the same Financial Account associated.
- Refundable: For payment type marked as Refundable it will be possible to refund to the Customer on that Payment Method. In the case it is unmarked it will not be possible to add a negative payment with that Payment Method from WebPOS.
- Show-Hide Taxes: A new button called show Tax Breakdown has been added in the Channel - Touchpoint Type screen to show or hide taxes in Web POS.
Through the touchpoint window, it is also possible to monitor some key metrics and facts of each terminal in the system.
The information is shown in touchpoint window header and it is grouped in Terminal Status section.
The user could monitor the following information in Terminal Status section
- Last Full Masterdata Load
- Datetime field with the information of the last time current terminal has completed successfully a full refresh of masterdata. For more information, refer to Time to fully refresh masterdata section.
- Last Incremental Masterdata Load
- Datetime field with the information of the last time current terminal has completed successfully an incremental refresh of masterdata. Time to incrementally refresh masterdata section.
- Last Cache Generation
- Datetime field with the information of the last time current terminal has generate cache data. For more information, refer to WebPOS cache section.
- Last JS Generation
- Datetime field with the information of the last time current terminal has upload of WebPOS js file. For more information, refer to caching and compression section.
Terminal status extension
As an extension of previous terminal status values user can monitor, now it is possible to monitor more in detail the current status of a terminal from Touchpoint Window
The information, as before, is shown in Touchpoint window header and it is grouped in Terminal Status section.
The user could monitor the following new information in Terminal Status section
- Last Log In Date
- Datetime field with the information of the last time a user logs in the specific terminal.
- Last Log In User
- Reference field with the information of the last user logged in the terminal.
- Last Performance Check Score
- Score of the last benchmark done in the terminal, refer to POS Terminal Performance Testing.
- Last Synchronized Order
- Datetime field with the information of the last sales order/layaway synchronized to the ERP from the terminal.
- Last Completed Cashup
- Datetime field with the information of the last processed cashup done in the terminal.
- Last Loaded Ticket
- Datetime field with the information of the last completed sales order loaded in the terminal.
- Last Transition To Offline
- Datetime field with the information of the last time the terminal goes offline (this information is updated once the terminal goes online again), refer to Terminal Offline mode.
- Last Transition to Online
- Datetime field with the information of the last time the terminal goes back online.
- Last Hardware Manager Version
- Indicates the last Hardware Manager major version used for this terminal.
- Last Hardware Manager Revision
- Indicates the last Hardware Manager revision used for this terminal.
- Last Hardware Manager Java Runtime Information
- Indicates the information of the Java used for this terminal. This field indicates the Java implementation information with the build and major version number
=Terminal status history=
In addition, a new sub tab has been created in Channel - Touchpoint window called "Terminal Status History".
Terminal Status History records are created once the cash up is synchronized with the ERP and are updated until the current cash up is processed in WebPOS.
The information the user could monitor is
- Cash Up
- The cash up related with this monitor process.
- Number Of Transitions to Online
- Number of times the terminal switches from offline mode to online mode during this cash up.
- Number Of Logclient Errors
- Number of logclient error registered during this cash up.
- Number Of Errors While Importing POS Data
- Number of records in Errors While Importing POS Data registered during this cash up.
- Average Latency in ms
- The average network latency in milliseconds.
- Average Upload Bandwidth in KB/s
- The average network upload bandwidth in kilobytes per second.
- Average Download Bandwidth in KB/s
- The average network donwload bandwidth in kilobytes per second.
Configuring for performance
Several settings have consequences for the performance of Web POS in the backend operations: creating orders, invoices and doing cashups. This section gives an overview of some settings.
Group orders in one invoice - Cashup Performance
In the POS Terminal Type you can check the group orders in one invoice. If this flag is not checked then each ticket in Web POS will result in a separate invoice in the backend. These invoices are created when doing the cashup.
If shops close at the same time and several shops do the cashup at the same time this can result in the cashups of different shops waiting for each other as they might share the same document sequences for invoices. See the next subsection on document sequences for more information.
In general it is fine/best to check the group orders in one invoice flag. This results in better cashup performance, smaller database sizes and most of the time no separate invoice is needed as there is already a printed ticket for the customer.
Generate invoice for orders
Another setting in the POS Terminal Type specifies if a separate invoice should be generated for each order/ticket when the ticket is created. This results in a slighly slower ticket creation in the backend. The Web POS user does not notice this as the backend ticket creation does not block the Web POS user interface. But having a separate invoice for each ticket will result in much more data in the database and more load on the server.
So the advice is to only check this option if it is really needed and in all other cases keep it unchecked.
Invoice Sequence project implements a clear way to distinguish "full", "simplified" and "aggregated" invoices created in any touchpoint, in terms of document type, numbering and printing.
Sometimes we could suffer performance problems when we are searching something in Web POS and it takes time to render all the items or when we have an environment with high volumes. Because of that, we can set this three preference (Searching in WebPOS limit value for Products, Searching in WebPOS limit value for Customers and Searching in WebPOS limit value for Orders). We have to put the number of items we would like to show in a search. By default this value is 300, in case you want to show less items, set preferences with your selected value. This feature is available searching Products, Customers and also Orders(Paid orders, layaways, quotations...).
Document Type and Sequence Numbers - (Cashup) Performance Consequences
The document type defines the document sequence which is being used for orders and also defines the document types for invoices and other business documents.
When creating some documents such as shipments, payments or reconciliations, the system uses the document sequence to generate a new document number for the business document (order/invoice/shipment). Document numbers need to be unique and also need to be incremented correctly. To ensure this the system will lock the database while creating business documents.
If different terminals share the same document sequence for a business document then POS actions of these terminals will sometimes wait on eachother (at database level) when new document sequence numbers are created. Especially with large cashups this can result in longer processing times.
In 19Q1 and earlier releases, the document types were configured at Touchpoint Type level, so each store had to configure its own terminal type with specific document types in order to have good performance. In 19Q2 and newer releases, the document types are configured at Organisation level, but it is still very important to configure specific document types for each store. This is the best way to ensure that the server can process documents from different organisations in parallel and that contention is kept to low levels.
Enabling Synchronized Request Order we will enable this functionality. From 16Q2.
This functionality makes the transaction be processed on the server completely synchronously. So the WebPOS user interface wait for the confirmation that the record has been successfully processed on one of the servers before it can proceed. If an error occurs the ticket is not saved on the server and a message is sent to the WebPOS client to show the error.
Hardware Manager window
This window defines the list of Hardware Manager URLs with configured printers that are available for assigning to POS Terminal Types.
See Hardware URL for configuring Hardware Managers for each Terminal Type.
For each Hardware Manager record you have to configure the following fields:
- Name: The name that will appear in the dialog to select printer.
- Hardware URL: The URL where the Hardware Manager is located. It must be the root location of the Hardware Manager web server.
- Has Receipt Printer: Indicates if the printer can be selected to print receipts.
- Has PDF Printer: Indicates if the printer can be selected to print PDF documents like service documents.
- Active: Indicates whether the printer is active or not.
A process called, Delete Auto Registered Hardware URL, allows to delete the automatically registered hardware manager urls. This process shows a pick and execute window that will let the user select the hardware managers that wants deleted.
Once the records to delete has been selected and the process is executed they will be removed with its dependencies in Touchpoint Type window.
The WebPOS supports offline operation. One of the most important parts of the support for offline operation is being able to save the application sources in a persisted state, so that if the connection is not available, the application can nonetheless be started correctly.
In previous versions of the application, we used the Application Cache technology to persist the application sources. This is still supported in current versions, and we expect to keep it for some time. However, starting from RR18Q3 we now also support the persisting of application sources using Service Workers. Service Workers are the preferred way to persist the sources nowadays, because they are more flexible and they give greater control to the developer of which resources he wants to cache, and how to manage this cache. However, they are not yet fully available in all browsers, which is the main reason why we are keeping the support for Application Cache as of now.
In RR18Q3, Service Workers was enabled by default for Google Chrome users. In RR20Q3, it was also enabled by default for Safari users.
However, as previously explained, it is possible to switch between Service Workers and Application Cache using the preference "Web POS Use Service Workers for Offline Support". This is a system-admin preference which must be defined using System Administrator role, and only once per system. If it's set to 'Y' (or if it doesn't exist) then Service Workers are enabled, otherwise Application Cache will be used instead.
This can be configured with the "Web POS Maximum time which the terminal can be offline" preference.
You can use the "Web POS Offline session time expiration" preference to specify how much time will the WebPOS consider a session still valid while being offline. This will slightly change the way the POS behaves is the user refreshes the application while being offline: before, it would always ask for the user to enter credentials to continue, and now it will only ask him to do so if the session is no longer considered valid.
Customizing UI through Touchpoint UI Configuration
A new window has been created to configure which actions will be shown in Web POS and where to place them. Below you can find the list of actions buttons areas which are available to be customized using this feature.
How to create a custom Touchpoint configuration
Step 1 (header): Create a new UI Configuration
- Search Key / Name: An identifier for this configuration
- Application: The application which will use this configuration. If Mobile core is selected, all mobile applications which are compatible with this new mechanism will be able to use it. (Currently (3.0RR19Q3) just web POS is compatible) so Web POS is recommended.
- Description: Here you can describe the aim of this configuration
- Window: Here will be listed available windows (this values will depend on the application selected in the previous step)
- Action Button Area: Here will be listed the action button areas present in the selected window (bellow is the list of action button areas per window)
- Action Button Area Layout Variant: This field is optional and depends on the selected action button area. Some of them have variants available (edit, scan) but others not (Receipt top Area)
Step 3 (3th level tab): Add and select the place for desired actions
- Action: Select an action from the list to be added to the action button area
- Row: (Starting from 0) Select the row where the action will be placed
- Column: (Starting from 0) Select the column where the action will be placed
- Col Span: (Default 1) Use this value if you want to extend your actions to the next columns
- Row Span: (Default 1) Use this value if you want to extend your actions to the next rows
- CSS class: This optional field allows to the user to apply an specific css class for this action.
Receipt Top Area [3.0RR19Q3]
This action button area is located at the top of the ticket. This area allows to customize 6 actions distributed in one row (from 0 to 5). This Action button area does not provide any layout variant. The configuration provided by default by Web POS does not add any button in this action button area. If you want to add new buttons here a new Touchpoint configuration must be used.
Edit - Bottom Right Button Area [3.0RR19Q3]
This action button area is located next to the keyboard which is shown when a line is being edited. It consist of a layout with 2 columns (0 to 1) and 6 rows (0 to 5). This action button area provides a layout variant which allow to place the action button area at the right or at the left of the keyboard (By default will be placed at the left of the keyboard).
Scan - Bottom Right Button Area [3.0RR19Q3]
This action button area is located next to the keyboard which is shown when SCAN is selected (no line selected). It consist of a layout with 2 columns (0 to 1) and 6 rows (0 to 5). This action button area provides a layout variant which allow to place the action button area at the right or at the left of the keyboard (By default will be placed at the left of the keyboard).
Not every user is supposed to have access to Web POS and not every Web POS user is supposed to have access to Cash Up and Cash Management. You can set access to these windows in the back office as follows.
Enabling a role to access Web POS:
- Go to the Role window in the back office (General Setup > Security > Role)
- Select the role you want to grant access to Web POS to
- Go to the child tab called Form Access
- If it does not exist yet, create a new record and set the Special Form field to Web POS.
- Save and reload the Web POS for the changes to take effect
Setting access to specific functionality:
Note roles defined as Automatic (Manual field is unchecked) have access to all functionality regardless preferences.
- Go to the Preference window in the back office (General Setup > Application > Preference)
- Create a new record and select the functionality in the Property field. For example order.discount or Web POS window Cash Up.
- Set the value to Y in the value field to enable access.
- Set the desired visibility in the Visibility section below.
- Save and reload the Web POS for the changes to take effect
The following functionalities are relevant for Web POS users:
- Changing price (Web POS action Change price, by default revoked)
- Giving discount (Web POS action Apply discount, by default revoked)
- Invoice receipt (Web POS action Invoice receipt, by default granted)
- Return receipt (Web POS action Return receipt, by default granted)
- Print report in Cash Up (Web POS action Print cash up, by default granted)
- Print report in Cash Management (Web POS action Print cash management, by default granted)
- Print receipt menu action (Web POS action Print receipt, by default revoked)
- Reject a quotation from the menu ('Web POS Quotation rejections', by default granted, available from 3.0RR15Q4)
- Using payment type card (Web POS payment Card, by default granted)
- Using payment type cash (Web POS payment Cash, by default granted)
- Using payment type voucher (Web POS payment Voucher, by default granted)
- Accessing Cash Management (Web POS window Cash management, by default revoked)
- Accessing Cash Up (Web POS window Cash Up, by default revoked)
- Accessing Point of Sale (Web POS window Point of Sale, by default granted)
- Accessing Back Office (Web POS Back Office, by default granted)
- Creating Discretionary Discounts (Web POS action Advanced Discounts, by default granted; together with Web POS action Apply discount)
- Editing Firm Quotation check when creating order from Quotation (Web POS Quotation: Editable Firm Check, default granted, available from RMP27)
- Change profile settings (Mobile Change Profile, by default granted, available from RMP30). Allows to change profile settings (role and language)
- Sales with Returns (Do not allow Sales with return, by default revoked)
- Switch from positive to return line ('Web POS Show Action Button Return, by default granted)
- Multi Order (Web POS Enable Multi Order menu entry, by default granted)
- Receipt Discounts from Keyboard (Web POS Open Discounts From Keyboard, by default granted, available from RMP28)
- Open Drawer button (Web POS Open drawer from menu, by default granted, available from RMP29)
- Select a specific warehouse to consume the goods for a specific order line (Allow to select a warehouse for a specific line order), by default revoked.
- Enable the functionality to split in shipment lines, lines from orders to be returned. (Split Lines in Shipments when Returning, by default disabled, available from RR15Q2)
- Save removed tickets or ticket lines in the backend when the user chooses to delete (Web POS Save Removed Tickets, by default revoked).
- Enable the functionality to have layaways with negative lines if there are no partial payments. (Allow layaways with negative lines, by default disabled, available from RR18Q2)
The following functionalities are related to Quotations:
- Create Quotation (Web POS action create new quotation, by default revoked)
- Sales Order from Quotation (Web POS action create sales order from quotation, by default revoked)
- Reactivate Quotation (Web POS action reactivate quotation, by default revoked)
- Show Quotation (Web POS action show quotations, by default revoked)
Note that access to Cash Up and Cash Management will be disabled by default for new roles.
When the user has no access to specific menu entries these ones will be hidden in the menu
Enabling specific terminals for users:
Starting Openbravo for Retail RMP20, specific users can be given access to specific POS terminals. This is done through the POS Terminal Access tab in the User window.
The following rules are followed to decide whether a user has access to a terminal or not:
- If a user doesn't have entries in the POS Terminal Access tab, then it can log in all the available POS Terminals (provided that it has access to a role with access to the Web POS form).
- If a user has entries in the POS Terminal Access tab, then it can only access the terminals specified there.
Several preferences have been created to be able to show or hide the action buttons related to the products in the order. The default value is to show them. Some examples of the preferences:
- Web POS Show Action Button Check Stock
- Web POS Show Action Button Delete
- Web POS Show Action Button Description
- Web POS Show Action Button Remove Discount
- Web POS Show Action Button Return
- Web POS Show Action Button Show Related Services
- Web POS Show Action Button Split
Some actions require of supervisor's approval in order to be accomplished.
When an action requiring of approval is performed a pop up requesting supervisor's credentials is shown and it is not possible to continue till these credentials are provided or the approval is cancelled aborting the action in this way.
In case the user launching the action is a supervisor, no approval is requested to complete it.
Each action requiring approval can have its own supervisors, thus it is possible for a user to be supervisor of action A but not action's B supervisor.
Each Approvable Action require of a different preference to be set:
- "Approvable Action" Preference with value N at client level. In order to show Approval Modal.
- "Approvable Action" Preference with value Y at user's or role level. In order to give access to this action.
Note that, as opposite as the other security preferences, supervisor preferences require of explicit setting, this means automatic roles are not considered as supervisor unless there is a preference defining it.
Here is the list of actions that can require approval:
- When pressing Total toolbar button, approve Discretionary Discounts. Property Web POS Discretionary Discount Approval (OBPOS_approval.discounts). More information about this action can be found here.
- Open Cash Management window. Property Web POS Cash Management window approval (OBPOS_approval.cashmgmt).
- Open Cash Up window. Property Web POS Cash Up window approval (OBPOS_approval.cashup).
- Open Cash Drawer in Cash Up window. Property Web POS Open Drawer approval Cash Up (OBPOS_approval.opendrawer.cashup).
- Open Cash Drawer in Point of Sale window. Property Web POS Open Drawer approval Menu (OBPOS_approval.opendrawer.menu).
- Remove suspended orders in Cash Up(Step 1) window. Property Web POS Remove Receipts Approval in Cash Up (OBPOS_approval.cashupremovereceipts).
- Remove receipts with Delete button or Loging out. Property Web POS Remove Receipts Approval (OBPOS_approval.removereceipts).
- Remove an order line. Property Web POS Delete Line Approval (OBPOS_approval.deleteLine).
- When pressing Total toolbar button, approve return lines. Property Web POS Returns Approval (OBPOS_approval.returns).
- Set price of a product in a line. Property Web POS set Price approval (OBPOS_approval.setPrice).
- Approve difference between Expected and Counted cash. Property Web POS Cash Up Differences Approval (OBPOS_approval.cashupdifferences).
- Approve menu opening. Property Open Menu Approval (OBMOBC_approval.openMenu). From 17Q2
Whenever an action is approved by a supervisor, the Sales Order created in the back office keeps track of the supervisor's user as well as the action she approved.
This information can be seen in the Approvals read only sub tab in Sales Order window.
Approvals can be granted in offline mode. In order to approve an action being in this mode, it is required that the user that has granted to that action has logged in at least one time being online in the terminal
Terminal Authentication Security
A fundamental WebPOS mandatory rule is not to access the same POS Terminal from two or more devices / web browser instances. For the same reason, it is not allowed to access from the same web browser instance to two or more terminals. To help avoid this, Openbravo have created the Enhanced Security Authentication.
Starting from RR16Q1 this functionality will be enabled by default thanks to the preference Terminal Authentication enabled.
If someone wants to overwrite the value of the main preference, a new preference for the same property should be created. The value of that new preference will override the value of the original one.
Take into account that this preference (to override the default one) should be created leaving the client field empty and it should be visible for Organization "*"
Remember that if terminal authentication is enabled, every terminals will share the same URL and then a specific terminal will be linked.
- Terminal Authentication enabled is 'Y': Access url --> openbravo/web/org.openbravo.retail.posterminal/
If security is not enabled we need to put the terminal searchKey in the URL.
- Terminal Authentication enabled is 'N': Access url --> openbravo/web/org.openbravo.retail.posterminal/?terminal=VBS-1
The following preferences can be also set.
- Quotations are not Firm by default. When creating an order from a quotation, by default Firm is checked unless this preference is set to Y.
Web POS Locale Settings
UI language in Web POS works in a similar way as in ERP: it is defined per session and can be changed, while being online, from User > Profile dialog.
It is possible to define a default language for Web POS at role level, this default language will be set to user when the role is set as default for Web POS. Additionally it a user can be restricted not to change her defaults by using the Change Profile Settings preference.
Business Objects such as Product, Product Categories, Taxes, Promotions and Discounts, etc. Are also translated to the same language the UI is set to.
Date and Numeric
Numeric and date formats in Web POS are defaulted to the same that in backoffice.
Starting from RMP31 these formats can be set different to the default ones at Store, Group of Stores or Group of Organization levels. It will be used the most specific one, for example having this Organization tree:
Formats in Format.xml: date: dd/MM/yyyy numeric: "." decimal, "," for thousand grouping Organizations/Stores definition: * |- Group 1 (defined date format: MM-dd-yyyy) | |- Store 1.1 | |- Store 1.2 (defined numeric format: "," decimal, "." for thousand grouping) |- Group 2 (defined numeric format: "," decimal, "." for thousand grouping) |- Store 2.1 |- Store 2.2 (defined numeric format: "." decimal, "," for thousand grouping)
The format that would be used in each of the stores would be:
|Store||Date Format||Numeric format (decimal/thousands separator)|
|Store 1.1||MM-dd-yyyy (taken from Group 1)||./, (taken from Format.xml)|
|Store 1.2||MM-dd-yyyy (taken from Group 1)||,/. (taken from Store 1.2)|
|Store 2.1||dd/MM/yyyy (taken Format.xml)||,/. (taken from Group 2)|
|Store 2.2||dd/MM/yyyy (taken Format.xml)||./, (taken from Store 2.2)|
These settings can be configured in Organization window:
Currency Format in Web POS is the same that in backoffice. It will be used to change the decimals of currency , by default it will be #,##0.00 , the same that priceInform in Format.xml.
Starting from 3.0RR17Q2 this format can be set different to the default one at #,##0.0 and #,##0.
The value of this field is defined in priceInform in Format.xml.
Formats in Format.xml:
<Number name="priceInform" decimal="." grouping="," formatOutput="#,##0.00" formatInternal="#0.00"/>
* |- Group 1 (defined currency format: #,##0) |- Store 1.1 |- Group 2 (defined currency format: #,##0.0) |- Store 2.1 |- Group 3 (defined currency format: #,##0.00) |- Store 3.1
The format that would be used in each of the stores would be:
These settings can be configured in Organization window
Print templates are used to print different reports from Web POS. Default ones can be overwritten by others provided by external modules.
In the same way it is possible to change date and numeric formats at Store/Organization level, templates can be defined at those levels. They are set in Organization window in Web POS Formats field section. Precedence of these settings works in the same way as described in previous section.
Do not clean the browser cache - Updating the Client Web POS
In normal operations the client side application is automatically updated when updating Web POS modules on the server. However in some cases it makes sense to refresh the client side application explicitly.
One way of refreshing the Openbravo Web POS client is to clean the cache. Then when refreshing the page the Web POS is reloaded from the server. But as is noted here one should be really careful with cleaning the cache during business operations.
Therefore this section describes a method which allows you to update the client side application without cleaning the cache.
- In the browser with Web POS go to the following URL: chrome://appcache-internals/
- Find the manifest with the url of the Web POS (most likely there is the only one manifest, see below)
- Press on Remove option for this manifest.
- Close the page, close the browser.
- Start the browser, start the Web POS by going to the original WebPOS URL.
Hide Cash Up Information to the Cashier
Since 3.0RR16Q4, it has been implemented a new property configurable from the Preference window named OBPOS_HideCashUpInfoToCashier. This preference allow to hide some critical information to the user in the cash up part.
Follow this link to learn more about this new functionality.
Configuring Web POS Import Transaction Process
From the 2015Q3 version of Openbravo Retail transactions which are sent through the server are imported by a separate process using parallel processing. The benefit of this approach is that it makes the Openbravo Retail solution much more stable in very high volume environments (1000 tickets/minute).
The import process will try to process transactions in parallel:
- tickets of different organizations are processed in parallel
- cashups of different organizations are processed in parallel
- business partners of different organizations are processed in parallel
So if there 10 stores, and in each store there are POS systems submitting tickets/cashups and business partners, there will be a total of 30 processes started. They are executed in parallel if there are CPU-processors available.
The parallel processing and even the disabling of this new import process can be controlled through several configuration parameters which can be defined in Openbravo.properties:
- import.disable.process (available from RR16Q1 release): default not set/false, if set to true then the import process will not run on this application server, is useful if multiple servers share the same database. In that case only server should be dedicated to process import entries, the one's should have this property set to false.
- import.bypass.entry.logic: default not set/false, if set to the value true then the import framework is not used and requests from WebPOS are processed directly.
- import.batch.size: default is 5000, minimum is 1000, defines the number of import entries read by type of data (Order, Cashup etc.) in each loop of the import process. This can be set to 10000 or 20000 if the server has 16GB of memory or more and there are 8 or 16 processors.
- import.number.of.threads: default is number of processors plus 2, minimum: 4, the number of threads available for the main import thread, archiving thread and the actual processors importing data. It depends on the number of cores in the system and also how many parallel processes are expected. A good value is the number of processor cores in the system (plus 2).
- import.max.task.queue.size: default is 1000, minimum: 50, the number of separate import tasks which are queued, the number of tasks depend on the type of data, the implementation of the data importer, for example in WebPOS there will be a separate order importer for each organization, the same for cashups and business partner imports. If there are memory limits and a lot of different stores then this value should be set to a lower value, for example 100.
- import.wait.time: (available from RR17Q1), defined in seconds, default is 600 seconds, when there are no actions which trigger an import entry loop the system will wait a specific amount of time before automatically triggering a read of any current 'Initial' entries. This property defines the wait time between runs/loops of the import entry logic when no other actions happen.
- import.processing.capacity.per.second: (available from RR19Q3). After completing an import entry loop, if there were entries to be processed the main thread will sleep for a period of time in order to give some time to the entries that were just submitted to be processed, during this time new entries will be added to the database but not tried to be submitted. Sleep time is at least 2 seconds, and it is calculated based on this property which defaults to 30 times the number of threads available for processing import entries.
Import Entry High Availability
Before 3.0PR18Q2 release when working in a clustered environment, it was only supported to run the import process in the same (one) node of the cluster. This was done by setting the import.disable.process property as true for that node.
Starting from 3.0PR18Q2 it is possible to configure the import entry processing as a high available service for the cluster. This means, that in case the node in charge of handling the service fails, eventually another available node of the cluster will take care of processing the import entries, replacing the node that failed.
- cluster: defined as true in all the nodes.
- import.disable.process: defined as false (or not defined) in every node which it is desired to enable as available for executing the import process.
Import Entry Cluster Service Settings
Once this feature is enabled, by default, each node in the cluster will check (ping) every 10 seconds if the node in charge of executing the import process is still "alive" or, on the other hand, if it should be replaced with another node of the cluster.
It is possible to change this default time to use a custom value by using the Cluster Service Settings window.
In this window a new record should be created with the following values:
- Cluster Service: Import Entry Cluster Service
- Timeout (seconds): the amount of seconds of the ping interval
Cluster Service Management Extension (JMX)
This feature also provides a management extension available through JMX. This extension provides:
- The ability of monitoring the status of the import entries service. It is possible to check, for instance, the current cluster node in charge of handling the import entries.
- The ability of disabling the ping service. In case the ping is disabled for the node in charge of handling the import entries service, that node will be automatically deregistered, allowing to promote another node in the cluster to be the responsible of processing the import entries.
Web POS Multi-Server Architecture
In the RR15Q4 release Openbravo takes a first step in allowing a WebPOS client to communicate to multiple servers. The first target architecture to support with this approach consists of store servers and one central server.
The store and central server architecture is described in more detail in the next section. The services and server architecture are defined in the back office system using several windows. These are described in the subsections below.
Store and Central Server
Openbravo Commerce Cloud can be deployed in environments in which stores can run a store server instance locally next to a central server instance hosted in the cloud.
A store server installed locally in the store can provide several benefits:
- in case of large master data volumes, these can be loaded in the store server, WebPOS clients can then load (on-demand) the master data from the store server. This ensures operation of the store in case of high master data volumes in combination with offline situations
- performance and robustness in case of lesser-bandwith internet connections to the store. A store server helps to handle many requests from WebPOS clients on the local network instead of making use of the internet connection of the store.
- many WebPOS clients in a store: when there are many WebPOS clients in a store (hunderds or more) then it can make sense to let the WebPOS clients login on a dedicated store server to balance the load across several servers in the network.
The current solution supports the following architecture:
- One central server instance
- One or more store server instances: one store can only work with one store server, but one store server can handle/operate for multiple stores.
The illustration below demonstrates a possible architecture with store servers hosted in the stores and a central server hosted in the cloud.
For backend replication between servers in the network we have good experience with Symmetric DS. For replication of transactions one can focus on replicating the data import entries. The SymmetricDS setup and replication logic for store and central servers will be delivered in a separate module and is targeted for the 16Q1 timeframe.
The store and central-server setup can also be used to define a failover mechanism in WebPOS. WebPOS clients will automatically switch from the store server to the central server if the store server is accidentally offline.
Base Setup: Enabling Preference & Multi-Server Authentication
This section describes several setup steps which need to be done before you can use Openbravo in a multi-server.
The enablement of the multi-server-communication functionality is controlled by a preference which by default is not set and therefore disables the multi-server logic.
So to enable multi-server-communication behavior for your stores you need to define the preference 'Mobile Multi-Server Architecture Enablement' (see screenshot below) with value Y and 'Selected' checkbox with value Y too. This preference needs to be defined on System level by the System Administrator.
The preference enables multi-server behavior for all WebPOS clients in the system across all clients/organizations/stores. But multi-server behavior will start only if there are Mobile Servers defined, so if you do not define mobile servers (see below) then the multi-server functionality is not operational and the WebPOS clients will work in the standard way. Also: you can assign servers to stores specifically, so it is possible to test multi-server behavior first for WebPOS systems of specific/selected stores.
Then as a second step, it is needed to enable specific authentication on each of the servers. This to support multi-server login. In each server which can be used from a WebPOS client the following authentication manager has to be set in Openbravo.properties:
Note: the value of the mobile.server.key should be taken from the mobile server definition, see later subsection.
Finally, if tickets are send to multiple servers simultaneously from WebPOS then it makes sense that the related documents of the tickets in the different servers have the same document numbers. To make sure this happens set the preference "Use Order Document Number for Related Docs" to Y:
This section described the first-base setup. The next step is to define the mobile servers, specify which services they provide and assign them to stores/organizations.
Mobile Server Authentication
The above section specified how to set the authentication manager.
To provide some background information: the mobile server authentication manager uses a symmetric-shared-key logic to authenticate a WebPOS client on several servers withour requiring to relogin.
The key is never send to the WebPOS clients but stored on the server. It is an generated key which is created automatically at first login and then replicated to all store servers.
It is possible to regenerate the authentication key. This should be done in off-hours when none of the stores are operating. To regenerate the authentication key login into the central server backoffice. Goto the role which is linked client for which you want to change the key. Then in quick launch start the 'Recreate Mobile Server Authentication Key' process. You see a popup with an information text, click ok to regenerate the authentication key.
After recreation the new authentication key is replicated to all store servers. The tomcat of all the store servers need to be restarted and all users should relogin.
When testing with multiple servers it is often not possible to setup replication logic directly between the central and store servers. This means that the servers will not have a shared key available to them. To force the servers to use the same authentication key you can set the key in the Openbravo.properties file.
To make use of the test key it is mandatory to also set the test.environment property to true.
The following properties have to be set:
Preferences: token age, offline ping
For a complete overview of all the relevant multi-server preferences please visit this page.
The services definition is done by developers and provided by modules. They are available under the System Admin role and shown as a reference here.
A description of the meaning of the fields:
- Module: services are provided by and implemented in modules
- Service: the service name, currently uniqueness of service names is not checked, the service name is used in client side code to call a service
- Routing Type: defines how the transport layer in the Web POS client should call the service:
- Fail Over: mostly used for querying services, if a call to a server fails for this service then Web POS will automatically try another server which provides the same service
- Transaction: as the name indicates is mostly used for transactions (such as new tickets/customers). Is similar to fail over, so servers are tried one by one until there is a server which can receive the transaction. The difference with fail over is that the system will store the message in the database and continue retrying until a server is able to receive the transaction. This makes this mode more robust than fail over which stops after all servers have been tried.
- Broadcast: the service request is automatically send (broadcasted) to all servers providing this service. Failed messages are not repeated. This type of request is useful for example for logout.
- Ping: a special service used to detect when a server is back online. Is used in the scenario that a server is offline (detected because another service request fails). In that case the Web POS client will ping the offline server to detect when it is back online
- Default Timeout: Time in seconds defined by default in the module for the request timeout related to the Mobile Service.
- Timeout: Time in seconds defined by the user, which overrides default timeout, for the request timeout related to the Mobile Service.
The service name uses 'contains' to match it with the requests from the client. So a service name of 'org.openbravo.retail.posterminal.master' will handle all the client side requests with 'org.openbravo.retail.posterminal.master' in the requested URL. In this way for example all the master data requests can be mapped to a server.
Note: In case of having more than one service for a given Service name, it gets longest name service. Longest name service will be the most similar to Service name. Avoid creating Java classes which contains another Java class name.
The following are examples of standard services, see the total list of services in the mobile core and webpos modules:
- org.openbravo.mobile.core.login.ContextInformation: retrieval, provides the current client/organization of the current user (after logging in)
- org.openbravo.retail.posterminal.CustomerAddrLoader: transactional, stores updated and new addresses in the database on the server
- org.openbravo.retail.posterminal.CustomerLoader: transactional, stores updated and new customers in the database on the server
- org.openbravo.retail.posterminal.master.BPLocation: retrieval, retrieves the business partner address from the server
- org.openbravo.retail.posterminal.master.BusinessPartner: retrieval, retrieves the business partners from the server
- org.openbravo.retail.posterminal.master.DiscountFilterBusinessPartner: retrieval, reads the discounts by business partner from the server
- org.openbravo.retail.posterminal.master.Product: retrieval, reads product data from the server
- org.openbravo.retail.posterminal.OrderLoader: transactional, stores new and updated tickets in the database on the server
- org.openbravo.retail.posterminal.PaidReceiptsHeader: retrieval, reads tickets (and layaways and quotations) from the server
- org.openbravo.retail.posterminal.POSLoginHandler: retrieval, login service
- org.openbravo.retail.posterminal.ProcessCashClose: transactional, stores the cashup on the server
- org.openbravo.retail.posterminal.ProcessCashMgmt: transactional, stores the cashup on the server
Mobile Server Definition
The Mobile Server Definition window allows you to define the servers which are available for WebPOS clients. Servers are used by WebPOS clients for logging in, retrieving master data, sending tickets/cashups and other transactional data.
A distinction is made between a store server and a main server. Store servers are mainly used for a specific store for logging in and querying. Main servers are used to store transactional data. Only transactions send to a Main Server are considered to be synchronized and are considered to be save. The 15Q4 Release assumes that a Web POS system has one main server (which can be shared by many Web POS clients). This main server receives the transactions. In addition there can be several store servers defined for logging in and providing querying services.
A store server can be used for system load distribution or if installed locally in the store can ensure store operation also when the store looses internet connection.
The setup for the rest allows a large degree of flexibility. It is perfectly fine to not have a store server and only main servers. Or to let smaller stores work on a single main server, while a large store has its own store server.
The image below illustrates the definition of a server:
A description of the meaning of the fields:
- Name: any unique name is allowed
- Description: additional description for describing the purpose of the server
- Server Type: there are two types:
- Main Server: a main server is often used to store transactional data such as new tickets/updated business partners etc. Only transactions send to a main server are considered to be synchronized and save.
- Store Server: a store server is mainly used for load distribution and if locally maintained to ensure store operations when the store looses internet connection.
- URL: the main url by which the server can be reached, see the examples above/below, should include the webapp context path (openbravo in the examples here)
- Priority: if multiple servers can provide the same service then they are tried in order of priority. This is relevant for failover services which are will be called on the first available server. If a server is not available then the next in line is tried (in increasing order of priority number). In a setup with a main server and store server(s) then the store servers normally have a higher priority (lower number) than the central server. This ensures that the WebPOS clients will first access the store server before trying the central server.
- All Organizations: if this checkbox is checked then the server is made available to all WebPOS systems and the organizations defined in the 'Organizations by Server' are ignored. If unchecked then the 'Organizations by Server' information is used to determine if a server is to be used by a WebPOS client.
- All Services: if this field is checked then the server is assumed to provide all services. If unchecked then the information in the subtab 'Services by Server' is used to determine what services a server can provide.
- Defined services (from 16Q2): if All Services field is unchecked then we will see this field and we can select All excluding defined or Only those defined. If Only those defined is selected then the information in the subtab 'Services by Server' is used to determine what services a server can provide. If All excluding defined is selected then the information in the subtab 'Services by Server' is used to determine what services a server cannot provide.
- Mobile Server Key (from 16Q1): is the unique key for the server, should be set in each server in Openbravo.properties, for example as: mobile.server.key=Central
- Server Status (from 16Q1): gives the current status of the server (offline, online, transitioning). See the Store Server page for more information on server status handling.
- Reload Status (from 17Q2 when the replication module is installed): defines the status of the initial data reload logic. For more information see this page.
- Version Status (from 17Q2.1 when the Store Server Retail module is installed): the version status shows if the store and central server have different versions. Field is relevant for store server updating. The following values can be shown:
- Same as Central: store and central server have the same version for the modules which they have in common
- Different from Central: store and central server have different versions for the modules they have in common
- Version (from 17Q2.1 when the Store Server Retail module is installed): the version is computed from the versions of all the modules installed on the store server. So store servers with different module (versions) will show different overall version numbers. A higher version number means a newer server, this because version numbers can only increase over time. Field is relevant for store server updating.
- Allowed Origin Domains (from 17Q1): a list of comma or new-line separate domain definitions. Each domain value can be a complete domain (including http/https and the port number) or a regular expression. See the screenshot above for examples. See the next section for more information.
- Offline Log/Cause (from 17Q1): if the store server is offline then this field gives information on the reason for being offline. See here for more details.
Allowed Origin Domains Field - Cross Domain Requests
Openbravo supports doing requests from a Web POS client to multiple servers in the architecture. The Web POS client has a url pointing to one host from which it obtains the source code. Requests to other servers (to search for products for example) are therefore so-called cross domain requests. Cross domain requests are handled specifically in web environments requiring special configuration.
A Web POS client is only allowed to call the other servers in the environment if the domain of the original url of the Web POS client (from where it loads the webpage itself) is:
- defined as an Allowed Origin Domain in any of the Mobile Server Definitions
- is the domain of the url of any of the Mobile Server Definitions
- if you define the store server with an url: http://store1.openbravo.com/openbravo and there is a central server with url: http://central.openbravo.com/openbravo.
- let's say that there is an alias host mystore.openbravo.com pointing to the same server as store1.openbravo.com.
- then a Web POS client loaded from http://store1.openbravo.com can do requests to central.openbravo.com, this is allowed and supported.
- however a Web POS client loaded from http://mystore.openbravo.com can not do requests to central.openbravo.com.
- to allow also Web POS clients loaded from mystore.openbravo.com to call central.openbravo.com you have to add: http://mystore.openbravo.com to the Allowed Origin Domains field of any Mobile Server Definition.
If you don't set the Allowed Origin Domains field then Web POS clients can only call other servers if they are loaded from the exact url/domain as defined in the mobile server definition of their respective store.
If you try to load the Web POS from a URL/location which is not defined as the url of a mobile server or allowed origin domain then when loading the client you will get a message as shown below.
In addition you will see messages like this in the log:
XMLHttpRequest cannot load http://store1.openbravo.com:8080/openbravo/org.openbravo.retail.posterminal…ls?terminalName=VBS-1&command=userImages&appName=WebPOS&0.7785557618144872. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://127.0.0.1:8080' is therefore not allowed access.
Mobile Server Organizations - Stores
A server can be linked to all organizations (stores), so it is available for all WebPOS clients, or a server can be assigned to a specific set of organizations (stores).
To flag a server to be available for all organizations, check the 'All Organizations' field in the server definition.
If you want to assign a server to a specific set of organizations/stores then you can use the sub tab 'Organizations by Server'. Make sure the 'All Organizations' checkbox is not checked in the server definition and then add records in the 'Organizations by Server'. Multiple servers can be assigned to multiple organizations and vice versa.
The Openbravo organization structure also plays a role here, so assigning a server to a parent organization automatically makes it available for all the child organizations of that parent organization.
Mobile Server Services
The information in this subtab is used when the 'All Services' checkbox in the Mobile Server definition is not checked.
'Defined services' value will define which services are available for the server. If Only those defined is selected then the information in the subtab 'Services by Server' is used to determine what services a server can provide. If All excluding defined is selected then the information in the subtab 'Services by Server' is used to determine what services a server cannot provide.
This subtab allows you to specify which services are provided by which server. There is a fair amount of freedom in assigning querying services. You can load products from one server and business partners from another server.
The thing to ensure though is that if users in WebPOS can create new customers and tickets that the tickets and customer are send to the same server. Or that the data between servers is synchronized in a different way. Also the cashup can only be send to a server which also receives or has all the WebPOS orders. This means that either the servers are synchronized in the backend or that all transactions are send to a server. All transactions can also be send to multiple servers.
The example below shows how all transactions services are assigned to a specific main server.
Modules by Server
This subtab is available from 17Q2.1 and only if the Retail Store Server module is installed.
To provide complete visibility of what is installed in your environment you can check the Modules by Server sub tab in the Mobile Server window. It shows the modules installed on the store server with their respective version numbers.
Multi Server Configuration: preferences and process
Multi server functionality is disabled by default. To make use of this advanced functionality you have to set specific preferences. In addition there are several preferences which control the behavior of multi-server logic. All these preferences are described in this page.
Store Server Backoffice ERP access disabled
The backoffice user interface is not official supported for the store server. This because the store server architecture assumes that changes in the store server are provided through webservices or symmetric ds replication and not done directly through the user interface.
It is therefore the safest if the backoffice ERP access is disabled. This can be done by setting a preference: Restrict ERP Access in Store Server to 'Y'.
This preference should be set by the system admin. If you need access to the store server backoffice UI to view current transactions or other diagnostic information then you can temporarily deactivate this preference by logging in with a system admin user/role.
Synchronized Transactions in Multi-Server Environments
The multi-server functionality is also supported for synchronized transactions. Synchronized transactions are defined as a fail-over service.
Synchronized transactions in a multi-server environment have specific characteristics. These are described in detail in the following document.
Supporting High Volume Master Data: Remote Master Data Handling
To support high volumes of products, customers and tickets, Openbravo allows you to work remotely with master data from the WebPOS client. The high volume master data is then not loaded into the WebPOS client database but accesses when needed on a server. The server can be a locally in-store server or a server available in the cloud.
The following data can be handled remotely from WebPOS clients:
- Customer and Customer Addresses
- Discounts by Customer
By enabling remote data handling the WebPOS clients are capable of working with millions of products, prices and customers. The remote data handling can be combined with the Openbravo multi-server architecture functionality to define (local store) servers which provide product/customer data querying services to Web POS clients.
By default remote data handling is disabled. The enabling of the remote data functionality is controlled by several preferences which are discussed in the next section.
Note that enabling remote data has as a consequence that it is not possible to operate the WebPOS client in complete offline mode. There are solutions to work with a local store server (physically located near the terminals - on the same local network) which can help in these type of specific cases.
Remote Data Preferences
Several preferences are used to control which data is handled remotely. These are illustrated in the screenshot below. The screenshot below shows that by default the remote-data preferences are set to N. To enable remote data handling you have to define the related preferences and set the value Y. In addition, 'Selected' check-box has to be set as Y too. In the screenshot below this is illustrated.
Note: it is important to define the preferences on at least one of client/org/user/role level to ensure that the system will prefer it over the default preferences which are set to N.
Use Contains Remote Data Preferences
There are also two preference more for remote searching: Use contains in Remote Customer search and Use contains in Remote Product search. By default, remote queries are done using starts With to filter in order to improve performance of those queries. In case of you need to filter using contains, you can create these preference setting them to 'Y' to have this ability in Web POS for remote models. Non remote models already use contains to filter.
Remote Data: Product Categories
In case of a high volume of product master data, so when products are accessed remotely then the way product categories are loaded by the WebPOS clients is also changed. The system needs to run an update process in a daily (for example) batch to determine which product categories should be loaded by which WebPOS.
After running the process the product categories which are loaded in the client are displayed in the assortment. Note, the subtab is only visible if there are product categories linked to an assortment.
Remote Master Data Limitations - Future enhancements
In the 15Q4 release, the remote data capability also has some limitations, these will be addressed in future releases:
- No client-side product catalog: the Openbravo product catalog functionality will be enhanced in a next release to work with remote product data. In the 15Q4 release it is assumed that the user will find products by scanning or searching for products. In the 16Q4 release a new hierarchical product catalog search will be added.
- No product characteristic support: remote product data can not be combined with product characteristic search. From the 16Q1 release onwards product characteristic and brand search is supported also for remote product data.
- No alphabetical search bar in customer search: the alphabetical bar on the left of the customer search is not available when customer data is remote, the search filter text field is there to search for customers.
- No automatic search customer/product when entering search term: with remote product/customer enabled after entering a search term in product/customer search the user has to explicitly tap the search button, with the remote preference set to N the search will automatically happen after 3 characters have been entered.
- Discounts: discounts are mostly all loaded in the client side Web POS database, only the business partner discount definitions are loaded on demand when a business partner is selected for a ticket. This means that:
- Openbravo can support 10-thousands of discount definitions on product, product category or business partner category level. They are loaded in the WebPOS client side database.
- But Openbravo can not support 100-thousands or more discount definitions on product/product category or business partner category level. This would make the WebPOS client too slow.
So in high volume environments it is better to limit the number of discount definitions by defining them on product/BP category level or only for specific business partner.
Default Web POS layout in case of remote product data (no browse/catalog option):
Retail Extension Modules enabled for Remote Data
In the subsequent releases many extension modules have been checked for their support of remote product/business partner data. Also automated tests have been added to ensure continuous correct operation with remote data.
This is the current (16Q2 release) list of modules which have been tested with remote data, most are also tested automatically:
- Gift card new entities
- Physical inventory
- Complementary products
- Copy Store
- Gift Card
- Print Giftcard
- Stock Criteria
- Price Criteria
- Retail Sessions
- Stock Validation
- Multi Tax Category
- Multi UPC
- Show Prod Description
- Tax Exempt
- Mobile Warehouse
- Multi Price List
- Print Last Ticket
- Retail Training
- Retail Analytics
- Level Pricing
- Best Sellers
Discount Modules (see limitations section, the remark for discount setup there still applies):
- Retail Discounts
- Best Sellers
- Copy Bestsellers
- Discounts by Total
- Combo Discount
- Two Families Discount
- Active Discount Popup
- Best Deal
- Discount Matrix
As a next step parallel to the 16Q2/Q3 releases we are adding automated tests on high volume datasets for many of these modules. This section will be updated when the automated tests on high volume data are enabled (probably around 16Q3 timeframe).
Terminal information and logging
Since 19Q1 release, the WebPOS is able to log any user action and system process execution which took place during the usage of the application. This information is then sent to the server, and stored in Openbravo.
A system administrator can then review this log to debug the system and better understand the causes of errors.
What can currently be logged
Currently three main items can be logged:
- Any user action:
- Clicks on buttons, key presses
- Any process execution (you can find out what processes are, and how they are defined, in this [ http://wiki.openbravo.com/wiki/Retail:Developers_Guide/How-to/Add_Mobile_Process howto ])
- Technical log messages generated with the old "log client" API (you can find out more about it here
How the log is generated
Both user actions and processes are logged automatically, the developer or admin doesn't need to do anything about it. Technical log messages are logged if they have been added in the code.
The log is collected in the frontend, and then is synchronised to the backend in an efficient way
There are several preferences which allow system administrators to configure how much log they want the system to generate:
- Enable Terminal Log User Actions: If set to 'Y', the system will collect and save all user action events.
- Enable Terminal Log Process: If set to 'Y', the system will collect every start or finish event of any execution of any process which has been defined to appear in the log (this can be configured per process, in the Mobile processes window)
- Terminal Log Synchronization Interval: The time frequency in which the user actions and processes log will be packaged and synchronised to the backend. Default value 30 secs
- Log Backup Interval: Frequency of save the info of log from ram to disk. Increasing this value will result in less resources usage in the client, but will increase the risk of lost log in case of unexpected shutdown. Default 1 sec.
- Mobile Log Client Activate Log (Y/N): The logs will be saved or not in the backend (by default Y)
Mobile Log Client Save Level (Trace/Debug/Info/Warn/Error/Critical): Level of logs saved in backend (by default Warn) Mobile Log Client Console Level (Trace/Debug/Info/Warn/Error/Critical): Level of logs displayed in console (by default Info)
Reviewing the log
Once generated, the log can be reviewed in the Terminal Log window. On this window, you can filter by device id (terminal), date, log level (so you can show each of the log categories independently, or combined), and context.
The context is a descriptor of the state of the system the moment a particular log even was generated. In the case of the WebPOS, it can contain either the name of the window (and modal popup if there is one open), and specifically in the main WebPOS window, it will contain the document number of the ticket which was open in the screen. This can be very useful to get all the log events which happened in the context of one particular ticket.