SugarCRM SupportDocumentationSugar DeveloperSugar Developer Guide 7.8IntroductionMigration 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.8. This guide focuses on changes in Sugar 7.8 that could cause an immediate impact on Sugar customizations and integrations built for Sugar 7.7.

Expected to Affect Most Developers

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

Support for PHP 5.6 only

In this release, Sugar has dropped support for PHP versions that had reached their end of life. This means we have dropped support for PHP 5.3, 5.4, and 5.5. Sugar Developers should ensure their development environments are setup with PHP 5.6 and that any on-site hosting environments are also using PHP 5.6 when running Sugar 7.8.

For more details on the benefits of PHP 5.6 and what it means for Sugar Developers please review the following blog posts.

Upgrade to Backbone v1.2.3

Backbone.js is the key library that serves as basis for the Sidecar framework used for Sugar client (front-end) development. This library underwent a long overdue upgrade from v0.9.10 to v1.2.3 in the Sugar 7.8 release. There were a significant number of API changes to Backbone that can affect custom Sidecar code. It is therefore essential that Sugar Developers test their custom Sidecar controllers in Sugar 7.8 to assure they continue to behave as expected.

A Sugar Developer blog was posted on July 13th, 2016 that covers in deep technical detail a number of impactful changes. Please review this blog post for more details.

Custom code that relies on Backbone v0.9.10 will break in Sugar 7.8.

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.8. It is expected that these items will affect some developers.

Removal of deprecated or empty Sidecar controllers, classes, and methods

Where these APIs are in use, this change will cause breakages.

A number of previously deprecated Sidecar classes and methods have been removed in this Sugar release. We have also removed a number of empty Sidecar controllers that were unnecessarily included in the codebase. If you are using any of the following then you need to update your code to remove these references. Where there is an alternative API, we have identified it in the format: Old API → Alternative API

Sugar Dashlets


Sidecar Methods

app.Bean.setDefaultAttributes() → app.Bean.setDefault()

app.Bean.setDefaultAttribute() → app.Bean.setDefault()


app.Bean.getDefaultAttribute() → app.Bean.getDefault()

app.Bean.getDefaultAttributes() → app.Bean.getDefault() → → → → →

Sidecar Controllers














Enforcement of CSRF Tokens

In this Sugar release, the $sugar_config['csrf']['soft_fail_form'] setting will default to false and the $sugar_config['csrf']['opt_in'] setting has been removed. This means that CSRF tokens are now enabled out of the box.

For more details on Sugar's CSRF implementation, please review the following post on the Sugar Developer blog.

HTML forms used in BWC modules need to be authenticated in order to continue to function. If necessary, Sugar Developers can temporarily set the following configuration variable to disable enforcement of CSRF tokens.

$sugar_config['csrf']['soft_fail_form'] = true

The above setting will generate FATAL messages in the sugarcrm.log whenever a CSRF authentication failure happens. Sugar Developers and Administrators should not use this configuration in production instances.

jQuery library upgrade

In this Sugar Release, we have upgraded jQuery from version 1.7.1 to version 1.11.3. This jQuery affects both Sidecar and BWC modules. Note that the jQuery 1.9 release was a major release that modified many existing jQuery APIs. So we have included jQuery Migrate 1.2.1 plug-in to preserve behavior for custom code using pre-1.9 jQuery APIs.

Please review the jQuery 1.9 Upgrade Guide for more details:

For more details on the jQuery Migrate plug-in, please review the README:

Sugar Developers migrate code using old jQuery APIs and re-test code that makes use of jQuery to ensure there are no unexpected changes in behavior. 

Underscore library upgrade in Sidecar framework

The Underscore.js library has been upgraded from v1.4.4 to v1.8.3. Sugar Developers that have written code that uses Underscore APIs should test their customizations to ensure regressions have not occurred.

An Underscore API change introduced in version 1.5.0 means that using _.bindAll(object) no longer works. You must specify the specific method names to bind using _.bindAll(object, methodNames). Any custom Sugar code that relies on _.bindAll(object) needs to be updated. We recommend Sugar Developers use Underscore _.bind() or some other alternative to pass context to individual callback methods instead.

There are, in other cases, a change in order of parameters used in some Underscore APIs. Usage of Sidecar provided APIs is unaffected by these changes in Underscore.

For full details, please refer to Underscore.js changelogs:

There has been a change to how the SugarCRM logo in the footer of the application is rendered. The logo URL is no longer part of the FooterLayout Handlebars template. It is now set using JavaScript within the FooterLayout controller each time the layout is rendered. These changes may affect those instances that have customized the theme and branding of the Sugar application.

Changes to the Preview layout

Previously, the Preview components were initialized only when first rendering the page. This sometimes meant the Preview components were not properly initialized for the correct module when previewing a record. The Preview components (such as the PreviewView) are now re-initialized and re-rendered whenever a preview icon is clicked to ensure it is properly initialized.

This change in behavior can affect code that relied on the old Preview initialization procedure.

Additionally, the Preview Layout metadata has changed to support lazy loading for performance improvements. Any custom Preview Layout metadata should have the lazy_loaded flag set to true.

For example,

