Developing with Synchronized Transactions
The OB Commerce infrastructure supports the concept of Synchronized Transactions.
From a technical perspective synchronized transactions are relevant only for data/models with tables which are synced to the server. This is data for which there is a client side table and a separate sync-definition. The details of these type of data are described in this related page.
This page is mostly relevant for you as a developer when you add new tables which need to be synced or when you add code which calls the OB functions: runSyncProcess or syncAllModels. In all other cases you don't need to do specific coding to support synchronized transaction mode.
Another thing to take into account as a developer is that the user interface is blocked while the synchronized transaction is being executed and the success/error callbacks of the runSyncProcess/syncAllModels function calls are executed when the transaction returns from the server.
Synchronized transactions are an advanced feature of OB Commerce. It is important to read and be familiar with the concepts outlined in the following wiki pages:
Default Approach: Async
The data synchronization tasks/tables are synced in one flow in the client. This means that there is one client side process called runSyncProcess or syncAllModels which reads the client-side tables and checks for any changes. Pending changes for one table are collected and send in one request. Different tables are send in separate requests. So if there are two changes in the c_order table and one in the cashup table then there will be 2 requests, one for the c_order changes, one other for the cashup table.
These requests are done asynchronously. So the user interface's success callback will be called before the server response success callback is called on the client.
This is called asynchronous mode, it is the default behavior of WebPOS.
From 16Q3 onwards the above process can also be run in synchronized mode.
Synchronous transaction mode is enabled 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.
The main difference with async mode is:
- the user interface is blocked while the transaction is send to and processed on the server
- the changes of all tables are combined in one request which is executed in one database transaction on the server.
- the success/error callback specified on the runSyncProcess/syncAllModels is called after the request returns from the server. So the processing is synchronous from the client to the server and back
- the request is send to the server(s) and processed there in a specific way to facilitate robustness and correct operation. See this page for more details.
The above also means that synchronized transactions can not be combined with standard client side offline behavior of WebPOS.
Synchronized Transactions Coding Aspects
Much of the synchronized transaction logic works automatically without additional coding from a developer. You only need to do specific coding if:
- you add new tables to the solution which need to be synced to the server, or
- you add code which (indirectly) calls the functions runSyncProcess or syncAllModels or related functions.
There are however a few areas which need to be handled specifically by a developer.
User Interface Logic: success/error callback
During the synchronized transaction execution the system will lock the UI and show a message box. So this is something to take into account when coding your functionality. Also the runSyncProcess callbacks (success/error) are called when the transaction returns and after the popup is hidden and the UI is unfrozen.
Register changing/new tables - to be checkpointed
When the user initiates an action which results in a sync to the server and your code changes a table in this process (after the user initiates the action) you need to register this related model to be backed up/checkpoint.
Also if you add new tables which are synced as part of the data synchronization from the client then you need to make sure that these tables are part of the checkpoint.
Below is a sample on how to do register a model for the sync checkpoint:
Success - Error - Rollback Handling
When the transaction fails the UI will be unfrozen. The error callback can be called in this case. It is also possible that the success callback is called with in the returned json an exception message.
When an error occurs on the server the transaction is not committed, it is rolled back on the server. On the client the same needs to happen.
The overall flow can be summarized like this:
- when the user action starts (for example when he/she presses a button) the system backs up the synced database tables. This is called the 'pre-change' backup.
- just before the request is send to the server the current state of the tables is again backed up. This is called the pre-sync backup. At the same time the pre-change backup is restored.
- so when the request is fired of to the server the state of the tables is such that they are the same as before the user started the action. The reason to do this is that if the user at this point presses refresh and the server encounters an error then the system will be in the old state again.
- when the request returns and is successful then the system restores the pre-sync backup
- if the request returns with an error then nothing is restored as the system was already in the pre-change state.
As a developer the only custom code you need to write is to make sure the pre-change backup is done. The best point is somewhere in the application code just after the user pressed a button or selected another option.
The OB Commerce suite provides an api to easily create a backup. This is an example call of the api:
This call creates a checkpoint (backup) of the specified models. This backup is stored in memory. If the server requests fails or returns with an error then the specified models are rolled back to the state they were when calling setSynchronizedCheckpoint.