MobileCaddy API Specification

 

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

 


 

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

Syntax

Parameters

key : String. Specifies the key to query for.

Example

 


 

.getCurrentUserId

Returns current Salesforce user ID.

Example

 


 

.getCurrentUserName

Returns the name of the currently logged-in Salesforce user.

Example

 


 

.getRecordTypes

Gets the known, mobilised record types for a given table. Returns a mapping of RecordTypeNames / RecordTypeIds.

Syntax

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.

 

v1.7.2 and older

Example

 


 

.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

 


 

.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

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

 


 

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

 


 

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

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


 

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

 


 

.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