<object>.startSync

Note:

• If sync is performed in an upload cache enabled scenario, cached requests that are timed out in the previous upload session are uploaded before the latest changes.
• The client does not handle partial records and expects the server to send the entire record. Full record with all the columns are expected in both upload and download responses. If the backend does not return the full record, use post processor to copy the missing columns from the request as demonstrated here.
• removeAfterUpload flag is only applicable for uploadOnly sync type.
• removeAfterUpload flag has no effect if it is set to downloadOnly or fullSync types.
• removeAfterUpload flag doesn’t clear entire local DB. It deletes the record that are only successfully uploaded during uploadOnly syncType.
• Client can do downloadOnly sync to get local deleted records back to local DB.
• removeAfterUpload flag is applicable for all three-level sync (app level, obj svc, and obj).

Volt MX Iris (JavaScript)

Signature

<VMXObj>.startSync(syncOptions, successCallback, failureCallback, progressCallback)

Parameters

Parameter	Type	Description	Required
syncOptions	JSON	The user can provide options to customize sync behavior. For example, Filters, download batch size etc, Refer Sync Options for supported options. Refer Offline Objects Getting Started guide for more details.	Yes
successCallback	Function	The function is invoked on a successful sync.	Yes
failureCallback	Function	The function is invoked on an error with the cause of failure as an argument upon Sync failure.	Yes
progressCallback	Function	The function is invoked on different sync phases along with phase specific data such as the number of records downloaded etc. Refer Offline Objects Getting Started guide for more details about sync progress events. Note: Not applicable for Mobile Web, Desktop Web and Desktop Native channels. If the app developer passes this parameter in the options, it will be ignored.	No

Sync Options

Option	Type	Description	Required
filter	String	The filter is a valid OData filter string, allows downloading specific records based on the supplied criteria. When the sync is performed at the object-level, filters should be supplied as valid OData filter string as shown in the sample code. All records are downloaded for the object with no or invalid OData filter.	No
downloadBatchSize	Number/String	downloadBatchSize option defines record based batching in downloads. Care should be taken to provide appropriate batch size (number of records) based on backend’s ability to support the same. downloadBatchsize is 500 (records) by default . Note: i) For SAP as backend, the BatchSize specifies the packet size in bytes. BatchSize option is deprecated from 8.0 version. ii) Supported for Mobile Web and Desktop Web channels from V8 SP4 Fix Pack 12 onwards.	No
uploadBatchSize	Number/String	uploadBatchSize option defines record based batching in uploads. uploadBatchSize is 50 (records) by default. Default BatchSize is assumed if the supplied value is <=0. Note: Supported for Mobile Web and Desktop Web channels from V8 SP4 Fix Pack 28 onwards.	No
getSyncStats	String	The getSyncStats option is used to get sync stats information through sync success callback. This option takes two values true or false. Sync stats information is not returned to the user if the getSyncStats option is not supplied or set to false or an invalid value.	No
syncType	String	downloadOnly will download the changes from the server. Change on the client side will not be pushed to the sever.uploadOnly will upload the changes from the client device to the server. Changes on the server will not be downloaded.fullSync will perform both upload and download from the client device to the server and vice-versa. Note: Sync will move to the error state, if any other value is provided other than the above mentioned values.If sync type is not selected, full sync is performed by default.	No
uploadRequestQueryParams	JSON	The uploadRequestQueryParams option is used to pass the query parameters in upload network requests. Note: i) The parameter is supported for Windows, Mobile Web, and Desktop Web channels from release version V8 SP4 FP2. ii) The keys and values in the JSON must be of the string data type. iii) This parameter is not supported for Desktop Native channel.	No
downloadRequestQueryParams	JSON	The downloadRequestQueryParams is used to pass the query parameters in download network requests. Note: i) The parameter is supported for Windows, Mobile Web, and Desktop Web channels from release version V8 SP4 FP2. ii) The keys and values in the JSON must be of the string data type. iii) This parameter is not supported for Desktop Native channel.	No
downloadReconciliationRequired	Boolean	This parameter specifies if download reconciliation is required or not. Download reconciliation is used to compare primary keys present in backend with application database primary keys for an object. In scenarios where there are no pending edits, it is advisable to perform startSync by setting downloadReconciliationRequired to false (as in the case of initial sync). downloadReconciliationRequired is set to true, by default. Note: i) This parameter is not supported for Desktop Native channel. ii) Supported for Mobile Web and Desktop Web channels from V8 SP4 Fix Pack 28 onwards.	No
preserveBatchContext	Boolean	preserveBatchContext specifies whether to preserve the batchContext of last successful download batch. If batchContext is preserved, the successive download call resumes from the last successful batch, else it starts from the first batch again. Set the option to True, to resume the download from last successful batch. Set the option to False, to start downloading from the first batch. preserveBatchContext is set to false, by default. Note: i) This parameter is not supported for Mobile Web, Windows, and Desktop Web channels. ii) This parameter is not supported for Windows, Mobile Web, Desktop Web and Desktop Native channels.	No
removeAfterUpload	Array (list of objects)	removeAfterUpload flag removes the entries from local DB once upload is successful to backend DB. This flag is passed as option parameter to startSync function as part of sync options.	No

