Omnis Technical Note TNJS0005Updated Nov 2016

Using the Omnis Synchronization Server

for Omnis Studio 6.1.x, 8.x, or above
(Studio 8.0.2 ZIP added Nov 2016)
By Rod Cooper, Omnis Engineering

The Synchronization Server in the Omnis Studio 6.x/8.x SDK together with the latest JavaScript wrappers provide the ability to synchronize data between a SQLite database on the client device and any supported database on the backend server, including Oracle, MySQL, PostgreSQL, and SQL Server.

This tech note describes how you can test the data synchronization using a demo library and a SQLite demo database. The demo library itself is optimized for iOS mobile devices and the iOS Application Wrapper but could be adapted to work with the other supported platforms.

Requirements

You will need to use Omnis Studio 6.1 or above since it contains the latest Synchronization Server which is required for the syncdemo library and database. In order to create standalone mobile apps (that work off-line in serverless client mode) you need to set the $serverlessclient property in your remote form. To set this property and to be able to build standalone mobile apps that use serverless client mode you will need to use an alternative development serial number – an evaluation serial number can be obtained here, or contact your local sales office to obtain a full development serial number.

The following ZIP files contain the demo library (syncdemo.lbs) and SQLite demo database (syncdemo.db) for different versions of Omnis Studio:

Studio 6.1.x and 8.0.1 (after conversion): syncdemo.zip
Studio 8.0.2 or above* syncdemo802.zip


You also need the source for the wrappers from here: http://www.omnis.net/download/jswrapper.jsp

*If you are using Omnis Studio 8.0.2 you will need to use the syncdemo802 library and version 2.3 of the Sync Server which uses a RESTful interface to communicate with mobile clients. When using the new SyncServer 2.3 you now require a Web Services serial number to use the Sync Server in the Development version of Studio 8.0.2 (all Server versions of Omnis include Web Services support). Contact your local sales office for further information.

Setting up the Synchronization server

To connect the Synchronization Server to a database, you must define a session template in the SQL browser. For this example, you should connect to the SQLite database provided.

Defining a session template

Select the SQL Browser node in the Studio Browser, click on the Session Manager hyperlink followed by the New Session hyperlink. Define a session template named SYNCDEMO using the entries shown below and press OK to save.

Sync demo

Configuring the Synchronization Server

Open the Synchronization Server in Omnis Studio using the Tools>>Add-Ons menu. On the CDB Config tab select the Session Template SYNCDEMO, then press Save Details followed by Connect.

Sync demo

On the Sync Groups tab add two groups named ‘group1’ and ‘group2’ both with a password of ‘syncdemo’ (without quotes).

Sync demo

On the CDB Tables tab check Sync and SSR for the Primary Key nat_ID of the table naturetable and press Save Changes.

Sync demo

Testing the connection

If the SQLite connection has been successful the session CDBSESS will be open in the SQL Browser and you will be able to view the data in the syncdemo database by testing the form ‘jsServer’ (right-click on the remote form and select Test Form).

Sync demo

Note, to view data on the Map View tab you must obtain a Google maps apikey and in design mode enter the key into $apikey property of the map control on the jsServer remote form. To do this, open the form ‘jsServer’ in design mode by double-clicking on the form in the Studio Browser, set the current page of the PagedPane to 2, click on the map control and enter your Google api key into the Property Manager under $apikey.

Preparing for client connections

To receive client connections, the Omnis server port on which to listen must be set by selecting ‘Studio 6.x.x’ in the Studio Browser, clicking on the ‘Prefs’ hyperlink and locating the $serverport preference in the Property manager.

Finally, you need to create the html page ‘jsClient.htm’ should the wrapper app be used in online mode. To do this, right-click on the form ‘jsClient’ and select ‘Test Form’, which creates the ‘jsClient.htm’ file automatically in the Omnis html folder and opens it in your web browser. Note that the form will not be fully functional since it is not running on a device, so close the form.

Building the JavaScript Wrapper App

To enable synchronization from a mobile device, you must compile your application into a standalone mobile app using the Omnis JavaScript wrapper, available for iOS and Android. You can download the source and documentation for the wrappers from here: www.omnis.net/download/jswrapper.jsp

Within the wrapper, set the following entries in the config.xml file where 99.99.99.99 is the IP address of your server and 1234 is the server port (as set up in step 1.4 above), and build the wrapper using the OmnisJSWrapper_SQLite active scheme.

<SettingsOnlineMode>0</SettingsOnlineMode>
<ServerOmnisWebUrl>http://99.99.99.99:1234</ServerOmnisWebUrl>
<ServerOnlineFormName>jschtml/jsClient.htm</ServerOnlineFormName>
<ServerOfflineFormName>jsClient</ServerOfflineFormName>
<ServerOmnisServer></ServerOmnisServer>
<ServerOmnisPlugin></ServerOmnisPlugin>
<ServerAppScafName>syncdemo<ServerAppScafName>

Connecting the Client to the Synchronization server

The first time you run the wrapper app, you will receive a message ‘no such table: naturetable’. This indicates that no tables exist on the client as it has yet to be synced with the server.

On the Settings tab of the client demo app, enter your Hostname together with a Group Name and Password as set up in the Synchronization Server (as above) and press Save.

Sync demo

Ensure that the Synchronization Server window is open on the server to view incoming connections, then press the Syncinit button on the client and note the entries in the Synchronization Server log.

Sync demo

Once synchronization is complete, go to the Data tab on your device, press refresh and note that the data has been synced to your device.

Sync demo

You can add new records or edit existing records within the local SQLite database on the device and then synced to the server by clicking on the Sync button.

Sync demo

Switching to the Cache tab prior to pressing sync displays the pending requests for synchronization together with a list of local tables on the device. Pressing Sync updates the server database and clears the cache.

Sync demo

If desired this tab can easily be hidden by editing the form 'jsClient' in design and setting the initial value of iShowCache to kFalse.