SugarCRM SupportDocumentationSugar DeveloperSugar Developer Guide 7.9IntroductionMigration Guide

Migration Guide


The purpose of this document is to provide insight to Sugar Developers for upgrading custom Sugar code, extensions, and integrations to Sugar 7.9. This guide focuses on changes in Sugar 7.9 that could cause an immediate impact on Sugar customizations and integrations built for Sugar 7.8.x.

Sugar Instance Upgrade Path

The supported upgrade path to Sugar is only from Sugar,,, 

Expected to Affect Most Developers

This section explains items expected to have widest impact on Sugar customizations and integrations when migrated to Sugar 7.9. We expect that these items will affect most developers.

Quotes Module Migration to Sidecar

Quotes is one of the most heavily used and customized modules in Sugar. It was also one of the most heavily customized modules that used Backward Compatibitliy in the Sugar 6.x Legacy MVC framework.

Customizations to Quotes JavaScript will need to be rewritten for the new Sidecar based Quotes UI. Automated migration of these customizations is not possible. Common quote customization areas can be found in the sections below:

How to Customize Quote Identifiers

Customers may need a custom quote identifier or numbering scheme that goes beyond the auto-incrementing scheme used out of the box. Information on customizing quote identifiers can be found in the Quote Identifiers section of the developer documentation.

How to Customize the Quote List Header

The Quote Data List Header is a complex view that pulls data from multiple modules.


Information on customizing quote identifiers can be found in the Quotes List Header section of the developer documentation. 

How to Customize the Quote Grand Totals Header

The Grand Total Header contains the overall calculated totals for the quote.grandtotal

Information on customizing quote grand totals header can be found in the Quotes Grand total Header section of the developer documentation. 

The Grand Total Footer contains the overall calculated totals for the quote .gtf

Information on customizing quote grand totals header can be found in the Quotes Grand Total Footer section of the developer documentation. 

Ungrouped Quoted Line Items and Notes

The new Sugar quotes module allows users to add quoted line items and notes to a quote without first adding a group. Adding at least one group to your quote was mandatory in earlier Sugar versions. Information on customizing quote PDF line items can be found in the Quotes Ungrouped Quoted Line Items and Notes section of the developer documentation. 

In Sugar 7.9, most queries that Sugar executes are now parameterized. Some new Query APIs have been added to support prepared statements as well. The most important change is that we have adopted parts of Doctrine's Database Abstraction Layer, especially the QueryBuilder class, for working with prepared statements. Many DBManager APIs and some SugarQuery APIs were deprecated as part of our plans to add prepared statement support to Sugar. These deprecated APIs have been removed in Sugar 7.9. If you haven't already, you must migrate your custom code that uses these APIs to alternative APIs prior to Sugar 7.9 upgrades.

As part of adding prepared statements support to Sugar, the following deprecated PHP classes and methods have been removed in this Sugar release.

  • SugarQuery_Builder_Delete
  • SugarQuery_Builder_Insert
  • SugarQuery_Builder_Update
  • SugarQuery_Builder_Literal
  • SugarQuery_Compiler
  • SugarQuery::joinRaw()
  • SugarQuery::compileSql()
  • DBManager::delete()
  • DBManager::retrieve()
  • DBManager::insertSQL()
  • DBManager::updateSQL()
  • DBManager::deleteSQL()
  • DBManager::retrieveSQL()
  • DBManager::preparedQuery()
  • DBManager::pQuery()
  • DBManager::prepareQuery()
  • DBManager::prepareTypeData()
  • DBManager::prepareStatement()

The following parameters have been removed their corresponding methods this Sugar release.

  • The $execute parameter on DBManager::insertParams() 
  • The $execute parameter on DBManager::updateParams() 

For more details on Prepared Statements and how to use them with your Sugar customizations, please refer to the SugarQuery documentation and this post on the Sugar Developer blog.

Expected to Affect Some Developers

This section explains items expected to have a moderate impact on Sugar customizations and integrations when migrated to Sugar 7.9. It is expected that these items will affect some developers.

Removal of Sidecar's invokeParent function

The deprecated Sidecar app.view.invokeParent() function has been removed in this Sugar release. Sugar Developers should use Component#_super() method instead. This function was commonly used in early Sidecar customizations prior to Sugar 7.5. Examples are shown below:

Old Usage

