Application Level

This set of APIs help the developer to perform various ORM operations at Application level.

sync.init

This function initializes the creation of device database as well sync environment. On successful sync init, the database structure without data (schema) gets created in the device database. Once the client database is created, subsequent calls to sync.init just initialize the sync environment.

Note: You should always call this function after application re-start and before you perform any Sync operation. You need to perform the sync.init function only once in the life span of an application.

Signature

sync.init (initSuccessCallback ,initFailCallback)

Parameters

• initSuccessCallback[function] - Optional

  Specifies the function that gets invoked on success

• initFailCallback[function] - Optional

  Specifies the function that gets invoked on failure

Platform Availability

Available on all platforms mentioned.

Example

function syncInit(){
sync.init(initSuccessCallback , initFailCallback);
}

function initSuccessCallback(){
alert("Sync Initialized");
}
function initFailCallback(res){
alert("Sync Failed" + " with Error Code:" + res.errorCode + ", error message:"+ res.errorMessage + ", error information:" + JSON.stringify(res.errorInfo));
}

sync.startSession

This function triggers the synchronization cycle. It receives a set of configuration as input that helps to fine tune the synchronization process to specific application needs.

Client Side Lifecycle Events

Configuration Parameters

{
syncscope1: {uploaderrorpolicy: "abortonerror"},
syncscope2: {uploaderrorpolicy: "continueonerror"},
}

config.sessiontasks = {
Scope1 : {
doupload : true,
dodownload : true,
uploaderrorpolicy : "continueonerror"
},
Scope2 : {
doupload : true,
dodownload : true,
uploaderrorpolicy : "abortonerror"
}
};

config.sessiontasks = { 
Scope1 : {
doupload : true,  
dodownload : false, uploaderrorpolicy :
"abortonerror"
}, 
Scope2 : {
doupload : true, 
dodownload : false, uploaderrorpolicy: "continueonerror"
}
}

{ScopeName : [{ 
SyncObjectName : [{ 
FilterName : "ProductName", Value1 : "" , Value2 : "" 
}] 
}] 
}

config.filterparams = { PersistentSyncScope : [ { Products : [ { Name : "ProductName", Value1 : "%Cha%" }  ] }  ] } ;

config.removeafterupload = {"scope1":[ ],"scope3":["syncObject4", "syncObject6"]};

config.passwordhashalgo  = myHashalgo
function myHashalgo(plainText){
//create Hash
return hash;
}

Note: For sync to work with iOS9.x, you need to modify value of the parameter, allow self signed certificates to YES in the Xcode.

Signature

sync.startSession(config)

Parameters

• config [JSObject or table] - Mandatory

  Specifies the table to set the configuration parameters.

Platform Availability

Available on all platforms.

Example

