SugarCRM SupportProduct GuidesSugar DeveloperSugar Developer Guide 10.0Data FrameworkVardefs



Vardefs (Variable Definitions) provide the Sugar application with information about SugarBeans. Vardefs specify information on the individual fields, relationships between beans, and the indexes for a given bean. 

Each module that contains a SugarBean file has a vardefs.php file located in it, which specifies the fields for that SugarBean. For example, the vardefs for the Contact bean are located in ./modules/Contacts/vardefs.php.

Dictionary Array

Vardef files create an array called $dictionary, which contains several entries including tables, fields, indices, and relationships.

  • table : The name of the database table (usually, the name of the module) for this bean that contains the fields
  • audited : Specifies whether the module has field-level auditing enabled
  • duplicate_check : Determines if duplicate checking is enabled on the module, and what duplicate check strategy will be used if enabled. 
  • fields : A list of fields and their attributes
  • indices : A list of indexes that should be created in the database
  • optimistic_locking : Determines whether the module has optimistic locking enabled
    • Optimistic locking prevents loss of data by using the bean's modified date to ensure that it is not being modified simultaneously by more than one person or process.
  • unified_search : Determines whether the module can be searched via Global Search 
    • This setting defaults to false and has no effect if all of the fields in the fields array have the 'unified_search' field attribute set to false.
  • unified_search_default_enabled : Determines whether the module should be searched by default for new users via Global Search
    • This setting defaults to true but has no effect if unified_search is set to false.
  • visibility : A list of visibility classes enabled on the module

Duplicate Check Array

The duplicate_check array contains two properties, that control if duplicate checking is enabled on the module, and which duplicate check strategy will be used to check for duplicates.

The two properties for the array are as follows:

Name Type Description
enabled Boolean Specifies whether or not the Bean is utilizing the duplicate check framework
<class_name> Array <class_name> is the name of the duplicate check strategy class that is handling the duplicate checking. It is set to an array of Metadata, specific to the strategy defined in the key. Review the Duplicate Check Framework for further information.

Fields Array

The fields array contains one array for each field in the SugarBean. At the top level of this array, the key is the name of the field, and the value is an array of attributes about that field.

The list of possible attributes are as follows:

  • name : The name of the field
  • vname : The language pack ID for the label of this field
  • type : The type of the attribute
    • assigned_user_name : A linked user name
    • bool : A boolean value
    • char : A character array
    • date : A date value with no time
    • datetime : A date and time
    • email : An email address field
    • enum : An enumeration (dropdown list from the language pack)
    • id : A database GUID
    • image : A photo-type field
    • link : A link through an explicit relationship. This attribute should only be used when working with related fields. It does not make the field render as a link.
    • name : A non-database field type that concatenates other field values
    • phone : A phone number field to utilize with callto:// links
    • relate : Related bean
    • team_list : A team-based ID
    • text : A text area field
    • url : A hyperlinked field on the detail view
    • varchar : A variable-sized string
  • table : The database table the field comes from.
    • The table attribute is only needed to join fields from another table outside of the module in focus.
  • isnull : Whether the field can contain a null value
  • len : The length of the field (number of characters if a string)
  • options : The name of the enumeration (dropdown list) in the language pack for the field
  • dbtype : The database type of the field (if different than the type)
  • reportable : Determines whether the field will be available in the Reports and Workflow modules
  • default : The default value for this field. Default values for the record are populated by default on create for the record view (for Sidecar modules) and edit view (for Legacy modules) layout but can be modified by users. The Default Value option is available for all data type fields except HTML, Image, Flex Relate, and Relate.
  • massupdate : Determines whether the field will show up in the mass-update panel on its module's list view
    • Some field types are restricted from mass update regardless of this setting.
  • rname : For relate-type fields, the field from the related variable that contains the text
  • id_name : For relate-type fields, the field from the bean that stores the ID for the related bean
  • source : Set to 'non-db' if the field value does not come from the database
    • The source attribute can be used for calculated values or values retrieved in some other way.
  • sort_on : The field to sort by if multiple fields are used in the presentation of field's information
  • fields : For concatenated values, an array containing the fields that are concatenated
  • db_concat_fields : For concatenated values, an array containing the fields to concatenate in the database
  • unified_search : Determines whether the field can be searched via Global Search
    • This has no effect if the dictionary array setting 'unified_search' is not set to true.
  • enable_range_search : For date, datetime, and numeric fields, determines if this field should be searchable by range in module searches
  • dependency : Allows a field to have a predefined formula to control the field's visibility
  • studio : Controls the visibility of the field in the Studio editor
    • If set to false, then the field will not appear in any studio screens for the module. Otherwise, you may specify an Array of view keys from which the field's visibility should be removed (e.g. array('listview'=>false) will hide the field in the listview layout screen).
The following example illustrates a standard ID field for a bean:
'id' => array (
    'name' => 'id',
    'vname' => 'LBL_ID',
    'type' => 'id',
    'required' => true,

Indices Array

This array contains a list of arrays that are used to create indices in the database. The fields in this array are:

  • name : The unique name of the index
  • type : The type of index (primary, unique, or index)
  • fields : An ordered array of the fields to index
  • source : Set to 'non-db' if you are creating an index for added application functionality such as duplication checking on imports
The following example creates a primary index called 'userspk' on the 'id' column:
    'name' => 'userspk', 
    'type' => 'primary', 
    'fields'=> array('id')

Relationships Array

The relationships array specifies relationships between beans. Like the indices array entries, it is a list of names with array values.

  • lhs_module : The module on the left-hand side of the relationship
  • lhs_table : The table on the left-hand side of the relationship
  • lhs_key : The primary key column of the left-hand side of the relationship
  • rhs_module : The module on the right-hand side of the relationship
  • rhs_table : The table on the right-hand side of the relationship
  • rhs_key : The primary key column of the right-hand side of the relationship
  • relationship_type : The type of relationship (e.g. one-to-many, many-to-many)
  • relationship_role_column : The type of relationship role
  • relationship_role_column_value : Defines the unique identifier for the relationship role
The following example creates a relationship between a contact and the contact that they report to. The reports_to_id field maps to the id of the record that belongs to the higher-ranked contact. This is a one-to-many relationship in that a contact may only report to one person, but many people may report to the same contact.
'contact_direct_reports' => array(
    'lhs_module' => 'Contacts',
    'lhs_table' => 'contacts',
    'lhs_key' => 'id',
    'rhs_module' => 'Contacts',
    'rhs_table' => 'contacts',
    'rhs_key' => 'reports_to_id',
    'relationship_type' => 'one-to-many'

Visibility Array

The visibility array specifies the row level visibility classes that are enabled on the bean. Each entry in the array, is a key-value pair, where the key is the name of the Visibility class and the value is set to boolean True. More information on configuring custom Visibility strategies can be found in the Architecture section under Visibility Framework.

Extending Vardefs

More information about extending and overriding vardefs can be found in the Extensions Framework documentation under Vardefs.


    The most common way to create custom fields in Sugar is via Studio inside the application. This page describes how to use the ModuleInstaller class or vardef extensions as alternative methods of creating custom fields.
    When importing records to Sugar via the Import Wizard, users can select which of the mapped fields they would like to use to perform a duplicate check and thereby avoid creating duplicate records. This article explains how to enable an additional field or set of fields for selection in this step.
    Sugar provides a simple method for creating custom indexes through the vardef framework. Indexes can be built on one or more fields within a module. Indexes can be saved down to the database level or made available only in the application for functions such as Import Duplicate Checking.

Last modified: 2020-03-16 17:00:15