Data model in mobile apps

From Resco's Wiki
Jump to navigation Jump to search

When designing an app project in Woodford, one of the first tasks is to decide which tables and columns should be available on the mobile device. Server databases of your CRM or ERP system often contain enormous amounts of data. However, mobile projects tailored for a particular group of users usually require only a minimal subset of the data.

Why reduce mobile data?

Reduce user error
Users can be overwhelmed if their mobile app is packed with data, features, nested menus... Provide just the right amount required for their job.
Faster operation in online mode
Users don't like waiting for their data to load. Large tables with many unnecessary columns take longer to load and display.
Faster synchronization in offline mode
High control over the sync process is one of the main differentiators of Resco mobile apps.
Security
The offline database on the mobile device is encrypted and password protected. Either way, sharing only the minimum subset of data can help protect it.

Terminology: tables versus entities versus objects

Resco mobile apps can connect to Microsoft Power Platform (with or without Dynamics), Salesforce, or Resco Cloud. These systems use different terms for tables, columns, and rows.

Woodford Power Platform Salesforce Resco Cloud
Entity Table Object Entity
Field Column Field Field
Record Row Record Record

The following content uses the Woodford terminology to match the user interface.

Managing entities

Use Woodford to select which entities and fields are available on the mobile device.

Edit your app project. The Project menu displays all entities available in your backend system. Some entities are grayed out or disabled. Disabled entities are invisible and unavailable in mobile apps (both online and offline mode).

  • To show or hide unavailable entities, toggle the phone button next to the search bar.
  • To make an entity available in your projects, select it and click Enable. You can modify its properties, then click Save.

managing entity and its field in woodford

Permission
You can set the Read, Write, Create, and Delete permissions for the whole entity.
Permissions can be also configured individually on each field, see #Managing fields below.
Mode
Select whether the data is available offline.
  • If set to Online & Offline mode, the CRM data is available in both online and offline mode. For offline mode, the app synchronizes the entity records: uploads user changes made in the Mobile CRM app and downloads changes from the server. In online mode, users have access to server records based on the configured view filters.
  • If set to Online only mode, the online mode continues to function as in the previous option. In offline mode, however, no records are downloaded from backend server, and even if a user creates a new record, the record cannot be uploaded. Basically, this entity is completely ignored by the synchronization process.
