SugarCRM - Synolab

SugarCRM – What is « mandatory_fetch », the hidden vardefs option ?

Par SynoLab le 29 novembre 2017

 Lecture 4 minutes

"mandatory_fetch" is an option passed to a field definition (vardefs) to point to the framework that the data for this field always have to be fetched from DB. This is not currently documented and only used in few cases by Sugar (currently with Sugar PRO, only the assigned_user_id fields have this option enabled but not really used as we will see), so in this post, I want to point first that it exists and then show how we can use this for customization with some simple usages.

This post needs notions about Sugar architecture like Vardefs, SugarQuery and custom ACLs deployment

Why should I care of this option ?

Implementation of "mandatory_fetch"

Let's have a look on where "mandatory_fetch" option is implemented before understanding when it is useful :

We can see here Sugar's logic for preparing the "select" part of the SugarQuery. It is based on a list of fields ( $fields in method signature) augmented with some special fields :

  • id  field is always forced
  • assigned_user_id is forced if current bean object implements assignable template (currently this field has "mandatory_fetch" option)
  • All fields with "mandatory_fetch" option set at "true" value

Ok so, some fields can be forced for a query execution but we don't know yet when this query is requested ?

Huge improvements have been brought to the management of listing processes (you must visualize all listing views as list view, search view, reliable records view, ...), first axis has been the prohibited process of loading "full beans". Each record found according to the query is now a "dematerialized" version of a bean with only specified values loaded. In that particular case, all your internal process build on one particular data should be aware of this situation.

Usages examples

I can't list all cases when this situation happens, this might be during some LogicHooks but not all of them because most of them will have the classic full bean loaded as "*_save" hook (keep in mind even if a user save bean from edit-inline action of a list view, this will use the full bean to save because not complete bean can't be saved without losing some data), SugarApiHelpers, SugarAcls, ...

I took SugarAcl to illustrate "mandatory_fetch" option action because it is simple and visual. We will imagine customization on a module to set in readonly mode a record with a custom_readonly_flag_c field (for example with a Checkbox type) :

If you try to access to your bean with the flag readonly up from the record view, it will be readonly (don't forget to add the field on record view from Studio!). Now if you try to use the edit inline action on the same record from the list view, the edit button visibility will depend on your columns configuration that implicitly means the fields asked for list view rendering process :

  • custom_readonly_flag_c field is enabled on list view (in studio drag  custom_readonly_flag_c from "Hidden" column to "Default" or "Available") => edit button disappear
  • custom_readonly_flag_c field is not available on list view (in studio drag  custom_readonly_flag_c from "Default" or "Available" column to "Hidden") => edit button is visible (save won't work because full bean will be loaded and a 403 exception will be raised)
  • Use "mandatory_fetch" option with "true" value on custom_readonly_flag_c => edit button disappear

This example shows a misconfiguration on a front-end process that can be fixed with the "mandatory_fetch" option, but some other back-end processes which are not visual could have a huge impact too. They are many alternatives like "related_fields", custom SugarApiHelpers and other great tools provided by the framework, but the purpose of this example is to see how is "mandatory_fetch" beneficial on a large scale management of data collection logic.

Personal note

It is great when some architects / developers anticipate other ones needs by putting the right option at the right place. "mandatory_fetch" option is a good example of the identification of a sensible process with a clever approach : use options instead of hard coding solutions. It is a strength of SugarCRM's technical team for giving good opportunities to customize without re-writing parts of framework.