Using Restriction Classes

MobileCaddy offers developers the ability to restrict data as it is refreshed from the Salesforce Platform to a device. We call these ‘Basic’ and ‘Platform Class’ restrictions – these are available from the ‘Change Data Restrictions’ button that sits on the Mobile Table record. The ‘Basic’ restriction offers the user the ability to restrict by a ‘User Id Location’ (a field containing an Id that must match the current user’s Id) and/or a ‘Boolean Restriction Field’ (a checkbox or formula checkbox that must be checked in order for the record to be considered for refresh). The ‘Platform Class’ (also referred to as ‘Restriction Class’) is an alternative method that we describe in this document in detail. The developer writes a class defining their restriction and ‘plugs this in’ to the MobileCaddy configuration. This document describes the restriction.


  • “Restriction Interface 2″ is available from ‘Package Version 1.0.121” onwards.
  • “Restriction Interface 1” is available from “Package Version 1.0.1” onwards.

Note that “Restriction Interface 2” is only available when using Data Sync Refresh Version 5.


Even though MobileCaddy offers the developer a great deal of flexibility when defining data restrictions on a Mobile Table using ‘Basic’ restrictions, there are some situations where a class is needed to refine the restrictions further. This is why the advanced ‘Platform Class’ restriction is available.

How To

Restriction Interface 2 – Data Sync/Refresh 5 (sync 5) and above.

This interface is the only one that supports paging and so may be using for Mobile Tables with or without paging switched on but only when using sync 5 or later. Follow the steps below.

1) Implement the mobilecaddy1.RestrictionInterface002_mc Interface

Your class must be global (as MobileCaddy will call it outside of its own mobilecaddy1 namespace) and it must implement this interface. The first line must be similar to the following.

The interface has only one method. In fact the entire interface follows.

The developer needs to implement the single method ‘returnRestrictedIds’. Astute developers who have previously written restriction classes for ‘Restriction Interface 1’ will note that the response from the method is now a ‘String’ an no longer a ‘Set<Id>’. This response is JSON that does contain the restricted Ids as well as additional information.

2) Extract Information from ‘String jsonParams’.

Deserialise Incoming Parameters

The jsonParams must be deserialise prior to use as shown below.

Retrieve Mobile Table Record and Extract Field Values

The incoming ‘jsonParams’ contain the entire Mobile Table record as configured in MobileCaddy. Developers can access the configuration in their class allowing them to write complex restrictions (e.g. use the SObject Name to write a class that is dynamic and may be used across several Mobile Tables, use the Paging Configuration to correctly restrict the data returned on first query etc). The Mobile Table Record may be extracted as a map as shown below.

The Mobile Table map shown will look similar to this:

Extracting Ids Already Processed

MobileCaddy refreshes in Batches of Pages designed around Salesforce Governor Limits. A ‘Batch’ contains multiple ‘Pages’. If there are so many records present that MobileCaddy hits the maximum governor limit for query rows, then MobileCaddy ‘assumes’ there is more data available and following all pages of the first batch being sent to the device, the device will perform a refresh for a second batch. When MobileCaddy executes the Platform Class it will pass in all ids that were processed on previous batches – thus enabling the developer to exclude these from the id query in the class. This code shows us extracting the ids and then using them in the query.

See below how we ‘tell’ MobileCaddy that we need to request another batch.

Extracting ‘isInstall’ Parameter

The ‘isInstall’ parameters tells the class that the user is currently installing data for the first time from this Mobile Table and is not merely refreshing a table that is already on their device. This value is useful when paging – this is because there are different data limits defined in our Paging Configuration that the class must consider. The parameter is extracted as follows.

If the developer has created a Mobile Table that implements paging then there are several ‘Best Practice’ steps that must be followed. These are:

  • Check that paging is indeed on! You can test the Mobile Table field ‘mobilecaddy1__Use_Paging__c’ that will be ‘true’ if paging is on. This enables you to write code that might (a) throw an exception if you are not happy with the value (see below for throwing an exception) or (b) allow paging / non paging in your class if this meets your business requirement.
  • When paging obtain the ‘Refresh Limit’. This differs when installing to subsequent paging. Sample code to obtain this limit follows:

From this point on, the developer should use this value (here ‘refreshRecordLimit’) in place of the ‘getQueryRows’ governor limit. A Platform Class may have several queries with the final query usually being that that extracts the Ids to be returned to MoibleCaddy. The developer must not exceed the limit in ‘refreshRecordLimit’ or the refresh will fail. Where the class contains only a single query then this is relatively straightforward:

This code shows the limit statement on its single query. If the developer needs to make several queries prior to the final ‘id list’ query then it is important that none of them blow our limit.

Warning: under some circumstances this approach is impractical. Suppose that the Mobile Table is on Account records and prior to issuing the final ‘Primary’ query, the Platform Class issues at least one ‘Secondary’ query in preparation on a custom field on Opportunities (for example to restrict the account query based on the set of results). If the Secondary query returns a huge number of records (10s of thousands) then it leaves so little room to actually query the Accounts that it makes little sense continuing with this approach and the developer should return to the design phase to attempt to overcome this issue. The developer might like to use the MobileCaddy Limits Exception (see below) to throw an exception where secondary queries are returning vast numbers of records.

Depending on how complex the developer’s class is, there could be multiple queries with the limit being reduced each time. The developer must keep track of this final limit for the next item.

  • We need to tell MobileCaddy if more batches are required. When we reach our final (perhaps our only) query in the Platform Class as discussed above, we check to see if the number of rows returned from the query have hit the limit that we gave the query. If it does then we assume there are more (better safe than sorry!) and tell MobileCaddy to issue a further batch refresh – in this case MobileCaddy will automatically pass in ids on the device as shown in ‘ids already processed’ above. An example is shown below.

Build Response to MobileCaddy

The response is a serialised JSON string containing the record ids queried and the ‘moreBatches’ flag. This is created as follows.

Throw MobileCaddy Exception

From package 1.0.121 we have opened up the MobileCaddy Exception class so that it may be thrown in a customer Platform Class. This means that customer exceptions will be captured in the same way as MobileCaddy’s own exceptions, with a Mobile Log being created against the Connection Session containing the developers error text. The exception class is called MC_001_mcException and it may be thrown as shown.

These messages will be reported in the Mobile Logs as error number ‘1000’. There is a further exception available (1001) which a developer uses where data volumes from Secondary Queries are so large that it is impractical continuing (see above).

Entering into Configuration

When a developer creates a brand new class and wishes to use it for the first time, the ‘Create Platform Object Support Entry’ button on the Mobile Table must be pressed. Enter the class name and when MobileCaddy confirms the save, click ‘Cancel’ to return to the Mobile Table record (remember the name of the created record!). Next click ‘Change Data Restrictions’ and choose ‘Platform Class’ and in the lookup choose the Platform Object Support Entry that was created.


A sample restriction 2 class is shown below.

The associated Test Class might look like this.