initialize: function(options) {
app.view.invokeParent(this, {
type: 'field',
name: 'rowaction',
method: 'initialize',
args: [options]

New Usage

initialize: function(options) {
this._super('initialize', [options]);

Module Loadable Packages Created Prior to are not Supported

Some Module Loadable Packages created using Module Builder in Sugar versions prior to cannot be installed into Sugar due to a change in relationship metadata format. When a package is already installed prior to upgrade, the Sugar upgrader will update the relationship metadata format automatically.

To correct this issue, developers must update their relationship metadata to use the Sugar format which defines field arrays using the field name as the index. 

 The change must modify the format of:

1 => array (
    'name' => 'date_modified',
    'type' => 'datetime',


'date_modified' => array (
    'name' => 'date_modified',
    'type' => 'datetime',

The format for ID fields has also changed. The Sugar format requires that ID fields use the id type.

Modify the format of:

    'name' => 'id',
    'type' => 'varchar',
    'len' => 36,


    'name' => 'id',
    'type' => 'id',

Once these changes are made to the metadata, developers will need to update the built_in_version value to or higher in the manifest.php of the installer package.

PHP 7.x code changes

Significant code changes were made in this Sugar release in preparation for PHP 7.x support in the near future. Some examples include removal of PHP 4 style constructors and other deprecated PHP functions or features. Sugar Developers should visit this developer blog post for more details on preparing code customizations for PHP 7.x. For example, if you have custom code that is calling a PHP 4 constructor for a core Sugar class then you will encounter errors.

Sugar Developers are also advised that we plan to certify support for PHP 7.1 and not PHP 7.0 in the future.

Replacement of Sugar's Built-in Help system

We have redesigned how the out of the box help system in Sugar works in this release. Sugar 7.9 introduces a new Help pop-up system which means customizations to several Help related dashlets or dashboards will need to be updated. Any changes to Help language strings, translations, or changes to learning resources links will continue to work because they are preserved in the new Help pop-up. Because of this, we expect the most common customizations to Help system will continue to work.

However, the following Sidecar controllers have been removed in this Sugar release.

  • ./clients/base/layouts/help-dashboard/
  • ./clients/base/views/help-dashlet
  • ./clients/base/views/help-dashboard-headerpane
  • ./modules/Home/clients/base/views/help-dashboard-headerpane
  • ./clients/base/views/search-help-dashboard-headerpane - note that this didn't exist before Sugar 7.7
  • ./modules/Forecasts/clients/base/views/help-dashlet

Reports List View Migration to Sidecar

The Reports module list view has been moved into Sidecar user interface. The Reports wizard and detail views have not been changed in this release. Customizations that have been made to the Reports module Sugar 6.x Legacy MVC list view will need to be migrated to the new Sidecar user interface. Automated migration of these customizations is not possible.

Miscellaneous Sidecar Refactoring and Changes

User interface customizations are typically built using the Sidecar framework. There have been some miscellaneous changes in Sidecar in a number of different areas that may affect customizations.

Browser Security

Web local storage is tied to a web application's domain. This can cause information to leak between web applications hosted on the same domain. For example, web applications hosted at and could potentially access each other's information in local storage.

Browser local storage is now flushed when logging into different instances on same web domain. This change prevents inadvertent sharing of OAuth tokens and other settings between Sugar instances on the same web domain.

JavaScript Library changes

The library that Sidecar uses to access web local storage library has been changed from stash.js to store.js. Stash.js has no active maintainers and was using deprecated browser APIs which necessitated a change to the better supported store.js open source library. This change will be transparent for app.cache.* Sidecar APIs but where Sugar Developers have used stash.js APIs directly then they will encounter breakages.

Code breakages are possible where custom JavaScript code has called stash.js APIs directly.

Sidecar libraries have also been moved from ./sidecar/lib/ directory to under ./sidecar/node_modules/ directory as part of this Sugar release. This is a side effect of using Yarn (JavaScript dependency manager) to manage Sidecar's JavaScript dependencies. Please view ./sidecar/package.json to see more details about each Sidecar dependency.

Sidecar Plug-Ins

The previously deprecated SearchAhead Sidecar plug-in has been removed in this Sugar release.

Sidecar JavaScript APIs

The following deprecated Sidecar JavaScript APIs were removed in this release. 

  • app.utils.tooltip 
  • options.clearAllListeners from Context#clear(options) has been deprecated.
  • SUGAR.util.ajaxCallInProgress() has been deprecated. Use jQuery's $.active API or ajaxStart and ajaxStop jQuery events instead.

Sidecar Events

The app:locale:change global Sidecar event is now triggered after app.lang.setCurrentLanguage() is called. The new locale code is also passed to listeners of this app:locale:change event. It is now easier to use the app:locale:change event to identify the correct new locale.

Sidecar Collection fields

For collection field types, Sidecar will now store values as MixedBeanCollection objects. This allows you to relate or unrelate records on a Sidecar Bean by adding and removing records from the MixedBeanCollection and then calling Bean#save()

Sidecar Controller changes

The Type parameter is no longer hardcoded within SubpanelLayout#initialize(). This will make it easier to extend SubpanelLayout classes. Customizations to SubpanelLayout should be tested to confirm they still function properly after upgrade.

Home module routing

Routing for the Home module has been simplified to load Home Dashboards by routing to record layout instead of list layout. This is primarily a routing change, the layout that is loaded and the structure of the Home Dashboard has not changed. This should only be a concern if routing for Home module has been customized.

Expected to Affect Few Developers

This section explains items expected to have a low impact on Sugar customizations and integrations when migrated to Sugar 7.9. It is expected that these items will affect few developers.

Removal of D&B Connector

D&B Connector and all related components have been removed in this Sugar release. All REST API endpoints, layouts, views, and dashlets associated with the D&B connector have been removed. The D&B connector settings page has also been removed from the Administration panel. The DUNS number and other D&B related fields are retained on those modules that had them.

Removal of Zend-Mail library

The Zend-Mail PHP library has been removed in this Sugar release. Sugar core code never used the Zend-Mail library and it has been the subject of recent CVE security advisory. Sugar Developers should make sure their customizations are not dependent on Sugar's Zend-Mail library prior to upgrade.

As part of this change, the following directory was removed. If you were relying on any PHP classes under that directory that you will need to fix this code.


Removal of Deprecated DB Adapters

The following DBManager classes are no longer available for use or have been removed in this Sugar release. These classes relied on PHP extensions that have been deprecated and removed in PHP 7.x:

  • MysqlManager is now an abstract class.
  • MssqlManager is now an abstract class.
  • FreeTDSManager has been removed entirely.

The following files have been removed:

  • ./include/database/FreeTDSManager.php
  • ./include/database/FreeTDSHelper.php

Where necessary, Sugar Developers can use the following classes instead:

  • MysqliManager
  • SqlsrvManager

Removel of allow_bwc in Button Metadata

As of 7.9, allow_bwc property has been deprecated and will be removed in 7.10. Developers should use the use the full_form metadata property instead.

DCMenu JavaScript functions related to our previous (Sugar 6.x based) Dashlet framework has been removed in this Sugar release.


The following JavaScript function that is used in BWC modules has been removed in this Sugar release.


Possible enforcement of supported platforms extension

A new Platforms extension has been added. This allows Sugar Developers to register new Sugar platform names that are used by the Sugar instance. Custom Sugar platforms are used by some REST API integrations or those creating new Sidecar clients.

Unregistered (unknown) platforms are not allowed to be used with Sugar when the $sugar_config['disable_unknown_platforms'] setting is enabled. This means that where it is enabled, REST API integrations that uses unregistered custom platforms will be intentionally broken.

For example, to create a new test platform, you would create a file ./custom/Extension/application/Ext/Platforms/test_platform.php with the contents: 


$platforms[] = 'test';

Relationship metadata array index changes

The format for Sugar metadata used to describe Relationships has changed in this release. Relationship field metadata is now array indexed by the name of the field. For example, the relationship ID field definition can now be accessed using $definition['fields']['id'] instead of $definition['fields'][0].

Existing metadata in prior Sugar versions will be migrated to the new format during an upgrade to Sugar 7.9.

Skip tutorial flag no longer needed

Sugar's tutorial system is no longer activated automatically when users log in for the first time. Therefore the following Sugar Config setting has been removed in this Sugar release since it is no longer needed.


PHP Autoloading changes

A big and welcome improvement to Sugar's Autoloader! The majority of core Sugar PHP classes are now autoloadable even many of those that are not PSR{0,4} compliant. This means that boilerplate code like require_once 'include/api/SugarApi.php' is no longer needed. Most of the unnecessary require_once calls have been removed from the Sugar codebase.

When adding new non-PSR4-compliant classes (e.g. ./custom/clients/base/api/SomeNewApi.php) then you may need to delete ./cache/class_map.php and ./cache/file_map.php or run a Quick Repair and Rebuild. This will clean the autoloader cache so that your new class is indexed and autoloaded by Sugar at runtime.

Last modified: 04/25/2018 11:25pm