SugarCRM SupportDocumentationSugar DeveloperSugar Developer Guide 8.0IntroductionMigration 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 8 (Spring '18) release. This guide focuses on changes in Sugar 8 (Spring '18) that could cause an immediate impact on Sugar customizations and integrations built for Sugar 7.11 (Winter '18) cloud or Sugar 7.9.x.x releases. 

Sugar Instance Upgrade Path

The upgrade path for Sugar 8.0.0 (Spring '18) is from Sugar Winter '18 cloud and Sugar 7.9.x.x releases.

Upgrading from Sugar 7.9 to Sugar 8

For those looking to upgrade from Sugar 7.9, you will be catching up with additional content released last Fall '17 and Winter '18. In addition to this guide, please review the developer guides, in particular the migration guide, for Sugar 7.10  and Sugar 7.11 and Sugar 7.10 and Sugar 7.11 release notes on the Sugar Support site to get a full view of changes since Sugar 7.9. For example, Sugar 7.10 introduced a revamped Emails module and Sugar 7.11 introduced extensive CSS changes that give Sugar a brand new look and feel.

Please also carefully review Sugar 8 Supported Platforms as they have changed since Sugar 7.9. You will have to upgrade some software, such as Elasticsearch, prior to upgrading to Sugar 8.

Expected to Affect Most Developers

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

Enabling Data Privacy features used for GDPR compliance

The main area of focus since the Sugar 7.11 (Winter '18) release has been on some new Data Privacy features. While these new features do not raise many compatibility concerns, it is important to understand that many of these features are disabled or hidden by default. If you are working with a customer who needs to comply with GDPR, there will be some configuration that needs to be done.

Here is a list of some of the Data Privacy controls in the system and how to enable them.

Feature How to enable
Data Privacy module

Navigate to Administration > Display Modules and Subpanels.

Drag "Data Privacy" module from Hidden Modules list to Displayed Modules list.

Data Privacy Manager role

Navigate to Administration > Role Management.

Click on "Data Privacy Manager" role and scroll down to the bottom to add Users.

Users with "Data Privacy Manager" role also need to have module "Admin" rights to Person modules they need to manage.

If using demo data, Sally is assigned to DPM role and is module admin for Accounts, Contacts, Leads, Prospects modules by default.

Ability to opt-out new email addresses from Campaigns by default

Navigate to Administration > System Email Settings.

Check the "Opt-out new email addresses by default" checkbox.

Marking fields as containing personally identifiable information (PII)

Navigate to Administration > Studio or Module Builder.

Select the <Module> then Fields.

Edit the Field you want to mark as PII.

Check the option called "Personal information".

You can also use Vardefs extension to mark fields with PII. Note that audit is required for PII fields.

Ability to fully disable Activity Streams

Navigate to Administration > System Settings.

Uncheck "Enable Activity Streams"

Activity streams messages can contain personal information about data subjects.

When activity streams are disabled:

  • Personal information contained in activity streams are not visible in Sugar user interface.
  • Activity records are no longer created in the database.


Elasticsearch 1.7.5 to 5.x upgrade for Sugar 7.9 instances

If you are running Sugar 7.9, then you will need to upgrade Elasticsearch (ES) 1.7.5 to a newer version. We recommend upgrading to ES 5.6 since it is supported by Elastic until March 2019. However, 1.x indices cannot be upgraded directly to ES 5.x. ES 5.x will fail to run with 1.x indices present. Refer to Elasticsearch documentation for steps you can take to upgrade your ES 1.7.5 install to ES 5.6.

After upgrading to Sugar 8.0.0, you will need to run a full reindex of full-text search data. It may be easier to delete the existing Elasticsearch index manually prior to upgrading to ES 5.6.

New Sidecar components and features to support Data Privacy

A number of new Sidecar components and features were added for viewing and managing PII as well as handling erasure of PII.

Viewing and Managing PII

As part of Personally Identifiable Information (PII) capabilities, several new Sidecar components have been added. The following components are used as part of the "View personal information" flow on record views when PII fields are present on a record. This new action is added dynamically so it may conflict with customizations that change the contents of the record view metadata button array.  When clicked, this action opens the PiiLayout.

You should test Sidecar extensions that modify the following arrays:

$viewdefs['<person module(s)>']['base']['view']['record']['buttons']

You should also test any record view overrides as well.

./custom/modules/<person module(s)>/base/view/record/

New Sidecar Fields

Class name Directory location
PiinameField ./clients/base/fields/piiname

New Sidecar Layouts

Class name Directory location
PiiLayout ./clients/base/layouts/pii

New Sidecar Views

Class name Directory location
PiiHeaderpaneView ./clients/base/views/pii-headerpane
PiiView ./clients/base/views/pii

New Sidecar Plugin

Class name Directory location
Pii ./include/javascript/sugar7/plugins/Pii.js

Erasure of PII

The "Mark for Erasure" flow is implemented as a new action field on the DataPrivacy.RecordView that launches a new DataPrivacy.MarkForErasureLayout layout. The following Sidecar components were added in addition to the standard Record and List layouts on the new Data Privacy module.

New Sidecar Fields

Class name Directory location
DataPrivacyEraseField ./clients/base/fields/dataprivacyerase

New Sidecar Layouts

Class name Directory location
MarkForErasureLayout ./modules/DataPrivacy/clients/base/layouts/mark-for-erasure

New Sidecar Views

Class name Directory location
MarkForErasureHeaderpaneView ./modules/DataPrivacy/clients/base/views/mark-for-erasure-headerpane
MarkForErasureView ./modules/DataPrivacy/clients/base/views/mark-for-erasure

Erased template for Sidecar Fields

An erasure feature has been added to Sidecar Fields. A new "erased" field template has been added and used when a field has been permanently erased in response to a data privacy request. This field template will display a "Value Erased" pill shaped icon.


If you have built custom Sidecar field types that can contain personal information, make sure that the erased template is used properly when the field is erased. You can test this by using a Data Privacy request to erase the value of this field. After that, the "Value Erased" icon should be shown in place of your normal field.

Expected to Affect Some Developers

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

Changes to Audit APIs, data model, and behavior

There have been a number of changes to Sugar's audit log behavior. The audit log data model has also been updated to better support tracking of events.

A new Audit\EventRepository class has been introduced for finer grain management and storage of audited changes. In particular, the Audit\EventRepository is used to track when field changes are associated with an update or erase event as well as the source (Security\Subject) of the change.

A new audit_events table in the Sugar database is associated with the new Audit\EventRepository implementation.

Also, as part of the Data Privacy work, a new method has been added to the SugarBean class.

SugarBean::erase(FieldList $fields, $check_notify)‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍

This method ensures that data for these fields are erased from the audit log as well.

If you have customizations that interact with the Sugar audit log or the audit tables in the database, then this should be a focus area for testing.

New Admin panel to register custom API platforms

Great news for our ISVs! It is now possible for an Administrator to add or remove custom API platforms using the "Configure API Platforms" admin panel. It is no longer necessary for the developer of a REST API integration to create and deploy a Platform extension into customer instances to allow the use of unregistered API platforms. This new admin functionality does not interfere with existing Platform extensions that may be installed on Sugar instance.

This may require changes to integration installation documentation to address how Sugar Administrators can configure the integration using this new user interface.

Changes to Sidecar's Email field

The EmailField Handlebars templates (detail, list) and JavaScript controller have been changed to allow opted out email addresses to be selected for use in transactional email.

Customizations to the following files will need to be reworked in order to incorporate the new opt-out behavior.

  • ./clients/base/fields/email/detail.hbs
  • ./clients/base/fields/email/list.hbs
  • ./clients/base/fields/email/email.js

Expected to Affect Few Developers

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

Default REST API version changed to v11.1

The Sugar REST API now supports Major and Minor versioning as discussed in a previous Sugar Developer blog post. This release introduces the v11.1 REST API. The v11.1 REST API adds some additional endpoints and features while maintaining full compatibility with v11.

The default server URL used by Sidecar and Sugar clients is now /rest/v11_1/. This change would affect Sidecar code reliant on custom REST API endpoints with a max version of v11.

Changes to Emails and EmailAddresses relationships and data model

EmailAddress invalid_email and opt_out fields were added to the emails_email_addr_rel relationship vardefs. This emails_email_addr_rel table is used with EmailParticipants beans.

The ./modules/Emails/clients/base/fields/email-recipients/select2-selection.hbs has also been updated to make sure opt-out e-mail addresses are decorated properly.

The invalid_email and opt_out fields are now included with fromtocc, and bcc collection field data for Emails module.

The meetings relationship between Emails and Meetings module has been removed in this release. It was reserved for Sugar Email Archiving (also known as SNIP) service but it was not actually used and caused data inconsistencies in certain situations.

Meetings are related to other Sugar records using a flex relate (parent) field. It is, therefore, possible to retrieve Meetings created by an imported Email (from SNIP) using SugarQuery or Filter API to select Meetings where parent_type=Emails and parent_id=email_id.

Consistent format for dates on SugarBean objects

Dates on SugarBean objects should now be consistently formatted in the DB format instead of user-selected format. Developers should ensure their code relies on DB format when working with date information on SugarBean objects.

Locale support added to Sucrose Charts

Charts within Sugar now fully support system and user locale settings. As part of this change, the Sucrose library version was upgraded from v0.7.5 to v0.8.0. To learn more about working with locales in Sucrose please check out the locale guide.

If you have added locale support to a Sugar Chart as a customization, you should remove it and adopt Sucrose's built-in locale support.

Last modified: 2018-05-15 19:34:09