<object>.update

The <object>.update API updates the records that are qualified for the criteria in the local database.

NOTE:
  • This API is supported from V8 SP4 onwards.
  • Supported for Windows from V8 SP4 Fix Pack 6 onwards.
  • The column names and the values provided as key value pairs are case sensitive.

Quantum Visualizer (JavaScript)

Signature



<KNYObj>.update(record, options, successCallback, failureCallback)

Parameters

Parameter Type Description Required
record JSON

A dictionary containing column name and value pairs which are to be updated.

Yes
options JSON

The options parameter accepts a JSON that has the following options keys

  • primaryKeys
  • whereCondition
  • whereConditionAsAString
  • trackChanges
  • trackIntermediateUpdates
  • markForUpload

For detailed information, refer Options Keys.

If the options parameter is null or empty, all the records are updated.

 Yes
successCallback Function The function is invoked when the records are updated successfully. Yes
failureCallback Function The function is invoked on an error with the cause of failure as an argument. Yes

Options Keys

Keys Type Description Required
primaryKeys JSON Specify the primary keys of the record to be updated. Key Name: primaryKeys and values are column names and their respective values. No
whereCondition JSON Specify the where condition for the update query. Key Name: whereCondition and values are column names and their respective values. No
whereConditionAsAString String

Specify the where condition for the update query. Key Name: whereConditionAsAString and the value is a string.

NOTE: For SPA/Desktop Web channels, each condition must have only one comparison operator (=,!=,>,<,>=,<=). Multiple conditions can be clubbed using conjunctions (AND, OR). Values containing whitespaces are not supported.

No
trackChanges Boolean

If trackChanges is set to False, the record level operations are not tracked. When the option is set to false, the CUD operations performed on a record are not synced (uploaded). The key is set to True, by default.

NOTE:
  • Supported for Mobile Web and Desktop Web channels from V8 SP4 Fixpack 12 onwards.
 No
trackIntermediateUpdates Boolean

If trackIntermediateUpdates is set to False, it enables to track the latest update performed on the record. The key is set to True, by default.

NOTE:
  • Supported for Mobile Web and Desktop Web channels from V8 SP4 Fixpack 12 onwards.
 No
markForUpload Boolean

If markForUpload is set toFalse, the record changes are not uploaded to the server. The key is set to True, by default.

NOTE:
  • Supported for Mobile Web and Desktop Web channels from V8 SP4 Fixpack 12 onwards.
 No

Return Type

void

Example

//------- update all records -------
var category = new kony.sdk.KNYObj("CATEGORY");
var record = {};
record["CATEGORY_DES"] = "Update existing record";

function successCallback(response) {
    //response holds the number of records updated
}

function errorCallback(error) {
    kony.print("Update failed with error: " + JSON.stringify(error));
}
category.update(record, null, successCallback, errorCallback);

//--------update a record using primary key--------
var category = new kony.sdk.KNYObj("CATEGORY");
var options = {};
var record = {};
var primaryKeys = {};
record["CATEGORY_DES"] = "Update existing record";
primaryKeys["CATEGORY_ID"] = "1234";
options["primaryKeys"] = primaryKeys;

function successCallback(response) {
    //response holds the number of records updated
}

function errorCallback(error) {
    kony.print("Update failed with error: " + JSON.stringify(error));
}
category.update(record, options, successCallback, errorCallback);

//------- update by whereCondition-------
var category = new kony.sdk.KNYObj("CATEGORY");
var options = {};
var record = {};
var whereClause = {};
whereClause["Category_PN"] = 7;
record["CATEGORY_DES"] = "Update existing record";
options["whereCondition"] = whereClause;

function successCallback(response) {
    //response holds the number of records updated
}

function errorCallback(error) {
    kony.print("Update failed with error: " + JSON.stringify(error));
}
category.update(record, options, successCallback, errorCallback);

