Concepts for DB Sync client apps

DB Sync client apps synchronize local databases with the central database using the DB Sync API. Synchronization involves registering local changes, retrieving central updates, and handling SQL operations with best practices like transaction management and error handling.

Client applications with local databases must use the DB Sync API to implement database synchronization.

The module providing DB Sync coding API is named dbsync_app. However, you will need to import other utility modules in your DB Sync client app code.

Important:
When deploying your server or client app program files, make sure to include the required DB Sync runtime files along with your application program files. The following DB Sync runtime files are required:
  • dbsync_core.42m
  • dbsync_err.42m
  • dbsync_app.42m (for DB Sync client apps)
  • dbsync_srvapp.42m (for DB Sync server-side apps)
  • dbsync_login.42f

When a DB Sync API function returns a negative integer, it indicates a failure. The corresponding error message can be retrieved with the dbsync_err.get_error_message(s) function.

The DB Sync client app code needs to be adapted in order to use a local SQLite database that will be updated with the DB Sync API.

A DB Sync client app (with its local database) needs to be identified by a unique id such as app_employee.

Connection information to the SSO IDP provider (GIP) and DB Sync RESTful service are provided in a specific record structure, that is typically loaded from the JSON configuration file.

The DB Sync user authentication is performed with login/password, either in direct mode or by using the SSO IDP with the functions of the OAuthAPI module.
Note:

The minimum required version of GMA, GMI and GWA is 5.01.

The DB Sync database schema must exist on the device where the DB Sync client app executes and needs to be declared to the DB Sync framework.

The SQL tables subject of synchronization must be declared.

The app code doing INSERT/UPDATE/DELETE instructions to modify the locale database must be extended to register changes in the local DB Sync log. These change events will be used in the next synchronization process.

A new action must be added to the app, to let the user start a synchronization process. This might also be done automatically after specific changes, but can only be performed if the app is on-line.

As a general rule, always consider to retrieve central changes as often as possible, to avoid conflicts when sending local app changes.

Central changes can be retrieved with a complete DB copy (with table creation and data), with a full sync (all data will be fetched from server, ignoring last modification timestamp for current user), or with an optimized sync (where last modification timestamp is compared with modification timestamps of data rows, for table where this information exists)

The data of SQL tables not declared for synchronization can be fetched, but there are only 2 options: Retrieve all rows (when using full sync option), or nothing, because DB Sync cannot guess what rows have been added or updated since last user modification timestamp.

End user creates new rows, updates and deletes existing rows. The application code uses INSERT, UPDATE and DELETE SQL commands to achieve this.

Best practice is to surround the SQL and DB Sync operations in a TRY/CATCH block, with transaction instructions BEGIN WORK / COMMIT WORK / ROLLBACK WORK, to revert all SQL changes in case of failure.