$viewdefs['base']['layout']['preview'] = array(
    'lazy_loaded' => 'true',
    'components' => array(


The oauth_token URL parameter is no longer enabled by default

A convenience feature that allowed an OAuth 2.0 access token to be passed via the oauth_token URL parameter instead of using the OAuth-Token HTTP header is no longer enabled by default in Sugar 7.8. This was disabled due to security concerns with passing and accepting session identifiers using URL parameters since this is against OWASP guidelines. The examples in this Sugar Developer Guide use the OAuth-Token HTTP header.

For reference:
Session Management Cheat Sheet - OWASP

This HTTP request is no longer supported

GET /sugar/rest/v10/Contacts?oauth_token={access-token} HTTP/1.1
Host: localhost:8080
Content-Type: application/json
Cache-Control: no-cache

 This HTTP request continues to be supported

GET /sugar/rest/v10/Contacts HTTP/1.1
Host: localhost:8080
Content-Type: application/json
OAuth-Token: {access-token}
Cache-Control: no-cache 

If you need to enable this feature temporarily then you can use the following SugarConfig setting.

$sugar_config['allow_oauth_via_get'] = true;

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.8. It is expected that these items will affect few developers.

Removal of external Job Queue framework classes added in Sugar 7.7

Where these APIs are in use, this change will cause breakages.

The partial implementation for an external job queue framework that was added in Sugar 7.7 has been removed in the Sugar 7.8 release. We decided to not go forward with the Sugar 7.7 based implementation of the external job queue. The cron.php based job queue and scheduler continues to be supported.



Removal of unused code in Advanced Workflow

Where these APIs are in use, this change will cause breakages.

Unused Advanced Workflow related code has been removed in this Sugar release. This does not have an impact on Advanced Workflow behavior.





Removal of unused SugarMVC Notifications controller

Where these APIs are in use, this change will cause breakages.

In this Sugar release, we have removed the empty SugarMVC Notifications module controller that has no longer been in use by Sugar.


Custom code that used or included these classes or files will need to be updated.

Removal of setFields parameter from Sidecar loadData() methods

Where these APIs are in use, this change will cause breakages.

There has been a change in the supported parameters for Sidecar's Layout#loadData() and View#loadData() methods in this Sugar release. The optional setFields parameter could be used to change the fields set on the current Context. This allowed a single Sidecar component on the page to alter the behavior of other Sidecar components on the page which is unwise. So support for the setFields parameter has been removed.

The new method signature for Sidecar loadData() functions is now:


TinyMCE library upgrade for Sidecar

The TinyMCE library has been upgraded from v3.5.8 to v4.1.8 for Sidecar modules. The TinyMCE version used in BWC modules has not changed. This may affect custom code that uses TinyMCE. For more details view the TinyMCE changelog.

Timepicker library upgrade

The jQuery timepicker plugin has been upgraded from v1.4.10 to v1.8.8 in this Sugar release. No changelog is available so please use the jQuery timepicker Github repository to review API changes between these versions.

Extraneous render in Record View

The Sugar Record view (RecordView) was being rendered twice on each page load. This performance issue has been corrected. Now the Record view renders once and the individual Field components are re-rendered when data is available. Sugar Developer should test their record view customizations to ensure this does not introduce any regressions in code that relied on this behavior.

Specifically, Developers should test if custom Sidecar code relies on field data being available during Record view render then this will break because Views are rendered before Fields.

Change in default model used for Sidecar's BeanCollection class

The default model class for Sidecar's Data.BeanCollection is now Data.Bean instead of Backbone.Model.
This change can affect code that expected Backbone.Model.

Removal of oracle_enable_ci setting

The Sugar Config setting oracle_enable_ci is being removed. It was a setting previously because case insensitive query behavior on Oracle was only obtained at a performance cost. This setting was removed because case insensitivity does not impact performance anymore for Oracle.

This can affect Sugar deployments using this setting but an internal survey of Oracle customers determined that use of this setting is limited.

Deprecation of Tooltip and EllipsisInline Sidecar plug-ins

The Tooltip and EllipsisInline Sidecar plug-ins have been deprecated in this release. As of Sugar 7.8, these plug-ins are ignored and the client will instead simply look for ellipsis_inline class and rel=tooltip attribute on DOM elements. Tooltips are now initialized during mouseover event.

Sugar Developers should verify that ellipsis_inline class and rel=tooltip attribute is not used where it is not needed otherwise ellipsis and tooltips may begin to appear in places where it did not appear in the past.

Sidecar Relate Field changes

The Sidecar Field def property that merged a field's viewdefs and vardefs has been deprecated in this Sugar release. This was necessary, in part, to address issues in Sidecar's Relate field.

The Sidecar RelateField has been changed in this release to rely on this.viewDefs and this.fieldDefs properties instead of the deprecated this.def property. This may affect some code customizations that have been made to Relate fields. For example, custom fields that extend from the RelateField controller.

Sidecar Alert auto-close changes

The default automatic close timeout when using Sidecar Alerts is now 5 seconds instead of 9 seconds. This may affect users expecting a longer timeout. Sugar Developers can optionally providing a delay time in milliseconds to change this behavior.

For example,

// This Sidecar Alert message will automatically close after 10 seconds'message-id', {
    level: 'success',
    messages: 'Task completed!',
    autoClose: true
    autoCloseDelay : 10000


Last modified: 11/27/2017 12:24pm