Metadata Upgrades

sugarcrmdevelopers —  May 26, 2010 — Leave a comment

This blog will cover what occurs to the metadata files during upgrades.  The files that are involved with parsing, merging and saving the metadata files are included in the upgrade zip file under the [SugarUpgradeVersion]/modules/UpgradeWizard/SugarMerge directory.  Today, both the silentUpgrade and Upgrade Wizard code execute the SugarMerge code.  The entry point to start the metadata merge process begins with the SugarMerge class.  The logic to handle merging the various views (Edit, Detail, List, Search, QuickCreate, Subpanel) is located in the EditViewMerge class and its subclasses (DetailViewMerge, ListViewMerge, QuickCreateMerge, SearchMerge and SubpanelMerge).

Below is a class diagram of EditViewMerge and its subclasses.  I only diagrammed some of the main variables and methods used by the merge code.

EditViewMerge and Subclasses Class Diagram

SugarMerge has an internal mapping to know which EditViewMerge class or subclass to associate with the file (detailviewdefs.php, editviewdefs.php, listviewdefs.php subpaneldefs.php, quickcreatedefs.php, searchdefs.php) being parsed.   When SugarMerge is invoked, it takes the following steps:

  1. Scan all custom/modules subdirectories for metadata files
  2. For each metadata file found, check to see if the original metadata file (modules/[module]/metadata) and target version metadata file  ([upgrade zip file]/modules/[module]/metadata)  exists
  3. If the required files are found, use the appropriate EditViewMerge class or subclass to merge the the file contents and save to custom/modules/[module]/metadata directory as well as create a backup file within the corresponding directory with the ‘.suback.php’ suffix.

Each EditViewmerge class or subclass uses four main class variables in EditViewMerge to handle the specific internals of the metadata file.

For example, a simplified version of the Accounts module editviewdefs.php looks like:

$viewdefs ['Accounts'] =  array (

'EditView' =>  array (

'templateMeta' => ( ...),

'panels' => (...)



$viewdefs is the variable name of all the contents (this is captured by the varName variable)

‘EditView’ is the second level key after the module name to denote the view (this is captured by the viewDefs variable)

‘templateMeta’ is the key to the portion of the metadata file used to generate and load the header, footer, buttons and any additional javascript needed (this is captured by the templateMetaName variable)

‘panels’ is the key to the layout portion of the view (this is captured by the panelName variable)

Therefore, the corresponding subclasses may alter these variables so that the EditViewMerge code knows the appropriate variable names to use when accessing various portions of the metadata file.  In the same fashion, the methods listed in the EditViewMerge class contain the logic to handle the merging of the various bits of data in the files.  The ListViewMerge class overrides most of EditViewMerge’s methods since the contents of the listviewdefs.php files are quite different.

The rest of this blog will cover what to expect when the metadata merge takes place.  The list below relates to what will occur when upgrading to SugarCRM 6.0.

1) For EditViews, DetailViews and QuickCreate views we will merge field attributes that have not been customized in 5.5.x, but altered in 6.0.x. This is necessary so that we retrieve any bug fixes that may have been done as well as provide the ability to allow the studio user to modify the rows and cols attributes of the textarea field.

For example, in 5.5.x versions, we defined the textarea field’s rows and cols in the metadata file:

'displayParams'=>array('rows'=>6, 'cols'=>80),

However, in 6.0, this has been changed to:


As a result, the upgrade will alter the metadata definition to remove the ‘displayParams’ key/value pair since the ‘displayParams’ key/value pair was not customized in 5.5.x. If however, the user had manually modified the ‘displayParams’ key value/pair to be:

'displayParams'=>array('rows'=>10, 'cols'=>100),

Then an upgrade will preserve this ‘displayParams’ key/value pair in the metadata file. Please see bug number 36257 for more information regarding why most of the ‘displayParams’ key/value pair definitions were removed from the metadata files in 6.0.

2) For DetailView, EditView and QuickCreate views we will append new fields that have been added to the 6.0 Out-of-the-box layouts to the bottom of the default panel. This rule applies as well to flavor conversion where the Team field will be added to the bottom of the default panel. In order to determine where exactly the new field goes, the upgrade code shall do the following:

For DetailView, EditView and QuickCreate views

a) Check to see if there is an empty cell in the last row of the default panel. If so, take the first one available (left). If it’s the right, take the right cell.

b) If no filler space is available, then add a new row to the panel and add the new field to the left space.

