With the Store Server solution the Openbravo Commerce Suite takes a major step in supporting retail environments which need in-store server capabilities because of high volume of transactions and master data or varying store-internet connectivity. The Store Server functionality is delivered as part of generic multi-server capabilities of OB Commerce.
The OB Commerce store server architecture serves two main purposes:
- Uninterrupted POS solution by off-line operations and transparent synchronizations
- High-availability and high performance during peak transactions for example during special events such as Black Friday.
The main characteristic of the Store Server solution is that it allows a OB-Commerce server to be installed in the store itself (or in the cloud) serving the specific store. The store server operates together with a central server. The central server can act as a backup/fail-over server if the store server is not available and vice versa.
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-bandwidth 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
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. The SymmetricDS setup in the Openbravo Commerce suite is discussed separately further down in this document.
Store Server - Central Server - Openbravo Commerce
The Store Server is a newer solution within the Openbravo Commerce Suite. A store server or central server is in essence a standard Openbravo Commerce instance. All our solutions use the same technology and platform. Different functionality for store or central is implemented by installing different modules or developing different code for the instance.
The common technology/platform provides many benefits for users, developers and system admins. This because the same development, usage and maintenance practices apply to the store server as well as the central server. They are all Openbravo servers.
Still there is a clear focus on the Store Server being a more minimal Openbravo server, providing only the functionality and api's relevant for in-store operations. A main reason for targeting a focused solution is that then only specific data and transactions need to be synchronized between servers. This should be done in a controlled manner.
The main entry point for a user of the store server will be a mobile front end.
In a multi-server environment it is critical that data in different servers is synced. Openbravo provides two different methods for data syncing:
- database level syncing using Symmetric DS: this works best for master data where there is a clear lead which system manages the data. Normally the master data is synced from the central server to the store server.
- transactional messaging: transactional messaging is a good approach in case of syncing complex transactions, such as consuming a stock. This type of data often flows from the store servers to the central server.
The advantage of the first (database level) approach is that it is very easy to setup. You only need to add an entry in the application dictionary to define a synced table. This type of replication can be used to handle master data and straightforward transactional updates (bidirectional even).
Each of the two methods is explained in more detail further down in this document.
Online & Offline concepts of Store Servers
An important feature of the store and central server management is keeping track of the connection status to other servers. The connection status to other servers (most importantly the central server) controls the 'online status' of a store server.
If a central server can be reached a store server is online, if it can't be reached a store server is offline. If the central server itself is offline all store servers are offline also. Moving to one state to another is a so-called 'transitioning' state.
In online mode the store server acts as a pass-through, all requests from the WebPOS systems are forwarded to the central server for processing. When the store goes to offline then the WebPOS requests are handled locally in the store this until the store transitions back to online.
The details of offline and online concepts are described in this page.
Synchronous transactions supports the idea that a WebPOS user should wait for the transaction (new ticket/updated business partner etc.) to be completely processed on the server. This to ensure that the user is notified instantly if processing fails for some reason. Also if processing on the server fails nothing is to be stored on the server. The user can execute the same transaction again to retry.
In contrast, asynchronous transactions (the WebPOS default) work differently: user transactions are executed on the client and then send to the server in the background. The user can continue with the next ticket while the server processes the transaction at the same time. The advantage of this approach is that it performs very well in high volume situations. For the user the system is very fast and he/she can continue performing the next task immediately. The asynchronous approach also supports the idea that it is important to continue selling and any processing issues on the server should be solved by the backoffice.
Therefore by default OB Commerce works in asynchronous mode. You can enable synchronous transaction mode by setting the preference WebPOS Synchronized Mode to Y. When set to Y then all WebPOS transactions (ticket, business partner, cashup, cash management, etc.) will run in synchronized mode.
- For multi-server environment synchronized transaction functionality will result in web service calls to be also executed on the central server in synchronized mode. For more information see this document: Synchronized_Transactions_in_Multi-Server_Environments.
- Synchronized mode only works for transactional data and master data (like updating or adding a business partner/address) which is handled remotely. So you need ti enable remote datasources for this data to work with in synchronized mode.
For WebPOS, in synchronized mode the user sees a popup like shown below while the transaction is being processed.
As you can see the ticket is still available in the background. The ticket is removed only when the transaction successfully processes on the server.
For more details specifically for this page, see the 'Developing_with_Synchronized_Transactions' page.
Store Server Creation Procedure
Creating a store server consists of system admin tasks as well as exporting and importing store server data. The details are described in this howto:
After reading the above howto it can make sense to try it out using the Openbravo multi-server sample data. For this refer to the following quick/short howto:
The store and central server uses the same technology as the standard Openbravo Commerce solution. They are the same as any Openbravo server, possibly only with different modules and logic. So all the developer documentation available for ERP and Retail is also relevant when developing specific functionality for multi-server environments:
This section therefore focuses mainly on the specifics related to developing multi-server functionality. We provide several howtos which guide you as a developer through defining and setting up a development environment and writing store or central server specific functionality:
A good starting point for multi-server development is to start with this checklist. It helps you to understand specific details which you should consider when developing for multi-server environments and synchronized mode.
Then next take a look at the other relevant HowTos for store server development:
- Developing with Synchronized Transactions
When you encounter issues while developing and deploying store servers it can make sense to check the troubleshooting page.
Adding table/entities/columns to the store server solution
It is quite common when developing to extend the db schema (add new tables or columns) which are to be used on the store server. Often the information in these new db schema elements has to be synced to the central server (and back).
A general statement is:
- transactional data is synced from central to store (normally) or vice versa if the store server was disconnected from central
- master data is synced from central to store
Both type of synchronizations can be handled through replication. For this we use Symmetric DS. When you add a new table or column you need to make sure that the data is read/used when creating a new store server and also later when it changes. This is discussed in more detail in the howto here:
Data Sync & Replication
In a multi-server environment running multiple instances of Openbravo Commerce it is critical to ensure data consistency. One of the techniques we use for this is data replication using Symmetric DS. This section contains guides and howtos on how to set up and work with Symmetric DS.
- How to Configure and Start the Synchronization Engine
- Monitoring Symmetric DS Replication Data
- Monitoring and Managing Synchronization Errors
- How to Configure the Synchronization of a Table
- How to Define a SymmetricDS Extension Point
- Managing the Store Servers registered in the Main Server
- How to Reload the Contents of a Synchronized Table
- How the Purge Job Works
- How to Configure Custom Routers
- How to Update the Configuration Tables of SymmetricDS
- How to Disable the SymmetricDS Triggers
Store Server Configuration, Status Handling
To work with store servers it is important to configure specific preferences. This is described in this section.
For a complete overview of all store specific preferences please check this page.
Store Server Operational Maintenance
This section of the store server landing page discusses different topics which are relevant when running a store server solution.
The main idea is that the system/application admin should be able to control the complete environment from the central server backoffice. Only in very specific cases it should be needed for an admin to visit the store server backoffice to perform maintenance activities.
Updating an Openbravo Multi-Server Environment
Installing new features and fixes in a (larger) production environment is a carefully organized activity. This is even more true for multi-server environments in which all servers should use the same software version.
With the Openbravo Central and Store server solution the main approach is to first update the central server and then the store servers. During the update process it is possible that the central and store servers temporarily have different versions. This is more apparent with a large number of store servers as it takes time to update them all. The Openbravo solution manages this situation by detecting version differences and limiting data exchange between servers with different versions.
The information in this wiki describes the main concepts of the update process and how Openbravo handles special situation like version differences between servers during the update process. It does not describe the detailed system management scripts or steps.
The store server update documentation is divided in several different parts:
Data - BP Segmentation
A specific store server topic is data segmentation: which data is replicated to which stores. In some regions in the world there are privacy considerations to only share customer data to stores in which the customer has executed a transaction. To support these environments the OB Commerce suite supports the concept of BP Segmentation.
The details of this concept are described in this page.
Multi-server Process Request Handling
In a multi-server environment the idea is to manage the store servers from the central server backoffice. The system/application admin should preferably not need to visit the store server backoffice. One of the topics which the application admin can manage from the central server is the scheduling of process requests at the store server. The admin can perform this task from the central server, scheduling and unscheduling process requests on one or more store servers. Also the runtime log of the process requests is aggregated to the central server.
For more information visit the specific page on this topic.
Monitoring and Managing (Error) logs
The system admin can monitor the store servers from the central server.
There are different types of logs which can be monitored.
- Processing: processing errors occur when the WebPOS client sends a json message to the server and the server can not process it. The OB Store Server solution provides the POS Errors from Mobile Servers function to help you view and resolve POS errors in the store servers from a central location (central server backoffice).
- Replication and Synchronization errors occur when data is replicated between servers: Monitoring and Managing Replication and Synchronization Errors
- Client Logging: all the webpos clients log client side events (info, warn, debug, error). All web pos client logs are send directly to the central server and are available through the Log Client window.
Replicating Document Sequence Number Changes
Increases in document number sequence changes are automatically synchronized bidirectionally from store to central and vice versa. However when a document number is decreased by replication the system will prevent this replication to ensure future unique document numbers.
Still there are cases when the document number is decreased manually. For example when resetting the document number to zero yearly.
For this business case the store server solution supports a specific approach to synchronize the decreasing document number from central to the stores. A new button has been added in the document sequence window. Select the document sequence which has a decreased next number and press the button. This will replicate the change to the store servers.
Replicating Gift Cards
For larger organizations it does not work to replicate all the gift cards to all the store servers to support offline operations. In this case it makes sense to distinguish between local and global gift cards. Local gift cards are gift cards which have been sold in a store, they are local to that store. Global gift cards are sold globally, for example a credit note is a global gift card.
A global gift card has the following characteristics:
- it belongs to an organization of type 'legal with accounting', or
- it has a gift card type with the flag 'Only this organization' checked
Local gift cards are all cards which are not global.
With this in mind the following logic applies:
- local gift cards (with their current balance information) are replicated to their respective stores.
- Global gift cards are not replicated to a store.
- Gift card transactions are never replicated to a store as it is not needed in the store.
Store Server Deployment Check
At runtime you can check the operation of a store server by using the Store Server Deployment Check. This check can be executed from the central server backoffice. Many different characteristics of the store server, its configuration, symmetric DS setup, store server state, etc. are checked and the result of the check-procedure are shown to you directly.
How to take a SymmetricDS Snapshot
There is a process to take a snapshot of the current SymmetricDS state. It can be executed by opening the Process Request window, and scheduling the Create SymmetricDS Snapshot process.
The process may take some seconds, and when it finishes the process log will show where the compressed snapshot has been stored.
The compressed file contains the following archives:
- config-export.csv: The definition of the SymmetricDS internal tables (sym_channel, sym_trigger, etc) and its contents
- jobs.txt: For each job (route, push, purge, etc) it shows when it was last executed, what cluster instance did it, its average execution time and how often it is scheduled to be executed.
- parameters.properties: The default values of all SymmetricDS properties
- parameters-changed.properties: The properties whose current value is different to their default value
- runtime-stats.properties: Some runtime statistics:
- number of synchronization errors
- database connection information (idle, max, used)
- jvm arguments
- memory statistics
- sym_data_gap.csv: Information about the data gaps (more info here)
- sym_identity.csv: Contains the mobile server key of the current server
- sym_incoming_batch: The list of incoming batches that have not been purged yet
- sym_incoming_batch_not_ok.csv: The list of incoming batches whose status is not OK. It will contains the batches that produced a synchronization error, and all those batches that are pending to be imported in the current store.
- sym_outgoing_batch.csv: The list of outgoing batches that have not been purged yet
- sym_outgoing_batch_not_ok.csv: The list of outgoing batches whose status is not OK. It will contains the batches that produced a synchronization error, and all those batches that are pending to be imported in the current store.
- sym_lock.csv: Information about the job locks. It contains info about what cluster instance currently has a lock (if any), and what was that cluster instance that had the previous lock, and when.
- sym_node.csv: Description about all the server registered in the current server (i.e. mobile server key, URL, database type and version, etc)
- sym_node_communication.csv: Information about communications from the current server to other servers. For more information read here
- system.properties: A bunch of system properties (catalina.base, java.class.path, java.version, java.io.tmpdir, machine.name, os.name, os.version, etc)
- table-definitions.xml: A complete definition of all SymmetricDS internal tables (column names, types, constraints, default values)
- threads.txt: A dump of all SymmetricDS threads
Server Status Log
When a Store Server status changes, this change is logged in the Server Status Log Window. All Store Server entries are synchonized to the Central Server in order to have a global overview of all server status changes.
The following transitions will be logged:
- Initialized as Online/Offline: This is the initial status of the store server as soon as the server is initialized (i.e. Tomcat starts)
- Successful transition to Online/Offline: This status will be registered when a transition is completed without errors
- Failed to transition to Online/Offline: When a transition fails. These entries contains additional information to ease troubleshooting.
For each entry, the following information is also registered:
- Mobile Server Key: Used to identify the Store Server whose status has changed
- Event datetime: Date and Time of the moment where the status change takes place.
- Description: In case of a transition failure, this contains additional information. Currently this stores the MobileServerDefinition statusLog value at the moment the transition failed.