View source | Discuss this page | Page history | Printable version   
Main Page
Upload file
What links here
Recent changes

PDF Books
Show collection (0 pages)
Collections help


Retail:Configuration Guide

Back to main page



This document describes how to configure the following specific settings of the Openbravo Commerce Suite:

For generic documentation about Openbravo configuration please follow the Quick Guide.

If you are trying out Openbravo Commerce Suite 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

Bulbgraph.png   The Retail system manages to hit a bug in the PostgreSQL database version as being currently shipped in the Openbravo rPath Appliance which can lead to bad performance of the application. To avoid this for the moment we recommend to use the On Demand or Ubuntu installation methods

The Openbravo for Retail module is the main module of the Openbravo Commerce Suite. 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):

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:




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:

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 Configuration

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:


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:


Category Tree Configuration

Select menu option: Application / Master Data Management / Product setup / Product Category. Push button to show Tree Grid Visibilty.


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:

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:

CountDifferenceLimit Org.png

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:

CountDifferenceLimit POSTermType.png

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.

Approval Reason

Navigate to POS Approval Reason window and edit/add the reasons, as shown on following figure:

CountDifferenceLimit ApprovalReason.png

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.

CustomersConfiguration rmp19.png


The following preferences have been created:

Grouped products

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.

Since RMP32 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 (Not allowed before).

Non Returnable Products

Bulbgraph.png   Starting from RR17Q2 below functionality is available

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:


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

OBPOS enable show stock.png
Bulbgraph.png   Starting from RR16Q2 below functionality is available

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.

CCWarehouse button.jpg

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

Included CCWarehouses.jpg

After this configuration, Web POS will open the stock window when a product is clicked in order to be added to the ticket.

OBPOS view cross store.png

Product Images

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.

OBPOS image preference.png

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.

OBPOS generateimageprocess.png

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.

Anonymous Layaways

Bulbgraph.png   This configuration will be available starting from RR16Q2

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

Bulbgraph.png   This configuration will be available starting from RR16Q4

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.


Web POS module

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.).

Most of the configuration take place in two windows:

The POS Terminal Type window contains what can be described as a "POS Terminal Configuration". This is a configuration designed to model a type of POS terminal. Each POS Terminal can only have one POS Terminal configuration.

It allows a very flexible configuration and an example would be a multi-store company. Each store could be managed differently (e.g have different cash up processes). In this case, different Pos Terminal Types could be defined for each store. And terminals within same store could share the same Pos Terminal Type.

This two tables are designed to simplify the configuration process for the user: if the user needs to configure 100 terminals, but all of them are basically identical, then the amount of data he will need to insert is quite small, because all POS terminals will point to the same POS Terminal configuration.

In this section, we will first describe how POS Terminal Types are configured, and then we will describe the POS Terminal window.

POS Terminal Type window

In this window, you basically design a POS Terminal configuration, which will be used by one or many POS terminals. Here you configure relevant information at POS level, but also at payment method level.


In the header, you configure the following fields:

In addition to these, there are two more fields which define how the masterdata reloading is done:

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.


In the Payment Method tab, you configure the following fields:

Cash Up

Cash management

Bulbgraph.png   Starting from RR15Q2 below functionality is available

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.


Hardware URL

Bulbgraph.png   Starting from RR17Q1 below functionality is available

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 terminals with the same POS Terminal Type and it must be configured using the Hardware Manager window.


Terminal for Seller

Bulbgraph.png   This feature is available starting from 3.0RR17Q3.

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 terminal to be a Terminal for Seller, the terminal needs to belong to a Pos Terminal Type with an specific configuration:

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:

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 terminal is not considered to work with payments, there are some flows that may need to get money back. Those flows are:

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

POS Terminal window

In this window specific POS terminals can be added. Every POS terminal needs to be added here.


In the header, the following fields are configured:

Bulbgraph.png   Starting from RR16Q3 below functionality is available


In the payment type, the following information is configured:

Very important. Payment methods are secured by Search key value in Role preferences. There are three predefined values: for cash payments. 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 posterminal has an open cashup. This window is to define configurations before start working in Web POS, if you change the configuration while the terminal is operating you could have errors in the terminal or data inconsistency.


In the cash up history, the following information is configured:

In the reconciliation subtab, the following information is configured:

Bulbgraph.png   The functionality described below is available starting from 15RRQ2
Bulbgraph.png   Starting from RR15Q4 below functionality is available

In POS Terminal window you can define a hierarchy of terminals in order to allow to share any payment method you have accross terminals 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” terminal cannot be slave of any terminal.


