Search
Link Search Menu Expand Document
Kony Quantum is now HCL Volt MX. See Revised Terminology. Current Quantum users, see the important note about API naming.

<objectService>.startSync

The <objectService>.startSync API performs sync for all objects under the object service.

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.

Volt MX Iris (JavaScript)

Signature

VMXObjSvc.startSync(syncOptions, successCallback, failureCallback, progressCallback)

Parameters

ParameterTypeDescriptionRequired
syncOptionsJSONThe user can provide options to customize sync behavior. For example, Filters, downloadBatchSize etc, Refer Sync Options for supported options. Refer Offline Objects Getting Started guide for more details.Yes
successCallbackFunctionThe function is invoked on successful sync with response as an argument. Response object includes sync status code, sync stats etc based on the supplied sync options.Yes
failureCallbackFunctionThe function is invoked on an error with the cause of failure as an argument upon Sync failure.Yes
progressCallbackFunctionThe 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 and Desktop Web channels. If app developer passes this parameter in the options, it will be ignored.No

Sync Options

OptionsTypeDescriptionsRequired
filterJSONThe filter is a valid OData filter string that allows downloading specific records based on the supplied criteria. When the sync is performed at object service-level, filters are supplied for all objects/entities of that service for which filter criteria needs to be applied as a key-value pair (object name, OData filter string) as shown in the sample code. All records are downloaded for those objects with no or invalid OData filter.No
downloadBatchSizeNumber/StringdownloadBatchSize 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 . No
uploadBatchSizeNumber/StringuploadBatchSize option defines record based batching in uploads. uploadBatchSize is 50 (records), by default. Default batch size is assumed if the supplied value is <=0. No
getSyncStatsStringThe 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
syncTypeStringdownloadOnly 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
uploadRequestQueryParamsJSONThe uploadRequestQueryParams option is used to pass the query parameters in upload network requests. No
downloadRequestQueryParamsJSONThe downloadRequestQueryParams is used to pass the query parameters in download network requests. No
downloadReconciliationRequiredBooleanThis 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
preserveBatchContextBooleanpreserveBatchContext 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: This parameter is not supported for Windows, Mobile Web, and Desktop Web channels.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.VMXObjSvc("Organization");
    var syncOptions = {};

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

    //Set filters to be applied during download on multiple objects
    syncOptions.filter = {
        "Employee": "EmployeeID eq 2",
        "Department": "Name eq 'Human Resource'"
    };

    //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.
}

Android (Java)

Signature

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

Parameters

ParameterTypeDescriptionRequired
syncOptionsHashMap<String, Object>The user can provide options to customize sync behavior. For example, Filters, downloadBatchSize etc, Refer Sync Options for supported options. Refer Offline Objects Getting Started guide for more details. Yes
syncCallbackVMXCallbackApplication implements onSuccess and onFailure methods of VMXCallback interface.Yes
progressCallbackVMXProgressCallbackApplication implements onProgress method of VMXProgressCallback interface if progress callback is supplied.No

Sync Options

OptionsTypeDescriptionsRequired
filterHashMap<String, Object>The filter is a valid OData filter string that allows downloading specific records based on the supplied criteria. When the sync is performed at the object service-level, filters are supplied for all objects/entities of that service for which filter criteria needs to be applied as a key-value pair (object name, OData filter string) as shown in the sample code. All records are downloaded for those objects with no or invalid OData filter.No
downloadBatchSizeNumber/StringThe 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. No
uploadBatchSizeNumber/StringuploadBatchSize option defines record based batching in uploads. uploadBatchSize is 50(records) by default. Default batch size is assumed if the supplied value is <=0. 
getSyncStatsStringThe 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 getSyncStats option is not supplied or set to false or an invalid value.No
syncTypeStringdownloadOnly 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
uploadRequestQueryParamsHashMap<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
downloadRequestQueryParamsHashMap<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
downloadReconciliationRequiredBooleanThis 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
preserveBatchContextBooleanpreserveBatchContext 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 an instance of VMXObjSvc 
    KVMXObjSvc syncObject = new
    VMXObjSvc("Organization");

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

    //Set downloadRequestQueryParams to be applied during download on multiple objects
    HashMap < String, String > downloadRequestQueryParams = new HashMap < String, String > ();
    downloadRequestQueryParams("LocationID", "32001");
    downloadRequestQueryParams("SiteID", "2");
    syncOptions.put("downloadRequestQueryParams", downloadRequestQueryParams);


    //Set filters to be applied during download on multiple objects
    HashMap < String, Object > filters = new HashMap < String, Object > ();
    filters.put("Employee", "EmployeeID eq 2");
    filters.put("Department", "Name eq ‘Human Resource’");
    syncOptions.put("filter", filters);


    //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("ObjectServiceSync", "ObjectService sync   successful");
            }

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