To avoid the creation of records in offline mode, it is possible to create a simple On Load rule for the entity form (Conditions: If Configuration.isonline equals True; Step: IsFormEditable equals False)
Synchronization
Select how this entity should be synchronized after it has been successfully synchronized at least once. (The initial entity sync always behaves in the same way: it downloads all records matching the sync filter.)
  • Standard Sync: This is the default option. The app downloads all changed records from the server. (Records that don't match the sync filter are later deleted.)
  • Always Full Sync: The app downloads all entity records (as if it was never synced before). In rare cases, performing full sync might be more efficient than the standard algorithm. However, in most cases, full sync increases synchronization time; sometimes dramatically. (When to use Always Full Sync?)
  • Incremental with Sync Filter: The app downloads all changed records that match the sync filter. This can save a lot of network traffic. However, the risk is that the client might not get the information that some server records stopped matching the sync filter. This option works best for immutable records.
Note: SyncAnalyzer can override the above setting by enforcing full sync for performance reasons. You can switch off SyncAnalyzer using Woodford configuration (Disable Sync Analyzer).
On Conflict
Conflict appears when the same record is changed on the device and before being synchronized, a change occurs on the CRM server (e.g. other user changes the same record and synchronizes changes before the first user, or the record is changed on the CRM server). See conflict resolution for details.
Upload Status with Data
This option controls how changes in the state/status fields are uploaded to the backend server during synchronization. The default behavior is that status fields for some entities are uploaded separately, after the regular fields. When you select this option, all entity fields including status are uploaded in one pass. See the description of the upload step for more information.
Include Lookup Labels
When checked, the app no longer shows data related to that entity as “Unknown” in the offline mode. This often happened with ownerIDs of records, as the data with User names is stored in the User entity (by default the Owner entity is not enabled in Woodford).
Incremental Linked SyncFilter
Incremental Linked Sync Filter ensures that the linked filters on entities are checked during Incremental Synchronization. You can enable or disable it per entity, or use project default.

Salesforce-only parameters

Sync linked files
Select which Salesforce files related to this object should be available offline.
  • Owned and shared: Only files that are created or explicitly shared with the user logged into the app are available offline.
  • All: Make all Salesforce files related to this object available offline.
When you enable Download only files linked to records (if enabled for entity) in the project Configuration, file ownership/sharing is no longer relevant.
  • All: Make all Salesforce files related to this object available offline.
  • None: No files are downloaded for this object.
This setting can have a considerable impact on sync performance and API count, especially when enabled for an object with a large number of records. After enabling this option, full sync is needed on all mobile devices.
Tip Owned and Shared means that from all of the files linked to the record, only a subset where the link to the same file exists in the user library or is explicitly shared with the user (except ones excluded by sync filter) will be available in the app. The limitation applies to users with “View All Data” permission, too. This means regular Salesforce API query call is used as described on Salesforce Developers web.

What is not intuitive but important to know is that Owned and Shared means that regular full/incremental sync is executed on ContentDocument and ContentVersion, applying only its sync filter. So if the app user sees a lot of files, even unrelated to other downloaded records, they are also downloaded.

Owned and Shared has the most efficient sync but is almost never suitable for real-world situations.

Option None means that no files linked to downloaded records of the target entity are downloaded.

Option All means that all files linked to downloaded records of the target entity are downloaded (except ones excluded by sync filter) in a separate query call.

We recommend that you use All or None to have the most control over the total amount of files downloaded. Since All has quite a large impact on sync (basically, full sync of parent records is executed on every sync, but it is downloading no attributes of records, just a list of its linked files, and then downloads new files), we recommend to use it only for entities where needed and the better sync filter for parent entity, the better sync performance.

Synchronize entity feed
Required for each object where you want to use chatter. This option is selected automatically when you add a chatter tab to any form of that object.
Sync shared records
Enable this option if you want to properly synchronize recently shared and unshared records during incremental sync.
Sync archived and deleted records
Enable this option to work with archived and deleted records in Resco mobile apps. This setting applies to both offline and online modes. After enabling this feature, full sync is required to make all records available offline. You can use Sync Filter or View Filter on fields "isdeleted" and "isarchived" if you want to download only deleted or only archived records. The ability to sync archived records is particularly useful for Events because Salesforce automatically archives them after one year.

Entity properties in Woodford for Salesforce

Toolbar functions

Sync Filter
Sync Filter allows you to limit the number of records downloaded into the offline storage on user devices.
Edit Index
Create indexes to optimize the performance of the application by speeding up offline queries. (Resco mobile apps create some indexes automatically. Consult a database engineer to suggest custom indexes
Check Usage
Check which fields are used in the mobile project.

Managing fields

After enabling an entity, you can select fields that you plan to use on this entity in Resco mobile apps.

  • To enable a field, select the checkbox in the field's row and click Save.
  • To disable a field, clear the checkbox in the field's row and click Save.
  • Some fields are mandatory and cannot be disabled.

For example, you can select additional fields to use in your mobile project: City, Country/Region, Street, or ZIP/Postal Code. You can also enable custom fields for the entity. You cannot create custom fields here; this must be done on the backend server.

Tip Best practice: We recommend not to include too many entities and fields in your mobile project. Backend servers often include a large wealth of entities and fields, and most organizations only use a small subset. An even smaller subset of the data is necessary in the field. Sync Filter can further restrict which records should be downloaded to the mobile device. Careful planning can improve the performance of the app and the satisfaction of the users.
Properties pane for entity fields

You can also configure some properties for each field. Select a row and modify the Properties pane on the right. Some parameters are read-only.

Permissions
Configure the permissions to Read, Create, or Update values in the field.

Formatting
Affects the appearance of the fields in the forms and views. Proper formatting ensures that the correct action button is displayed next to the field.
  • Single line – Field is formatted to have the appearance of a single-line field in the mobile app.
  • Multiline – Field will have the appearance of a multiline field.
  • Email – Adds an action button to the field in the mobile app, activation of which will provide user with an opportunity to create an email immediately.
  • Phone number – Field gets an action button that provides phone call functionality (the device will dial the number contained in the field).
  • URL – Adds an action button to open the URL in the native browser of the device.
  • Barcode – Adding an action button that activates a camera so user can scan Barcodes and QR codes. This function will only work on devices that have a camera with Autofocus.
  • HTML – Formats the text field into an HTML type (bodies of email, signatures and etc).
  • DropDown, DropDownList, Multi DropDown, Multi DropDownList – this feature allows you to predefine input for users, so instead of entering a value, they can choose to use options from a drop-down list (or enter what is needed manually). See detailed instructions or watch this webinar section. Webinar
Requirement Level
  • A field can be either optional ("None") or required ("SystemRequired").
Options
For option/status fields, the available values are listed here.
Default
The default value of the field.
Constraints
For numbers, see the minimum and maximum allowed value. For strings, see the maximum size.
Precision
For floating-point numbers, see the maximum allowed precision.
Lookup Targets
For lookup fields, this parameter lists the allowed targets of the lookup.
Advanced
Mark as Parent Pointer – When you enable this flag for a lookup field, you can establish a child-parent relationship between entities. See Mark as Parent Pointer for implications.
Description
Description of the field.
Warning If you disable any previously enabled field, please check all existing views and forms and remove any fields or lists marked by the sign “Invalid”, or enable the corresponding field so that the field will no longer be listed as invalid. If there are any invalid fields or lists in the form or view, the application will crash when you try to open an entity list or record details. See Metadata changes in live projects for more information.

Which fields are used?

Imagine the following scenarios:

  • Your database administrator removed a field from an entity. You need to verify if this field is used in the mobile app.
  • You are trying to optimize sync times by removing unneeded data. Which fields are actually necessary?

Use the Check Usage button in the toolbar to display a list of used and unused fields and the various UI or configuration elements where they are used.

  • On the Unused Fields tab, click Disable to remove the selected unused fields from the offline data model. Remember to save changes to confirm.
  • The Possible Unused Fields tab lists additional fields that might or might not be safe to remove.
  • On the Used Fields tab, you can see the components where a particular field is used.
  • The Search tab displays the entity usage as well as all fields.

check which fields are used in the mobile project

This feature does not check field usage in the Offline HTML content such as JSBridge scripts. Use the Whitelist feature to manually mark fields as used.

Note The Check Usage feature is also available in the Data model explorer. When started from there, you can disable unused fields en bloc, across all entities.

See also