A POS terminal can use both standard payment methods and shared payment methods at the same time.

When a POS terminal is defined in the backoffice, another terminal can be specified as its “master”. When this is done, two important changes happen in the POS operation:


Bulbgraph.png   The functionality described below is available starting from RR17Q2

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.

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 new orders, shipments and invoices 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 POS 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.

Therefore the advice is to let different POS Terminals use different document sequences, especially in high volume environments. This means that different POS terminals will have to make use of different POS Terminal Types.

Querying performance

Bulbgraph.png   Starting from RR16Q1 below functionality is available

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...).

Synchronized order

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

Bulbgraph.png   Starting from RR17Q1 below functionality is available

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:


Security Settings

View larger

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:

Setting access to specific functionality:

Note roles defined as Automatic (Manual field is unchecked) have access to all functionality regardless preferences.

The following functionalities are relevant for Web POS users:

The following functionalities are related to Quotations:

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.

View larger

The following rules are followed to decide whether a user has access to a terminal or not:


Bulbgraph.png   This feature is available starting from RMP26

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:

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.

Approvable Actions

Here is the list of actions that can require approval:

Audit Information

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. 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 should be created for the affected client and it should be visible for Organization "*"

Term authentication preference.jpg

Remember that if terminal authentication is enabled, every terminals will share the same URL and then a specific terminal will be linked.

If security is not enabled we need to put the terminal searchKey in the URL.

Other Settings

The following preferences can be also set.

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.

Bulbgraph.png   Topics covered in this section below this line are available starting from RMP31

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.

Bulbgraph.png   Topics covered in this section below this line are available starting from RMP31

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.

Bulbgraph.png   Topics covered in this section below this line are available starting from 3.0RR17Q2

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"/>

Organizations/Stores definition:

  |- 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:

Store Currency Format
Store 1.1 #,##0
Store 2.1 #,##0.0
Store 3.1 #,##0.00

These settings can be configured in Organization window

Print Templates

Print templates are used to print different reports from Web POS. Default ones can be overwritten by others provided by external modules.

Bulbgraph.png   Topics covered in this section below this line are available starting from RMP31

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.

  1. In the browser with Web POS go to the following URL: chrome://appcache-internals/
  2. Find the manifest with the url of the Web POS (most likely there is the only one manifest, see below)
  3. Press on Remove option for this manifest.
  4. Close the page, close the browser.
  5. Start the browser, start the Web POS by going to the original WebPOS URL.


Hide Cash Up Information to the Cashier

Bulbgraph.png   Starting from RR16Q4 below functionality is available

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

Bulbgraph.png   Starting from RR15Q3 below functionality is available

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:

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

Web POS Multi-Server Architecture

Bulbgraph.png   Starting from RR15Q4 you can configure a WebPOS client to operate in a multi-server system architecture.

In the RR15Q4 release the Openbravo Commerce suite 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 Suite 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:

The current solution supports the following architecture:

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

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.

Test Setup

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 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.

Mobile Services

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:

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:

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 of the Commerce Suite assumes that a WebPOS system has one main server (which can be shared by many WebPOS 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:


Allowed Origin Domains Field - Cross Domain Requests

Openbravo Commerce supports doing requests from one WebPOS client to multiple servers in the architecture. The WebPOS 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 WebPOS client is only allowed to call the other servers in the environment if the domain of the original url of the WebPOS client (from where it loads the webpage itself) is:

For example:

If you don't set the Allowed Origin Domains field then WebPOS 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 WebPOS 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.

Cors error load webpos.png

In addition you will see messages like this in the log:

XMLHttpRequest cannot load…ls?terminalName=VBS-1&command=userImages&appName=WebPOS&0.7785557618144872.
No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin '' 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.

StoreServerUpdate Modules by Server.png

Multi Server Configuration: preferences and process


Bulbgraph.png   This functionality is available from RR16Q1.

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

Bulbgraph.png   This functionality is available from RR16Q3.

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 OB Commerce 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

Bulbgraph.png   Starting from RR15Q4 below functionality is available

To support high volumes of products, customers and tickets, Openbravo Commerce 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:

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 WebPOS 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:

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 WebPOS 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:

Discount Modules (see limitations section, the remark for discount setup there still applies):

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).

Retrieved from ""

This page has been accessed 81,238 times. This page was last modified on 23 May 2017, at 07:12. Content is available under Creative Commons Attribution-ShareAlike 2.5 Spain License.