//------- update by whereConditionAsAString -------
var category = new kony.sdk.KNYObj("CATEGORY");
var options = {};
var record = {};
var whereClause = "Category_PN = '7'";
record["CATEGORY_DES"] = "Update existing record";
options["whereConditionAsAString"] = whereClause;

function successCallback(response) {
    //response holds the number of records updated
}

function errorCallback(error) {
    kony.print("Update failed with error: " + JSON.stringify(error));
}
category.update(record, options, successCallback, errorCallback);

//------- update using Disable change tracking flag - trackIntermediateUpdates ---------
var options = {
    "trackIntermediateUpdates": false
};
var KNYObject = new kony.sdk.KNYObj("CATEGORY");
KNYObject.update(record, options, successCallback, errorCallback);

//------- update using Disable change tracking flag – trackChanges ---------
var options = {
    "trackChanges": false
};
var KNYObject = new kony.sdk.KNYObj("CATEGORY");
KNYObject.update(record, options, successCallback, errorCallback);

//------- update using markForUpload flag --------- 
var options = {
    "markForUpload": false
};
var KNYObject = new kony.sdk.KNYObj("CATEGORY");
KNYObject.update(record, options, successCallback, errorCallback);

Android (Java)

Signature



void <KNYObj>.update(HashMap<String, Object> record,
HashMap<String, Object> options,
final KNYCallback callback) throws Exception

Parameters

Parameter Type Description Required
record HashMap<String, Object> A HashMap containing column name and value pairs which are to be updated. Yes
options HashMap<String, Object>

The options parameter accepts a HashMap with the following option keys:

  • primaryKeys
  • whereCondition
  • whereConditionAsAString
  • trackChanges
  • trackIntermediateUpdates
  • markForUpload

For detailed information, refer Options Keys.

If the options parameter is omitted, all the records are updated.

Yes
callback KNYCallback Application implements onSuccess and onFailure methods of KNYCallback interface. Yes

Options Keys

Keys Type Description Required
primaryKeys HashMap<String, Object> Specify the primary keys of the record to be updated. Key Name: primaryKeys and values are column names and their respective values. No
whereCondition HashMap<String, Object> Map of column names and their respective values according to which the records are to be updated. No
whereConditionAsAString String

Specify the where condition for the select query. Key Name: whereConditionAsAString and the value is a string.

NOTE: For SPA/Desktop Web channels, each condition must have only comparison parameter (=,!=,>,<,>=,<=). Multiple conditions can be clubbed using conjunctions(AND, OR). Values with whitespaces are not supported.

No
trackChanges Boolean If trackChanges is set to False, the record level operations are not tracked. When the option is set to false, the CUD operations performed on a record are not synced (uploaded). The key is set to True, by default. No
trackIntermediateUpdates Boolean If trackIntermediateUpdates is set to False. The option enables us to track the latest update performed on the record. The option is set to True, by default. No
markForUpload Boolean If markForUpload is set to false, the record changes are not uploaded to the server. The option is set to True, by default. No

Return Type

void

Example

//Update record with a primary key 
KNYObj category = new KNYObj("CATEGORY");
HashMap < String, Object > record = new HashMap < String, Object > ();
record.put("CATEGORY_PN", "7");
record.put("CATEGORY_DES", "new updated description");
HashMap < String, Object > primaryKeys = new HashMap < > ();
primaryKeys.put("CATEGORY_ID", "123");
HashMap < String, Object > options = new HashMap < > ();
options.put("primaryKeys", primaryKeys);
try {
    category.update(record, options, new KNYCallback() {
        @Override
        public void onSuccess(Object object) {
            Log.d("Object Update", "Object Update Successful for category");
        }
        @Override
        public void onFailure(Object error) {
            OfflineObjectsException e = (OfflineObjectsException) error;
            Log.e("Object Update", "Object Update Unsuccessful for category with Error :" + e.getMessage());
        }
    });
    catch (Exception e) {
        Log.e("Object Update".
            "Object Update Unsuccessful with error: " + e.getMessage());
    }
}