Return Type

void

Example

function successCallback(object) {
    //Handle sync success response.
}

function failureCallback(error) {
    //Handle sync failure response.
}

function progressCallback(object) {
    //Handle sync progress response.
}

try {
    var syncObject = new voltmx.sdk.VMXObj("Employee");
    var syncOptions = {};

    //Set filters to be applied during download on object.
    syncOptions.filter = "EmployeeID eq 2";

    //Set uploadRequestQueryParams to be sent during sync in Sync Options.
    syncOptions.uploadRequestQueryParams = {
        "LocationID": "32001",
        "SiteID": "2"
    };

    //Set upload BatchSize.
    syncOptions.uploadBatchSize = "200";

    //Set getSyncStats to receive sync stats on sync success.
    syncOptions.getSyncStats = "true";

    //Set syncType to perform a sync session
    syncOptions.syncType = "uploadOnly";

    //Supplying call back to receive sync progress events too
    syncObject.startSync(syncOptions, successCallback,
        failureCallback, progressCallback);
} catch (err) {
    //Handles Exception.
}

removeAfterUpload Example

var objectSync = new voltmx.sdk.VMXObj("<Obj_Name>");
var syncOptions = {};
syncOptions.removeAfterUpload = [<Obj_Name>];
syncOptions.isUploadCacheEnabled=true;
syncOptions.syncType = "uploadOnly";
objectSync.startSync(syncOptions, onSuccess, onFailure, onProgress);
function onSuccess(response)
{     //Handle sync success response. }
function onFailure(error)
{     //Handle sync failure response. }
function onProgress(object)
{     //Handle sync progress response. }

Android (Java)

Signature

void <VMXObj>.startSync(final HashMap<String, Object> syncOptions, final VMXCallback syncCallback, final VMXProgressCallback progressCallback) throws Exception

Parameters

Parameter	Type	Description	Required
syncOptions	HashMap<String, Object>	The user can provide event callbacks, batchsize to the sync engine. Refer Sync Options for supported options. Refer Offline Objects Getting Started Guide for more details.	Yes
callback	VMXCallback	Application implements onSuccess and onFailure methods of VMXCallback interface.	Yes
progressCallback	VMXProgressCallback	Application implements onProgress method of VMXProgressCallback interface if progress callback is supplied.	No

Sync Options

Options	Type	Descriptions	Required
filter	String	The filter is a valid OData filter string, allows downloading specific records based on the supplied criteria. When the sync is performed at the object-level, filters should be supplied as valid OData filter string as shown in the sample code. All records are downloaded for object with no or invalid OData filter.	No
downloadBatchSize	Number/String	The downloadBatchSize option defines record based batching in downloads. Care should be taken to provide appropriate batch size (number of records) based on backend’s ability to support the same. downloadBatchSize is 500 (records) by default. Note: For SAP as backend, the BatchSize specifies the packet size in bytes. BatchSize option is deprecated from 8.0 version.	No
uploadBatchSize	Number/String	uploadBatchSize option defines record based batching in uploads. uploadBatchSize is 50(records) by default. BatchSize is assumed if the supplied value is <=0.	No
getSyncStats	String	The getSyncStats option is used to get sync stats information through sync success callback. This option takes two values true or false. Sync stats information is not returned to the user if the getSyncStats option is not supplied or set to false or an invalid value.	No
syncType	String	downloadOnly will download the changes from the server. Change on the client side will not be pushed to the sever.uploadOnly will upload the changes from the client device to the server. Changes on the server will not be downloaded.fullSync will perform both upload and download from the client device to the server and vice-versa. Note: Sync will move to the error state, if any other value is provided other than the above mentioned values.If sync type is not selected, full sync is performed by default.	No
uploadRequestQueryParams	HashMap<String, String>	The uploadRequestQueryParams option is used to pass the query parameters in upload network requests. Note: The keys and values in the Hashmap must be of the string data type.	No
downloadRequestQueryParams	HashMap<String, String>	The downloadRequestQueryParams is used to pass the query parameters in download network requests. Note: The keys and values in the Hashmap must be of the string data type.	No
downloadReconciliationRequired	Boolean	This parameter specifies if download reconciliation is required or not. Download reconciliation is used to compare primary keys present in backend with application database primary keys for an object. In scenarios where there are no pending edits, it is advisable to perform startSync by setting downloadReconciliationRequired to false (as in the case of initial sync). downloadReconciliationRequired is set to true, by default.	No
preserveBatchContext	Boolean	preserveBatchContext specifies whether to preserve the batchContext of last successful download batch. If batchContext is preserved, the successive download call resumes from the last successful batch, else it starts from the first batch again. Set the option to True, to resume the download from last successful batch. Set the option to False, to start downloading from the first batch. preserveBatchContext is set to false, by default.	No

Return Type

void

Example

try {
    //Create VMXObj object for object which needs to be synced.
    VMXObj syncObject = new VMXObj("Employee");

    HashMap < String, Object > syncOptions = new HashMap < String,
    Object > ();

    //Set downloadRequestQueryParams to be applied while downloading object
    HashMap < String, String > downloadRequestQueryParams = new HashMap < String, String > ();
    downloadRequestQueryParams("Location ID", "32001");
    downloadRequestQueryParams("SiteID", "2");
    syncOptions.put("downloadRequestQueryParams", downloadRequestQueryParams);

    //Set filters to be applied during download on object.
    syncOptions.put("filter", "EmployeeID eq 2");

    //Set download BatchSize.
    syncOptions.put("downloadBatchSize", "100");


    //Set getSyncStats to receive sync stats on sync success.   
    syncOptions.put("getSyncStats", "true");

    //Set syncType to perform a sync session
    syncOptions.put("syncType", "downloadOnly");

    //Supplying call back to receive sync progress events too
    syncObject.startSync(syncOptions, new VMXCallback() {
            @Override
            public void onSuccess(Object object) {

                Log.d("ObjectSync", "Object sync successful");
            }

            @Override
            public void onFailure(Object error) {
                OfflineObjectsException e = (OfflineObjectsException) error;
                Log.e("ObjectSync", "Object sync failed with error: " + e.getMessage());
            }
        },
        new VMXProgressCallback() {
            @Override
            Public void onProgress(Object object) {
                Log.d("ObjectSync", "Object sync Progress");
            }
        });
} catch (Exception e) {
    Log.e("ObjectSync", "Object sync failed with error:" + e.getMessage());
}

iOS (Objective C)

Signature

void <VMXObj> startSync:(NSDictionary <NSString *, id> *)syncOptions
       onSuccess:(VMXSuccessCompletionHandler)onSuccess
       onFailure:(VMXFailureCompletionHandler)onFailure
      onProgress:(VMXProgressCompletionHandler)onProgress;

Parameters

Parameter	Type	Description	Required
syncOptions	NSDictionary<NSString*, id>	A User can provide options to customize sync behavior. For example, Filters, download batch size etc, Refer Sync Options for supported options. Refer Offline Objects Getting Started guide for more details.	Yes
onSuccess	VMXSuccessCompletionHandler	The method to be called after successful sync.	Yes
onFailure	VMXFailureCompletion Handler	The method called on sync failure.	Yes
onProgress	VMXProgress CompletionHandler	The method called on sync Progress.	No

Sync Options

Options	Type	Descriptions	Required
filter	NSString	The filter is a valid OData filter string, allows downloading specific records based on the supplied criteria. When the sync is performed at the object level, filters should be supplied as valid OData filter string as shown in the sample code. All records are downloaded for object with no or invalid OData filter.	No
downloadBatchSize	NSNumber/NSString	The downloadBatchSize option defines record based batching in downloads. Care should be taken to provide appropriate batch size (number of records) based on backend’s ability to support the same. downloadBatchSize is 500 (records) by default. Note: For SAP as backend, the BatchSize specifies the packet size in bytes. BatchSize option is deprecated from 8.0 version.	No
uploadBatchSize	NSNumber/NSString	uplaodBatchSize option defines record based batching in uploads. uploadBatchSize is 50 (records) by default. Default BatchSize is assumed if the supplied value is <=0.	No
getSyncStats	NSString	The getSyncStats option is used to get sync stats information through sync success callback. This option takes two values true or false. Sync stats information is not returned back to the user if the getSyncStats option is not supplied or set to false or an invalid value.	No
syncType	String	downloadOnly will download the changes from the server. Change on the client side will not be pushed to the sever.uploadOnly will upload the changes from the client device to the server. Changes on the server will not be downloaded.fullSync will perform both upload and download from the client device to the server and vice-versa. Note: Sync will move to the error state, if any other value is provided other than the above mentioned values.If sync type is not selected, full sync is performed by default.	No
uploadRequestQueryParams	NSDictionary<NSString*, id>	The uploadRequestQueryParams option is used to pass query parameters in the upload network requests. Note: The keys and values in the NSDictionary must be of the string data type.	No
downloadRequestQueryParams	NSDictionary<NSString*, id>	The downloadRequestQueryParams option is used to pass query parameters in download network requests. Note: The keys and values in the NSDictionary must be of the string data type.	No
downloadReconciliationRequired	Boolean	This parameter specifies if download reconciliation is required or not. Download reconciliation is used to compare primary keys present in backend with application database primary keys for an object. In scenarios where there are no pending edits, it is advisable to perform startSync by setting downloadReconciliationRequired to false (as in the case of initial sync). Note:downloadReconciliationRequired is set to true, by default.	No
preserveBatchContext	Boolean	preserveBatchContext specifies whether to preserve the batchContext of last successful download batch. If batchContext is preserved, the successive download call resumes from the last successful batch, else it starts from the first batch again. Set the option to True, to resume the download from last successful batch. Set the option to False, to start downloading from the first batch. Note: preserveBatchContext is set to false, by default.	No

Return Type

void

Example

NSError * error;

VMXObj * syncObject = [
    [VMXObj alloc] initWithName: @"Employee"
    error: & error
];

if (error) {
    NSLog(@"Object Sync Object Creation Failed");
} else {

    VMXSuccessCompletionHandler onSuccess = ^ void(id object) {
        //Operation to be performed on successful sync.
    };

    VMXFailureCompletionHandler onFailure = ^ void(id object) {
        //Operation to be performed on sync failure.
    };

    VMXProgressCompletionHandler onProgress = ^ void(id object) {
        //Operation to be performed on sync progress.
    };

    NSMutableDictionary * syncOptions = [NSMutableDictionary new];

    //Set uploadRequestQueryParams to be applied during upload on object 
    NSMutableDictionary * uploadRequestQueryParams = [NSMutableDictionary new];
    uploadRequestQueryParams[@"LocationID"] = @"32001";
    uploadRequestQueryParams[@"SiteID"] = @"2";
    [syncOptions setObject: uploadRequestQueryParams
        forKey: @"uploadRequestQueryParams"
    ];

    //Set downloadRequestQueryParams to be applied during download on object
    NSMutableDictionary * downloadRequestQueryParams = [NSMutableDictionary new];
    downloadRequestQueryParams[@"LocationID"] = @"32001";
    downloadRequestQueryParams[@"SiteID"] = @"2";
    [syncOptions setObject: downloadRequestQueryParams
        forKey: @"downloadRequestQueryParams"
    ];

    //Set filters to be applied during download on object.
    [syncOptions setObject: @"EmployeeID eq 2"
        forKey: @"filter"
    ];

    //Set upload and download BatchSize.
    [syncOptions setObject: @"100"
        forKey: @"downloadBatchSize"
    ];
    [syncOptions setObject: @"200"
        forKey: "uploadBatchSize"
    ];

    //Set getSyncStats to receive sync stats on sync success.   
    [syncOptions setObject: @"true"
        forKey: @"getSyncStats"
    ];

    //Set syncType to perform a sync session.
    [syncOptions setObject: @"fullSync"
        forKey: @"syncType"
    ];

    //Supplying call back to receive sync progress events too
    [syncObject startsync: syncOptions
        onSuccess: onSuccess
        onFailure: onFailure
        onProgress: onProgress
    ];
}

Note: Refer the Offline Objects Getting Started Guide for more details on Offline Objects features and options.