c) Additional new files shall be added following the steps in a & b.
For 6.0, we have added the following new OOTB fields. Here is a breakdown of the files and the new OOTB fields for the layout we added.

Module Layout New Field(s) Notes
Campaigns DetailView Date Modified, Date Created
Cases DetailView Date Modified, Date Created
Contacts DetailView Picture
Contacts EditView Picture
Contracts DetailView Date Modified, Date Created
Employees DetailView Picture
Employees EditView Picture
Leads DetailView Date Created, Website For Website, assumes Website was not added to custom DetailView file
Leads EditView Website For Website, assumes that Website was not added to custom EditView file
Meetings DetailView Date Modified, Date Created
Projects DetailView Date Modified, Date Created
Targets DetailView Date Modified, Date Created

The same should occur with flavor conversions (upgrading from CE to PRO or CE to ENT).  In addition, team field will be added to the EditView, QuickCreate and DetailView views in all modules that support team security.

For SearchView and ListView views

a) We will not alter the positions of their fields as they have specified in their metadata files prior to the upgrade

b) We will merge the field metadata except for the ‘default’ attribute values. This will prevent new fields from appearing or existing fields from being removed.

c) New fields that are defined in 6.0 will have ‘default’ attribute set to false.
3) For the ListView and SearchView layouts, a number of things have changed in 6.0 that will affect the appearance of these fields in studio. There were various bug fixes applied to filter/add fields back into the Default and Hidden lists shown as well as out-of-the-box layout changes that were made. In order for a field to appear in either the Default or Hidden list for the ListView and SearchView studio layout editor, it must meet the following criteria:

  • ‘studio’=>’visible’ attribute has to be set in vardefs
  • In the vardefs definition of the field, the ‘studio’=>false attribute cannot be set
  • It cannot be an id field (user_id, team_id, modified_by_user_id, currency_id, parent_id, etc. will not appear in the lists)
  • It has to be a type of db or custom field
  • It cannot be the ‘deleted’ field
  • If the ‘query_only’ attribute for the field is defined in subpaneldefs.php, then exclude this field from the lists
  • -NOTE- If you had moved the offending fields from the hidden to the default panel prior to 5.5.x, then we will keep them in the Default list; however, if they then move the offending field back into the hidden list and then save the changes, the offending field will no longer be shown.

4) For all non-customized metadata files (i.e. there is no custom/modules/[module]/metadata/[metadata file] entry), we will just replace the existing files in modules/[module]/metadata with the out-of-the-box 6.0 file. We feel that this is consistent with the behavior of previous upgrades and is easier to implement because we would otherwise have to copy the contents of their modules/[module]/metadata directory and then create the corresponding modules/[module]/metadata directory to preserve the 5.5.x out-of-the-box metadata layouts.

5) For all customized DetailView and EditView metadata files, we will keep the layout in panel format. Otherwise for non-customized metadata files, we will just replace their metadata files as mentioned in #4. Because of this there will be some modules that may now default to the tab layout for DetailView and EditView. So if the system does not contain customized EditView or DetailView layouts for the Contacts, Accounts, Leads and Targets modules, the EditView and/or DetailView layouts for these modules will appear with the tab layout format.

6) For the special cases were ‘created_by’, ‘created_by_name’ or ‘modified_by_name’ fields were declared in the DetailView 5.5.x custom layout, we will rename these fields to ‘date_entered’ upon merging to ensure that the DetailView custom layout accurately reflects that available fields in studio. This change is needed because ‘created_by’, ‘created_by_name’, ‘modified_by_name’ do not appear in the list of fields for the modules in the studio editor. The known modules that may be affected are:

Module File Field Name Notes
Campaigns detailviewdefs.php created_by_name, modified_by_name
Cases detailviewdefs.php created_by_name, modified_by_name
Contracts detailviewdefs.php created_by_name, modified_by_name
Leads detailviewdefs.php created_by
Meetings detailviewdefs.php created_by_name, modified_by_name
ProspectLists detailviewdefs.php created_by_name, modified_by_name
Prospects detailviewdefs.php created_by_name, modified_by_name
Tasks detailviewdefs.php created_by_name, modified_by_name

7) For all existing SugarCRM dashlets, the upgrade simply replaces existing search and list definitions with those defined out-of-the-box in 6.0. This may have the affect of altering previous layouts and functionality.

No Comments

Be the first to start the conversation!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s