//Update record with composite primary key 
HashMap < String, Object > record = new HashMap < String, Object > ();
record.put("CATEGORY_PN", "7");
record.put("CATEGORY_DES", "new updated description");
HashMap < String, Object > primaryKeys = new HashMap < > ();
primaryKeys.put("CATEGORY_KEY1", "123");
primaryKeys.put("CATEGORY_KEY2", "124");
HashMap < String, Object > options = new HashMap < > ();
options.put("primaryKeys", primaryKeys);
try {
    category.update(record, options, new KNYCallback() {
        @Override
        public void onSuccess(Object object) {
            Log.d("Object Update", "Object Update Successful for category");
        }
        @Override
        public void onFailure(Object error) {
            OfflineObjectsException e = (OfflineObjectsException) error;
            Log.e("Object Update", "Object Update Unsuccessful for category with Error :" + e.getMessage());
        }
    });
} catch (Exception e) {
    Log.e("Object Update", "Object Update Unsuccessful for category with Error :" + e.getMessage());
}

//Update record using whereCondition 
KNYObj category = new KNYObj("CATEGORY");
HashMap < String, Object > record = new HashMap < String, Object > ();
record.put("CATEGORY_PN", "7");
record.put("CATEGORY_DES", "new updated description");
HashMap < String, Object > whereClause = new HashMap < > ();
whereClause.put("CATEGORY_ID", "123");
HashMap < String, Object > options = new HashMap < > ();
options.put("whereCondition", whereClause);
try {
    category.update(record, options, new KNYCallback() {
        @Override
        public void onSuccess(Object object) {
            Log.d("Object Update", "Object Update Successful for category");
        }
        @Override
        public void onFailure(Object error) {
            OfflineObjectsException e = (OfflineObjectsException) error;
            Log.e("Object Update", "Object Update Unsuccessful for category with Error :" + e.getMessage());
        }
    });
} catch (Exception e) {
    Log.e("Object Update".
        "Object Update Unsuccessful with error: " + e.getMessage());
}

//Update record using whereConditionAsAString 
KNYObj category = new KNYObj("CATEGORY");
HashMap < String, Object > record = new HashMap < String, Object > ();
record.put("CATEGORY_PN", "7");
record.put("CATEGORY_DES", "new updated description");
String whereClause = "CATEGORY_ID = 123";
HashMap < String, Object > options = new HashMap < > ();
options.put(“whereConditionAsAString”, whereClause);
try {
    category.update(record, options, new KNYCallback() {
        @Override
        public void onSuccess(Object object) {
            Log.d("Object Update", "Object Update Successful for category");
        }
        @Override
        public void onFailure(Object error) {
            OfflineObjectsException e = (OfflineObjectsException) error;
            Log.e("Object Update", "Object Update Unsuccessful for category with Error :" + e.getMessage());
        }
    });
} catch (Exception e) {
    Log.e("Object Update".
        "Object Update Unsuccessful with error: " + e.getMessage());
}

//Disable change tracking - trackIntermediateUpdates 
HashMap < String, Object > options = new HashMap < > ();
options.put(KSPublicConstants.TRACK_INTERMEDIATE_UPDATES, false);
category.update(record, options, new KNYCallback() {
    @Override
    public void onSuccess(Object object) {}
    @Override
    public void onFailure(Object object) {}
});

//Disable change tracking - trackChanges 
HashMap < String, Object > options = new HashMap < > ();
options.put(KSPublicConstants.TRACK_CHANGES, false);
category.update(record, options, new KNYCallback() {
    @Override
    public void onSuccess(Object object) {}
    @Override
    public void onFailure(Object object) {}
});