function syncStart() 
{
varconfig = {};

//onXXXXDemo is a function that is called on these callbacks
	config.onsyncstart = onsyncstartDemo;
	config.onscopestart = onscopestartDemo;
	config.onscopeerror = onscopeerrorDemo;
	config.onscopesuccess = onscopesuccessDemo;
	config.onuploadstart = onuploadstartDemo;
	config.onuploadsuccess = onuploadsuccessDemo;
	config.ondownloadstart = ondownloadstartDemo;
	config.ondownloadsuccess = ondownloadsuccessDemo;
	config.onbatchprocessingstart = onbatchprocessingstartDemo;
	config.onbatchprocessingsuccess = onbatchprocessingsuccessDemo;
	config.onsyncsuccess = onsyncsuccessDemo;
	config.onsyncerror = onsyncerrorDemo;

//Selected records need to be downloaded to the device database from the server.
config.filterparams = 
{
PerProv1 : [{Categories : [ { Name : "CategoryID", Value1 : "1,2"}]}] 
}

//Remove data in the specific tables after upload
	config.removeafterupload = {"scope1":[],"scope3":["tab4", "tab6"]};

//To achieve the below said 3 usecases, pass configparam to sync.startsession() as above

Example : scope1 (table 1, table 2), scope2 (table 3, table 4), scope3 (table 4, table 5, table 6)
1. delete all records in all tables in scope1 after upload
2. delete none of the records in tables in scope2 after upload
3. delete only records of table4  and table6 in scope3 after upload

//The below values can be passed by the developer
	config.userid= "syncadmin";
	config.password="SyncAdmin123";
	config.appid = "APPIDNorthwind";
	config.serverhost ="10.10.10.10";
	config.serverport = "8080";

//Configure the size of the batch to be downloaded
config.batchsize= "1000"// Default value is 500

-- Session level tasks to control at scopes
      -- These parameters help to configure Download or Upload only for a scope
	config.sessiontasks = 
	{
	Scope1 : {doupload : true, dodownload : true, uploaderrorpolicy:"continueonerror"}
	}

// The sync.startSession command after populating the config object
	sync.startSession(config);

sync.startReconciliation

sync.startReconciliation API is used to compare primary keys present in backend with application database primary keys for all objects configured in input params. It involves 2 service calls:

1. getAllPKs - Captures all corresponding object PKs from the backend.
2. bulkGet - Retrieves the actual record for given PKs.

From SDK, the first service call is getAllPKs used to fetch the PK values for corresponding objects. SDK compares the PKs with application database. If any extra records are found in application database, the corresponding record will be deleted. If any record is missing, the actual record will be retrieved through bulkGet service call.

Important: PK - Primary Key

Workflow

The following diagram illustrates the end-to-end workflow of sync.startReconciliation API:

Configuration Parameters

Limitation: If there are any pending changes in any object, then corresponding scope will be ignored in reconciliation process.

Note: If any error / failure occurs, reconciliation starts from the scratch and does not have an option to resume its process.

Note: For parent child relationship in sync config, it is recommended that the order of passing object names in config.reconcile param of sync.startReconciliation is first the child object has to be passed and then the parent object .

Note: getAllPKs is a new operation which is not supported in IDE, so customer needs to map the operation manually.

Example

config.reconciliation = {
"scope1": [{ "Account": {} },{"Contact": {}}, {"Opportunity": {}}],
"scope2": [{"Lead": {}}]
};
 config.reconcilebulkgetbatchsize = "2"; // Used for bulkgetService
 config.reconciledownloadbatchsize = "100"; //Used for getAllPk service
	
 //The below values can be passed by the developer
	config.userid= "syncadmin";
	config.password="SyncAdmin123";
	config.appid = "APPIDNorthwind";
	config.serverhost ="10.10.10.10";
	config.serverport = "8080";

	//User defined callbacks as per the requirement
	config.onreconciliationscopestart = onReconciliationScopeStartCallback;
	config.onreconciliationscopesuccess = onReconciliationScopeSuccessCallback;
	config.onreconciliationscopeerror = onEeconciliationScopeErrorCallback;
	config.onreconciliationstart = onReconciliationStartCallback;
	config.onreconciliationbatchprocessingstart = onReconciliationBatchProcessingStartCallback;
	config.onreconciliationbatchprocessingsuccess = onReconciliationBatchProcessingSuccessCallback;
	config.onreconciliationsuccess = onReconciliationSuccessCallback;
	config.onreconciliationerror = onRconciliationErrorCallback;
	config.onreconciliationdownloadstart = onreconciliationdownloadstart;
   	config.onreconciliationbulkgetdownloadstart = onreconciliationbulkgetdownloadstart;
    	config.onreconciliationbulkgetbatchprocessingstart = onreconciliationbulkgetbatchprocessingstart;
config.onreconciliationbulkgetbatchprocessingsuccess = onreconciliationbulkgetbatchprocessingsuccess

sync.stopSession

You can stop the sync process using the sync.stopSession API. If you perform sync.stopsession and then sync.startsession, sync starts from where it stopped before.

Signature

sync.stopSession(callback)

Platform Availability

The Stop Sync API is supported on the following platforms:

• iOS
• Android
• Windows

Example

sync.stopSession( function () 
{ 
alert(“Sync has been stopped”); 
});

Following illustration shows the end-to-end workflow for the stop sync API: 

Requirements

Following are some of the key requirements that need to be enabled for the stop sync process: 

• You must be able to call sync.stopSession to cancel any in progress sync.
• If the network call is in progress, stop sync will not cancel the process right away. Instead it will wait for the network call to complete and stops triggering further sync calls (next batches or scopes).

• If you call the sync.stopSession API multiple times, an error Session is in Progress appears and the sync continues.

• If you call the sync.stopSession API when sync is not in progress, a sync cycle is triggered and makes network calls in background.

• After the sync is stopped first the pending callbacks (like onbatchsuccess, onscopesuccess will get called before invoking the stop callback).

sync.reset

This method resets the device database by removing all the data and restoring it to a state after first sync.init.

Signature

sync.reset(successCallback, errorCallback)

Parameters

• successCallback[function] - Optional

  Specifies the function that gets invoked on success

• errorCallback[function] - Optional

  Specifies the function that gets invoked on error

Platform Availability

Available on all platforms mentioned.

Example

function syncReset(){
sync.reset(resetSuccessCallback,resetFailCallback );
}

function resetSuccessCallback(){
alert("Sync reset successfully.");
}

function resetFailCallback(res){
alert("Sync reset failed" + " with Error Code:" + res.errorCode + ", error message:"+ res.errorMessage + ", error information:" + JSON.stringify(res.errorInfo));
}

sync.rollbackPendingLocalChanges

This method resets the data to last synchronized state. You can use this method to undo the all the client side changes.

Signature

sync.rollbackPendingLocalChanges(successCallback, errorCallback)

Parameters

• successCallback[function] - Optional

  Specifies the function that gets invoked on success

• errorCallback[function] - Optional

  Specifies the function that gets invoked on error

Platform Availability

Available on all platforms mentioned.

Example

function syncRollBack(){
sync.rollbackPendingLocalChanges(rollbackSuccessCallback,rollbackFailCallback);
}

function rollbackSuccessCallback(){
alert("All recent changes rollbacked successfully");
}

function rollbackFailCallback(res)
{
alert("Problem occurred in rollbacking recent changes." + " with Error Code:" + res.errorCode + ", 
error message:"+ res.errorMessage + ", error information:" + JSON.stringify(res.errorInfo));
}

sync.getPendingAcknowledgement

This method retrieves all the rows across all the SyncObjects that are waiting for acknowledgement from the Sync Server. You use the method for persistent sync strategy.

Note: For OTA strategy, sync.getPendingAcknowledgement API always returns 0.

Signature

sync.getPendingAcknowledgement(successCallback, errorCallback)

Parameters

• successCallback[function] - Optional

  Specifies the function that gets invoked on success

• errorCallback[function] - Optional

  Specifies the function that gets invoked on error

Platform Availability

Available on all platforms mentioned.

Example

function fetchPendingAcknowledgement(){
sync.getPendingAcknowledgement(ackSuccessCallback ,ackFailCallback)
}

function ackSuccessCallback(res){
/* res contains all information regarding the Pending Acknowledgements. 
It contains the total number of Pending Acknowledgements and information regarding the tables whose Acknowledgment is pending */
     alert(“Total Number of Pending Acknowledgements: ” + res. totalCount);
     alert(“Data Regarding Tables waiting for Acknowledgement:“     
     +res.totalData);
alert("Sync Pending Acknowledgement Success");
}

function ackFailCallback(res){
alert("Sync Pending Acknowledgement Failed" + " with Error Code:" + res.errorCode + ", error message:"+ res.errorMessage + ", error information:" + JSON.stringify(res.errorInfo));
}

sync.getPendingUpload

This method retrieves all the rows across all the SyncObjects that are pending to be uploaded to the Kony Fabric SyncServer.

Signature

sync.getPendingUpload(successCallback, errorCallback)

Parameters

• successCallback[function] - Optional

  Specifies the function that gets invoked on success

• errorCallback[function] - Optional

  Specifies the function that gets invoked on error

Platform Availability

Available on all platforms mentioned.

Example

function fetchPendingUpload(){
sync.getPendingUpload(pendingUploadSuccessCallback, pendingUploadFailCallback)
}

function pendingUploadSuccessCallback(res){
     /* res contains all information regarding the Pending Uploads. It contains the total number of Pending Uploads and information regarding the tables whose upload is pending */
     alert(“Total Number of Pending uploads: ” + res. totalCount);
     alert(“Data Regarding Tables waiting to get uploaded:“ +res.totalData);
     alert("Sync Pending Upload Success");
}

function pendingUploadFailCallback(res){
alert("Sync Pending Upload Failed" + " with Error Code:" + res.errorCode + ", error message:"+ res.errorMessage + ", error information:" + JSON.stringify(res.errorInfo));
}

sync.getDeferredUpload

This ORM API helps to retrieve the list of rows that are set for hold at sync level.

Signature

sync.getDeferredUpload(successCallback, errorCallback)

Parameters

• successCallback[function] - Optional

  Specifies the function that gets invoked on success

• errorCallback[function] - Optional

  Specifies the function that gets invoked on error

Platform Availability

Available on all platforms mentioned.

Example

function GetDeferredUpload()
{
sync.getDeferredUpload(deferredUploadSuccessCallback, deferredUploadFailCallback)
}

function deferredUploadSuccessCallback(res)
{    
 /* res contains all information regarding the deferred Uploads. It contains the total number of Deferred Uploads and information regarding the tables whose upload is deferred */
     alert(“Total Number of Deferred Uploads: ” + res. totalCount);
     alert(“Data Regarding Tables whose upload is deferred:“ +res.totalData);
     alert("Deferred Upload Success");
}

function deferredUploadFailCallback(res){
alert("Deferred Upload Failed" + " with Error Code:" + res.errorCode + ", error message:"+ res.errorMessage + ", error information:" + JSON.stringify(res.errorInfo));
}