iOS (Objective C)

Signature

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

Parameters

ParameterTypeDescriptionRequired
syncOptionsNSDictionary<NSString*, id>A user can provide options to customize sync behavior. For example, Filters, download batch size etc, see Sync Options section for supported options. Refer Offline Objects Getting Started guide for more details.Yes
onSuccessVMXSuccessCompletionHandlerThe method called after a successful sync.Yes
onFailureVMXFailureCompletionHandlerThe method called on sync failure.Yes
onProgressVMXProgress CompletionHandlerThe method called on sync progress events.No

Sync Options

OptionsTypeDescriptionsRequired
filterNSDictionary<NSString*, id>The filter is a valid OData filter string, allows downloading specific records based on the supplied criteria. When a sync is performed at object service level, filters should be supplied for all objects/entities of that service for which filter criteria needs to be applied as a key-value pair (object name, OData filter string) as shown in the sample code. All records are downloaded for those objects with no or invalid OData filter.No
downloadBatchSizeNSNumber/NSStringThe downloadBatchSize option defines record based batching in downloads. Care should be taken to provide appropriate BatchSize (number of records) based on backend’s ability to support the same. downloadBatchSize is 500 (records) by default. No
uploadBatchSizeNSNumber/NSStringuploadBatchSize option defines record based batching in uploads. uploadBatchSize is 50 (records) by default. Default BatchSize is assumed if the supplied values<=0.No
getSyncStatsNSStringThe 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 getSyncStats option is not supplied or set to "false" or an invalid value.No
syncTypeStringdownloadOnly 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
uploadRequestQueryParamsNSDictionary<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
downloadRequestQueryParamsNSDictionary<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
downloadReconciliationRequiredBooleanThis 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
preserveBatchContextBooleanpreserveBatchContext 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

NSError * error;
> 
> VMXObjSvc * syncObject = [
>     [VMXObjSvc alloc] initWithName: @"Organization"
>     error: & error
> ];
> 
> if (error) {
>     NSLog(@"Object Service 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 multiple objects
>     NSMutableDictionary * uploadRequestQueryParams = [NSMutableDictionary new];
>     uploadRequestQueryParams[@"LocationID"] = @"32001";
>     uploadRequestQueryParams[@"SiteID"] = @"2";
>     [syncOptions setObject: uploadRequestQueryParams
>         forKey: @"uploadRequestQueryParams"
>     ];
> 
>     //Set downloadRequestQueryParams to be applied during download on multiple objects
>     NSMutableDictionary * downloadRequestQueryParams = [NSMutableDictionary new];
>     downloadRequestQueryParams[@"LocationID"] = @"32001";
>     downloadRequestQueryParams[@"SiteID"] = @"2";
>     [syncOptions setObject: downloadRequestQueryParams
>         forKey: @"downloadRequestQueryParams"
>     ];
> 
>     //Set filters to be applied during download on object
>     NSMutableDictionary * filters = [NSMutableDictionary new];
>     [filters setObject: @"EmployeeID eq 2"
>         forKey: @"Employee"
>     ];
> 
>     [filters setObject: @"Name eq ‘Human Resource’"
>         forKey: @"Department"
>     ];
> 
>     [syncOptions setObject: filters
>         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: For more details on Offline Objects features and options, refer Offline Objects Getting Started Guide.