All the methods available are implemented as JavaScript promises (unless otherwise specified)
devUtils
.dirtyTables
Returns a list of table names that have local updates that have not yet been pushed to SFDC.
Returns
Array of strings or empty array.
Example
|
1 2 3 4 5 6 |
devUtils.dirtyTables().then(function(tableNames){ console.log(tableNames); // e.g. tableNames = ['myFirstTable', 'AnotherTable'] }); |
.getCachedAppSoupValue
Queries the AppSoup table for a key. The first call for a key caches the value.
See the Package Release Notes for available values. These include items such as DefaultCurrency, UserRoleId, OrganisationName.
Syntax
|
1 2 3 |
getCachedAppSoupValue(key); |
Parameters
key : String. Specifies the key to query for.
Example
|
1 2 3 4 5 6 |
devUtils.getCachedAppSoupValue(OrgansiationId).then(function(orgId){ console.log(orgId); // e.g. orgId = 00524000000EnWoAAK }); |
.getCurrentUserId
Returns current Salesforce user ID.
Example
|
1 2 3 4 5 6 |
devUtils.getCurrentUserId().then(function(userId){ console.log(userId); // e.g. userId = 00524000000EnWoAAK }); |
.getCurrentUserName
Returns the name of the currently logged-in Salesforce user.
Example
|
1 2 3 4 5 6 |
devUtils.getCurrentUserName().then(function(userName){ console.log(userName); // e.g. userName = "John Doe" }); |
.getRecordTypes
Gets the known, mobilised record types for a given table. Returns a mapping of RecordTypeNames / RecordTypeIds.
Syntax
|
1 2 3 |
getRecordTypes(table); |
Parameters
table : String. Specifies the table to query for.
Returns
v1.7.3+
An of object specifying a 2-way map of names to.from Ids.
As of v1.7.3 the map includes information on the recordTypeDevName as well as the recordTypeName, since the latter can be translated. The map is also bi-directional and so lookup from names to Ids is also possible
Example
In this case the Salesforce translation has been set up for Expenses, and ran for a Spanish user.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
devUtils.getRecordTypes("MC_Time_Expense__ap").then(function(rTypes){ console.log(rTypes); }); // Outputs { "0120Y0000009os6QAA": { recTypeDevName: "Expenses", recTypeName: "Gastos" }, "Expenses": "0120Y0000009os6QAA", "Gastos": "0120Y0000009os6QAA" } |
v1.7.2 and older
Example
|
1 2 3 4 5 6 |
devUtils.getRecordTypes("MC_Time_Expense__ap").then(function(rTypes){ console.log(rTypes); // e.g. rTypes = {0120Y0000009os6QAA: "Expense", 0120Y0000009os7QAA: "Time"} }); |
.getUserLocale
Returns the locale setting of the currently logged-in Salesforce user. This value is set based upon the value that was set in Salesforce.com when the application was first installed.
Example
|
1 2 3 4 5 6 |
devUtils.getUserLocale().then(function(userLocale){ console.log(userLocale); // e.g. userName = "en_US" }); |
.initialSync
Requests sequential one-way sync calls to the backend (Salesforce) for each table name passed in.
This should be used on the first run of the application only, to initially pull down data into the local tables.
v1.8.2+ The initialSync runs a total of three retries if any of the tables fail to sync on their first attempt. If all three retries are used and the initialSync has not completed for all tables specified then then promise will reject. The rejection will contain a list of all table attempts and their statuses. Upon failures Mobile_Log entries (at D0 level) shall be written and pushed to the platform.
Syntax
|
1 2 3 |
initialSync(tableNames) |
Parameters
tableNames : An array of strings representing the tables to be synchronized.
Returns
An array of objects, each like this:
- tableName – string representing the name of the table
- status – Status code – see below for details
- 100400 – OK
- 100401 – Unknown table
- 100402 – Sync not OK
- 100497 – Table too young (if sync was not processed due to maxTableAge setting)
- 100498 – Sync already in progress
- 100499 – Other error
- mc_add_status – (optional) specifies additional status info
Example
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
devUtils.initialSync(['Tab1', 'Tab2', 'Tab3']).then(function(resObject){ // Our sync is complete }); // could result in this, where "Tab1" sync failed [ { "table": "Tab1", "status": 100402, "mc_add_status": "Dirty records" }, { "table": "Tab2", "status": 100400 }, { "table": "Tab3", "status": 100400 } ] |
.insertRecord / .insertRecords
Inserts one or many (insertRecords) records into a table in the encrypted SmartStore
Syntax
|
1 2 3 4 5 |
insertRecord(tableName,rec); //or insertRecords(tableName,recs); |
Parameters
tableName : Specifies a string representing the table.
rec / recs : Specifies a(n array of) Objects to be inserted.
Returns
object:
- status – Status code
- 100700 – OK
- 100701 – Unknown table
- 100702 – Unknown field. See object for further details
- 100703 – Access denied
- 100704 – Mandatory field is missing. See object for further details
- 100705 – Datatype mismatch. See object for further details
- 100706 – Tried to write to protected field. See object for further details
- 100708 – Unknown RecordType Name
- 100799 – Other error
- mc_add_status – (optional) specifies additional status info
- upgradeAvailable – (boolean) specifies if there is an upgrade available to the user.
Example
|
1 2 3 4 5 6 7 |
devUtils.insertRecord('myTable',myNewRec).then(function(res) { console.log('My res object', res); }).catch(function(e) { console.log('Insert failed', e); }); |
.readRecords
Reads the entries from a table in the encrypted SmartStore
Syntax
|
1 2 3 |
readRecords(tableName,options) |
Parameters
tableName : Specifies a string representing the table.
options : An array of option flags. Currently none are supported.
Returns
object:
- records – An array of objects. Note: each record shall contain an additional device-only field dirtyFlag. This has a boolean value specifying whether the local version of the record has had modifications to it since the last synchronisation with SFDC, i.e. there are change to the record that have not yet been pushed to the platform.
- status – Status code – see below for details
- 101000 – OK
- 101001 – Unknown table
- 101003 – Access denied
- 101099 – Other error
- mc_add_status – (optional) specifies additional status info
- upgradeAvailable – (boolean) specifies if there is an upgrade available to the user.
Example
|
1 2 3 4 5 |
devUtils.readRecords('myTable', []).then(function(resObject) { records = resObject.records; }); |
.smartSql
Reads the entries from a table in the encrypted SmartStore
Syntax
|
1 2 3 |
smartSql(ssql, pageSize) |
Parameters
ssql : Specifies a string representing the Smart SQL to be run. Info on valid Smart SQL syntax can be found in the Salesforce Mobile SDK documentation. NOTE: the entire set of calls are not currently available.
pageSize: Optional. Integer. From v1.8.0. How many records to bring back from the Database per page. Note this does not impact the number or records returned from the devUtils call, only how many are retrieved from the database into memory at once. Default 1000.
From MC_Resource v1.8.0 it is possible to specify the table columns to return.
Returns
object:
- records – If fields-to-return are not specified then will return an array of objects, else will be an array of arrays. Note: each record shall contain an additional device-only field dirtyFlag. This has a boolean value specifying whether the local version of the record has had modifications to it since the last synchronisation with SFDC, i.e. there are change to the record that have not yet been pushed to the platform.
NOTE: If fields-to-return are not specified then will return an array of objects, else will be an array of arrays. - status – Status code – see below for details
- 101000 – OK
- 101001 – Unknown table
- 101003 – Access denied
- 101099 – Other error
- mc_add_status – (optional) specifies additional status info
- upgradeAvailable – (boolean) specifies if there is an upgrade available to the user.
Example
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
devUtils.smartSql("Select * from {MC_Project_Location__ap} WHERE {MC_Project_Location__ap:Name} = 'Client Site'") .then(function(res){ console.log(res); }); // returns // {status: 101000, records: Array[1], upgradeAvailable: false} devUtils.smartSql("Select {MC_Project_Location__ap:Id}, {MC_Project_Location__ap:Name} from {MC_Project_Location__ap} WHERE {MC_Project_Location__ap:Name} = 'Client Site'") .then(function(res){ console.log(res); }); // returns // {status: 101000, records: [['abc123ghj123bnm678', 'Client Site']], upgradeAvailable: false} |
.syncMobileTable
Requests a sync call to the backend (Salesforce) for a table in the encrypted SmartStore
Syntax
|
1 2 3 |
syncMobileTable(tableName, syncWithoutLocalUpdates, maxTableAge, maxRecsPerCall, skipP2M) |
Parameters
tableName : Specifies a string representing the table.
syncWithoutLocalUpdates : Optional. Boolean. Whether to perform the sync even if there are no local updates to be pushed to the platform. If false and there are no outstanding local update to be pushed to the platform then the sync will not take place. Default = true.
maxTableAge : Optional. Integer (Number of seconds). A value that determines whether or not a sync will take place based on the age of the table (based on when it was last synced). If the last sync occurred within the number of seconds specified then no sync will take place. Note: unless there are local updates that need to be pushed to the platform, if this is the case then a sync will always take place.
maxRecsPerCall : Optional. Integer. The maximum number of records that will pushed per http call to SFDC. If there are more local records than maxRecsPerCall then the sync will take place over multiple http calls. Maximum value is 200. Default value is 50.
skipP2M: Optional. Boolean. Flag to determine whether the call to request new records should take place. Available v1.7.1
Returns
object:
- status – Status code – see below for details
- 100400 – OK
- 100401 – Unknown table
- 100402 – Sync not OK
- 100497 – Table too young (if sync was not processed due to maxTableAge setting)
- 100498 – Sync already in progress
- 100499 – Other error
- mc_add_status – (optional) specifies additional status info
Example
|
1 2 3 4 5 |
devUtils.syncMobileTable('myTable').then(function(resObject){ // Our sync is complete }); |
.updateRecord / .updateRecords
Updates an existing record(s) in a table in the encrypted SmartStore.
Syntax
|
1 2 3 4 5 |
updateRecord(tableName,rec, idField) // or updateRecords(tableName,recs, idField) |
Parameters
tableName : Specifies a string representing the table.
rec / recs : Specifies a(n array of) Objects to be updated.
idField : Specifies a string representing the field name to be used to match on (must be an index).
Returns
object:
- status – Status code – see below for details
- 101100 – OK
- 101101 – Unknown table
- 101102 – Unknown field. See object for further details
- 101103 – Access denied
- 101104 – Mandatory field is missing. See object for further details
- 101105 – Datatype mismatch. See object for further details
- 101106 – Tried to write to protected field. See object for further details
- 101107 – Unknown ID – Could not find a record for the specified ID
- 101199 – Other error
- mc_add_status – (optional) specifies additional status info
- upgradeAvailable – (boolean) specifies if there is an upgrade available to the user.
Example
|
1 2 3 4 5 |
devUtils.updateRecord('myTable',myUpRec, 'Id').then(function(resObject) { // continue }); |
logger
.debug
.error
.info
.log
.warn
Writes an entry to the Mobile_Log__mc table that can be sync’d to the platform. By default only error entries will be automatically written, this is based upon the localStorage item logLevel. Adjusting this item configures which entries shall be logged, and which shall be ignored.
When running in Codeflow this also acts as a wrapper around the console.log etc functions.
Syntax
|
1 2 3 |
logger.error(arg1, "you can specify", {1: "many items of different types"}) |
Parameters
Supply single or multiple string/integer/objects to be stringified.
Returns
Promise
Example
|
1 2 3 |
logger.error("Something bad happened", e); |
vsnUtils
The version of the application (Data Model, Business Logic, or both) is controlled via the Dynamic Version assigned in the platform configuration.
With each sync call made to the platform (devUtils.syncMobileTable()) the response contains information as to whether or not a new version is available for the current user. This could be a newer or older version, to cater for downgrades, for example where a user was accidentally upgraded previously.
The MobileCaddy API exposes this information in the response object to the insertRecord(), readRecords(), smartSql() and updateRecord() calls (see the API docs).
.upgradeAvailable
Returns whether there is an upgrade available for the current user. This information is based upon whether or not the Dynamic Version associated with the user on the platform is different from the one that they currently have in use.
Note that even if there is an upgrade available it the application can only be upgraded if there are no dirty tables in the local database.
Returns
Boolean
Example
|
1 2 3 4 5 6 |
vsnUtils.upgradeAvailable().then(function(res){ console.log(res); // e.g. res = true }); |
.upgradeIfAvailable
Attempts to do an upgrade if one is available. If an upgrade takes places then currently all local application data is wiped prior to the upgrade taking place. There should be no need for the user to re-authenticate/re-install etc.
If the upgrade can take place then the app shall continue to upgrade, which will include an automatic restart of the application.
In the circumstances where no upgrade is available, or an upgrade is available but there are dirty local tables and so the upgrade cannot take place at this time the JavaScript promise will result in reject(false).
Parameters
- skipDirtyCheck – (optional) String:
- “force” – Will force through an update, disregarding any dirty records
- “skip-failures” – Will disregard any records that are dirty but have also had a sync attempt made against them. The upgrade shall not take place if there are any dirty records that have not yet had an attempted sync request made.
Example
|
1 2 3 4 5 6 7 8 |
vsnUtils.upgradeIfAvailable().then(function(){ // an upgrade will now begin in the background. }).catch(function(e){ // if e === false then an upgrade is not available // or cannot be run at present due to dirty tables }); |
connSessUtils
The connSessUtils gives access to information surrounding synchronisations
.getSyncRecFailures
Gets records that have failed synchronisation calls.
Parameters
- table – (optional) String: The name of the table to get failures for
Returns
An object where there is a property for each failed record, accessible via it’s ID or Proxy ID (for insert), for the table specified. Each property points to an object containing attributes giving details of the record (it’s ID or proxy ID) and the reason the sync failed.
If no table parameter is given then an array of objects is returned, with each object having a table attribute giving the name of the table, and a failures attribute that is an object with a property for each failed record (as above)