//Mark for Upload 
HashMap < String, Object > options = new HashMap < > ();
options.put(KSPublicConstants.MARK_FOR_UPLOAD, false);
category.update(record, options, new KNYCallback() {
    @Override
    public void onSuccess(Object object) {}
    @Override
    public void onFailure(Object object) {}
});

iOS (Objective C)

Signature



void <KNYObj>.update:(NSDictionary<NSString *, id> *)record
options:(NSDictionary<NSString *, id> *)options
onSuccess:(KNYSuccessCompletionHandler)onSuccess
onFailure:(KNYFailureCompletionHandler)onFailure

Parameters

Parameter Type Description Required
record NSDictionary<NSString*, id> A dictionary containing column name and value pairs which are to be updated. Yes
options NSDictionary<NSString*, id>

The options parameter accepts a NSDictionary with the following option keys:

  • primaryKeys
  • whereCondition
  • whereConditionAsAString
  • trackChanges
  • trackIntermediateUpdates
  • markForUpload

For detailed information, refer Options Keys.

If the options parameter is null or empty, all the records are updated.

Yes
onSuccess KNYSuccessCompletionHandler The function is invoked when records are updated successfully. Yes
onFailure KNYFailureCompletionHandler The function is invoked when updating records fail with the cause of failure. Yes

Options Keys

Keys Type Description Required
primaryKeys NSDictionary<NSString*, id> Specify the primary keys of the record to be updated. Key Name: primaryKeys and the values are column names and their respective values. No
whereCondition NSDictionary <NSString*, id> Dictionary of column names and their respective values according to which the records are to be updated. No
whereConditionAsAString NSString Specify the where condition for the update query. Key Name: whereConditionAsAString and the value is a string. No
trackChanges Boolean If trackChanges is set to False, the record level operations are not tracked. When the option is set to false, the CUD operations performed on a record are not synced (uploaded). The option is set to True, by default. No
trackIntermediateUpdates Boolean If trackIntermediateOptions is set to False, it enables to track the latest update performed on the record. The option is set to True, by default. No
markForUpload Boolean If markForUpload is set to false, the record changes are not uploaded to the server. The option is set to True, by default. No

Return Type

void

Examples

// Update record with a primary key 
KNYObj * _categories = [
    [KNYObj alloc] initWithName: @"CATEGORY"
    error: & error
];
NSMutableDictionary * recordToUpdate = [NSMutableDictionary new];
recordToUpdate[@"CATEGORY_DES"] = @"updated description";
recordToUpdate[@"CATEGORY_PN"] = @"3";
NSMutableDictionary * options = [NSMutableDictionary new];
NSMutableDictionary * primaryKeys = [NSMutableDictionary new];
primaryKeys[@"CATEGORY_ID"] = @"112";
options[@"primaryKeys"] = primaryKeys;
[_categories update: recordToUpdate
    options: options
    onSuccess: ^ (id object) {
        NSLog(@"Update record succeded");
    }
    onFailure: ^ (id object) {
        OfflineObjectsError * error = (OfflineObjectsError) object;
        NSLog(@"Update record failed with error %@", [error.userInfo localizedDescription]);
    }
];

// Update record with composite primary key 
KNYObj * _categories = [
    [KNYObj alloc] initWithName: @"CATEGORY"
    error: & error
];
NSMutableDictionary * recordToUpdate = [NSMutableDictionary new];
recordToUpdate[@"CATEGORY_DES"] = @"updated description";
recordToUpdate[@"CATEGORY_PN"] = @"3";
NSMutableDictionary * options = [NSMutableDictionary new];
NSMutableDictionary * primaryKeys = [NSMutableDictionary new];
primaryKeys[@"PRIMARY_KEY1"] = @"123";
primaryKeys[@"PRIMARY_KEY2"] = @"222";
options[@"primaryKeys"] = primaryKeys;
[_categories update: recordToUpdate
    options:
    onSuccess: ^ (id object) {
        NSLog(@"Updated successfully");
    }
    onFailure: ^ (id object) {
        OfflineObjectsError * error = (OfflineObjectsError) object;
        NSLog(@"Update record failed with error %@", [error.userInfo localizedDescription]);
    }
];

