From SugarCRM Wiki

Notice: This documentation is about SugarCRM 4.5. There may be more current documentation available here or take a look at all metadata related articles here.

Contents 1 About Vardefs 1.1 Dictionary Array 1.2 Fields Array 1.2.1 Examples 1.3 Indices Array 1.4 Relationships Array

About Vardefs

Vardefs are used to provide the Sugar application with information about SugarBeans. They 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 is located in sugarcrm/modules/Contacts/vardefs.php.

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

Dictionary Array

• 'table' = The name of the database table (usually, the name of the module) for this bean that contains the fields.
• 'audited' = True if this module has auditing turned on
• 'fields' = A list of fields and their attributes (see below)
• 'indices' = A list of indexes that should be created in the database (see below)
• 'relationships' = A list of the relationships for this bean (see below)
• 'optimistic_locking' = True if this module should obey optimistic locking. Optimistic locking uses the modified date to ensure that the bean you are working on has not been modified by anybody else when you try and save. This prevents loss of data.

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
  • relate = Related Bean
  • date = Just the date
  • datetime = A date and time
  • bool = A boolean value
  • enum = An enumeration (dropdown list from the language pack)
  • char = A character array
  • assigned_user_name = A linked user name
  • varchar = A variable sized string
  • int = A number value
  • link = ???
  • name = ???
  • function = Fill the field from a function, see below
  • currency = A field describing a currency amount
• 'len' = The length of the field (number of characters if a string)
• Ways to fill an enum:
  • 'options' = The name of the enumeration in the language pack for this field
  • 'function' = The name of the function that fills the option list
• When using type = 'function'
  • 'function_name' = 'getEmployeesFromLastAnnual',
  • 'function_class' = If the function is part of a class, specify class here
  • 'function_params' = Array specifying the function parameters, for example: array('id'),
  • 'function_params_source' = 'this' or 'parent', are the parameters coming from this bean or a parent bean?
  • 'function_require' = Allows you to specify a script to include
• 'table' = The table this field comes from
• 'isnull' = Is this field allowed to be set to null?
• 'dbtype' = The database type of the field (if different than the type)
• 'reportable' = Should this field show up in the list of fields for the reporting module (if applicable).
• 'required' = true if this field is a required field
• 'default' = The default value for this field
• 'massupdate' = false if you do not want this field to show up in the mass update section at the bottom of the list views. Defaults to true.
• 'rname' = (for type relate only) The field from the related variable that has the text
• 'id_name' = (for type relate only) The field from the bean that stores the id for the related Bean
• 'source' = Specifies the source of the field value. Default is from the database. 'non-db' ('nondb' is deprecated) if the field value does not come from the database. This 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.
• 'fields' => (for concatinated values only) An array containing the fields that are concatenated.
• 'db_concat_fields'=> (for concatinated values only) An array containing the fields to concatenate in the DB.
• 'auto_increment' = make this an auto increment field (it will create the correct SQL for table creation and will not update the field from SugarBean.php.
• 'studio' = 'false' or 'true' (these are strings, not booleans). Flag to disable the display of the field in Studio. This can be helpful if Studio cannot handle the field properly.

Examples

A standard ID field for a Bean:

'id' => array(
  'name' => 'id',
  'vname' => 'LBL_ID',
  'type' => 'id',
  'required'=>true,
),

A standard dropdown (enum) field:

'lead_source' => array(
  'name' => 'lead_source',
  'vname' => 'LBL_LEAD_SOURCE',
  'type' => 'enum',
  'options' => 'lead_source_dom',
  'len' => '100',
  'comment' => 'How did the contact come about',
),

A field getting its results from a function:

$dictionary["Account"]["fields"]['employees'] = array(
  'name' => 'employees',
  'vname' => 'LBL_EMPLOYEES',
  'type' => 'function',
  'len' => 10,
  'function_name' => 'getEmployeesFromLastAnnual', //function name
  'function_params' => array('id'), //get these fields
  'function_params_source' => 'this', //from the current bean
  'function_require' => 'custom/modules/Accounts/madcap_functions.php', //file with function
  'comment' => 'Number of employees, prefilled with employees value from last annual report',
);

More information on using functions to fill fields, see SugarBean::process_union_list_query() in ./data/SugarBean.php.

Indices Array

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

• 'name' = The name of the index. This must be unique in most databases.
• 'type' = The type of the index (primary, unique, or index)
• 'fields' = The fields to index. This is an ordered array.

The following example is to create a primary index called 'userspk' on the 'id' column

array(
  'name' => 'userspk',
  'type' => 'primary',
  'fields' => array('id')
),

Relationships Array

The relationships array is used to specify 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 ('one-to-many' or 'many-to-many')
• 'relationship_role_column_value'=???

The following example creates a reporting relationship between a contact and the person that they report to. The reports_to_id field is used to map to the id field in the contact of the person they report to. This is a one to many relationship in that each person is only allowed to report to one person. Each person is allowed to have an unlimited number of direct reports.

'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'
),