MobileCaddy API Specification

 

All the methods available are implemented as JavaScript promises (unless otherwise specified)


devUtils

.deleteRecord

Deletes a record from a table in the encrypted SmartStore. This only currently works on records that have not yet been synced with SFDC.

Syntax

Parameters

tableName : String. Specifies a string representing the table.

rec : Object. Specifies the object (or just enough to identify the idField) to be deleted.

idField : String. Specifies the index to be used to identify the record.

Returns

object:

  • status – Status code
    • 101200 – OK
    • 101201 – Unknown table
    • 101202 – Unknown field. See object for further details
    • 101203 – Access denied
    • 101204 – Mandatory field is missing. See object for further details
    • 101299 – Other error
  • mc_add_status – (optional) specifies additional status info

Example

 


 

 

.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


 

.getCurrentUserId

Returns current Salesforce user ID.

Example

 


 

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

Syntax

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

 


.insertRecord / .insertRecords

Inserts one or many (insertRecords) records into a table in the encrypted SmartStore

Syntax

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
    • 100799 – Other error
  • mc_add_status – (optional) specifies additional status info
  • upgradeAvailable – (boolean) specifies if there is an upgrade available to the user.

Example

 


 

.readRecords

Reads the entries from a table in the encrypted SmartStore

Syntax

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
  • 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

 


.smartSql

Reads the entries from a table in the encrypted SmartStore

Syntax

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 documentationNOTE: the entire set of calls are not currently available.

Returns

object:

  • records – An array of objects
  • 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


 

.syncMobileTable

Requests a sync call to the backend (Salesforce) for a table in the encrypted SmartStore

Syntax

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.

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

 


 

.updateRecord / .updateRecords

Updates an existing record(s) in a table in the encrypted SmartStore.

Syntax

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

 


 

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

Parameters

Supply single or multiple string/integer/objects to be stringified.

Returns

Promise

Example


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

 


 

 

.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).

Example