// Update record using whereCondition
KNYObj * _categories = [
    [KNYObj alloc] initWithName: @"CATEGORY"
    error: & error
];
NSMutableDictionary * recordToUpdate = [NSMutableDictionary new];
recordToUpdate[@"CATEGORY_DES"] = @"updated description";
recordToUpdate[@"CATEGORY_PN"] = @"3";
NSMutableDictionary * options = [NSMutableDictionary new];
NSMutableDictionary * whereClause = [NSMutableDictionary new];
whereClause[@"CATEGORY_ID"] = @"112";
options[@"whereCondition"] = whereClause;
[_categories update: recordToUpdate
    options: options
    onSuccess: ^ (id object) {
        NSLog(@"Updated successfully");
    }
    onFailure: ^ (id object) {
        OfflineObjectsError * error = (OfflineObjectsError) object;
        NSLog(@"Update record failed with error %@", [error.userInfo localizedDescription]);
    }
];

// Update record using whereConditionAsAString
KNYObj * _categories = [
    [KNYObj alloc] initWithName: @"CATEGORY"
    error: & error
];
NSMutableDictionary * recordToUpdate = [NSMutableDictionary new];
recordToUpdate[@"CATEGORY_DES"] = @"updated description";
recordToUpdate[@"CATEGORY_PN"] = @"3";
NSMutableDictionary * options = [NSMutableDictionary new];
NSString * whereClause = @"CATEGORY_ID = 112";
options[@"whereConditionAsAString"] = whereClause;
[_categories update: recordToUpdate
    options: options
    onSuccess: ^ (id object) {
        NSLog(@"Updated successfully");
    }
    onFailure: ^ (id object) {
        OfflineObjectsError * error = (OfflineObjectsError) object;
        NSLog(@"Update record failed with error %@", [error.userInfo localizedDescription]);
    }
];

//Disable change tracking - trackIntermediateUpdates 
NSDictionary < NSString * , id > * options = @ {
    KNYCONSTANTS_TRACK_ INTERMEDIATE_UPDATES: @NO
};
[sdkObjectSync update: record
    options: options
    onSuccess: ^ (id object) {}
    onFailure: ^ (id object) {}
];
//Disable change tracking - trackChanges 
NSDictionary < NSString * , id > * options = @ {
    KNYCONSTANTS_TRACK_CHANGES_ UPDATES: @NO
};
[sdkObjectSync update: record
    options: options
    onSuccess: ^ (id object) {}
    onFailure: ^ (id object) {}
];
//Mark for Upload 
NSDictionary < NSString * , id > * options = @ {
    KNYCONSTANTS_MARK_FOR_ UPLOAD: @NO
};
[sdkObjectSync update: record
    options: options
    onSuccess: ^ (id object) {}
    onFailure: ^ (id object) {}
];
NOTE:
  • The trackChanges flag must be used consistently (either always true or always false) for all CUD operations on a record. You must not update the value of "change tracking" flag in between CUD operations on a record.
  • When you set both markForUpload and trackChanges flags, an error is reported as these are mutually exclusive options.
  • When the user sets both trackIntermediateUpdates and trackChanges flags, an error is reported as these are mutually exclusive options.
  • For Hierarchical Objects, you must provide a proper value for both parent and child record operations.
  • The primaryKeys, whereCondition, and whereConditionAsAString are considered as the criteria to update a record. Only one criterion is considered at a time and the order is primaryKeys> whereCondition > whereConditionAsAString.

 

NOTE: To soft delete a column, mention the softdelete column name. Ensure all the tables have the same softdelete column name. For the offline object service with multiple objects, if the soft delete column is not common for all the objects, instead of using delete API, use the <object>.update API and set the softdelete field to true in the device database.